LimeSurvey MCP

Expõe a funcionalidade da API Remota do LimeSurvey como ferramentas MCP.

Documentação

LimeSurvey MCP Server

Um servidor Model Context Protocol (MCP) que expõe a funcionalidade da LimeSurvey Remote API como ferramentas MCP. Este servidor fornece uma maneira padronizada de interagir com os poderosos recursos de gerenciamento de pesquisas do LimeSurvey por meio de clientes MCP.

Instalação

# 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

Configuração

Crie um arquivo .env no diretório raiz com as seguintes variáveis:

# 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

Quando o servidor estiver em execução, você pode usar qualquer cliente MCP para se conectar a ele e acessar a funcionalidade do LimeSurvey.

Por padrão, o servidor inicia apenas com stdio. Defina ENABLE_SSE=true quando precisar do transporte HTTP/SSE em /sse e /messages, por exemplo, quando o servidor MCP for executado remotamente em vez de ser iniciado localmente pelo cliente.

Construção de pesquisa sem interface (addSurvey → grupos → perguntas)

Você pode construir uma pesquisa sem a interface administrativa do LimeSurvey combinando ferramentas de escrita:

addSurvey — crie uma pesquisa inativa; anote o ID da pesquisa retornado (sid).
addGroup — crie um ou mais grupos de perguntas; cada chamada retorna um ID de grupo (gid) para a próxima etapa.
importQuestion — para cada pergunta, passe o conteúdo codificado em base64 .lsq (exporte uma pergunta protótipo uma vez pela interface ou gere XML compatível). Use importDataType: lsq.
setSurveyProperties — texto de boas-vindas, descrição, URL final, etc.
activateSurvey — quando a estrutura estiver pronta.

Reconstruções idempotentes: use deleteQuestion (por qid, com confirmDeletion: true) e deleteGroup (por pesquisa + gid) para remover um grupo ou perguntas individuais antes de reimportar os modelos .lsq. Excluir um grupo remove o conteúdo desse grupo; confirme o comportamento na sua versão do LimeSurvey em uma pesquisa de desenvolvimento primeiro.

Padrão de link de participante: https://<host>/index.php/<sid> (use sid de addSurvey ou listSurveys). O acesso tokenizado usa suas ferramentas de participante existentes.

Exemplo de trecho de cliente MCP (pseudo-YAML) para listar pesquisas:

tool: listSurveys
args: {}

Referência da API

Cobertura do RemoteControl2

A tabela abaixo mostra como os métodos RemoteControl2 do LimeSurvey são expostos como ferramentas MCP neste servidor. Os métodos que não estão implementados aqui não estão disponíveis na instância LimeSurvey de destino ou foram intencionalmente ignorados (por exemplo, endpoints instáveis ou não documentados).

