survey-mcp-server

---

🛠️ Descripción general de las herramientas

Este servidor proporciona ocho potentes herramientas para gestionar el ciclo de vida completo de la encuesta con interacciones impulsadas por LLM:

Nombre de la herramienta	Descripción
survey_list_available	Descubre las encuestas disponibles en el directorio de definiciones.
survey_start_session	Inicializa una nueva sesión con el contexto completo de la encuesta, todas las preguntas y preguntas sugeridas iniciales.
survey_get_question	Actualiza el estado de elegibilidad de una pregunta específica después de cambios de estado (útil para lógica condicional).
survey_submit_response	Registra las respuestas de los participantes con validación, puntuación, y devuelve el progreso actualizado y las siguientes preguntas sugeridas.
survey_get_progress	Verifica el estado de finalización, la puntuación actual, las preguntas obligatorias/opcionales restantes y la elegibilidad de finalización.
survey_complete_session	Finaliza una sesión completada con el resumen de puntuación final (requiere que todas las preguntas obligatorias estén respondidas).
survey_export_results	Exporta los datos de la sesión en formato CSV o JSON con filtrado opcional por estado, rango de fechas, etc.
survey_resume_session	Reanuda una sesión incompleta, restaurando el contexto completo, incluidas las preguntas respondidas y el progreso.

survey_list_available

Descubre las encuestas disponibles cargadas desde tu directorio de definiciones de encuestas.

Características clave:

• Enumera todas las encuestas descubiertas mediante el escaneo recursivo del directorio de SURVEY_DEFINITIONS_PATH
• Devuelve metadatos de la encuesta: ID, título, descripción, duración estimada y número de preguntas
• Filtrado opcional por inquilino para despliegues multiinquilino

Casos de uso de ejemplo:

• "Muéstrame todas las encuestas disponibles"
• "¿Qué encuestas pueden tomar los participantes?"
• "Enumera las encuestas del inquilino X"

---

survey_start_session

Inicializa una nueva sesión de encuesta con contexto completo para conversaciones impulsadas por LLM.

Características clave:

• Crea una nueva sesión con ID de sesión único y seguimiento de participantes
• Carga la definición completa de la encuesta con todas las preguntas de antemano
• Devuelve preguntas sugeridas iniciales según la configuración de la encuesta (mín/máx configurable, por defecto 3-5) basadas en la elegibilidad (preguntas incondicionales primero, obligatorias antes que opcionales)
• Cada pregunta incluye la marca currentlyEligible y eligibilityReason para transparencia
• Proporciona el campo guidanceForLLM con instrucciones conversacionales
• Soporta metadatos de sesión para el seguimiento de origen, agente de usuario, etc.

Casos de uso de ejemplo:

• "Inicia la encuesta de satisfacción del cliente para el participante ABC123"
• "Comienza una nueva sesión para la encuesta de retroalimentación del primer trimestre"
• "Inicializa la sesión de encuesta con metadatos: source=web, userAgent=Claude"

---

survey_get_question

Actualiza la elegibilidad de una pregunta y sus detalles después de cambios en el estado de la sesión.

Características clave:

• Devuelve el estado de elegibilidad actual basado en el estado más reciente de la sesión
• Proporciona el motivo de elegibilidad (p. ej., "Lógica condicional satisfecha", "Siempre disponible")
• Indica si la pregunta ya fue respondida
• Útil para verificar si las preguntas condicionales están disponibles después de respuestas anteriores

Casos de uso de ejemplo:

• "¿La pregunta q2 ya está disponible?"
• "Verifica si la pregunta de seguimiento ahora es elegible"
• "Actualiza los detalles de la pregunta después de que el participante respondió la dependencia"

---

survey_submit_response

Registra las respuestas de los participantes con validación y obtén orientación dinámica de respuesta.

Características clave:

