wjx-mcp-use

wjx-mcp-server Usage Guide

wjx-mcp-server 提供 58 个 MCP 工具、8 个参考资源和 23 个 prompt 模板，覆盖问卷星 OpenAPI 的全部能力。

AI Agent 行为准则（必读）

规则 0：创建问卷只用 create_survey_by_json（强制）

禁止使用 create_survey_by_text 与 create_survey——除非用户用"DSL"、"文本格式"、"老版接口"等字眼明确要求。原因：DSL 只覆盖 27 种题型而 JSON 覆盖 70+，且 DSL 容易被字符转义破坏。所有题型、投票、考试、表单都走 create_survey_by_json。

规则 1：一个需求 = 一个问卷

无论用户要求多少种题型，必须在一次 create_survey_by_json 调用中包含所有题目。一个问卷可包含任意数量、任意类型的题目。

规则 2：问卷类型 ≠ 题目类型

"投票/考试/调查"是问卷类型（atype 参数）。JSONL 创建投票时使用 qtype:"投票单选" / qtype:"投票多选"，并显式传 atype: 3；只有旧 DSL 文本格式才使用普通 [单选题] / [多选题]，不存在 [投票单选题] 标签。

规则 3：不支持的题型要明确告知

签名题（用 [绘图题] 替代）、地区题（用 [多级下拉题] 或网页端添加）、NPS 专用题（用 [量表题] + 0~10）不在 DSL 支持范围内。告知用户替代方案，继续创建其他题目，不要反复尝试或拆分多个问卷。

规则 4：面向用户说自然语言，不说工具名

用户不需要知道 MCP 工具的存在。不要在回复中展示工具名或调用参数。唯一例外：用户明确要求调试时。

规则 5：首次使用时检查配置

在首次配置/初始化、用户明确要求检查配置，或工具实际返回 API Key 相关错误时，引导用户处理 API Key。

• api_key 未设置：如果工具返回未配置错误，停止当前业务操作，不要继续调用创建、查询、导出等需要鉴权的工具；引导用户在 AI 工具的 MCP 配置中添加 WJX_API_KEY 环境变量
• api_key 错误或过期：提醒用户重新获取 API Key，更新 MCP 配置后再继续原任务
• 已返回 API Key 相关错误：如果工具返回 API Key is required、Invalid API Key、appkey error 或类似鉴权错误，必须立刻向用户说明需要处理 API Key，并给出获取/更新 WJX_API_KEY 的下一步；不要只复述错误信息，也不要继续调用其他业务工具反复尝试
• base_url 与用户域名不符：引导添加 WJX_BASE_URL 环境变量（如 https://xxx.sojump.cn）
• 获取 API Key：让用户访问 https://<域名>/weixinlogin.aspx?redirecturl=%2Fnewwjx%2Fmanage%2Fuserinfo.aspx%3FshowApiKey%3D1，微信扫码登录后复制 Key
• cli_version 未安装：可选，安装 npm install -g wjx-cli 后用 wjx init --api-key 统一配置

收到 API Key 相关错误后的用户提醒应使用自然语言，不暴露 MCP 工具调用细节，例如：

刚才的操作返回了 API Key 相关错误，所以我暂时不能继续创建或查询问卷。请先打开下面的链接获取/重新获取 API Key，然后在 MCP 配置中添加或更新 WJX_API_KEY 环境变量：
https://www.wjx.cn/weixinlogin.aspx?redirecturl=%2Fnewwjx%2Fmanage%2Fuserinfo.aspx%3FshowApiKey%3D1

规则 6：提交答卷的几个易错点

• jpmversion 无需手动管：submit_response 内部会自动 get_survey 取最新 version 并注入。不要手动算或省略。仅当外部已自行管理版本时才显式传入 jpmversion 参数。问卷被发布/编辑后服务端 version 自增，不带最新版本号会被拒绝并报"问卷已被修改请刷新"。
• submitdata 题号用 get_survey 返回的原始 q_index：服务端严格按此校验——"问卷基础信息"元数据占 q_index=1，真实题目从 2 开始。AI 自己按"第 N 题"顺序数（1$..., 2$...）极易与服务端 q_index 错位，被拒"5〒答案不符合要求"。正确流程：先 get_survey({ vid, get_questions: true }) 拿 questions[].q_index，再按每题 q_index 拼 submitdata。选项序号仍是 1-based（从 1 数到 N）。
• 矩阵题用行号!列号，行用 , 分隔（每题 3 条可复制示例）：
  • 矩阵单选（q_subtype=702）3 行：3$1!1,2!3,3!2 — 第 3 题第 1 行选第 1 列、第 2 行选第 3 列、第 3 行选第 2 列
  • 矩阵多选（q_subtype=703）3 行：4$1!1|2,2!3,3!1|4 — 同一行多个列用 | 拼
  • 矩阵量表（q_subtype=701）3 行：5$1!5,2!4,3!3 — 行号!分值
  • 矩阵题的"行数"来自 get_survey 返回的 item_rows.length；items 数组是列头（列选项），不是行。
