MCP 接入
RooQuiz 提供一个 MCP(Model Context Protocol)server,让 ChatGPT、claude.ai、Claude Desktop、Claude Code、Cursor、Codex 等 AI 客户端能在你的团队下直接干活——用自然语言就能从模板或从零创建测验,追加与修改题目,配置报告维度与分型结果,修改投放设置并拿到分享链接,管理多语言译文与答题者,跟进线索,以及读取预约、答题记录、统计与转化漏斗——而不必在编辑器里一样样手动操作。
RooQuiz 没有内置的 AI 出题功能。想用 AI 搭测验,就通过 MCP 连上你自己的 AI 客户端,让它来做——它会调用下面这些工具,你再到编辑器里检查结果。
MCP 是面向进阶用户的能力,需要你会使用支持 MCP 的 AI 客户端。基础的可视化搭建仍推荐用 编辑器。
工作原理
- AI 客户端连接到 RooQuiz 的 MCP 端点(
/api/mcp),认证方式有两种:OAuth 授权(推荐,支持的客户端在浏览器里登录授权即可)或 个人 API Token。 - 无论哪种方式,AI 都会以你的身份在当前激活的团队下执行操作。
- 所有操作都会经过与后台一致的权限校验,写操作还会记录到审计日志。
- 所以 AI 能做什么,完全取决于你在该团队里的角色与权限,不会越权。
连接方式一:OAuth 授权(推荐)
ChatGPT、claude.ai、Claude Code 等支持 MCP OAuth 的客户端无需手动创建 Token——只要填入 Endpoint URL,客户端会自动发现授权服务并打开浏览器,你登录 RooQuiz 账号、选择要授权的团队、点「授权」即完成连接。
RooQuiz 已作为应用上架 ChatGPT。在 RooQuiz 后台顶部点 在 ChatGPT 中使用 打开它,然后连接——浏览器会跳转到 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:
- 填写 Token 名称(便于识别,例如
Cursor - 我的 Mac)。 - 选择 默认团队——Token 创建后默认操作这个团队,AI 后续可用
switch_active_tenant工具切换到你所在的其它团队。 - 生成后会显示一段以
rqp_live_开头的明文 Token。
Token 明文只显示这一次,离开页面后无法再查看。请立刻复制保存;丢失只能吊销后重新生成。
限制:
- 每个用户最多保有 5 个 Token(含已吊销的,OAuth 连接不计入)。要再建新的,需先删除一个释放名额(「吊销」只是停用,不释放名额)。已吊销的个人 Token 可以点 启用 重新打开。
- 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 助手可调用以下 44 个工具。它们都作用在 Token 当前激活的团队下。
团队(Tenant)
| 工具 | 作用 |
|---|---|
list_my_tenants | 列出你所在的所有团队,标记当前激活的那个。 |
get_active_tenant | 返回 Token 当前激活的团队信息(含团队地址);所有写操作默认作用在该团队。 |
switch_active_tenant | 切换当前激活团队(持久化、跨会话保留;目标必须是你已加入的团队)。 |
invite_member | 按邮箱邀请别人以成员、查看者或管理员身份加入当前团队,会发出一封带加入链接的邀请邮件。仅所有者 / 管理员可用。 |
update_tenant_slug | 修改团队地址——平台域名下每条测评链接的第一段路径。仅所有者 / 管理员可用。所有公开测评链接会一起变更,旧地址立即失效;/a/<token> 形式的链接不受影响。 |
模板(Templates)
| 工具 | 作用 |
|---|---|
list_templates | 列出公共模板库里上架中的模板(标题、场景、描述、分类、使用次数),按使用次数从多到少排列。 |
create_form_from_template | 一次调用从模板创建新测验:题目结构、计分 / 报告配置、视觉设置与全部语言版本。有合适模板时,这是建卷最快的方式。 |
测验(Form)
| 工具 | 作用 |
|---|---|
create_form | 创建测验(knowledge_quiz、scored_quiz 或 outcome_quiz 分型测验),可一次性传入题目数组和报告配置,减少往返调用。分型测验必须在创建时一并传入 report.outcomes(结果类型列表),并让每个选项通过 outcomes 给类型投票。 |
list_forms | 列出当前团队的测验,最新的在前,不含题目内容。 |
get_form | 查看指定测验的完整详情(题目列表 fields[]、报告配置等);改题前需先用它拿到每道题的 code,分型测验则从 report.outcomeAnalysis.outcomes 拿结果类型的 code。 |
update_form | 更新标题、描述、开启/关闭状态、封面(flagImg / landingImage)、主题、社交分享卡片(openGraph)、系统文案,或按子键合并替换 report 配置;分型测验传 report.outcomes 即按 code 合并更新结果类型(已配置的图片保留;删除仍被题目投票引用的类型会被拒绝)。语言只有在测验还没有语言版本时才能改;**场景(scene)**永远不能改。 |
delete_form | 把测验移入回收站(软删):list_forms 中不再显示,5 天内可用 restore_form 找回(到期自动彻底清除)。仅测验 owner 或团队所有者 / 管理员可删;答题记录在彻底清除前保留。 |
restore_form | 从回收站恢复被 delete_form 删除的测验。 |
duplicate_form | 复制一份测验:克隆题目结构、评分、报告、视觉与设置以及全部语言译文,生成归属你的新测验(新链接)。不复制答题记录、共享设置、集成与封禁状态。可选传 newTitle。 |
分享与投放设置
| 工具 | 作用 |
|---|---|
get_form_share_info | 发布一份测验所需的全部信息:公开答题链接(也包括各语言版本的链接)、团队自定义域名及其是否生效、三种模式(内嵌 / 弹窗 / iframe)的嵌入代码,以及当前的投放设置。传 utmSource 可给所有链接和代码打上同一个渠道标记。 |
update_form_settings | 修改测验的投放方式:谁能作答、看报告是否需要留邮箱(留资门槛)以及是否要验证码、限时答题(知识测验)、分享与分享卡片、答题卡、群体对照、结果页预约块及其 Cal.com 链接、反馈板块、PDF 下载(Pro)、Google Analytics ID 等。 |
题目(Question)
| 工具 | 作用 |
|---|---|
add_question | 往测验末尾追加一项:题目、分页符(Breaker)或展示块(Statement 富文本段落、Swiper 图片轮播)。题型:SingleCheck / MultiCheck / TrueFalse、FillBlank、DropDown、Cascade(评分测验)、Ordering(知识测验)、DateField / TimeField(评分测验)、NumberField 与 Rate(评分测验)。分型测验的选择题需为每个选项指明投给哪些结果类型(判断题用 trueOutcomes / falseOutcomes)。 |
insert_question | 在指定位置插入一项,用 after / before 引用一个已存在的 code。 |
move_question | 按 code 把已有题目或分页符挪到新位置。 |
update_question | 按 code 更新题目:题干、说明、解析、是否必答、分值、正确答案、填空题的 AI 智能判分、数字 / 日期 / 评分的选项,或整体替换选择题的全部选项。展示块也在这里编辑。不能改题型。 |
delete_question | 按 code 删除一道题目或分页符。 |
报告维度
| 工具 | 作用 |
|---|---|
set_dimension_analysis | 整体设置测验的多维度分析(雷达图维度);只有 scored_quiz 场景有维度,每个维度写引用题目 code 的公式(知识测验没有维度)。传空数组即清空。分型测验不适用(它没有维度概念,用 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)
做测验的人——后台界面里叫「答题者」,工具名仍沿用 examinee 的叫法。答题者强绑定单一团队;工具仅返回安全字段——密码、验证码、重置令牌等敏感字段绝不外泄。
| 工具 | 作用 |
|---|---|
list_examinees | 列出当前团队的答题者,支持按邮箱 / 姓名模糊搜索与状态(active / disabled)过滤。 |
get_examinee | 按业务 ID examineeId(如 AB1234567890,见列表)查看某答题者详情(含自定义字段 customData)。 |
update_examinee | 按 examineeId 编辑答题者的姓名 / 状态 / 自定义字段(customData 按团队字段定义校验,并整体替换)。邮箱与所属团队不可改。 |
线索(Leads)
| 工具 | 作用 |
|---|---|
list_leads | 列出团队的线索——每个答题者跨所有测评一条,含跟进状态、负责人、颜色标记、提交次数与下一场预约。可按状态 / 负责人 / 标记 / 创建时间 / 关键词 / 即将到来的预约筛选。 |
get_lead | 按 leadId 查看一条线索,可选带上该答题者的提交历史、团队内部评论与变更时间线。 |
list_lead_settings | 读取团队的跟进状态、标记库与可指派的成员。写入前先调用它——状态 code、标记 code 与成员 id 都因团队而异。 |
update_lead | 把一条线索移到另一个跟进状态(如 new → contacted);会记入该线索的时间线。 |
assign_leads | 一次把最多 50 条线索指派给一位在职的非查看者成员("me" 表示自己),或清空负责人。负责人会收到一条汇总通知。 |
set_lead_tags | 一次给最多 50 条线索设置颜色标记:replace(单条线索),或批量用 add / remove,保留别人打的标记。 |
add_lead_comment | 在线索上写一条内部跟进评论(仅团队可见,答题者永远看不到),可选关联到某一次提交。 |
预约(Bookings)
| 工具 | 作用 |
|---|---|
list_bookings | 列出团队从 Cal.com 同步过来的预约,最早的在前,含时间、状态、Cal.com 预约类型、预约人、来源测评与答卷,以及线索负责人。可按状态 / 测评 / 答题者 / 时间范围筛选。只读——预约要在 Cal.com 里修改。 |
数据与分析(Records & Analytics)
读取测验表现与答题记录,让 AI 形成「建卷 → 度量 → 迭代」闭环。
| 工具 | 作用 |
|---|---|
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 引用它。 |
典型流程:
- 从模板建卷:
list_templates→create_form_from_template→ 用update_form/update_question调整。 - 考试 / 评分测验:
create_form创建测验并拿到每道题的code→ 用update_form或set_dimension_analysis按code配置报告公式 / 维度。 - 分型测验:
create_form一次传齐report.outcomes(每个类型自定义一个唯一code,如lion)与各题选项的投票映射 → 答题后票数最高的类型胜出(平票按列表顺序),后续用update_form微调类型文案 / CTA。 - 上线:
update_form_settings设置留资门槛与结果页板块 →get_form_share_info拿到链接和嵌入代码。
当前限制
- 随机知识测验(Random Knowledge Quiz)不支持:这类测验的题目存放在题库(QuestionBank)中,请在后台编辑器里管理,MCP 暂不覆盖。
- 不能改题型:需要换题型时,先
delete_question再add_question重建。选项可以用update_question整体替换,但判断题的分型投票(trueOutcomes/falseOutcomes)仍需删题重建。 - 按场景区分的计分方式:在评分测验和分型测验场景下,
update_question不接受顶层的score/correctAnswer/aiMatch——请改传带choices[i].score(选项分值,Option Scoring)或choices[i].outcomes(投票)的选项。 - 各场景可用的题型:Ordering 仅限知识测验;Cascade、Rate、DateField、TimeField 仅限评分测验;评分测验里的 FillBlank 只收集数据;分型测验接受 SingleCheck / MultiCheck / DropDown / TrueFalse(以及分页符和展示块)。
- 结果类型配图:结果类型的配图暂不能通过 MCP 上传,请在后台编辑器配置(MCP 更新
report.outcomes时已配置的图片会保留)。 - 场景创建后锁定;语言只有在测验还没有语言版本时才能修改。
- 删除是软删:
delete_form移入回收站(5 天后自动彻底清除),并非立即永久删除;彻底删除请在后台二次删除。 - 题数上限:免费版每份测评最多 50 道题(分页符、富文本、图片轮播不计入),超过后
create_form、add_question、insert_question会被拒绝;duplicate_form、create_form_from_template不受限制。Pro 不限,详见 题数上限。 - 复制不含数据:
duplicate_form只克隆结构与译文,不复制答题记录、共享设置与集成(含密钥),新测验为干净状态。 - 答题者身份字段不可改:
update_examinee不能改邮箱、所属团队与examineeId(它们是认证身份)。 - 个人信息返回时已脱敏:线索、预约、答题者与答题记录类工具返回的姓名、邮箱、手机号都是脱敏的——包括答题者在作答里填写的邮箱和手机号。脱敏不可逆;指代某个人请用
examineeId、leadId或记录 id。
安全与频率
- 无论 OAuth 还是 Token,都以你的身份操作,会触发现有的权限校验与审计日志(写操作均会留痕)。
- 每个连接的调用频率限制为 60 次 / 分钟,超出会被限流。
- 不再使用时,在 设置 → MCP 接入 中吊销(立即失效;对 OAuth 连接即断开对应客户端)或删除(并释放名额)。
- OAuth 流程强制 PKCE(S256),授权码一次性使用,刷新令牌每次续期自动轮换,旧令牌即刻失效。
概览
这一章面向开发者，讲怎么用代码或 AI 客户端接入 RooQuiz：只读的 REST API 用账号级密钥拉取表单定义与提交记录，附带 OpenAPI 规范，适合自建看板或同步到数据仓库；MCP 接入让你自己的 AI 客户端（ChatGPT、Claude 等）直接建测评、跟进线索、读取预约。RooQuiz 没有内置 AI 出题，想用 AI 建卷就走 MCP。也介绍不写代码时的替代做法。
REST API
RooQuiz 提供一个轻量的只读 REST API，方便把团队的表单数据拉进脚本、自动化工具（Zapier、Make、n8n）或自建看板，以纯 JSON 返回表单的标题、字段、设置与报告配置，以及收集到的提交记录。这一页讲它的工作方式、怎么获取账号级 API 密钥、如何鉴权、有哪些端点，以及错误与限流规则。接口只读，不会修改任何数据；密钥请当作密码保管，泄露后可以随时重置。