• Valida las respuestas contra las restricciones de la pregunta (longitud mín/máx, patrones, campos obligatorios, etc.)
• Calcula y devuelve la puntuación de la respuesta (si la puntuación está habilitada en las opciones de la pregunta)
• Devuelve errores de validación con retroalimentación específica y procesable
• Actualiza el progreso de la sesión (porcentaje completado, preguntas respondidas, tiempo restante estimado, puntuación actual)
• Devuelve el arreglo updatedEligibility que muestra las preguntas condicionales recientemente disponibles
• Proporciona nextSuggestedQuestions actualizado según el nuevo estado (cantidad configurable por encuesta)
• Incluye guidanceForLLM con instrucciones conscientes del contexto

Casos de uso de ejemplo:

• "Envía la respuesta 'muy-satisfecho' para la pregunta q1"
• "Registra el correo electrónico del participante: user@example.com"
• "Guarda la respuesta de formato libre con validación"

---

survey_get_progress

Verifica el estado de la sesión y la elegibilidad de finalización.

Características clave:

• Devuelve el estado de finalización: in-progress, completed, abandoned
• Métricas de progreso: total de preguntas, cantidad respondida, obligatorias restantes, porcentaje completado, puntuación actual
• Enumera todas las preguntas obligatorias sin responder (con estado de elegibilidad)
• Enumera todas las preguntas opcionales sin responder (con estado de elegibilidad)
• Booleano canComplete que indica si la sesión se puede finalizar
• Arreglo completionBlockers que explica lo que impide la finalización

Casos de uso de ejemplo:

• "¿Cuánto de la encuesta está completado?"
• "¿Qué preguntas obligatorias siguen sin responder?"
• "¿Podemos completar la encuesta ahora?"

---

survey_complete_session

Finaliza una sesión completada cuando todas las preguntas obligatorias han sido respondidas.

Características clave:

• Valida que todas las preguntas obligatorias (incluidas las condicionalmente obligatorias) estén respondidas
• Actualiza el estado de la sesión a completed y establece la marca de tiempo completedAt
• Devuelve un resumen con el total de preguntas respondidas, duración de la sesión y puntuación final (si la puntuación está habilitada)
• Evita la finalización duplicada

Casos de uso de ejemplo:

• "Completa la sesión de encuesta"
• "Finaliza la sesión sess_abc123"
• "Marca la encuesta como finalizada"

---

survey_export_results

Exporta los datos de la sesión para análisis y elaboración de informes.

Características clave:

• Exporta en formato CSV o JSON
• Filtra por ID de encuesta, estado, rango de fechas y criterios personalizados
• Devuelve datos formateados con el conteo de registros y la marca de tiempo de generación
• El formato CSV incluye una fila por sesión con respuestas de preguntas aplanadas
• El formato JSON preserva la estructura completa de la sesión

Casos de uso de ejemplo:

• "Exporta todas las respuestas completadas para la encuesta customer-satisfaction-q1-2025 como CSV"
• "Obtén la exportación JSON de las sesiones completadas en enero de 2025"
• "Exporta las sesiones en curso para análisis"

---

survey_resume_session

Reanuda una sesión incompleta con restauración completa del contexto.

Características clave:

• Restaura el contexto completo de la encuesta y el estado de la sesión
• Devuelve todas las preguntas respondidas anteriormente con sus respuestas
• Proporciona nextSuggestedQuestions actualizado para las preguntas restantes (cantidad configurable por encuesta)
• Muestra el tiempo transcurrido desde la última actividad
• Resumen del progreso actual (porcentaje, preguntas restantes, puntuación actual)
• Incluye guidanceForLLM con sugerencias de mensajes de bienvenida de regreso

Casos de uso de ejemplo:

• "Reanuda la sesión sess_abc123"
• "Continúa la encuesta donde el participante la dejó"
• "Restaura el estado de la sesión para que el participante termine más tarde"

✨ Características

Este servidor está construido sobre el mcp-ts-template y hereda su rico conjunto de características:

• Herramientas declarativas: Define capacidades en archivos únicos autocontenidos. El framework maneja el registro, la validación y la ejecución.
• Manejo robusto de errores: Un sistema unificado de McpError garantiza respuestas de error consistentes y estructuradas.
• Autenticación conectable: Asegura tu servidor con soporte sin complicaciones para los modos none, jwt o oauth.
• Almacenamiento abstraído: Cambia los backends de almacenamiento (in-memory, filesystem, Supabase, Cloudflare KV/R2) sin modificar la lógica de negocio.
• Observabilidad integral: Información profunda con registro estructurado (Pino) y OpenTelemetry opcional, autoinstrumentado para trazas y métricas.
• Inyección de dependencias: Construido con tsyringe para una arquitectura limpia, desacoplada y comprobable.
• Listo para el edge: Escribe código una vez y ejecútalo sin problemas en tu máquina local o en el edge con Cloudflare Workers.

