survey-mcp-server

---

🛠️ 工具概览

此服务提供八种强大的工具，通过大模型驱动的交互管理完整的调查生命周期：

工具名称	描述
survey_list_available	在定义目录中查找可用的调查。
survey_start_session	初始化新会话，其中包含完整的调查上下文、所有问题和初始建议问题。
survey_get_question	状态变更后刷新特定问题的符合条件状态（适用于条件逻辑）。
survey_submit_response	记录参与者答案并进行验证和评分，同时返回更新后的进度和下一批建议问题。
survey_get_progress	检查完成状态、当前得分、剩余的必答／选答问题以及是否符合完成条件。
survey_complete_session	完成会话并生成最终得分摘要（需要回答所有必答问题）。
survey_export_results	以 CSV 或 JSON 格式导出会话数据，可按状态、日期范围等进行筛选。
survey_resume_session	恢复未完成的会话，还原包括已回答问题和进度在内的完整上下文。

survey_list_available

查找可用的调查，这些调查从你的调查定义目录加载。

主要功能：

• 通过递归扫描 SURVEY_DEFINITIONS_PATH 列出发现的所有调查
• 返回调查元数据：ID、标题、描述、预计时长和问题数量
• 支持为多租户部署按租户筛选

示例用例：

• “显示所有可用的调查”
• “参与者可以参加哪些调查？”
• “列出租户 X 的调查”

---

survey_start_session

初始化一个新的调查会话，为由大模型驱动的对话提供完整上下文。

主要功能：

• 创建新会话，生成唯一会话 ID 并跟踪参与者
• 预先加载包含所有问题的完整调查定义
• 根据调查设置返回初始建议问题（最小值和最大值可配置，默认为 3-5 个），并依据可回答条件排序（先显示无条件问题，再显示必答问题，然后是选答问题）
• 每个问题都包含 currentlyEligible 标记和 eligibilityReason，确保信息透明
• 提供 guidanceForLLM 字段，包含对话指引
• 支持会话元数据，用于跟踪来源、用户代理等信息

示例用例：

• “为参与者 ABC123 开始客户满意度调查”
• “为 Q1 反馈调查开始一个新会话”
• “使用元数据初始化调查会话：source=web，userAgent=Claude”

---

survey_get_question

刷新问题的可回答条件及会话状态变更后的详细信息。

主要功能：

• 根据最新会话状态返回当前可回答状态
• 提供可回答原因（例如，“条件逻辑已满足”“始终可用”）
• 指明问题是否已回答
• 适用于检查回答先前问题后，条件问题是否变为可回答

示例用例：

• “问题 q2 现在可以回答了吗？”
• “检查后续问题现在是否可以回答”
• “参与者回答依赖问题后刷新问题详情”

---

survey_submit_response

记录参与者的回答，并进行验证、提供动态回答指引。

主要功能：

• 根据问题约束验证回答（最小/最大长度、模式、必填字段等）
• 计算并返回回答得分（如果问题选项启用了评分）
• 返回验证错误，并提供具体且可执行的反馈
• 更新会话进度（完成百分比、已回答问题数、预计剩余时间、当前得分）
• 返回 updatedEligibility 数组，显示新变为可回答的条件问题
• 根据新状态返回更新后的 nextSuggestedQuestions（数量可按调查配置）
• 提供包含上下文相关指令的 guidanceForLLM

示例用例：

• “为问题 q1 提交回答 ‘very-satisfied’”
• “记录参与者的电子邮件：[email protected]”
• “保存自由文本回答并进行验证”

---

survey_get_progress

检查会话状态和是否符合完成条件。

主要功能：

• 返回完成状态：in-progress、completed、abandoned
• 进度指标：问题总数、已回答数量、剩余必答问题数、完成百分比、当前得分
• 列出所有未回答的必答问题（包含可回答状态）
• 列出所有未回答的选答问题（包含可回答状态）
• canComplete 布尔值，指示会话是否可以完成
• completionBlockers 数组，说明阻止完成的原因

