wjx-mcp-use

wjx-mcp-server Usage Guide

wjx-mcp-server 提供 MCP 工具、参考资源和 prompt 模板，覆盖问卷星核心业务子集；CLI 是主入口，工作站能力（初始化、配置、补全、Skill 安装）保持 CLI-only。完整差异以仓库 capabilities/capability-matrix.json 为准。

HTTP 凭据边界

本地优先使用 stdio，并通过 WJX_API_KEY 提供上游凭据。HTTP 模式中，MCP_AUTH_TOKEN 只保护 /mcp 的 Authorization: Bearer 访问 gate；单租户上游仍使用 WJX_API_KEY。启用 MCP_TENANT_MODE=1 时，每个请求必须提供 X-WJX-API-Key，服务端按 session 隔离且不回退进程级 key。只有显式设置 MCP_LEGACY_BEARER_API_KEY=1 才允许 Bearer 兼作上游 API Key；/health 不要求 Bearer。不要在消息、日志或 URL 中输出完整凭据。

HTTP 服务配置

如果使用已部署的 MCP HTTP 服务，无需在本机安装 wjx-mcp-server 或配置本地 WJX_API_KEY。在支持 MCP HTTP 的客户端配置中添加：

{
  "mcpServers": {
    "wjx": {
      "type": "http",
      "url": "https://alifc.wjx.cn/mcp/latest",
      "headers": {
        "Authorization": "Bearer sk-wjx-xxx"
      }
    }
  }
}

将 sk-wjx-xxx 替换为服务端分配的 HTTP 访问令牌。保存配置后完全重启客户端；启用多租户模式时，还需按服务端要求提供 X-WJX-API-Key。

Agent 前门

MCP 任务遵循“发现意图 -> 预检 -> 计划 -> 确认 -> 执行 -> 读回验证 -> 报告”。Prompt 只提供指导，不执行工具也不保证验证；Agent 必须根据工具返回的 isError 和 result 字段判断成功。WorkBuddy、Cowork、Codex Work、Qianwen Work 都先按 宿主中立握手与路由 检查真实能力，不根据宿主名称猜测配置或 API。创建、发布、提交、设置替换、清理和凭据相关操作先说明副作用，高风险和队列消费操作需要确认；网络超时后的结果按 unknown 处理并优先读回。风险、重试、验证和 JSONL 题型以生成的 agent-contract/jsonl-qtypes 资料及对应只读资源为准。 其中包括 wjx://reference/jsonl-qtypes。

query_responses_realtime 会消费服务端实时答卷队列，因此 Agent contract 将它标记为高风险且不可重放；调用前先向用户说明会移除/消费队列中的记录并取得确认。该标记是 MCP/Agent 层的安全策略，不改变 CLI 的 response realtime metadata 或退出码。

外部问卷产品的常见入口可这样映射：question builder 对应 create_survey_by_json 的 JSONL；preview 对应 build_preview_url；publish 对应 update_survey_status；collect 对应 query_responses/download_responses；analyze 对应分析工具。分支、随机、配额和 piping 只有在生成 profile 明确列出并通过 SDK 校验时才可使用，否则视为未验证能力。

AI Agent 行为准则（必读）

规则 0：按场景选择 JSONL 或 XML DSL

问卷可通过 create_survey_by_json（JSONL）或 create_survey_from_definition（完整 XML DSL）创建。修改使用 update_survey_from_definition，查询 DSL 使用 query_wjx_dsl；XML DSL 的生成与校验使用 generate_wjx_dsl。所有 DSL 输入必须符合 wjx-dsl 1 规范并经过校验。