Más las características especializadas para la Gestión de Encuestas:

• Encuestas impulsadas por LLM: Las herramientas proporcionan contexto enriquecido (progreso, siguientes preguntas sugeridas, resultados de validación, puntuaciones) para guiar el flujo natural de la conversación.
• Control de flujo híbrido: Modo guiado con preguntas sugeridas configurables (por defecto 3-5) + orden flexible basado en el contexto de la conversación.
• Sistema de puntuación: Soporte para cuestionarios y evaluaciones con campos de puntuación opcionales en las opciones de preguntas. Cálculo automático de puntuación y acumulación por sesión.
• Lógica condicional avanzada: Soporte para lógica de salto simple y ramificación compleja de múltiples condiciones AND/OR con seguimiento de elegibilidad.
• Definiciones de encuestas basadas en JSON: Define encuestas en archivos JSON simples con escaneo recursivo de directorios.
• Múltiples tipos de preguntas: free-form, multiple-choice, multiple-select, rating-scale, email, number, boolean, y tipos avanzados como cuadrículas de date, datetime, time y matrix.
• Motor de validación: Longitud mín/máx, patrones, campos obligatorios, restricciones personalizadas y reglas de fecha/hora con patrón de mapa de validadores extensible.
• Reanudación de sesión: Gestión de estado integrada que permite a los participantes pausar y continuar más tarde.
• Texto de ayuda: Un campo helpText en las preguntas proporciona a los LLMs contexto y orientación para hacer preguntas de forma natural.
• Soporte de paginación: Recuperación de datos escalable con paginación configurable para consultas y exportaciones de sesiones.

🚀 Comenzando

Configuración del cliente MCP / Ajustes

Agrega lo siguiente a tu archivo de configuración del cliente MCP (p. ej., cline_mcp_settings.json).

{
  "mcpServers": {
    "survey-mcp-server": {
      "command": "bunx",
      "args": ["@cyanheads/survey-mcp-server@latest"],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "SURVEY_DEFINITIONS_PATH": "./survey-definitions",
        "SURVEY_RESPONSES_PATH": "./survey-responses"
      }
    }
  }
}

Requisitos previos

• Bun v1.2.0 o superior.

Instalación

1. Clona el repositorio:

git clone https://github.com/cyanheads/survey-mcp-server.git

2. Navega al directorio:

cd survey-mcp-server

3. Instala las dependencias:

bun install

4. Explora las encuestas de ejemplo: El directorio survey-definitions/ contiene archivos JSON de ejemplo que demuestran varios tipos de preguntas y características. Úsalos como punto de partida para crear tus propias encuestas.

🛠️ Capacidades principales: Herramientas de encuesta

Este servidor equipa a los agentes de IA con herramientas especializadas para realizar encuestas conversacionales y dinámicas mientras mantiene la recopilación de datos estructurada.

Flujo de interacción de ejemplo

1. LLM calls survey_start_session
   → Receives full survey context, all questions, and first 3-5 suggested questions

2. LLM asks questions naturally in conversation
   → Follows suggestions but can adapt order based on context
   → Uses natural language while ensuring survey questions are covered

3. For each answer, LLM calls survey_submit_response
   → Receives validation feedback (re-prompts if needed)
   → Gets score for response (if scoring enabled): "+5 points (Total: 45)"
   → Gets progress update (50% complete, 2 of 4 questions answered)
   → Refreshed suggestions with newly eligible conditional questions

4. LLM can check survey_get_progress anytime
   → Knows exactly what's required vs optional
   → Understands what remains before completion is possible

5. When all required questions answered, LLM calls survey_complete_session
   → Session finalized with timestamp, summary, and final score
   → Ready for export via survey_export_results