示例用例：

• “调查完成了多少？”
• “还有哪些必答问题未回答？”
• “现在可以完成调查了吗？”

---

survey_complete_session

在所有必答问题均已回答后，完成调查会话。

主要功能：

• 验证所有必答问题（包括有条件限制的必答问题）是否均已回答
• 将会话状态更新为 completed，并设置 completedAt 时间戳
• 返回摘要，其中包含已回答问题总数、会话时长和最终得分（如果启用了评分）
• 防止重复完成

示例用例：

• “完成调查会话”
• “结束会话 sess_abc123”
• “将调查标记为已完成”

---

survey_export_results

导出会话数据，用于分析和报告。

主要功能：

• 导出为 CSV 或 JSON 格式
• 按调查 ID、状态、日期范围和自定义条件筛选
• 返回格式化的数据，并包含记录数和生成时间戳
• CSV 格式每个会话占一行，问题回答已扁平化
• JSON 格式保留完整的会话结构

示例用例：

• “将调查 customer-satisfaction-q1-2025 中所有已完成的回答导出为 CSV”
• “获取 2025 年 1 月已完成会话的 JSON 导出”
• “导出进行中的会话以供分析”

---

survey_resume_session

恢复未完成的会话，并完整还原上下文。

主要功能：

• 还原完整的调查上下文和会话状态
• 返回所有已回答的问题及其回答
• 为剩余问题提供更新后的 nextSuggestedQuestions（每项调查可配置数量）
• 显示距离上次活动的时长
• 当前进度摘要（百分比、剩余问题数、当前得分）
• 提供 guidanceForLLM，其中包含欢迎用户回来的措辞建议

示例用例：

• “恢复会话 sess_abc123”
• “继续参与者上次中断的调查”
• “还原会话状态，让参与者稍后完成”

✨ 功能

此服务基于 mcp-ts-template 构建，并继承了其丰富的功能集：

• 声明式工具：在单个独立文件中定义功能。框架负责注册、验证和执行。
• 稳健的错误处理：统一的 McpError 系统确保错误响应保持一致且结构化。
• 可插拔的身份验证：轻松支持 none、jwt 或 oauth 模式，保护你的服务。
• 抽象化存储：可切换存储后端（in-memory、filesystem、Supabase、Cloudflare KV/R2），无需更改业务逻辑。
• 全栈可观测性：通过结构化日志记录（Pino）深入了解运行情况，并可选择启用自动插桩的 OpenTelemetry，以获取跟踪和指标。
• 依赖注入：基于 tsyringe 构建，实现简洁、解耦且易于测试的架构。
• 适用于边缘环境：一次编写代码，即可在本地设备或 Cloudflare Workers 边缘环境中无缝运行。

此外，还提供专为调查管理打造的功能：

• 由大模型驱动的调查：工具提供丰富的上下文（进度、建议的下一步问题、验证结果、得分），引导自然流畅的对话。
• 混合流程控制：引导模式可配置建议的问题数量（默认为 3-5 个），并根据对话上下文灵活调整顺序。
• 评分系统：支持测验和评估，问题选项可包含可选的得分字段。自动计算得分并在每个会话中累计。
• 高级条件逻辑：支持简单的跳题逻辑，以及通过 AND/OR 多条件分支实现复杂逻辑，并跟踪资格状态。
• 基于 JSON 的调查定义：通过简单的 JSON 文件定义调查，并递归扫描目录。
• 多种问题类型：free-form、multiple-choice、multiple-select、rating-scale、email、number、boolean，以及 date、datetime、time 和 matrix 网格等高级类型。
• 验证引擎：支持最小/最大长度、模式、必填字段、自定义约束以及日期/时间规则，并采用可扩展的验证器映射模式。
• 会话恢复：内置状态管理功能，允许参与者暂停会话并稍后继续。
• 帮助文本：问题中的 helpText 字段为大模型提供上下文和指导，帮助其自然地提出问题。
• 分页支持：通过为会话查询和导出配置分页，实现可扩展的数据检索。

