LimeSurvey MCP

Expone la funcionalidad de la API remota de LimeSurvey como herramientas MCP.

Documentación

Servidor MCP de LimeSurvey

Un servidor de Model Context Protocol (MCP) que expone la funcionalidad de la API remota de LimeSurvey como herramientas MCP. Este servidor proporciona una forma estandarizada de interactuar con las potentes capacidades de gestión de encuestas de LimeSurvey a través de clientes MCP.

Instalación

# Clone the repository
git clone https://github.com/TonisOrmisson/limesurvey-mcp.git
cd limesurvey-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Configuración

Crea un archivo .env en el directorio raíz con las siguientes variables:

# LimeSurvey Remote API Settings
LIMESURVEY_API_URL=https://your-limesurvey-instance.com/admin/remotecontrol
LIMESURVEY_USERNAME=your_username
LIMESURVEY_PASSWORD=your_password

# Server settings
PORT=3000
ENABLE_SSE=false

# Optional: run in read‑only mode
# When true, all write tools short‑circuit and return an error message
# instead of calling LimeSurvey.
READONLY_MODE=false

Uso

Una vez que el servidor esté en ejecución, puedes usar cualquier cliente MCP para conectarte a él y acceder a la funcionalidad de LimeSurvey.

Por defecto, el servidor se inicia solo con stdio. Establece ENABLE_SSE=true cuando necesites el transporte HTTP/SSE en /sse y /messages, por ejemplo, cuando el servidor MCP se ejecuta de forma remota en lugar de ser iniciado localmente por el cliente.

Construcción de encuestas sin interfaz (addSurvey → grupos → preguntas)

Puedes construir una encuesta sin la interfaz de administración de LimeSurvey combinando herramientas de escritura:

addSurvey — crea una encuesta inactiva; anota el ID de encuesta devuelto (sid).
addGroup — crea uno o más grupos de preguntas; cada llamada devuelve un ID de grupo (gid) para el siguiente paso.
importQuestion — para cada pregunta, pasa contenido .lsq codificado en base64 (exporta una pregunta prototipo una vez desde la interfaz, o genera XML compatible). Usa importDataType: lsq.
setSurveyProperties — texto de bienvenida, descripción, URL final, etc.
activateSurvey — cuando la estructura esté lista.

Reconstrucciones idempotentes: usa deleteQuestion (por qid, con confirmDeletion: true) y deleteGroup (por encuesta + gid) para desmontar un grupo o preguntas individuales antes de reimportar plantillas .lsq. Eliminar un grupo elimina el contenido de ese grupo; confirma el comportamiento en tu versión de LimeSurvey en una encuesta de desarrollo primero.

Patrón de enlace de participantes: https://<host>/index.php/<sid> (usa sid de addSurvey o listSurveys). El acceso con token utiliza tus herramientas de participantes existentes.

Ejemplo de fragmento de cliente MCP (pseudo-YAML) para listar encuestas:

tool: listSurveys
args: {}

Referencia de la API

Cobertura de RemoteControl2

La tabla siguiente muestra cómo los métodos de LimeSurvey RemoteControl2 se exponen como herramientas MCP en este servidor. Los métodos que no están implementados aquí no están disponibles en la instancia de LimeSurvey objetivo o se omiten intencionalmente (por ejemplo, endpoints inestables o no documentados).