📖 Ver especificación detallada y ejemplos →

⚙️ Configuración

Toda la configuración está centralizada y validada al inicio en src/config/index.ts. Las variables de entorno clave en tu archivo .env incluyen:

Variable	Descripción	Por defecto
SURVEY_DEFINITIONS_PATH	Ruta al directorio que contiene los archivos JSON de encuestas (escaneo recursivo).	./survey-definitions
SURVEY_RESPONSES_PATH	Ruta al directorio para almacenar las respuestas de sesión (modo filesystem).	./survey-responses
MCP_TRANSPORT_TYPE	El transporte a utilizar: stdio o http.	http
MCP_HTTP_PORT	El puerto para el servidor HTTP.	3019
MCP_AUTH_MODE	Modo de autenticación: none, jwt o oauth.	none
STORAGE_PROVIDER_TYPE	Backend de almacenamiento: in-memory, filesystem, supabase, cloudflare-kv, r2.	in-memory
OTEL_ENABLED	Establecer en true para habilitar OpenTelemetry.	false
LOG_LEVEL	El nivel mínimo para el registro de logs (debug, info, warn, error).	info
MCP_AUTH_SECRET_KEY	Requerido para autenticación jwt. Una clave secreta de 32+ caracteres.	(none)
OAUTH_ISSUER_URL	Requerido para autenticación oauth. URL del proveedor OIDC.	(none)

▶️ Ejecutando el Servidor

Desarrollo Local

• Compilar y ejecutar la versión de producción:

  # One-time build
  bun rebuild
  
  # Run the built server
  bun start:http
  # or
  bun start:stdio
  

• Ejecutar comprobaciones y pruebas:

  bun devcheck # Lints, formats, type-checks, and more
  bun test # Runs the test suite
  

Cloudflare Workers

1. Compilar el bundle del Worker:

bun build:worker

2. Ejecutar localmente con Wrangler:

bun deploy:dev

3. Desplegar en Cloudflare:

   bun deploy:prod
   

📂 Estructura del Proyecto

Directorio	Propósito y Contenido
survey-definitions/	Definiciones de encuestas (archivos JSON). Se admiten directorios anidados para organización.
survey-responses/	Respuestas de sesión (cuando se usa el proveedor filesystem). Organizadas por ID de tenant.
src/mcp-server/tools	Definiciones de herramientas de encuesta (survey-*.tool.ts). 8 herramientas para el ciclo de vida completo.
src/mcp-server/resources	Definiciones de recursos para metadatos y descubrimiento de encuestas.
src/services/survey/	Servicio de encuestas con proveedor filesystem para cargar definiciones.
src/mcp-server/transports	Implementaciones para transportes HTTP y STDIO, incluido el middleware de autenticación.
src/storage	Abstracción de StorageService y todas las implementaciones de proveedores de almacenamiento.
src/container	Registros y tokens de contenedores de inyección de dependencias.
src/utils	Utilidades principales para logging, manejo de errores, rendimiento y seguridad.
src/config	Análisis y validación de variables de entorno con Zod.
tests/	Pruebas unitarias y de integración, que reflejan la estructura del directorio src/.
docs/	Especificaciones y guías detalladas (ver survey-mcp-server-spec.md).

🧑‍💻 Guía de Desarrollo para Agentes

Para reglas estrictas al usar este servidor con un agente de IA, consulte el archivo .clinerules (o AGENTS.md) en este repositorio. Los principios clave incluyen:

• La Lógica Lanza, los Handlers Capturan: Nunca use try/catch en su logic de herramienta. Lance un McpError en su lugar.
• Pase el Contexto: Siempre pase el objeto RequestContext a través de su pila de llamadas para logging y trazabilidad.
• Use las Exportaciones del Índice: Registre nuevas herramientas y recursos solo en los archivos índice index.ts dentro de sus respectivos directorios definitions.

🤝 Contribuciones

¡Las issues y pull requests son bienvenidas! Si planea contribuir, ejecute las comprobaciones y pruebas locales antes de enviar su PR.

bun run devcheck
bun test

📜 Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0. Consulte el archivo LICENSE para más detalles.