问卷编程服务器

Qualtrics MCP服务器

用于端到端Qualtrics问卷编程和操作的MCP服务器。它的112个工具允许任何MCP客户端构建复杂的调查、编辑嵌套流逻辑、管理选项、配额、翻译、版本、联系人、发行版、库、Webhook和响应，而无需导入此存储库的TypeScript服务。

该服务器在14个API区域中拥有110个Qualtrics操作工具，外加2个服务器权限控件。它提供了一个全面的监视-编程表面和一个有保护的JSON API v3逃生口；它并没有声称每个获得许可的Qualtrics企业产品都有一个专用的包装器。

工具覆盖范围

看 docs/API_COVERAGE.md文件 用于精确的工具清单、范围映射和边界。

仅通过MCP进行复杂问卷调查

该工具集支持完整的构造循环：

1. 创建或复制草图测量并检索其默认块。
2. 创建有意义的块和常见问题类型 DataExportTag 值、重新编码、验证、HTML和可选 QuestionJS.
3. 使用原始问题有效载荷或克隆 get_question_template 输出专门的Qualtrics问题类型。
4. 构建嵌套的分支、组、随机化器、嵌入式数据声明和分配、块引用和web服务调用。增量流工具分配无冲突 FlowID 值和归一化 Properties.Count.
5. 安全地修补调查选项，配置配额和翻译，然后运行 validate_survey_design 在创建版本或激活调查之前。

参考实施 示例/动机推理研究 在stdio上为每个操作使用MCP客户端。它创建了一个多块随机实验，其中包含显式导出标签、嵌入式数据、管道文本、预/后测量、选项、验证和草案版本。它故意不激活调查。

从存储库签出，仅当您想在配置的Qualtrics帐户中创建草稿时才运行它。该脚本在进行MCP调用之前构建并启动打包的服务器入口点：

pnpm example:motivated-reasoning

值得注意的工具

调查结构和逻辑

• create_question 和 update_question 公开完整的问题定义字段，同时在部分更新期间保留现有字段。
• add_multiple_choice_question, add_text_entry_question, add_descriptive_text_question, add_likert_question, add_matrix_question, add_rank_order_question，以及 add_constant_sum_question 提供经过验证的通用路径。
• get_question_template 返回一个经过净化的定义，用于克隆并排、滑块或热图等特殊类型。
• insert_flow_element, update_flow_element, move_flow_element，以及 delete_flow_element 编辑顶级流节点和嵌套流节点，而无需重建无关的分支。
• add_embedded_data 和 add_web_service 支持在流中的精确放置； piped_text_reference 返回相应的Qualtrics语法。
• validate_survey_design 检查重复或缺失 FlowID 值， Properties.Count、块和问题引用、无法访问的块以及缺少或重复的导出标记。

调查设置和可重复使用的设计

• update_survey_options 默认情况下，递归地将补丁与当前选项合并，因此省略的嵌套设置将继续存在。集 replace=true 仅用于有意的完全替换。
• 调查版本、启用的语言和翻译都有专门的读/写工具；默认情况下，语言映射和翻译更新会安全地合并。
• 配额和配额组有完整的专用CRUD工具。
• 图书馆工具列出了可重复使用的调查块、问题和调查；管理多语言消息；上传或删除JPEG、GIF和PNG图形。
• copy_survey 保留了复杂的问题类型、评分、样式、流程和其他没有单独公共突变端点的设置。
• import_survey_qsf, import_survey_text，以及 import_survey_docx 使用官方的多部分导入路径； import_survey_from_url 允许Qualtrics获取公共HTTPS QSF、TXT或DOCX文件。

联系人和响应数据

• 所有联系工具都使用当前的XM Directory API，并且需要许可的目录ID(directoryId，通常 POOL_...).使用 list_directories 如果您还不知道可用的目录ID，请查找。
• 邮件列表页面最多接受100个结果，联系人页面最多接受50个。继续返回 nextSkipToken; includeCount 是近似的，在大列表上可能会更慢。
• remove_contact 仅从所选邮件列表中删除成员资格；它不会从目录中删除该人。Qualtrics不支持 get_mailing_list 或 delete_mailing_list 在共享邮件列表中。
• 联系人身份规则因目录配置而异；创建工具接受电子邮件、名字/姓氏，或 externalDataReference 让Qualtrics应用该品牌的精确匹配要求。
• bulk_import_contacts 是一个有界的、顺序的、非原子的辅助程序，并报告每个输入失败。它并没有掩盖部分成功。
• get_distribution_history 返回每个收件人的传递状态（已发送、已打开、已退回、已响应） contactLookupId 它将来自单个链接分布的响应与联系人联系起来。
• 响应下载缓冲区只有小结果；大型物体流到下载中的碰撞安全文件。缓慢而健康的转移可能会超过 REQUEST_TIMEOUT 总的来说，因为下载超时是应用于标头和每个非活动读取的，而不是总持续时间。

高级JSON API访问

使用 qualtrics_api_request 当授权的Qualtrics API v3 JSON端点缺少专用工具时。请求仍固定在配置的Qualtrics源：