Dominio	Método RemoteControl2	Nombre de herramienta MCP	Notas
Encuestas	`list_surveys`	`listSurveys`	solo lectura
Encuestas	`get_survey_properties`	`getSurveyProperties`	solo lectura
Encuestas	`activate_survey`	`activateSurvey`	escritura (protegida por `READONLY_MODE`)
Encuestas	`get_language_properties`	`getSurveyLanguageProperties`	solo lectura
Encuestas	`get_site_settings`	`getAvailableLanguages`	lee la configuración `availablelanguages`
Encuestas	— (derivado)	`getSurveyLanguages`	derivado de las propiedades de la encuesta
Encuestas	`get_fieldmap`	`getFieldMap`	solo lectura
Ciclo de vida de encuestas	`add_survey`	`addSurvey`	escritura (protegida)
Ciclo de vida de encuestas	`import_survey`	`importSurvey`	escritura (protegida)
Ciclo de vida de encuestas	`copy_survey`	`copySurvey`	escritura (protegida)
Ciclo de vida de encuestas	`delete_survey`	`deleteSurvey`	escritura (protegida, se requiere confirmación)
Ciclo de vida de encuestas	`activate_tokens`	`activateTokens`	escritura (protegida)
Ciclo de vida de encuestas	`set_survey_properties`	`setSurveyProperties`	escritura (protegida)
Grupos de preguntas	`list_groups`	`listQuestionGroups`	solo lectura
Grupos de preguntas	`get_group_properties`	`getGroupProperties`	solo lectura
Grupos de preguntas	`add_group`	`addGroup`	escritura (protegida); devuelve nuevo `gid`
Grupos de preguntas	`delete_group`	`deleteGroup`	escritura (protegida, se requiere confirmación)
Grupos de preguntas	`set_group_properties`	`setGroupProperties`	escritura (protegida)
Preguntas	`list_questions`	`listQuestions`	solo lectura
Preguntas	`get_question_properties`	`getQuestionProperties`	solo lectura
Preguntas	`import_question`	`importQuestion`	escritura (protegida); `.lsq` en base64
Preguntas	`delete_question`	`deleteQuestion`	escritura (protegida, se requiere confirmación)
Preguntas	`set_question_properties`	`setQuestionProperties`	escritura (protegida)
Respuestas	`get_summary`	`getResponseSummary`	solo lectura
Respuestas	`list_response_exports`	`listResponseExportFormats`	descubrimiento de solo lectura (compatible con plugins)
Respuestas	`export_responses`	`exportResponses`	exportación de solo lectura
Respuestas	`add_response`	`addResponse`	escritura (protegida)
Respuestas	`update_response`	`updateResponse`	escritura (protegida)
Respuestas	`delete_response`	`deleteResponse`	escritura (protegida, se requiere confirmación)
Respuestas	`get_response_ids`	`getResponseIds`	solo lectura
Respuestas	`export_responses_by_token`	`exportResponsesByToken`	exportación de solo lectura
Respuestas	`export_timeline`	`exportTimeline`	recuentos agregados de solo lectura
Archivos	`upload_file`	`uploadFile`	escritura (protegida)
Archivos	`get_uploaded_files`	`listUploadedFiles`	solo lectura
Participantes/tokens	`add_participants`	`addParticipant`, `addMultipleParticipants`	escritura (protegida)
Participantes/tokens	`list_participants`	`listParticipants`, `listFilteredParticipants`	solo lectura
Participantes/tokens	`get_participant_properties`	`getParticipantProperties`	solo lectura
Participantes/tokens	`delete_participants`	`deleteParticipants`	escritura (protegida, se requiere confirmación)
Participantes/tokens	`invite_participants`	`inviteParticipants`	escritura (protegida, correo/notificación)
Participantes/tokens	`remind_participants`	`remindParticipants`	escritura (protegida, correo/notificación)
Cuotas	`get_quota_properties`	`getQuotaProperties`	solo lectura; sin envoltorio de listado completo
Cuotas	`add_quota`	`addQuota`	escritura (protegida)
Cuotas	`set_quota_properties`	`setQuotaProperties`	escritura (protegida)
Cuotas	`delete_quota`	`deleteQuota`	escritura (protegida, se requiere confirmación)
Idiomas	`add_language`	`addSurveyLanguage`	escritura (protegida)
Idiomas	`delete_language`	`deleteSurveyLanguage`	escritura (protegida, se requiere confirmación)
Idiomas	`set_language_properties`	`setSurveyLanguageProperties`	escritura (protegida)
Configuración del sitio	`get_site_settings`	`getAvailableLanguages`	solo lectura

Cuando READONLY_MODE=true esté configurado en el entorno, todas las herramientas marcadas como "escritura (protegida)" anteriormente devolverán un mensaje de error claro sin llamar a LimeSurvey.

Gestión de Encuestas

listSurveys

Lista todas las encuestas a las que el usuario autenticado tiene permiso de acceso.

Parámetros: Ninguno

Devuelve:

Matriz de objetos de encuesta con propiedades:
- sid: ID de la encuesta
- surveyls_title: Título de la encuesta
- active: Si la encuesta está activa ("Y" o "N")
- expires: Fecha de expiración (si está configurada)
- startdate: Fecha de inicio (si está configurada)
- Y otros metadatos de la encuesta

Ejemplo de respuesta:

[
  {
    "sid": "123456",
    "surveyls_title": "Customer Satisfaction Survey",
    "active": "Y",
    "expires": null,
    "startdate": "2023-01-01 00:00:00"
  },
  {
    "sid": "789012",
    "surveyls_title": "Employee Feedback",
    "active": "N",
    "expires": "2023-12-31 23:59:59",
    "startdate": "2023-06-01 00:00:00"
  }
]

getSurveyProperties

Obtiene propiedades detalladas de una encuesta específica.

Parámetros:

surveyId: El ID de la encuesta para obtener sus propiedades

Devuelve:

Objeto que contiene las propiedades de la encuesta, incluyendo configuración, ajustes y metadatos

activateSurvey

Activa una encuesta que actualmente está inactiva.

Parámetros:

surveyId: El ID de la encuesta a activar

Devuelve:

Resultado del proceso de activación

getSurveyLanguageProperties

Obtiene propiedades específicas de idioma para una encuesta.

Parámetros:

surveyId: El ID de la encuesta
language: El código de idioma

Devuelve:

Objeto que contiene las propiedades específicas de idioma para la encuesta

getAvailableLanguages

Obtiene los idiomas disponibles en la instalación de LimeSurvey.

Parámetros: Ninguno

Devuelve:

Lista de códigos de idioma disponibles y sus nombres

getSurveyLanguages

Obtiene los idiomas disponibles para una encuesta específica.

Parámetros:

surveyId: El ID de la encuesta

Devuelve:

Matriz de códigos de idioma disponibles para la encuesta

getQuotaProperties

Obtiene propiedades para una cuota específica.

Esta herramienta envuelve el método RemoteControl get_quota_properties: get_quota_properties($sessionKey, $iQuotaId, $aQuotaSettings = null, $sLanguage = null). No se admite el listado de todas las cuotas de una encuesta a través de este servidor MCP.

Parámetros:

quotaId: ID de cuota específico (obligatorio)
language (opcional): Idioma para las descripciones de la cuota

Devuelve:

Información de la cuota para el ID de cuota dado

addQuota

Añade una nueva cuota a una encuesta.

Parámetros:

surveyId: El ID de la encuesta
name: Nombre de la cuota
limit: Número máximo de respuestas para la cuota

Devuelve:

Objeto de resultado de LimeSurvey que contiene los datos de la cuota creada

setQuotaProperties

Actualiza las propiedades de una cuota existente.

Parámetros:

quotaId: El ID de la cuota a actualizar
properties: Objeto con los campos de la cuota a actualizar (por ejemplo, name, limit, active, action, message, url)

Devuelve:

Objeto de resultado que describe la cuota actualizada

deleteQuota

Elimina una cuota existente.

Parámetros:

quotaId: El ID de la cuota a eliminar

Devuelve:

Objeto de resultado que indica si la cuota se eliminó correctamente

addSurveyLanguage

Añade un nuevo idioma a una encuesta. Parámetros:

surveyId: El ID de la encuesta
language: Código de idioma a añadir (por ejemplo "de", "fr")

Devuelve:

Objeto de resultado de LimeSurvey para la adición del idioma

deleteSurveyLanguage

Elimina un idioma de una encuesta.

Parámetros:

surveyId: El ID de la encuesta
language: Código de idioma a eliminar

Devuelve:

Objeto de resultado que indica si el idioma fue eliminado

setSurveyLanguageProperties

Establece propiedades específicas de idioma para un idioma de encuesta.

Parámetros:

surveyId: El ID de la encuesta
language (opcional): Código de idioma; omitir para apuntar al idioma base
localeData: Objeto con campos de configuración regional a actualizar (por ejemplo surveyls_title, surveyls_description, surveyls_welcometext)

Devuelve:

Objeto de resultado que describe las propiedades de idioma actualizadas

setSurveyProperties

Establece propiedades para una encuesta.

Esta herramienta envuelve el método de Control Remoto set_survey_properties: set_survey_properties($sessionKey, $iSurveyID, $aSurveyData). Algunos campos (por ejemplo sid, active, language, additional_languages y varios campos en encuestas activas) no se pueden cambiar y serán ignorados por LimeSurvey.

Parámetros:

surveyId: El ID de la encuesta
properties: Objeto de campos de la encuesta a actualizar

Devuelve:

Objeto de resultado que describe qué campos se actualizaron correctamente

Gestión de Preguntas

listQuestions

Lista todas las preguntas de una encuesta específica.

Parámetros:

surveyId: El ID de la encuesta
groupId (opcional): Obtener solo preguntas de este grupo
language (opcional): Idioma para los textos de las preguntas

