survey-mcp-server

---

🛠️ Visão Geral das Ferramentas

Este servidor fornece oito ferramentas poderosas para gerenciar o ciclo de vida completo da pesquisa com interações orientadas por LLM:

Nome da Ferramenta	Descrição
survey_list_available	Descubra pesquisas disponíveis no diretório de definições.
survey_start_session	Inicialize uma nova sessão com contexto completo da pesquisa, todas as perguntas e perguntas sugeridas iniciais.
survey_get_question	Atualize o status de elegibilidade de uma pergunta específica após mudanças de estado (útil para lógica condicional).
survey_submit_response	Registre respostas dos participantes com validação, pontuação, retornando progresso atualizado e próximas perguntas sugeridas.
survey_get_progress	Verifique o status de conclusão, pontuação atual, perguntas obrigatórias/opcionais restantes e elegibilidade para conclusão.
survey_complete_session	Finalize uma sessão concluída com resumo final da pontuação (exige que todas as perguntas obrigatórias sejam respondidas).
survey_export_results	Exporte dados da sessão em formato CSV ou JSON com filtragem opcional por status, intervalo de datas, etc.
survey_resume_session	Retome uma sessão incompleta, restaurando o contexto completo, incluindo perguntas respondidas e progresso.

survey_list_available

Descubra pesquisas disponíveis carregadas do seu diretório de definições de pesquisas.

Principais Recursos:

• Lista todas as pesquisas descobertas por meio de varredura recursiva de diretório de SURVEY_DEFINITIONS_PATH
• Retorna metadados da pesquisa: ID, título, descrição, duração estimada e contagem de perguntas
• Filtragem opcional por tenant para implantações multi-tenant

Exemplos de Casos de Uso:

• "Mostre-me todas as pesquisas disponíveis"
• "Quais pesquisas os participantes podem responder?"
• "Liste pesquisas para o tenant X"

---

survey_start_session

Inicialize uma nova sessão de pesquisa com contexto completo para conversas orientadas por LLM.

Principais Recursos:

• Cria nova sessão com ID de sessão único e rastreamento de participante
• Carrega a definição completa da pesquisa com todas as perguntas antecipadamente
• Retorna perguntas sugeridas iniciais com base nas configurações da pesquisa (mín/máx configuráveis, padrão de 3-5) com base na elegibilidade (perguntas incondicionais primeiro, obrigatórias antes de opcionais)
• Cada pergunta inclui o sinalizador currentlyEligible e eligibilityReason para transparência
• Fornece o campo guidanceForLLM com instruções conversacionais
• Suporta metadados de sessão para rastreamento de origem, user agent, etc.

Exemplos de Casos de Uso:

• "Inicie a pesquisa de satisfação do cliente para o participante ABC123"
• "Comece uma nova sessão para a pesquisa de feedback do Q1"
• "Inicialize a sessão da pesquisa com metadados: source=web, userAgent=Claude"

---

survey_get_question

Atualize a elegibilidade de uma pergunta e detalhes após mudanças no estado da sessão.

Principais Recursos:

• Retorna o status de elegibilidade atual com base no estado mais recente da sessão
• Fornece o motivo da elegibilidade (ex.: "Lógica condicional satisfeita", "Sempre disponível")
• Indica se a pergunta já foi respondida
• Útil para verificar se perguntas condicionais ficaram disponíveis após respostas anteriores

Exemplos de Casos de Uso:

• "A pergunta q2 já ficou disponível?"
• "Verifique se a pergunta de acompanhamento agora é elegível"
• "Atualize os detalhes da pergunta após o participante responder a dependência"

---

survey_submit_response

Registre respostas dos participantes com validação e obtenha orientação dinâmica de resposta.

Principais Recursos:

• Valida respostas contra restrições da pergunta (comprimento mín/máx, padrões, campos obrigatórios, etc.)
• Calcula e retorna pontuação para a resposta (se a pontuação estiver habilitada nas opções da pergunta)
• Retorna erros de validação com feedback específico e acionável
• Atualiza o progresso da sessão (percentual concluído, perguntas respondidas, estimativa de tempo restante, pontuação atual)
• Retorna o array updatedEligibility mostrando perguntas condicionais recém-disponíveis
• Fornece nextSuggestedQuestions atualizado com base no novo estado (contagem configurável por pesquisa)
• Inclui guidanceForLLM com instruções sensíveis ao contexto

Exemplos de Casos de Uso:

• "Envie a resposta 'muito-satisfeito' para a pergunta q1"
• "Registre o e-mail do participante: user@example.com"
• "Salve resposta de formato livre com validação"

---

survey_get_progress

Verifique o status da sessão e a elegibilidade para conclusão.

Principais Recursos:

• Retorna o status de conclusão: in-progress, completed, abandoned
• Métricas de progresso: total de perguntas, contagem respondida, obrigatórias restantes, percentual concluído, pontuação atual
• Lista todas as perguntas obrigatórias não respondidas (com status de elegibilidade)
• Lista todas as perguntas opcionais não respondidas (com status de elegibilidade)
• Booleano canComplete indicando se a sessão pode ser finalizada
• Array completionBlockers explicando o que está impedindo a conclusão