🚀 入门

MCP 客户端设置/配置

将以下内容添加到 MCP 客户端配置文件中（例如 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"
      }
    }
  }
}

前置条件

• Bun v1.2.0 或更高版本。

安装

1. 克隆仓库：

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

2. 进入目录：

cd survey-mcp-server

3. 安装依赖：

bun install

4. 查看示例调查问卷： survey-definitions/ 目录包含示例 JSON 文件，展示了各种问题类型和功能。你可以将这些文件作为起点来创建自己的调查问卷。

🛠️ 核心功能：调查工具

此服务为 AI Agent 提供专用工具，用于开展动态对话式调查，同时保持结构化数据收集。

交互流程示例

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

📖 查看详细规范和示例 →

⚙️ 配置

所有配置都集中在 src/config/index.ts 中，并会在启动时进行验证。.env 文件中的关键环境变量包括：

Variable	Description	Default
SURVEY_DEFINITIONS_PATH	存放调查问卷 JSON 文件的目录路径（递归扫描）。	./survey-definitions
SURVEY_RESPONSES_PATH	存放会话回复的目录路径（文件系统模式）。	./survey-responses
MCP_TRANSPORT_TYPE	要使用的传输方式：stdio 或 http。	http
MCP_HTTP_PORT	HTTP 服务的端口。	3019
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv、r2。	in-memory
OTEL_ENABLED	设置为 true 以启用 OpenTelemetry。	false
LOG_LEVEL	日志记录的最低级别（debug、info、warn、error）。	info
MCP_AUTH_SECRET_KEY	jwt 身份验证必需。 长度至少为 32 个字符的密钥。	(none)
OAUTH_ISSUER_URL	oauth 身份验证必需。 OIDC 提供商的 URL。	(none)

▶️ 运行服务

本地开发

• 构建并运行生产版本：

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

• 运行检查和测试：

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

Cloudflare Workers

1. 构建 Worker 包：

bun build:worker

2. 使用 Wrangler 在本地运行：

bun deploy:dev

3. 部署到 Cloudflare：

   bun deploy:prod
   

📂 项目结构

目录	用途与内容
survey-definitions/	调查定义（JSON 文件）。支持使用嵌套目录进行组织。
survey-responses/	会话响应（使用 filesystem provider 时）。按租户 ID 组织。
src/mcp-server/tools	调查工具定义（survey-*.tool.ts）。提供覆盖完整生命周期的 8 个工具。
src/mcp-server/resources	调查元数据和发现功能的资源定义。
src/services/survey/	调查服务，使用 filesystem provider 加载定义。
src/mcp-server/transports	HTTP 和 STDIO 传输的实现，包括身份验证中间件。
src/storage	StorageService 抽象及所有存储 provider 的实现。
src/container	依赖注入容器的注册项和令牌。
src/utils	日志记录、错误处理、性能和安全方面的核心实用工具。
src/config	使用 Zod 解析和验证环境变量。
tests/	单元测试和集成测试，目录结构与 src/ 对应。
docs/	详细的规范和指南（参见 survey-mcp-server-spec.md）。

🧑‍💻 Agent 开发指南

使用 AI Agent 搭配此服务时的严格规则，请参阅此仓库中的 .clinerules 文件（或 AGENTS.md）。核心原则包括：

• 逻辑抛出错误，处理器捕获错误：切勿在工具的 logic 中使用 try/catch。应改为抛出 McpError。
• 传递上下文：始终在调用链中传递 RequestContext 对象，以便进行日志记录和跟踪。
• 使用 Barrel 导出：仅在各自 definitions 目录中的 index.ts barrel 文件内注册新工具和资源。

🤝 贡献

欢迎提交问题和拉取请求！如果计划贡献，请在提交 PR 前运行本地检查和测试。

bun run devcheck
bun test

📜 许可证

本项目采用 Apache 2.0 License 许可。详情请参阅 LICENSE 文件。