RooQuiz 文件
整合與 API

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:

  1. 填寫 Token 名稱(便於識別,例如 Cursor - 我的 Mac)。
  2. 選擇 預設團隊——Token 建立後預設操作這個團隊,AI 後續可用 switch_active_tenant 工具切換到你所在的其他團隊。
  3. 生成後會顯示一段以 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),授權碼一次性使用,重新整理權杖每次續期自動輪換,舊權杖即刻失效。

本頁目錄