Exemplos de Casos de Uso:

• "Quanto da pesquisa está concluído?"
• "Quais perguntas obrigatórias ainda não foram respondidas?"
• "Podemos concluir a pesquisa agora?"

---

survey_complete_session

Finalize uma sessão concluída quando todas as perguntas obrigatórias tiverem sido respondidas.

Principais Recursos:

• Valida que todas as perguntas obrigatórias (incluindo condicionalmente obrigatórias) foram respondidas
• Atualiza o status da sessão para completed e define o timestamp completedAt
• Retorna resumo com total de perguntas respondidas, duração da sessão e pontuação final (se a pontuação estiver habilitada)
• Evita conclusão duplicada

Exemplos de Casos de Uso:

• "Conclua a sessão da pesquisa"
• "Finalize a sessão sess_abc123"
• "Marque a pesquisa como finalizada"

---

survey_export_results

Exporte dados da sessão para análise e relatórios.

Principais Recursos:

• Exportação em formato CSV ou JSON
• Filtre por ID da pesquisa, status, intervalo de datas e critérios personalizados
• Retorna dados formatados com contagem de registros e timestamp de geração
• Formato CSV inclui uma linha por sessão com respostas achatadas das perguntas
• Formato JSON preserva a estrutura completa da sessão

Exemplos de Casos de Uso:

• "Exporte todas as respostas concluídas para a pesquisa customer-satisfaction-q1-2025 como CSV"
• "Obtenha exportação JSON das sessões concluídas em janeiro de 2025"
• "Exporte sessões em andamento para análise"

---

survey_resume_session

Retome uma sessão incompleta com restauração completa do contexto.

Principais Recursos:

• Restaura o contexto completo da pesquisa e o estado da sessão
• Retorna todas as perguntas respondidas anteriormente com respostas
• Fornece nextSuggestedQuestions atualizado para as perguntas restantes (contagem configurável por pesquisa)
• Mostra o tempo decorrido desde a última atividade
• Resumo do progresso atual (percentual, perguntas restantes, pontuação atual)
• Inclui guidanceForLLM com sugestões de mensagens de boas-vindas de retorno

Exemplos de Casos de Uso:

• "Retome a sessão sess_abc123"
• "Continue a pesquisa de onde o participante parou"
• "Restaure o estado da sessão para o participante finalizar depois"

✨ Recursos

Este servidor é construído sobre o mcp-ts-template e herda seu rico conjunto de recursos:

• Ferramentas Declarativas: Defina capacidades em arquivos únicos e autocontidos. O framework gerencia registro, validação e execução.
• Tratamento Robusto de Erros: Um sistema unificado McpError garante respostas de erro consistentes e estruturadas.
• Autenticação Plugável: Proteja seu servidor com suporte sem complicações para modos none, jwt ou oauth.
• Armazenamento Abstraído: Troque backends de armazenamento (in-memory, filesystem, Supabase, Cloudflare KV/R2) sem alterar a lógica de negócios.
• Observabilidade Full-Stack: Insights profundos com logging estruturado (Pino) e OpenTelemetry opcional com instrumentação automática para traces e métricas.
• Injeção de Dependência: Construído com tsyringe para uma arquitetura limpa, desacoplada e testável.
• Pronto para Edge: Escreva código uma vez e execute-o perfeitamente na sua máquina local ou na edge com Cloudflare Workers.

Além disso, recursos especializados para Gerenciamento de Pesquisas:

• Pesquisas Orientadas por LLM: As ferramentas fornecem contexto rico (progresso, próximas perguntas sugeridas, resultados de validação, pontuações) para guiar o fluxo natural da conversa.
• Controle de Fluxo Híbrido: Modo guiado com perguntas sugeridas configuráveis (padrão de 3-5) + ordenação flexível com base no contexto da conversa.
• Sistema de Pontuação: Suporte para quizzes e avaliações com campos de pontuação opcionais nas opções das perguntas. Cálculo automático de pontuação e acumulação por sessão.
• Lógica Condicional Avançada: Suporte para lógica de desvio simples e ramificação complexa de múltiplas condições AND/OR com rastreamento de elegibilidade.
• Definições de Pesquisa Baseadas em JSON: Defina pesquisas em arquivos JSON simples com varredura recursiva de diretório.
• Múltiplos Tipos de Pergunta: free-form, multiple-choice, multiple-select, rating-scale, email, number, boolean e tipos avançados como grades date, datetime, time e matrix.
• Mecanismo de Validação: Comprimento mín/máx, padrões, campos obrigatórios, restrições personalizadas e regras de data/hora com padrão de mapa de validadores extensível.
• Retomada de Sessão: Gerenciamento de estado integrado permite que participantes pausem e continuem depois.
• Texto de Ajuda: Um campo helpText nas perguntas fornece aos LLMs contexto e orientação para fazer perguntas naturalmente.
• Suporte a Paginação: Recuperação escalável de dados com paginação configurável para consultas e exportações de sessão.