Domínio	Método RemoteControl2	Nome da ferramenta MCP	Observações
Pesquisas	`list_surveys`	`listSurveys`	somente leitura
Pesquisas	`get_survey_properties`	`getSurveyProperties`	somente leitura
Pesquisas	`activate_survey`	`activateSurvey`	escrita (protegida por `READONLY_MODE`)
Pesquisas	`get_language_properties`	`getSurveyLanguageProperties`	somente leitura
Pesquisas	`get_site_settings`	`getAvailableLanguages`	lê a configuração `availablelanguages`
Pesquisas	— (derivado)	`getSurveyLanguages`	derivado das propriedades da pesquisa
Pesquisas	`get_fieldmap`	`getFieldMap`	somente leitura
Ciclo de vida da pesquisa	`add_survey`	`addSurvey`	escrita (protegida)
Ciclo de vida da pesquisa	`import_survey`	`importSurvey`	escrita (protegida)
Ciclo de vida da pesquisa	`copy_survey`	`copySurvey`	escrita (protegida)
Ciclo de vida da pesquisa	`delete_survey`	`deleteSurvey`	escrita (protegida, confirmação necessária)
Ciclo de vida da pesquisa	`activate_tokens`	`activateTokens`	escrita (protegida)
Ciclo de vida da pesquisa	`set_survey_properties`	`setSurveyProperties`	escrita (protegida)
Grupos de perguntas	`list_groups`	`listQuestionGroups`	somente leitura
Grupos de perguntas	`get_group_properties`	`getGroupProperties`	somente leitura
Grupos de perguntas	`add_group`	`addGroup`	escrita (protegida); retorna novo `gid`
Grupos de perguntas	`delete_group`	`deleteGroup`	escrita (protegida, confirmação necessária)
Grupos de perguntas	`set_group_properties`	`setGroupProperties`	escrita (protegida)
Perguntas	`list_questions`	`listQuestions`	somente leitura
Perguntas	`get_question_properties`	`getQuestionProperties`	somente leitura
Perguntas	`import_question`	`importQuestion`	escrita (protegida); base64 `.lsq`
Perguntas	`delete_question`	`deleteQuestion`	escrita (protegida, confirmação necessária)
Perguntas	`set_question_properties`	`setQuestionProperties`	escrita (protegida)
Respostas	`get_summary`	`getResponseSummary`	somente leitura
Respostas	`list_response_exports`	`listResponseExportFormats`	descoberta somente leitura (ciente de plugins)
Respostas	`export_responses`	`exportResponses`	exportação somente leitura
Respostas	`add_response`	`addResponse`	escrita (protegida)
Respostas	`update_response`	`updateResponse`	escrita (protegida)
Respostas	`delete_response`	`deleteResponse`	escrita (protegida, confirmação necessária)
Respostas	`get_response_ids`	`getResponseIds`	somente leitura
Respostas	`export_responses_by_token`	`exportResponsesByToken`	exportação somente leitura
Respostas	`export_timeline`	`exportTimeline`	contagens agregadas somente leitura
Arquivos	`upload_file`	`uploadFile`	escrita (protegida)
Arquivos	`get_uploaded_files`	`listUploadedFiles`	somente leitura
Participantes/tokens	`add_participants`	`addParticipant`, `addMultipleParticipants`	escrita (protegida)
Participantes/tokens	`list_participants`	`listParticipants`, `listFilteredParticipants`	somente leitura
Participantes/tokens	`get_participant_properties`	`getParticipantProperties`	somente leitura
Participantes/tokens	`delete_participants`	`deleteParticipants`	escrita (protegida, confirmação necessária)
Participantes/tokens	`invite_participants`	`inviteParticipants`	escrita (protegida, e-mail/notificação)
Participantes/tokens	`remind_participants`	`remindParticipants`	escrita (protegida, e-mail/notificação)
Cotas	`get_quota_properties`	`getQuotaProperties`	somente leitura; sem wrapper de listar todos
Cotas	`add_quota`	`addQuota`	escrita (protegida)
Cotas	`set_quota_properties`	`setQuotaProperties`	escrita (protegida)
Cotas	`delete_quota`	`deleteQuota`	escrita (protegida, confirmação necessária)
Idiomas	`add_language`	`addSurveyLanguage`	escrita (protegida)
Idiomas	`delete_language`	`deleteSurveyLanguage`	escrita (protegida, confirmação necessária)
Idiomas	`set_language_properties`	`setSurveyLanguageProperties`	escrita (protegida)
Configurações do site	`get_site_settings`	`getAvailableLanguages`	somente leitura

Quando READONLY_MODE=true está definido no ambiente, todas as ferramentas marcadas como "escrita (protegida)" acima retornarão uma mensagem de erro clara sem chamar o LimeSurvey.

Gerenciamento de Pesquisas

listSurveys

Lista todas as pesquisas que o usuário autenticado tem permissão para acessar.

Parâmetros: Nenhum

Retorna:

Matriz de objetos de pesquisa com propriedades:
- sid: ID da pesquisa
- surveyls_title: Título da pesquisa
- active: Se a pesquisa está ativa ("Y" ou "N")
- expires: Data de expiração (se definida)
- startdate: Data de início (se definida)
- E outros metadados da pesquisa

Exemplo de Resposta:

[
  {
    "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

Obtém propriedades detalhadas de uma pesquisa específica.

Parâmetros:

surveyId: O ID da pesquisa para obter as propriedades

Retorna:

Objeto contendo propriedades da pesquisa, incluindo configurações, definições e metadados

activateSurvey

Ativa uma pesquisa que está atualmente inativa.

Parâmetros:

surveyId: O ID da pesquisa a ser ativada

Retorna:

Resultado do processo de ativação

getSurveyLanguageProperties

Obtém propriedades específicas de idioma para uma pesquisa.

Parâmetros:

surveyId: O ID da pesquisa
language: O código do idioma

Retorna:

Objeto contendo propriedades específicas de idioma para a pesquisa

getAvailableLanguages

Obtém os idiomas disponíveis na instalação do LimeSurvey.

Parâmetros: Nenhum

Retorna:

Lista de códigos de idiomas disponíveis e seus nomes

getSurveyLanguages

Obtém os idiomas disponíveis para uma pesquisa específica.

Parâmetros:

surveyId: O ID da pesquisa

Retorna:

Matriz de códigos de idiomas disponíveis para a pesquisa

getQuotaProperties

Obtém propriedades de uma cota específica.

Esta ferramenta encapsula o método RemoteControl get_quota_properties: get_quota_properties($sessionKey, $iQuotaId, $aQuotaSettings = null, $sLanguage = null). Listar todas as cotas de uma pesquisa não é suportado por meio deste servidor MCP.

Parâmetros:

quotaId: ID específico da cota (obrigatório)
language (opcional): Idioma para descrições da cota

Retorna:

Informações da cota para o ID de cota fornecido

addQuota

Adiciona uma nova cota a uma pesquisa.

Parâmetros:

surveyId: O ID da pesquisa
name: Nome da cota
limit: Número máximo de respostas para a cota

Retorna:

Objeto de resultado do LimeSurvey contendo os dados da cota criada

setQuotaProperties

Atualiza propriedades de uma cota existente.

Parâmetros:

quotaId: O ID da cota a ser atualizada
properties: Objeto com campos da cota a serem atualizados (por exemplo, name, limit, active, action, message, url)

Retorna:

Objeto de resultado descrevendo a cota atualizada

deleteQuota

Exclui uma cota existente.

Parâmetros:

quotaId: O ID da cota a ser excluída

Retorna:

Objeto de resultado indicando se a cota foi excluída com sucesso

addSurveyLanguage

Adiciona um novo idioma a uma pesquisa. Parâmetros:

surveyId: O ID da pesquisa
language: Código do idioma a adicionar (por exemplo, "de", "fr")

Retornos:

Objeto de resultado do LimeSurvey para a adição do idioma

deleteSurveyLanguage

Exclui um idioma de uma pesquisa.

Parâmetros:

surveyId: O ID da pesquisa
language: Código do idioma a remover

Retornos:

Objeto de resultado indicando se o idioma foi excluído

setSurveyLanguageProperties

Define propriedades específicas de idioma para um idioma de pesquisa.

Parâmetros:

surveyId: O ID da pesquisa
language (opcional): Código do idioma; omita para direcionar o idioma base
localeData: Objeto com campos de localidade para atualizar (por exemplo, surveyls_title, surveyls_description, surveyls_welcometext)

Retornos:

Objeto de resultado descrevendo as propriedades de idioma atualizadas

setSurveyProperties

Define propriedades para uma pesquisa.

Esta ferramenta encapsula o método RemoteControl set_survey_properties: set_survey_properties($sessionKey, $iSurveyID, $aSurveyData). Alguns campos (por exemplo, sid, active, language, additional_languages e vários campos em pesquisas ativas) não podem ser alterados e serão ignorados pelo LimeSurvey.

Parâmetros:

surveyId: O ID da pesquisa
properties: Objeto de campos da pesquisa para atualizar

Retornos:

Objeto de resultado descrevendo quais campos foram atualizados com sucesso

Gerenciamento de Perguntas

listQuestions

Lista todas as perguntas de uma pesquisa específica.

Parâmetros:

surveyId: O ID da pesquisa
groupId (opcional): Obter apenas perguntas deste grupo
language (opcional): Idioma para os textos das perguntas

Retornos:

Matriz de objetos de pergunta com propriedades incluindo ID, texto, tipo e outras configurações

listQuestionGroups

Lista todos os grupos de perguntas de uma pesquisa específica.

Parâmetros:

surveyId: O ID da pesquisa
language (opcional): Idioma para os textos dos grupos

Retornos:

Matriz de objetos de grupo de perguntas com propriedades incluindo ID, título, descrição e ordem

addGroup

Cria um grupo de perguntas vazio em uma pesquisa. Encapsula o RemoteControl add_group e retorna o novo ID do grupo (inteiro em caso de sucesso), que você passa para importQuestion como groupId.

Parâmetros:

surveyId: ID da pesquisa
title: Título do grupo
description (opcional): Descrição do grupo; padrão é string vazia

importQuestion

Importa uma pergunta de dados codificados em base64 .lsq para um grupo. Mesma ideia do importSurvey com .lss: prepare modelos (por exemplo, exporte uma pergunta de cada tipo do LimeSurvey uma vez) e depois chame esta ferramenta repetidamente com diferentes cargas úteis.

Parâmetros:

surveyId, groupId: Pesquisa e grupo de destino
importData: Conteúdo .lsq codificado em base64
importDataType: Deve ser lsq (padrão)
mandatory: Y ou N (padrão N)
newQuestionTitle, newQuestionText, newQuestionHelp (opcional): Substituem argumentos opcionais correspondentes do RemoteControl após a importação

Retornos: Novo ID da pergunta em caso de sucesso (inteiro), ou uma estrutura de erro do LimeSurvey em caso de falha.

deleteGroup

Remove um grupo de perguntas de uma pesquisa. Encapsula o RemoteControl delete_group. Normalmente também exclui as perguntas dentro do grupo; verifique na sua instância.

Parâmetros:

surveyId, groupId: Pesquisa e grupo a remover
confirmDeletion: Deve ser true (proteção de segurança)

deleteQuestion

Remove uma pergunta pelo qid. Encapsula o RemoteControl delete_question. Tipos complexos (por exemplo, ranking) podem usar linhas adicionais em listQuestions (subperguntas); exclua ou reconstrua de acordo com o que seu ciclo de exportação/importação produziu.

Parâmetros:

questionId: ID da pergunta a excluir
confirmDeletion: Deve ser true

getQuestionProperties

Obtém propriedades de uma pergunta específica.

Parâmetros:

questionId: O ID da pergunta
language (opcional): Idioma para os textos da pergunta
properties (opcional): Matriz de nomes de propriedades a recuperar

Retornos:

Objeto contendo as propriedades solicitadas para a pergunta

setQuestionProperties

Atualiza campos graváveis em uma pergunta via RemoteControl set_question_properties. Descoberta primeiro: chame getQuestionProperties (opcionalmente com uma lista de nomes de configurações) para enviar apenas as chaves que o LimeSurvey aceita. A API bloqueia alterações em campos estruturais como qid, gid, sid, parent_qid, type e language.

Edições comuns

question: Texto do enunciado (geralmente HTML).
help: Texto de ajuda abaixo do enunciado.
Passe language ao atualizar um idioma de pesquisa que não seja o base.

Perguntas de ranking (tipo R)
Os rótulos de classificação voltados ao participante geralmente ficam nas linhas de subpergunta (parent_qid aponta para a pergunta pai). Atualize o texto question de cada subpergunta com setQuestionProperties no qid dessa linha, ou ajuste o modelo .lsq e reimporte.

Tipos de lista / lista com comentário
O prompt principal ainda é question / help na pergunta pai. Os rótulos de resposta podem ser registros de resposta separados; se o RemoteControl não expor o que você precisa, prefira editar o modelo .lsq e usar importQuestion (ou a interface administrativa) para listas de escolha, e use esta ferramenta para ajustes de redação que a API permitir.

Gerenciamento de Respostas

getResponseSummary

Obtém informações resumidas sobre as respostas coletadas de uma pesquisa.

Parâmetros:

surveyId: O ID da pesquisa

Retornos:

Objeto de resumo contendo informações sobre contagens e status das respostas

listResponseExportFormats

Lista os formatos de exportação de respostas disponíveis globalmente, incluindo tipos fornecidos por plugins.

Parâmetros:

Nenhum

Retornos:

Uma lista de objetos de formato de exportação com:
- type
- pluginClass
- label (anulável)
- tooltip (anulável)
- onclick (anulável)
- isDefault (booleano)

exportResponses

Exporta respostas de uma pesquisa no formato especificado.

Parâmetros:

surveyId: O ID da pesquisa
documentType: Tipo de formato de exportação (dinâmico/ciente de plugins). Chame listResponseExportFormats primeiro - padrão: "csv"
language (opcional): Idioma para a exportação de respostas
completionStatus: Filtrar por status de conclusão ('complete', 'incomplete', 'all') - padrão: "all"
headingType: Tipo de cabeçalhos ('code', 'full', 'abbreviated') - padrão: "code"
responseType: Tipo de resposta ('short' ou 'long') - padrão: "short"
fields (opcional): Matriz de nomes de campos para exportar

Retornos:

Um resumo de sucesso mais a carga útil bruta da exportação
Para formatos de texto com decodeOutput: true, também inclui uma prévia decodificada

Fluxo de trabalho de exportação com descoberta primeiro

Chame listResponseExportFormats para descobrir valores válidos de type expostos pela instância atual do LimeSurvey.
Escolha um type retornado (por exemplo, csv, json ou um formato de plugin personalizado).
Chame exportResponses com esse documentType.

Exemplo:

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

listResponses

Lista IDs de respostas de uma pesquisa específica.

Parâmetros:

surveyId: O ID da pesquisa
start: Índice inicial da resposta - padrão: 0
limit: Número de respostas a retornar - padrão: 10
attributes (opcional): Matriz de nomes de atributos a incluir

Retornos:

Matriz de IDs de respostas e atributos solicitados

Gerenciamento de Participantes

addParticipant

Adiciona um participante a uma pesquisa.

Parâmetros:

surveyId: O ID da pesquisa
email: Endereço de e-mail do participante
firstName (opcional): Primeiro nome
lastName (opcional): Sobrenome
language (opcional): Código do idioma
usesLeft: Número de vezes que o participante pode acessar a pesquisa - padrão: 1
validFrom (opcional): Data de validade inicial (AAAA-MM-DD HH:mm:ss)
validUntil (opcional): Data de validade final (AAAA-MM-DD HH:mm:ss)

Retornos:

Dados do participante incluindo o token gerado

listParticipants

Lista participantes de uma pesquisa específica.

Parâmetros:

surveyId: O ID da pesquisa
start: Índice inicial do participante - padrão: 0
limit: Número de participantes a retornar - padrão: 10
unused: Mostrar apenas tokens não utilizados - padrão: false
attributes (opcional): Matriz de nomes de atributos a incluir

Retornos:

Matriz de objetos de participante com os atributos solicitados

getParticipantProperties

Obtém propriedades de um participante/token específico.

Parâmetros:

surveyId: O ID da pesquisa
tokenId: O ID do token
attributes (opcional): Matriz de nomes de atributos a incluir

Retornos:

Objeto contendo propriedades para o participante especificado

Gerenciamento de Estatísticas

exportStatistics

Exporta estatísticas da pesquisa em formato PDF, Excel ou HTML com gráficos opcionais.

Parâmetros:

surveyId: O ID da pesquisa para exportar estatísticas
documentType: Formato da exportação: 'pdf', 'xls' ou 'html' - padrão: "pdf"
language (opcional): Idioma para a exportação de estatísticas (padrão: idioma padrão da pesquisa)
includeGraphs: Se deve incluir gráficos na exportação (aplicável apenas para PDF) - padrão: false
groupIds (opcional): ID(s) específico(s) de grupo de perguntas a incluir nas estatísticas; pode ser um único ID ou uma matriz de IDs

Retornos:

String codificada em base64 contendo o arquivo de estatísticas no formato solicitado

Exemplo de Uso:

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

Desenvolvimento

Este projeto é construído usando:

Node.js
@modelcontextprotocol/sdk - SDK do servidor MCP
TypeScript - Para segurança de tipos e recursos modernos de JavaScript
dotenv - Para gerenciamento de variáveis de ambiente
Axios - Para requisições HTTP à API Remota do LimeSurvey

Compilação

npm run build

Modo de Desenvolvimento

npm run dev

Licença

MIT