• 考试题分值/答案无法通过 submit API 设置：创建考试问卷后需要去网页端配置。submit_response 仅用于答题端提交。

快速路由

工具总览（58 tools）

详细参数见 references/tools-survey.md、references/tools-response.md、references/tools-other.md。

核心工作流

创建问卷（统一使用 JSON 方式）

唯一推荐：所有问卷创建一律使用 create_survey_by_json（支持 70+ 题型，覆盖全部 q_type/q_subtype 编码）。

1. 使用 prompt 模板生成题目 JSON（如 generate-survey-json、generate-exam-json 等）
2. create_survey_by_json({ questions: [...], title: "问卷标题", atype: 1 })
3. get_survey({ vid: N }) — 验证内容
4. build_survey_url({ mode: "edit", activity: N }) — 提供编辑链接

create_survey_by_text（DSL 文本方式）已弃用，仅为兼容保留，新代码不要使用。

考试问卷（atype=6）注意：正确答案和每题分值无法通过 API 设置。创建后应提供编辑链接，指引用户在网页端配置答案与评分。

题型字段映射详见 wjx://reference/question-types 资源，或 references/dsl-and-types.md。

查询和分析数据

1. get_report({ vid: N }) — 统计概览（首选）
2. query_responses({ vid: N, page_size: 50 }) — 明细数据
3. decode_responses({ submitdata: "..." }) — 解码答卷格式
4. calculate_nps / calculate_csat — 分析指标
5. detect_anomalies({ responses: [...] }) — 数据质量检查

提交答卷（代填/导入）

submitdata 题号必须与 get_survey 返回的原始 q_index 对齐——先拉结构再拼数据，不要凭"第几题"硬数：

1. get_survey({ vid, get_questions: true, get_items: true })
   → 拿到 questions[]，每题含 q_index / q_type / q_subtype / items / item_rows
2. 按每题 q_type 拼 placeholder（举例）：
   - q_type=3（单选/量表/下拉）   →  `${q.q_index}$1`
   - q_type=4（多选）              →  `${q.q_index}$1|2`
   - q_type=4 + q_subtype=402（排序）→ `${q.q_index}$2|3|1`（按名次列出选项序号）
   - q_type=5（填空）              →  `${q.q_index}$答案文本`
   - q_type=6（多项填空）          →  `${q.q_index}$空1|空2|空3`
   - q_type=7（矩阵）：行用 item_rows.length 决定，逐行 `行号!列号`，行间用 `,` 拼
   - q_type=10（滑动条）           →  `${q.q_index}$5`
3. 用 `}` 拼接所有题，得到完整 submitdata
4. submit_response({ vid, inputcosttime: 30, submitdata, ... })
   — 内部会自动注入最新 jpmversion

跳过 q_type === 1（分页栏）和 q_type === 2（段落说明），它们不接受答案。

常见错误与处理

更多排查详见 references/troubleshooting.md。

MCP 资源（参考数据）

Prompt 模板（19 个）

通用/运维（6）： design-survey, analyze-results, create-nps-survey, configure-webhook, anomaly-detection, user-system-workflow

分析（6）： nps-analysis, csat-analysis, cross-tabulation, sentiment-analysis, survey-health-check, comparative-analysis

问卷生成 — DSL 文本（7，已弃用，保留兼容）： generate-survey, generate-nps-survey, generate-360-evaluation, generate-satisfaction-survey, generate-engagement-survey, generate-exam-from-document, generate-exam-from-knowledge

问卷生成 — JSON（3，唯一推荐）： generate-survey-json, generate-exam-json, generate-form-json

常用枚举值

Reference 文件（按需查阅）

• DSL 语法与题型 — DSL 格式、25+ 题型标签、q_type/q_subtype 映射表
• 问卷工具详解 — 12 个问卷管理工具的完整参数
• 答卷工具详解 — 9 个答卷数据工具的完整参数
• 其他工具详解 — 通讯录、子账号、SSO、分析、推送工具参数
• 错误排查 — API 错误码、配置问题、自定义域名、考试限制