🚀 Começando

Configurações do Cliente MCP

Adicione o seguinte ao seu arquivo de configuração do Cliente MCP (ex.: 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"
      }
    }
  }
}

Pré-requisitos

• Bun v1.2.0 ou superior.

Instalação

1. Clone o repositório:

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

2. Navegue até o diretório:

cd survey-mcp-server

3. Instale as dependências:

bun install

4. Explore as pesquisas de exemplo: O diretório survey-definitions/ contém arquivos JSON de exemplo demonstrando vários tipos de perguntas e recursos. Use-os como ponto de partida para criar suas próprias pesquisas.

🛠️ Capacidades Principais: Ferramentas de Pesquisa

Este servidor equipa agentes de IA com ferramentas especializadas para conduzir pesquisas dinâmicas e conversacionais, mantendo a coleta estruturada de dados.

Fluxo de Interação de Exemplo

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

📖 Veja a especificação detalhada e exemplos →

⚙️ Configuração

Toda a configuração é centralizada e validada na inicialização em src/config/index.ts. As principais variáveis de ambiente no seu arquivo .env incluem:

Variável	Descrição	Padrão
SURVEY_DEFINITIONS_PATH	Caminho para o diretório contendo os arquivos JSON de pesquisa (varredura recursiva).	./survey-definitions
SURVEY_RESPONSES_PATH	Caminho para o diretório de armazenamento das respostas das sessões (modo sistema de arquivos).	./survey-responses
MCP_TRANSPORT_TYPE	O transporte a ser usado: stdio ou http.	http
MCP_HTTP_PORT	A porta para o servidor HTTP.	3019
MCP_AUTH_MODE	Modo de autenticação: none, jwt ou oauth.	none
STORAGE_PROVIDER_TYPE	Backend de armazenamento: in-memory, filesystem, supabase, cloudflare-kv, r2.	in-memory
OTEL_ENABLED	Defina como true para habilitar o OpenTelemetry.	false
LOG_LEVEL	O nível mínimo para registro de logs (debug, info, warn, error).	info
MCP_AUTH_SECRET_KEY	Obrigatório para autenticação jwt. Uma chave secreta com 32+ caracteres.	(none)
OAUTH_ISSUER_URL	Obrigatório para autenticação oauth. URL do provedor OIDC.	(none)

▶️ Executando o Servidor

Desenvolvimento Local

• Compile e execute a versão de produção:

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

• Execute verificações e testes:

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

Cloudflare Workers

1. Compile o bundle do Worker:

bun build:worker

2. Execute localmente com Wrangler:

bun deploy:dev

3. Implante no Cloudflare:

   bun deploy:prod
   

📂 Estrutura do Projeto

Diretório	Propósito e Conteúdo
survey-definitions/	Definições de pesquisa (arquivos JSON). Diretórios aninhados suportados para organização.
survey-responses/	Respostas de sessão (ao usar o provedor filesystem). Organizadas por ID de locatário.
src/mcp-server/tools	Definições de ferramentas de pesquisa (survey-*.tool.ts). 8 ferramentas para ciclo de vida completo.
src/mcp-server/resources	Definições de recursos para metadados e descoberta de pesquisas.
src/services/survey/	Serviço de pesquisa com provedor de sistema de arquivos para carregar definições.
src/mcp-server/transports	Implementações para transportes HTTP e STDIO, incluindo middleware de autenticação.
src/storage	Abstração de StorageService e todas as implementações de provedores de armazenamento.
src/container	Registros de contêiner de injeção de dependência e tokens.
src/utils	Utilitários principais para registro de logs, tratamento de erros, desempenho e segurança.
src/config	Análise e validação de variáveis de ambiente com Zod.
tests/	Testes unitários e de integração, espelhando a estrutura do diretório src/.
docs/	Especificações detalhadas e guias (veja survey-mcp-server-spec.md).

🧑‍💻 Guia de Desenvolvimento para Agentes

Para regras estritas ao usar este servidor com um agente de IA, consulte o arquivo .clinerules (ou AGENTS.md) neste repositório. Os princípios-chave incluem:

• Lógica Lança, Handlers Capturam: Nunca use try/catch em seu logic de ferramenta. Lance um McpError em vez disso.
• Passe o Contexto: Sempre passe o objeto RequestContext pela sua pilha de chamadas para registro de logs e rastreamento.
• Use as Exportações Barrel: Registre novas ferramentas e recursos apenas nos arquivos barrel index.ts dentro de seus respectivos diretórios definitions.

🤝 Contribuindo

Issues e pull requests são bem-vindos! Se você planeja contribuir, execute as verificações e testes locais antes de enviar seu PR.

bun run devcheck
bun test

📜 Licença

Este projeto está licenciado sob a Licença Apache 2.0. Consulte o arquivo LICENSE para obter detalhes.