MCP 接入
RooQuiz 提供一个 MCP(Model Context Protocol)server,让 Claude Desktop、Claude Code、Cursor、Codex 等 AI 客户端能在你的团队下直接操作测验——用自然语言就能创建考试、评分测验、分型测验,追加题目、调整顺序、配置报告维度与分型结果;还能复制 / 删除测验、做多语言译文、管理考生,以及读取答题记录、统计与转化漏斗——而不必手动在编辑器里一个个搭。
MCP 是面向进阶用户的能力,需要你会使用支持 MCP 的 AI 客户端。基础的可视化搭建仍推荐用 编辑器。
工作原理
- AI 客户端连接到 RooQuiz 的 MCP 端点(
/api/mcp),认证方式有两种:OAuth 授权(推荐,支持的客户端在浏览器里登录授权即可)或 个人 API Token。 - 无论哪种方式,AI 都会以你的身份在当前激活的团队下执行操作。
- 所有操作都会经过与后台一致的权限校验,写操作还会记录到审计日志。
- 所以 AI 能做什么,完全取决于你在该团队里的角色与权限,不会越权。
连接方式一:OAuth 授权(推荐)
claude.ai、Claude Code 等支持 MCP OAuth 的客户端无需手动创建 Token——只要填入 Endpoint URL,客户端会自动发现授权服务并打开浏览器,你登录 RooQuiz 账号、选择要授权的团队、点「授权」即完成连接。
打开 claude.ai 的 设置 → 连接器(Connectors)→ 添加自定义连接器:
- 名称随意填(例如
RooQuiz)。 - 远程 MCP 服务器 URL 填入你的 Endpoint(形如
https://你的域名/api/mcp)。 - 保存后点「连接」,浏览器会跳转到 RooQuiz 授权页——登录并选择团队,点「授权」。
关于 OAuth 连接:
- 授权时选择的团队即初始激活团队,AI 后续仍可用
switch_active_tenant切换。 - 连接会出现在 设置 → MCP 接入 的 Token 列表中(标有 OAuth),吊销即断开对应客户端;它不占个人 Token 的 5 个名额。
- 凭证由客户端自动续期(访问令牌 1 小时滚动刷新,连接本身 30 天有效,期间使用会自动延续),无需手动维护。
连接方式二:个人 Token(PAT)
不支持 OAuth 的客户端(Cursor、Codex CLI、Claude Desktop 等),或 CI 等无浏览器环境,使用个人 API Token 连接。
创建 Token
进入 设置 → MCP 接入,点「创建 Token」:
- 填写一个名称(便于识别,例如
Cursor - 我的 Mac)。 - 选择一个默认团队——Token 创建后默认操作这个团队,AI 后续可用
switch_active_tenant工具切换到你所在的其它团队。 - 生成后会显示一段以
rqp_live_开头的明文 Token。
Token 明文只显示这一次,离开页面后无法再查看。请立刻复制保存;丢失只能吊销后重新生成。
限制:
- 每个用户最多保有 5 个 Token(含已吊销的,OAuth 连接不计入)。要再建新的,需先删除一个释放名额(「吊销」只是停用,不释放名额)。
- Token 是个人凭证,请勿提交到代码仓库或公开分享。
在 AI 客户端中配置
在 设置 → MCP 接入 页面可以直接复制各客户端的配置片段和你的 Endpoint URL(形如 https://你的域名/api/mcp)。把片段里的 rqp_live_xxx... 替换成你刚生成的 Token。
Claude Code 推荐走上方的 OAuth 方式;仅在 CI 等无浏览器环境才需要 token header:
claude mcp add --transport http rooquiz https://你的域名/api/mcp \
--header "Authorization: Bearer rqp_live_xxx..."示例指令
连上之后直接用自然语言说话即可。下面每一条分别调用服务器的不同部分：
从模板建卷
看一下教练类模板，用其中的 readiness 那个建一份计分测评，然后加两道关于预算的题。
依次调用 list_templates → create_form_from_template → add_question。
处理线索
列出我的 Wheel of Life 测评这周收到的线索，给得分低于 40 的都打上 follow-up 标签，并指派给我。
依次调用 list_leads → set_lead_tags → assign_leads。
诊断漏斗
我哪份测评的完成率最差？人具体是在哪一步流失的？
依次调用 list_forms → get_form_stats → get_form_funnel。
做多语言
把 promotion-readiness 这份测评翻成西班牙语和德语，题目 code 保持不变。
依次调用 list_form_translations → create_form_translation。
答题者的姓名、邮箱和手机号返回时是脱敏的（j***[email protected]）。脱敏不可逆，所以引用某个
答题者请用 id，不要把脱敏后的值再贴回指令里。
支持的工具
连接成功后,AI 助手可调用以下工具。它们都作用在 Token 当前激活的团队下。
团队(Tenant)
| 工具 | 作用 |
|---|---|
list_my_tenants | 列出你所在的所有团队,标记当前激活的那个。 |
get_active_tenant | 返回 Token 当前激活的团队信息;所有写操作默认作用在该团队。 |
switch_active_tenant | 切换当前激活团队(持久化、跨会话保留;目标必须是你已加入的团队)。 |
测验(Form)
| 工具 | 作用 |
|---|---|
create_form | 创建测验(knowledge_quiz 考试、scored_quiz 评分测验 或 outcome_quiz 分型测验),可一次性传入题目数组和报告配置,减少往返调用。分型测验必须在创建时一并传入 report.outcomes(结果类型列表),并让每个选项通过 outcomes 给类型投票。 |
list_forms | 列出当前团队的测验,支持按 scene 或标题模糊过滤。 |
get_form | 查看指定测验的完整详情(题目列表 fields[]、报告配置等);改题前需先用它拿到每道题的 code,分型测验则从 report.outcomeAnalysis.outcomes 拿结果类型的 code。 |
update_form | 更新标题、描述、开启/关闭状态,或按子键合并替换 report 配置;分型测验传 report.outcomes 即按 code 合并更新结果类型(名称/描述/CTA,已配置的图片保留;删除仍被题目引用的类型会被拒绝)。场景(scene)与语言创建后锁定,不可改。 |
delete_form | 把测验移入回收站(软删):列表中不再显示,5 天内可用 restore_form 找回(到期自动彻底清除)。仅测验 owner / 团队 owner 可删;答题记录在彻底清除前保留。 |
restore_form | 从回收站恢复被 delete_form 删除的测验。仅 owner / 团队 owner 可恢复;不在回收站会报错。 |
duplicate_form | 复制一份测验:克隆题目结构、评分、报告、视觉与设置以及全部语言译文,生成归属你的新测验(新链接)。不复制答题记录、共享设置、集成与封禁状态。可选传 newTitle。 |
题目(Question)
| 工具 | 作用 |
|---|---|
add_question | 往测验末尾追加一项:题目(单选/多选/判断/填空)或分页符(Breaker)。分型测验的选择题需为每个选项指明投给哪些结果类型(判断题用 trueOutcomes / falseOutcomes)。 |
insert_question | 在指定位置插入一项,用 after / before 引用一个已存在的 code。 |
move_question | 按 code 把已有题目或分页符挪到新位置。 |
update_question | 按 code 更新题干、说明、解析、是否必答、分值、正确答案,或填空题的 AI 智能判分。不能改题型与选项内容。 |
delete_question | 按 code 删除一道题目或分页符。 |
报告维度
| 工具 | 作用 |
|---|---|
set_dimension_analysis | 整体设置测验的多维度分析(雷达图维度);quiz 场景每个维度引用题目 code,scored quiz 场景每个维度写公式。传空数组即清空。分型测验不适用(它没有维度概念,用 report.outcomes 配结果类型)。 |
多语言译文(FormTranslation)
为同一测验提供多语言版本:一份源测验(主语言)+ 每个其它语言一份译文(结构与源同构,只译文字,答题记录恒锚定源测验)。
| 工具 | 作用 |
|---|---|
create_form_translation | 为测验新增一个语言版本,克隆源文案为初稿(同 code、源语言文字),并返回克隆内容供直接翻译。语言必须不同于主语言,每种语言至多一份。 |
list_form_translations | 列出某测验已有的语言版本(语言、启用状态、公开链接等)。 |
get_form_translation | 读取某语言版本的完整内容(含 fields[] 与 report),用于就地翻译——所有 code 必须与源测验保持一致。 |
update_form_translation | 保存某语言版本的译文文案(title / description / fields / report / systemText),或用 isActive 暂停该语言;结构由源决定,只改文字,未传的字段视为部分翻译。 |
delete_form_translation | 删除某语言版本。 |
考生(Examinee)
测验的答题人。考生强绑定单一团队;工具仅返回安全字段——密码、验证码、重置令牌等敏感字段绝不外泄。
| 工具 | 作用 |
|---|---|
list_examinees | 列出当前团队的考生,支持按邮箱 / 姓名模糊搜索与状态(active / disabled)过滤。 |
get_examinee | 按业务 ID examineeId(如 AB1234567890,见列表)查看某考生详情(含自定义字段 customData)。 |
update_examinee | 按 examineeId 编辑考生的姓名 / 状态 / 自定义字段(customData 按团队字段定义校验)。邮箱与所属团队不可改。 |
数据与分析(Records & Analytics)
读取测验表现、转化漏斗与线索(leads),让 AI 形成「建卷 → 度量 → 迭代」闭环。线索类工具会返回答题人信息(PII)。
| 工具 | 作用 |
|---|---|
get_form_stats | 读取某测验近 N 天(默认 30,上限 180)的统计:总览 KPI、每日趋势、渠道(utm_source)、登录方式、设备,以及单选类题目的答案分布。 |
get_form_funnel | 读取某测验近 N 天的转化漏斗:浏览 → 开始 → 提交 → 留资 → 看报告 → 点 CTA → 分享,以及分渠道漏斗与流失点。 |
list_records | 列出当前团队的答题记录(线索):答题人、作答、报告结果摘要与 UTM;可按测验、报告状态、提交时间筛选。 |
get_record | 按记录 id(list_records 返回)查看单条记录详情:完整作答、报告结果与提交元数据。 |
图片上传(Image upload)
| 工具 | 作用 |
|---|---|
prepare_image_upload | 第一步:为封面等图片签发直传地址(把文件 PUT 上去)。 |
finalize_image_upload | 第二步:校验并把图片落库到团队媒体库,返回 media id;再用 update_form 的 flagImg / landingImage 引用它。 |
典型流程:
- 考试 / 评分测验:
create_form创建测验并拿到每道题的code→ 用update_form或set_dimension_analysis按code配置报告公式 / 维度。 - 分型测验:
create_form一次传齐report.outcomes(每个类型自定义一个唯一code,如lion)与各题选项的投票映射 → 答题后票数最高的类型胜出(平票按列表顺序),后续用update_form微调类型文案 / CTA。
当前限制
- 随机题库(Random Knowledge Quiz)不支持:这类测验的题目存放在题库(QuestionBank)中,请在后台编辑器里管理,MCP 暂不覆盖。
- 不能直接改题型或选项内容:需要换题型或改选项时,先
delete_question再add_question重建。分型测验的选项投票映射同理——要改投票就删题重建。 - 评分测验(scored quiz)的选项计分走「选项分值(Option Scoring)」:
update_question在 scored quiz 场景下不接受score/correctAnswer/aiMatch,改选项分值请在后台编辑,或删了重建。分型测验(outcome)同样不接受这三个参数(它按票数判型,没有计分概念)。 - 分型测验的题型范围:投票题型为单选 / 多选 / 判断(不支持填空);结果类型的配图暂不能通过 MCP 上传,请在后台编辑器配置(MCP 更新
report.outcomes时已配置的图片会保留)。 - 场景与语言创建后锁定,无法通过 MCP 修改。
- 删除是软删:
delete_form移入回收站(5 天后自动彻底清除),并非立即永久删除;彻底删除请在后台二次删除。 - 复制不含数据:
duplicate_form只克隆结构与译文,不复制答题记录、共享设置与集成(含密钥),新测验为干净状态。 - 考生身份字段不可改:
update_examinee不能改邮箱、所属团队与examineeId(它们是认证身份)。 - 线索含个人信息(PII):
list_records/get_record会返回答题人邮箱、姓名、自定义字段等,请妥善使用。 - 填空 AI 智能判分(
aiMatch,仅 quiz 场景、Beta)会消耗团队的 AI 额度。
安全与频率
- 无论 OAuth 还是 Token,都以你的身份操作,会触发现有的权限校验与审计日志(写操作均会留痕)。
- 每个连接的调用频率限制为 60 次 / 分钟,超出会被限流。
- 不再使用时,在 设置 → MCP 接入 中吊销(立即失效;对 OAuth 连接即断开对应客户端)或删除(并释放名额)。
- OAuth 流程强制 PKCE(S256),授权码一次性使用,刷新令牌每次续期自动轮换,旧令牌即刻失效。
概览
这一章面向开发者，讲怎么用代码或 AI 客户端接入 RooQuiz：只读的 REST API 用账号级密钥拉取表单定义与提交记录，适合自建看板或同步到数据仓库；MCP 接入让 Claude、Cursor 等 AI 客户端直接在你的团队下操作测验。也介绍不写代码时的替代做法。两条路径都不需要改动测评本身，也不会影响答题者在作答页上看到的体验。
REST API
RooQuiz 提供一个轻量的只读 REST API，方便把团队的表单数据拉进脚本、自动化工具（Zapier、Make、n8n）或自建看板，以纯 JSON 返回表单的标题、字段、设置与报告配置。这一页讲它的工作方式、怎么获取账号级 API 密钥、如何鉴权、有哪些端点，以及错误与限流规则。接口只读，不会修改任何数据；密钥请当作密码保管，泄露后可以随时重置。