Devuelve:

Matriz de objetos de pregunta con propiedades que incluyen ID, texto, tipo y otras configuraciones

listQuestionGroups

Lista todos los grupos de preguntas de una encuesta específica.

Parámetros:

surveyId: El ID de la encuesta
language (opcional): Idioma para los textos de los grupos

Devuelve:

Matriz de objetos de grupo de preguntas con propiedades que incluyen ID, título, descripción y orden

addGroup

Crea un grupo de preguntas vacío en una encuesta. Envuelve el Control Remoto add_group y devuelve el nuevo ID del grupo (entero en caso de éxito), que se pasa a importQuestion como groupId.

Parámetros:

surveyId: ID de la encuesta
title: Título del grupo
description (opcional): Descripción del grupo; cadena vacía por defecto

importQuestion

Importa una pregunta desde datos codificados en base64 .lsq a un grupo. Misma idea que importSurvey con .lss: preparar plantillas (por ejemplo, exportar una pregunta por tipo desde LimeSurvey una vez), luego llamar a esta herramienta repetidamente con diferentes cargas útiles.

Parámetros:

surveyId, groupId: Encuesta y grupo de destino
importData: Contenido .lsq codificado en base64
importDataType: Debe ser lsq (por defecto)
mandatory: Y o N (por defecto N)
newQuestionTitle, newQuestionText, newQuestionHelp (opcional): Anulan argumentos opcionales coincidentes del Control Remoto después de la importación

Devuelve: Nuevo ID de pregunta en caso de éxito (entero), o una estructura de error de LimeSurvey en caso de fallo.

deleteGroup

Elimina un grupo de preguntas de una encuesta. Envuelve el Control Remoto delete_group. Normalmente también elimina las preguntas dentro del grupo; verificar en su instancia.

Parámetros:

surveyId, groupId: Encuesta y grupo a eliminar
confirmDeletion: Debe ser true (protección de seguridad)

deleteQuestion

Elimina una pregunta por qid. Envuelve el Control Remoto delete_question. Los tipos complejos (por ejemplo, clasificación) pueden usar filas adicionales en listQuestions (subpreguntas); eliminar o reconstruir según lo que produjo su ciclo de exportación/importación.

Parámetros:

questionId: ID de la pregunta a eliminar
confirmDeletion: Debe ser true

getQuestionProperties

Obtiene propiedades de una pregunta específica.

Parámetros:

questionId: El ID de la pregunta
language (opcional): Idioma para los textos de las preguntas
properties (opcional): Matriz de nombres de propiedades a recuperar

Devuelve:

Objeto que contiene las propiedades solicitadas para la pregunta

setQuestionProperties

Actualiza campos escribibles en una pregunta mediante el Control Remoto set_question_properties. Descubrimiento primero: llamar a getQuestionProperties (opcionalmente con una lista de nombres de configuración) para enviar solo las claves que LimeSurvey acepta. La API bloquea cambios en campos estructurales como qid, gid, sid, parent_qid, type y language.

Ediciones comunes

question: Texto del enunciado (a menudo HTML).
help: Texto de ayuda debajo del enunciado.
Pasar language al actualizar un idioma de encuesta no base.

Preguntas de clasificación (tipo R)
Las etiquetas de clasificación visibles para el participante suelen estar en filas de subpreguntas (parent_qid apunta al padre). Actualizar el texto question de cada subpregunta con setQuestionProperties en el qid de esa fila, o ajustar la plantilla .lsq y reimportar.

Tipos de lista / lista con comentario
El mensaje principal sigue siendo question / help en el padre. Las etiquetas de respuesta pueden ser registros de respuesta separados; si el Control Remoto no expone lo que necesita, prefiera editar la plantilla .lsq y usar importQuestion (o la interfaz de administración) para listas de opciones, y use esta herramienta para ajustes de redacción que la API permita.

Gestión de Respuestas

getResponseSummary

Obtiene información resumida sobre las respuestas recopiladas de una encuesta.

Parámetros:

surveyId: El ID de la encuesta

Devuelve:

Objeto de resumen que contiene información sobre recuentos y estado de respuestas

listResponseExportFormats

Lista los formatos de exportación de respuestas disponibles globalmente, incluidos los tipos proporcionados por complementos.

Parámetros:

Ninguno

Devuelve:

Una lista de objetos de formato de exportación con:
- type
- pluginClass
- label (anulable)
- tooltip (anulable)
- onclick (anulable)
- isDefault (booleano)

exportResponses

Exporta respuestas de una encuesta en el formato especificado.

Parámetros:

surveyId: El ID de la encuesta
documentType: Tipo de formato de exportación (dinámico/consciente de complementos). Llamar a listResponseExportFormats primero - por defecto: "csv"
language (opcional): Idioma para la exportación de respuestas
completionStatus: Filtrar por estado de finalización ('complete', 'incomplete', 'all') - por defecto: "all"
headingType: Tipo de encabezados ('code', 'full', 'abbreviated') - por defecto: "code"
responseType: Tipo de respuesta ('short' o 'long') - por defecto: "short"
fields (opcional): Matriz de nombres de campos a exportar

Devuelve:

Un resumen de éxito más la carga útil de exportación sin procesar
Para formatos de texto con decodeOutput: true, también incluye una vista previa decodificada

Flujo de trabajo de exportación con descubrimiento primero

Llamar a listResponseExportFormats para descubrir valores válidos de type expuestos por la instancia actual de LimeSurvey.
Elegir un type devuelto (por ejemplo csv, json o un formato de complemento personalizado).
Llamar a exportResponses con ese documentType.

Ejemplo:

tool: listResponseExportFormats
args: {}
---
tool: exportResponses
args:
  surveyId: "123456"
  documentType: "csv"

listResponses

Lista los IDs de respuestas de una encuesta específica.

Parámetros:

surveyId: El ID de la encuesta
start: Índice de respuesta inicial - por defecto: 0
limit: Número de respuestas a devolver - por defecto: 10
attributes (opcional): Matriz de nombres de atributos a incluir

Devuelve:

Matriz de IDs de respuestas y atributos solicitados

Gestión de Participantes

addParticipant

Añade un participante a una encuesta.

Parámetros:

surveyId: El ID de la encuesta
email: Dirección de correo electrónico del participante
firstName (opcional): Nombre
lastName (opcional): Apellido
language (opcional): Código de idioma
usesLeft: Número de veces que el participante puede acceder a la encuesta - por defecto: 1
validFrom (opcional): Fecha de validez desde (AAAA-MM-DD HH:mm:ss)
validUntil (opcional): Fecha de validez hasta (AAAA-MM-DD HH:mm:ss)

Devuelve:

Datos del participante incluido el token generado

listParticipants

Lista participantes de una encuesta específica.

Parámetros:

surveyId: El ID de la encuesta
start: Índice de participante inicial - por defecto: 0
limit: Número de participantes a devolver - por defecto: 10
unused: Mostrar solo tokens no utilizados - por defecto: false
attributes (opcional): Matriz de nombres de atributos a incluir

Devuelve:

Matriz de objetos de participante con los atributos solicitados

getParticipantProperties

Obtiene propiedades de un participante/token específico.

Parámetros:

surveyId: El ID de la encuesta
tokenId: El ID del token
attributes (opcional): Matriz de nombres de atributos a incluir

Devuelve:

Objeto que contiene propiedades para el participante especificado

Gestión de Estadísticas

exportStatistics

Exporta estadísticas de la encuesta en formato PDF, Excel o HTML con gráficos opcionales.

Parámetros:

surveyId: El ID de la encuesta para exportar estadísticas
documentType: Formato de la exportación: 'pdf', 'xls' o 'html' - por defecto: "pdf"
language (opcional): Idioma para la exportación de estadísticas (por defecto: idioma predeterminado de la encuesta)
includeGraphs: Si incluir gráficos en la exportación (solo aplicable para PDF) - por defecto: false
groupIds (opcional): ID(s) de grupo de preguntas específico(s) a incluir en las estadísticas, puede ser un solo ID o una matriz de IDs

Devuelve:

Cadena codificada en base64 que contiene el archivo de estadísticas en el formato solicitado

Ejemplo de uso:

exportStatistics:
  surveyId: "123456"
  documentType: "pdf"
  includeGraphs: true

Desarrollo

Este proyecto está construido usando:

Node.js
@modelcontextprotocol/sdk - SDK del servidor MCP
TypeScript - Para seguridad de tipos y características modernas de JavaScript
dotenv - Para gestión de variables de entorno
Axios - Para solicitudes HTTP a la API remota de LimeSurvey

Compilación

npm run build

Modo de Desarrollo

npm run dev

Licencia

MIT