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***g@example.com)。脫敏不可逆,所以引用某個
答題者請用 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 找回(到期自動徹底清除)。團隊任意成員都可刪;答題記錄在徹底清除前保留。 |
restore_form | 從回收站恢復被 delete_form 刪除的測驗。 |
duplicate_form | 複製一份測驗:克隆題目結構、評分、報告、視覺與設定以及全部語言譯文,生成歸屬你的新測驗(新連結)。不複製答題記錄、整合與封禁狀態。可選傳 newTitle。 |
分享與投放設定
| 工具 | 作用 |
|---|---|
get_form_share_info | 發佈測驗需要的一切:公開答題連結(每個語言版本各一條)、團隊自訂網域及其是否已生效、三種模式(inline / popup / iframe)的嵌入程式碼,以及目前的投放設定。傳 utmSource 可給所有連結和程式碼加上同一個管道標記。 |
update_form_settings | 修改測驗的投放方式:誰能答題、看報告是否要留信箱(留資門檻)以及是否要驗證碼、限時答題(知識測驗)、結果頁分享與分享卡片、答題卡、群體對照、結果頁預約區塊及其 Cal.com 連結、回饋區塊、PDF 下載(Pro)、Google Analytics ID 等。 |
題目(Question)
| 工具 | 作用 |
|---|---|
add_question | 往測驗末尾追加一項:題目、分頁符(Breaker),或展示區塊(Statement 富文本段落、Swiper 圖片輪播)。題型:SingleCheck / MultiCheck / TrueFalse、FillBlank、DropDown、Ordering(知識測驗)、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(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拿連結與嵌入程式碼。
目前限制
- 不能改題型:需要換題型時,先
delete_question再add_question重建。選項可以用update_question整體替換,但判斷題的分型投票(trueOutcomes/falseOutcomes)仍需刪題重建。 - 各場景的計分方式:評分測驗和分型測驗場景下,
update_question不接受頂層的score/correctAnswer/aiMatch——請改為傳入帶choices[i].score(選項分值,Option Scoring)或choices[i].outcomes(投票)的選項。 - 各場景的題型範圍:Ordering 僅限知識測驗;Rate 僅限評分測驗;評分測驗裡的 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 用帳號級金鑰拉取表單定義與提交記錄,適合自建看板或同步到資料倉儲;MCP 接入讓你自己的 AI 客戶端在團隊下建立測驗、跟進線索、讀取預約。也介紹不寫程式碼時的替代做法。兩條路徑都不需要改動測評本身,也不會影響答題者在作答頁上看到的體驗。
REST API
RooQuiz 提供一個輕量的唯讀 REST API,方便把團隊的表單資料拉進腳本、自動化工具(Zapier、Make、n8n)或自建看板,以純 JSON 回傳表單的標題、欄位、設定與報告設定,以及收集到的提交記錄。這一頁講它的工作方式、怎麼取得帳號級 API 金鑰、如何驗證、有哪些端點,以及錯誤與限流規則。介面唯讀,不會修改任何資料;金鑰請當作密碼保管,外洩後可以隨時重置。