• GET 以只读模式工作。
• POST, PUT，以及 PATCH 接受JSON正文。
• DELETE 需要 confirmDelete: true.
• 已知路由仍然需要其正常的最小特权范围；只有在其他情况下未映射的写入才会使用高风险 advanced 范围。
• 路径不能包含其他原点、查询文本、片段、反斜杠、遍历、空格、重复/尾随斜杠或百分比编码段。查询参数是单独编码的。

更喜欢可用的专用工具，因为它们可以验证有效载荷，保留完整的替换资源，并添加安全检查。逃生舱故意以JSON为中心；使用专用的调查导入工具进行多部分上传，使用响应导出工具进行下载。

安全和写入范围

安全默认值为只读。除非 QUALTRICS_READ_ONLY=false 已设置，启动时未启用写作用域。大多数读取操作（包括启动响应导出）仍然可用。 list_distribution_links 是例外：Qualtrics记录了这种药物的副作用 GET，因此服务器需要 distributions 范围。

使用 set_write_scopes 仅启用任务所需的类别：

set_read_only_mode 仍然是一个方便的开关。将其设置为 false 启用每个范围；范围权限授予对于正常使用更安全。删除工具还需要在适当的情况下进行明确确认。

设置

需求

• Node.js 22或更高版本
• 具有您使用的终结点所需权限的Qualtrics API令牌
• 您的Qualtrics数据中心ID

pnpm install
cp .env.example .env
# Fill in the two required Qualtrics values, then:
pnpm start

配置

根据安装指南，启动时缺少令牌或数据中心配置失败。永远不要承诺代币； .env 和 .mcp.json 被忽视是因为它们可能包含秘密。

MCP客户端配置

构建一次，然后将任何支持stdio的MCP客户端指向编译的入口点：

pnpm build

{
  "mcpServers": {
    "qualtrics": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/absolute/path/to/qualtrics_mcp/build/index.js"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
        "QUALTRICS_API_TOKEN": "your_api_token",
        "QUALTRICS_DATA_CENTER": "your_data_center_id"
      }
    }
  }
}

使用绝对路径 which node 在您的机器上打印为 command （如上所示：Homebrew在Apple Silicon上；Intel Homebrew安装到 /usr/local/bin/node，nvm安装在 ~/.nvm/versions/node/.../bin/node).

macOS故障排除：服务器从未出现，UI中没有错误

GUI启动的MCP客户端，如克劳德桌面生成服务器，具有最小的 PATH 这不包括Homebrew和nvm目录，由此产生的故障是无声的。两层断裂：

1. 光秃秃的 "command" 的 node 或 npx 根本找不到。
2. 即使有绝对 npx/tsx 路径，脚本的 #!/usr/bin/env node 谢邦仍然无法解决 node (env: node: No such file or directory).

上面的配置修复了这两个问题：绝对 command path处理第一层 PATH 报关进口 env 处理shebang分辨率。您可以通过管道在客户端外重现故障 initialize JSON-RPC请求已配置的命令 PATH.

Qualtrics设计惯例

• 设定一个明确、稳定的 DataExportTag 关于每一个数据收集问题。创建工具在省略时会产生可读的回退，但明确的研究特定名称会使导出和前后测量保持明确。
• 对于Matrix问题， Choices 是行/语句和 Answers 是列/刻度点。 add_matrix_question 提供Qualtrics样板并验证选择器/子选择器对。语句对象 textEntry: true 在单独的行中添加一个内联文本框（例如，“其他（请指定）”）。
• 在TypeScript模板文本中，将Qualtrics管道文本中的美元符号转义为 \${...} 当它在运行时必须保持字面意义时。
• 每个原始流量元件都需要一个独特的 FlowID; Properties.Count 必须等于最高的数字ID。增量流工具会自动管理这两个值。
• 在流的开头附近声明嵌入式数据字段，然后在生成它们的问题或web服务之后分配它们的值。
• 在“新测量体验”（以前为“简单布局”）中，使用拖放(DND)用于排名顺序和选择/文本输入(VRTL)对于恒和。排名顺序选择/文本框和恒和条/滑块变体需要传统的体验。

发展

pnpm start                 # Run from TypeScript using .env
pnpm dev                   # Watch mode
pnpm typecheck             # Type-check server code
pnpm typecheck:examples    # Type-check the MCP-only reference example
pnpm test                  # Run the Node test suite
pnpm build                 # Compile the distributable server

MCP协议使用stdout，因此诊断必须转到stderr。实现的速率限制和模式消息遵循该规则。

覆盖范围边界

Qualtrics公开了其他特定于产品、许可、私有、仅限UI和二进制API。该项目没有为每个XM产品端点提供专用的语义工具。授权的JSON API v3端点通常可以通过 qualtrics_api_request；多部分调查导入和响应导出有专用路径。端点可用性和接受的有效负载仍然取决于帐户的许可证、品牌配置和API权限。

一些调查特征没有单独的公共突变终点。复制或导入已知良好的调查是保留评分或专业演示设置等功能的可靠方法； get_question_template 为专门的问题类型提供了类似的模式。

许可证

麻省理工学院