Recap Raven
官方Discord D&D 筆記工具：可從任何 AI 搜尋並引用你的 TTRPG 團錄回顧、任務、NPC 和逐字稿。需要 Recap Raven API 金鑰。
你可以用 Recap Raven MCP 做什麼？
- 列出戰役與場次 — 請你的 AI 列出你的戰役，並在提取詳細資料前，先將場次編號對應到正確的摘要。
- 搜尋逐字稿與場景節拍 — 對逐字稿輪次或場景節拍執行精確關鍵字搜尋，找出某個名字、物品或地點出現的位置。
- 閱讀摘要與逐字稿片段 — 依索引範圍，取得玩家安全的摘要，或某場次已儲存輪次中特定位置的片段。
- 檢視準備資料與未解伏筆 — 提取某個戰役尚未解決的敘事伏筆、下一場次的準備包，以及前情提要。
- 查詢實體與世界觀設定 — 取得實體名冊或單一實體卡，以及世界觀設定文件與詞彙條目。
- 檢查參與度與任務 — 閱讀各發言者的參與趨勢、玩家可見的任務日誌，以及你的 Ask 額度使用量。
託管 MCP 伺服器
npx add-mcp 'https://mcp.recapraven.com/mcp'可安裝到 Claude Code、Codex、Cursor 等客戶端
文件
用於自訂 AI 工作流程
你的戰役工具，在相容的 AI 用戶端中。
透過 MCP 讀取你的回顧與戰役資料。現有的 API 金鑰存取可與相容的用戶端搭配使用。請從支援公開用戶端身分的 AI 應用程式登入；連線前請先查看下方用戶端的需求。
什麼是 MCP？
MCP 讓相容的 AI 應用程式直接呼叫 Recap Raven 工具。你的 AI 不必再將回顧複製到另一個 AI，而是可以向 Recap Raven 請求工作階段、逐字稿區間、鉤子、實體、引文與戰役解答。
開始使用
Raven 的遠端 MCP 端點為 https://mcp.recapraven.com/mcp 。請選擇一個用戶端以取得設定說明。Premium 包含確定性讀取；記憶搜尋與 AI 解答則需要 Searchable Memory。
MCP 端點
https://mcp.recapraven.com/mcp
ChatGPT 設定
- 在 ChatGPT 網站上開啟 外掛，選擇 +，然後選取「新增自訂 MCP 伺服器」。輸入「Recap Raven」以及下方的伺服器 URL。
- 啟用 Raven 登入後，選擇 OAuth 以及採用公開用戶端驗證的已發布用戶端身分 (CIMD) 選項。不需要用戶端密鑰或 Raven API 金鑰。Raven 不支援自動用戶端註冊。
- 建立外掛、安裝外掛，然後登入 Raven 並檢視應用程式身分與要求的存取權限。只核准由你發起的連線。
- 在對話中，使用 @ 選取 Recap Raven 並詢問：「Use Recap Raven to list my campaigns.」
- 讀取與寫入工具取決於你的權限與確認設定。若缺少設定，請檢查工作區限制，並參閱你應用程式的官方 ChatGPT 設定指南。
ChatGPT 遠端伺服器 URL
https://mcp.recapraven.com/mcp
同意與連線說明
Raven 登入連線會要求取得存取你的戰役、逐字稿與僅限 GM 資訊的權限。工具結果會傳送給你所選的 AI 供應商，而付費工具會花費你現有的 Ask 額度。
若你核准背景存取，應用程式最多可在 30 天內重新整理其連線，即使你已登出 Raven 亦然。到期或撤銷後，請重新連線並再次核准。在帳戶設定中，檢視已核准的 AI 連線，並中斷單一連線或使用「中斷所有 AI 連線」。API 金鑰則另行管理。
結果為空？請確認你登入的是擁有你戰役的 Raven 帳戶。方案變更可能會移除工具存取權；AI 解答也需要有可用的額度。若同意已到期或失敗，請從用戶端重新啟動連線。
缺少選單或不受支援的工作區無法透過變更你的 Raven 金鑰來修正。請查看連結的供應商需求，或帶著應用程式名稱、版本與錯誤訊息聯絡我們的 Discord 社群。請勿傳送權杖或金鑰。
適用於 Premium 與 Searchable Memory
Premium 包含 API 金鑰，以及存取你可用的回顧、逐字稿與手動 World 資料。記憶工具、戰役搜尋與 AI 解答則需要 Searchable Memory。語意搜尋與 AI 解答會花費你現有的 Ask 額度。
各方案的 MCP 可用性
| 免費方案 | 無法使用 |
| Premium | API 金鑰、可用的回顧、逐字稿與手動 World 資料。不包含記憶工具。 |
| 含記憶的方案 | 確定性工具不額外收費；search_corpus 每次搜尋使用少量聊天額度，而附引用的 ask 工具會花費 Ask 額度。 |
| API 金鑰 | 從 API 金鑰建立個人 API 金鑰。可隨時撤銷；當帳戶回到免費方案時，MCP 存取即結束。 |
合理使用與速率限制
MCP 伺服器是共享且計量的介面。為了維持其永續性（並避免失控的代理迴圈在幾分鐘內耗盡整份授權），每個 API 金鑰除了你的 Ask 額度外，還受到速率限制。
MCP 速率限制
| 伺服器合理使用 | MCP 伺服器本身對每個 API 金鑰的請求上限（所有工具呼叫合計）——防止單一金鑰灌爆端點。超過上限的回應會傳回 429 與 Retry-After。 |
| Premium · 所有方案 / Memory · 5 個工作階段 | 每分鐘 15 次請求，每小時 150 次請求。 |
| Memory · 10 個工作階段 | 每分鐘 30 次請求，每小時 450 次請求。 |
| Memory · 20 個工作階段 | 每分鐘 60 次請求，每小時 1200 次請求。 |
| 免費工具 | 依每個 API 金鑰進行速率限制。確定性讀取與關鍵字搜尋（search_transcript、search_facts）不花費額度。此處不包含語意 search_corpus；它每次完成的搜尋會使用少量聊天額度。 |
| 聊天額度工具 | search_corpus（少量聊天額度）與附引用的 ask 工具同時受你的 Ask 額度與每個金鑰的速率限制約束。用量閘門會在額度耗盡時停止花費；速率限制則可防止突發用量瞬間耗盡額度。沒有獨立的 MCP 配額——你的代理花費的是與應用程式中相同的每授權聊天額度。 |
不額外收費即包含
確定性讀取工具——工作階段、實體與帳本、鉤子、機制、參與度、逐字稿與節拍搜尋、回顧、傳說與詞彙。它們傳回已儲存的戰役資料，不進行 AI 推論，因此可用的工具不花費額度。記憶工具仍需要 Searchable Memory。語意 search_corpus 不在此清單中；它會使用少量聊天額度。展開任一工具以查看範例輸入、範例輸出與欄位參考。
list_campaigns
不額外收取工具費用
探索工具：列出你的 MCP 金鑰可用的戰役，讓其他工具能使用正確的 campaign_id。
範例輸入
{}
範例輸出
{
"campaigns": [
{
"campaign_id": "a1b2c3d4-…",
"name": "The White Moose",
"module": "Dolmenwood"
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaigns | array | 你的帳戶所擁有的戰役。 |
| campaigns[].campaign_id | string (uuid) | 將此 id 用於以戰役為範圍的 MCP 工具。 |
| campaigns[].name | string | 戰役名稱。 |
| campaigns[].module | string | null | 選用的模組／系統標籤。 |
list_sessions
不額外收取工具費用
探索工具：列出已就緒的工作階段及其 session_number 與標題，讓代理能將「第 12 次工作階段」對應到正確的 recap_id。
範例輸入
{
"campaign_id": "a1b2c3d4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 省略 | 選用的戰役篩選條件。 |
範例輸出
{
"recaps": [
{
"recap_id": "r1e2c3a4-…",
"campaign_id": "a1b2c3d4-…",
"session_number": 12,
"title": "The Choosing",
"status": "ready"
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| recaps | array | 你的帳戶可見的已就緒工作階段。 |
| recaps[].recap_id | string (uuid) | 將此 id 用於 get_recap、get_transcript_window 與 get_mechanics_events。 |
| recaps[].campaign_id | string (uuid) | null | 擁有該工作階段的戰役。 |
| recaps[].session_number | integer | null | GM 自己的、從 1 開始的工作階段編號（DM 可編輯），若有設定時。 |
| recaps[].title | string | null | 工作階段標題。 |
| recaps[].status | string | 僅列出已就緒的工作階段。 |
get_engagement
不額外收取工具費用
戰役參與度儀表板：各發言者的參與趨勢，以及快取的跨工作階段綜合分析（摘要 + 關鍵事件時間軸）。
範例輸入
{
"campaign_id": "a1b2c3d4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要讀取的戰役。必須由你的帳戶所擁有。 |
範例輸出
{
"sessions": [
{
"recap_id": "…",
"session_ref": "S01AB",
"session_at": "2026-06-20T19:00:00Z"
}
],
"players": [
{
"speaker": "Mira",
"points": [
{
"session_ref": "S01AB",
"participation_pct": 28.4,
"turn_count": 42,
"talk_time_seconds": 612,
"word_count": 1840
}
]
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| sessions | array | 戰役中每個已就緒工作階段各一筆。 |
| sessions[].recap_id | string (uuid) | 回顧／工作階段 id。 |
| sessions[].session_ref | string | 簡短的人類可讀參照，例如 S01AB。 |
| sessions[].session_at | string (ISO 8601) | 工作階段開始的時間（UTC）。 |
| players | array | 每個辨識出的發言者各一筆。 |
| players[].speaker | string | 發言者顯示名稱。 |
| players[].points | array | 此發言者各工作階段的指標。 |
| players[].points[].participation_pct | number | 對話佔比，0–100。 |
| players[].points[].turn_count | integer | 發言回合數。 |
| players[].points[].talk_time_seconds | integer | 發言總秒數。 |
| players[].points[].word_count | integer | 發言總字數。 |
get_credit_balance
不額外收取工具費用
你的 Ask 額度使用百分比，以及近期活動摘要。原始額度計數不會向 MCP 用戶端揭露。
範例輸入
{}
範例輸出
{
"usage": {
"percent_used": 29
},
"recent_activity": [
{
"type": "recap_ready",
"label": "Session S01AB recap is ready",
"date": "2026-06-21T08:02:00Z",
"recap_id": "…"
},
{
"type": "credit",
"label": "Asked your campaign",
"date": "2026-06-21T08:05:00Z"
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| usage.percent_used | integer | 從 0 到 100 的整數 Ask 使用量。 |
| recent_activity | array | 最新在前的摘要（工作階段已錄製、回顧已就緒、額度帳本事件）。 |
| recent_activity[].type | string | 事件種類。 值：recap_ready | session_recorded | credit |
| recent_activity[].label | string | 人類可讀的摘要。 |
| recent_activity[].date | string (ISO 8601) | 事件發生的時間。 |
| recent_activity[].recap_id | string (uuid) | null | 與回顧／工作階段相關的事件才會出現。 |
get_memory_overview
不額外收取工具費用
最豐富的 GM 情境感知資料集：分佈、參與趨勢 + 整體分數、各工作階段參與度、遊玩支柱。
範例輸入
{
"campaign_id": "a1b2c3d4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要讀取的戰役。 |
範例輸出
{
"distribution": [
{
"label": "Roleplay",
"pct": 58
}
],
"engagement": {
"overall": {
"score": 74,
"label": "Playful / tense"
}
},
"pillars": [
"The green-eyed stranger",
"The old inn",
"The white moose hunt"
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| distribution | array | 各類別的遊玩佔比。 |
| distribution[].label | string | 類別名稱。 |
| distribution[].pct | number | 佔比，0–100。 |
| engagement.overall.score | number | null | 綜合參與度分數，0–100。 |
| engagement.overall.label | string | null | 質性標籤，例如「Playful / tense」。 |
| pillars | string[] | null | 反覆出現的主題／遊玩支柱。 |
get_quest_log
不額外收取工具費用
玩家可見的任務日誌。GM 的新增與編輯會透過 Discord /questlog 與隊伍分享。請勿放入 GM 機密。
範例輸入
{
"campaign_id": "a1b2c3d4-…",
"page": 1
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要讀取的你的戰役。 |
| page | integer | 選用，從 1 開始。每頁十個任務。 |
範例輸出
{
"quests": [
{
"id": "d4e5f6a7-…",
"title": "Find the missing courier",
"objective": "Follow the trail from the bridge.",
"status": "active",
"progress": "The party found a torn satchel."
}
],
"page": 1,
"has_more": false
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| quests | array | 進行中／停滯者在前，接著是已完成／已放棄。內部編輯中繼資料與來源連結會被排除。 |
| quests[].id | string (uuid) | 任務識別碼。 |
| quests[].title | string | 任務標題。 |
| quests[].objective | string | 隊伍的目標。 |
| quests[].status | string | active、stale、completed 或 abandoned。 |
| quests[].progress | string | 最新儲存的進度。 |
| page | integer | 目前頁面。 |
| has_more | boolean | 為 true 時請求下一頁。 |
get_open_hooks
不額外收取工具費用
未解決的敘事鉤子——下次工作階段該準備什麼。
範例輸入
{
"campaign_id": "a1b2c3d4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要讀取的戰役。 |
範例輸出
{
"hooks": [
{
"text": "Nobody bypasses the Choosing.",
"session_ref": "S01AB",
"session_date": "2026-06-20"
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| hooks | array | 目前開啟的敘事鉤子。 |
| hooks[].text | string | 鉤子說明。 |
| hooks[].session_ref | string | 引入該鉤子的工作階段。 |
| hooks[].session_date | string (YYYY-MM-DD) | 該工作階段的日期。 |
get_previously_on
不額外收取工具費用
戰役的前情提要脈絡，由擁有者範圍的記憶建構而成。
範例輸入
{
"campaign_id": "a1b2c3d4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要讀取的戰役。 |
範例輸出
{
"sections": [
{
"title": "Last time",
"bullets": [
"The party followed the white moose into the mist."
]
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| sections | array | 用於回顧／脈絡的戰役記憶區段。 |
| sections[].title | string | 區段標題。 |
| sections[].bullets | string[] | 精簡的記憶要點。 |
get_next_session_prep_pack
不額外收取工具費用
僅限 GM 的下一場遊戲準備建議，來自 Recap Raven 的準備快取。它可能生成一次，之後會保持快取，直到下一次回顧被匯入。回傳 credit_cost: 0。
範例輸入
{
"campaign_id": "a1b2c3d4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要準備的戰役。必須由你的帳號擁有。 |
範例輸出
{
"likely_directions": [
{
"title": "Return to the inn",
"detail": "The unresolved clue points back to the old inn."
}
],
"threads_to_watch": [
"Who opened the moonstone gate?"
],
"prep_suggestions": [
"Review the innkeeper and the gate password."
],
"credit_cost": 0,
"cache_policy": "cached_until_next_recap_ingested"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| likely_directions | array | 面向 GM 的可能下一步方向。 |
| threads_to_watch | string[] | GM 可能想留意的線索。 |
| prep_suggestions | string[] | 給 GM 的具體準備提示。 |
| credit_cost | number | 此 MCP 工具一律為 0。 |
| cache_policy | string | cached_until_next_recap_ingested。 |
get_chronicle
不額外收取工具費用
每場遊戲場景地圖 — 結構化的戰役編年史。
範例輸入
{
"campaign_id": "a1b2c3d4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要讀取的戰役。 |
範例輸出
{
"sessions": [
{
"recap_id": "…",
"session_ref": "S01AB",
"scenes": [
"The market",
"The hunt",
"The banshee fight"
]
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| sessions | array | 每場遊戲一筆項目。 |
| sessions[].recap_id | string (uuid) | 回顧／場次 id。 |
| sessions[].scenes | string[] | 該場次依序排列的場景標籤。 |
get_entity
不額外收取工具費用
由已記錄場次推導出的玩家可見實體帳冊；私人上傳的設定資料會被排除。未提供名稱時回傳名冊。提供名稱或別名時，回傳相符的卡片、互動歷史、逐字稿回合連結、關聯，或歧義候選。
範例輸入
{
"campaign_id": "a1b2c3d4-…",
"name": "Captain Vale"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要讀取的戰役。 |
| name | string | omitted | 要解析為單一卡片的實體名稱／別名。省略則回傳名冊。 |
範例輸出
{
"entity": {
"id": "…",
"canonical_name": "Captain Vale",
"kind": "npc",
"aliases": [
"Vale"
],
"search_aliases": [],
"interactions": [
{
"recap_id": "…",
"summary": "Vale warned the party.",
"turn_start": 12,
"turn_end": 16
}
],
"relations": [
{
"subject": "Captain Vale",
"predicate": "located_in",
"object": "Saltmoor Harbour",
"recap_id": "…",
"turn_start": 41,
"turn_end": 44,
"visibility": "player_known",
"session_date": "2026-05-01T00:00:00Z",
"is_current": true,
"predicate_class": "stateful"
}
]
}
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| entities | array（名冊模式） | 未提供名稱時：每個實體的 {canonical_name, kind, aliases, search_aliases}。 |
| entity | object | null（卡片模式） | 提供名稱時：解析出的實體卡片；若名稱未命中任何項目則為 null。 |
| candidates | array | 別名有歧義時的可能實體卡片；解析結果唯一時為空。 |
| entity.id | string (uuid) | 穩定的戰役實體 id。 |
| entity.canonical_name | string | 實體正式名稱。 |
| entity.kind | string | 實體種類。 值：pc | npc | creature | place | item | faction | deity | other |
| entity.aliases | string[] | 顯示用別名。 |
| entity.search_aliases | string[] | 僅供檢索用的別名。 |
| entity.interactions | array | 有依據的歷史項目，附回顧與逐字稿回合連結。 |
| entity.interactions[].recap_id | string (uuid) | 包含該互動的場次。 |
| entity.interactions[].turn_start | integer | null | 證據連結的第一個逐字稿回合。 |
| entity.interactions[].turn_end | integer | null | 證據連結的最後一個逐字稿回合。 |
| entity.interactions[].identity_match | string | confirmed 或 suggested；suggested 連結是可能的別名相符，並非正式身分主張。 值：confirmed | suggested |
| entity.relations | array | 關聯圖（由舊到新）。 |
| entity.relations[].predicate | string | 例如 located_in、ally_of、owns。 |
| entity.relations[].recap_id | string (uuid) | 為該關聯提供證據的場次。 |
| entity.relations[].visibility | string | 該邊的 GM 可見性。舊版見證前資料可能帶有 dm_only 邊 — 請勿向玩家揭露。 值：player_known | dm_only |
| entity.relations[].is_current | boolean | 具狀態述詞的現行分支。 |
get_mechanics_events
不額外收取工具費用
單一場次中以回合為錨點的機制事件（攻擊、法術、傷害、休息、狀態）— 與機制分頁相同的資料。
範例輸入
{
"recap_id": "…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| recap_id | string (uuid) | 要讀取的場次。使用 list_sessions 探索 id。 |
範例輸出
{
"recap_id": "…",
"mechanics": [
{
"action": "attack",
"actor": "Mira",
"target": "Goblin",
"damage_amount": 7,
"damage_type": "slashing",
"evidence_turn_start": 41,
"evidence_turn_end": 41
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| recap_id | string (uuid) | 這些事件所屬的場次。 |
| mechanics | array | 以回合為錨點的機制事件。 |
| mechanics[].action | string | 事件種類。 值：attack | spell_cast | short_rest | long_rest | consumable_used | condition_applied | ability_used | form_changed |
| mechanics[].actor | string | 行動者。 |
| mechanics[].evidence_turn_start | integer | 為該事件提供證據的第一個回合。 |
| mechanics[].evidence_turn_end | integer | 為該事件提供證據的最後一個回合。 |
get_lore_documents
不額外收取工具費用
該戰役的設定文件清單。
範例輸入
{
"campaign_id": "a1b2c3d4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要讀取的戰役。 |
範例輸出
{
"documents": [
{
"id": "…",
"title": "The Choosing",
"updated_at": "2026-06-20"
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| documents | array | 設定文件。 |
| documents[].id | string (uuid) | 文件識別碼。 |
| documents[].title | string | 文件標題。 |
get_lore_document
不額外收取工具費用
單一設定文件及其完整內容。
範例輸入
{
"campaign_id": "a1b2c3d4-…",
"doc_id": "…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要讀取的戰役。 |
| doc_id | string (uuid) | 要取得的設定文件。 |
範例輸出
{
"document": {
"id": "…",
"title": "The Choosing",
"body": "…"
}
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| document.id | string (uuid) | 文件識別碼。 |
| document.title | string | 文件標題。 |
| document.body | string | 完整文件內容（markdown）。 |
get_lexicon
不額外收取工具費用
詞彙表項目（正式名稱、別名、類型、信心度）。
範例輸入
{
"campaign_id": "a1b2c3d4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要讀取的戰役。 |
範例輸出
{
"entries": [
{
"id": "…",
"canonical": "Sol’Thun",
"type": "npc",
"aliases": [
"the archmage"
],
"confidence": 0.92,
"enabled": true
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| entries | array | 詞彙表項目。 |
| entries[].canonical | string | 正式名稱。 |
| entries[].type | string | 實體種類。 值：npc | place | item | creature | other |
| entries[].aliases | string[] | 替代名稱／別名。 |
| entries[].confidence | number | 擷取信心度，0–1。 |
| entries[].enabled | boolean | 此項目是否啟用。 |
get_transcript_window
不額外收取工具費用
場次已儲存回合的位置切片（不進行內容搜尋 — 僅依 from/to 回合索引）。
範例輸入
{
"recap_id": "…",
"from": 0,
"to": 20
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| recap_id | string (uuid) | 要讀取的回顧／場次。使用 list_sessions 探索 id。 |
| from | integer | 起始回合索引（含，預設 0）。 |
| to | integer | 結束回合索引。省略則從起始索引取 50 回合視窗。 |
範例輸出
{
"recap_id": "…",
"total_turns": 184,
"from": 0,
"to": 20,
"turns": [
{
"index": 0,
"t": "~00:01",
"speaker": "GM",
"text": "…"
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| total_turns | integer | 場次中的回合總數。 |
| from | integer | 回傳的起始索引。 |
| to | integer | 回傳的結束索引。 |
| turns | array | 所請求視窗中的回合。 |
| turns[].index | integer | 場次中的位置索引。 |
| turns[].t | string | 相對時間戳，例如 ~00:01。 |
| turns[].speaker | string | 發言者顯示名稱。 |
| turns[].text | string | 發言文字。 |
get_recap
不額外收取工具費用
就緒回顧的玩家安全回顧 HTML。成品類型由伺服器決定；沒有類型輸入。
範例輸入
{
"recap_id": "…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| recap_id | string (uuid) | 要取得其玩家安全回顧的回顧／場次。 |
範例輸出
{
"recap": {
"recap_id": "…",
"content_type": "player_recap_html",
"html": "<!doctype html>…",
"truncated": false
}
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| recap.recap_id | string (uuid) | 回顧／場次 id。 |
| recap.content_type | string | 一律為 player_recap_html。 值：player_recap_html |
| recap.html | string | 玩家安全回顧 HTML。 |
| recap.truncated | boolean | 當 MCP 回應上限截斷 HTML 時為 true。 |
search_transcript
不額外收取工具費用
對你的戰役逐字稿回合進行精確關鍵字（全文）搜尋。回傳包含該精確詞句的回合，附上其場次、發言者與時間戳 — 不使用 LLM、不使用嵌入、不消耗點數。
範例輸入
{
"campaign_id": "a1b2c3d4-…",
"query": "white moose",
"recap_id": "r1e2c3a4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要搜尋的戰役。 |
| query | string | 要相符的精確詞句（對逐字稿文字進行全文搜尋）。 |
| recap_id | string (uuid) | omitted | 選用的場次範圍。使用 list_sessions 探索回顧 id。 |
範例輸出
{
"query": "white moose",
"matches": [
{
"recap_id": "…",
"speaker": "GM",
"t": "~01:04",
"text": "All you know is that it’s a white moose."
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| query | string | 回傳所提交查詢的內容。 |
| matches | array | 包含該精確詞句的逐字稿回合，最相符者在前。 |
| matches[].recap_id | string (uuid) | 相符項目來自的回顧／場次。 |
| matches[].speaker | string | 相符回合的發言者。 |
| matches[].t | string | 相對時間戳，例如 ~01:04。 |
| matches[].text | string | 相符的逐字稿文字。 |
search_facts
不額外收取工具費用
對你的戰役場景節拍進行關鍵字全文搜尋 — 聊天通道用來推理的密集、逐拍摘要。最適合精確詞彙（名稱、物品、地點）。回傳節拍文字及其場景／場次脈絡與回合範圍，讓代理能定位該時刻，接著取得精確的逐字稿視窗。不使用 LLM、不使用嵌入、不消耗點數。若需自然語言、基於語意的查詢，請使用 search_corpus。
範例輸入
{
"campaign_id": "a1b2c3d4-…",
"query": "white moose hunt",
"recap_id": "r1e2c3a4-…"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要搜尋的戰役。 |
| query | string | 要對節拍文字進行相符的關鍵字（全文搜尋）。 |
| recap_id | string (uuid) | omitted | 選用的場次範圍。使用 list_sessions 探索回顧 id。 |
範例輸出
{
"matches": [
{
"recap_id": "…",
"session_number": 12,
"session_title": "The Choosing",
"scene_title": "The hunt",
"beat_index": 3,
"turn_start": 120,
"turn_end": 168,
"text": "The party tracked the white moose north of the old inn…",
"truncated": false
}
]
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| matches | array | 相符的節拍，最相符者在前。 |
| matches[].recap_id | string (uuid) | 節拍來自的場次。 |
| matches[].session_number | integer | null | GM 的場次編號（若有設定）。 |
| matches[].session_title | string | null | 場次標題（若有設定）。 |
| matches[].scene_title | string | null | 節拍所屬場景的標題。 |
| matches[].beat_index | integer | 節拍在其場景中的位置。 |
| matches[].turn_start | integer | 節拍視窗的第一個回合（可傳入 get_transcript_window）。 |
| matches[].turn_end | integer | 節拍視窗的最後一個回合。 |
| matches[].text | string | 節拍文字（上限 1200 字元）。 |
| matches[].truncated | boolean | 當節拍文字被截斷時為 true。 |
使用聊天點數
有三個工具會消耗計量的聊天點數。可想像成尋找器與答案：search_corpus（低聊天點數）會把最強的相符項目以結構化證據交給你自己的模型推理 — 是快速的尋找器，而非詳盡索引；ask_campaign_cited 以逐字稿原文引述與回合引用回答面向 GM 的問題；ask_player_campaign_cited 則透過玩家通道提供較短的玩家面向版本。除了你的餘額之外，所有工具都依 API 金鑰進行速率限制。
search_corpus
使用低聊天點數
search_corpus 即使你不知道確切措辭，也能找到相關的戰役片段。它使用語意搜尋與重新排序，回傳最有力的證據匹配，包括摘要、場次脈絡與回合範圍。它是尋找器，不是窮盡式索引：只會回傳最相符的結果，因此請把空白或單薄的結果視為「沒有浮現強烈匹配」，而非證明什麼都不存在。利用這些匹配來發掘表格實際使用的詞彙或名稱，接著用 search_facts / search_transcript 執行窮盡式的免費關鍵字搜尋，或直接把回合範圍交給 get_transcript_window 取得逐字片段。若需要對問題取得確定、經驗證的答案——逐字引文與引用——請改用 ask_campaign_cited（費用較高，回傳書面回覆而非結構化資料列）。設定 player_safe: true 可將僅限 GM 的內容排除於搜尋結果之外。每次搜尋使用少量聊天額度，任何完成的搜尋都會計費，即使沒有匹配也一樣。
範例輸入
{
"campaign_id": "a1b2c3d4-…",
"query": "when did the party first distrust the mayor?",
"player_safe": false
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要搜尋的戰役。 |
| query | string | 以自然語言描述你要找的內容。 |
| player_safe | boolean (預設 false) | 為 true 時，檢索會依可見性過濾——僅限 GM、推斷與臆測記憶，以及 GM 標記的設定資料都會被排除。供玩家會看到的任何內容使用。 |
範例輸出
{
"matches": [
{
"object_id": "…",
"type": "plot_event",
"visibility": "player_known",
"recap_id": "…",
"session_number": 8,
"session_title": "The Mayor’s Bargain",
"turn_start": 212,
"turn_end": 240,
"text": "The party noticed the mayor’s story about the missing caravan didn’t add up…",
"truncated": false
}
],
"credit_cost": "<chat credits charged for this search>"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| matches | array | 依序排列的記憶匹配，最佳匹配在前。 |
| matches[].object_id | string (uuid) | 記憶物件的 id。 |
| matches[].type | string | 記憶的種類（例如 plot_event、npc_fact）。 |
| matches[].visibility | string | 誰知道這件事。在 player_safe 搜尋中，只會是玩家可見的內容。 |
| matches[].recap_id | string (uuid) | null | 該記憶來自的場次。 |
| matches[].session_number | integer | null | GM 的場次編號（若有設定）。 |
| matches[].session_title | string | null | 場次標題（若有設定）。 |
| matches[].turn_start | integer | null | 證據範圍的第一個回合（可傳入 get_transcript_window）。 |
| matches[].turn_end | integer | null | 證據範圍的最後一個回合。 |
| matches[].text | string | 記憶摘要（上限 1200 字元）。 |
| matches[].truncated | boolean | 摘要被截斷時為 true。 |
| credit_cost | number | 此次完成搜尋所扣的聊天額度。 |
ask_campaign_cited
使用聊天額度
向你的戰役提出一個面向 GM 的事實性問題，取得 AI 答案——與應用程式內聊天相同的 beats 答案引擎，附逐字轉錄引文與回合引用。使用 GM 聊天額度，費用與應用程式內聊天相同。除餘額外，另依 API 金鑰進行速率限制。
範例輸入
{
"campaign_id": "a1b2c3d4-…",
"question": "Where did the hunter see the moose?"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要提問的戰役。 |
| question | string | 你的問題。 |
| clarification | object | 省略 | 選填：回答引擎提出的釐清問題（僅限 GM 通道）。 |
| clarification.question | string | 引擎提出的釐清問題。 |
| clarification.answer | string | 你對該問題的回答。 |
| supersedes | string | 省略 | 要取代之先前答案的訊息 id（僅限 GM 通道）。 |
範例輸出
{
"answer_markdown": "The hunter reported seeing the white moose near the old inn to the north of town [1].",
"quotes": [
{
"turn": 104,
"speaker": "Skoll",
"text": "All you know is that it’s a white moose.",
"recap_id": "…"
}
],
"confidence_label": "high",
"credit_cost": 1
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| answer_markdown | string | 附引用的答案，含行內 [n] 標記。 |
| citations | array | 支撐每個標記的引用中繼資料。 |
| quotes | array | 作為證據使用的逐字轉錄引文。 |
| confidence_label | string | 粗略的信心區間。 值：high | medium | low |
| credit_cost | number | 此答案所扣的額度。 |
| quotes[].turn | integer | 被引用的回合索引。 |
| quotes[].recap_id | string (uuid) | null | 引文來自的場次。 |
ask_player_campaign_cited
使用聊天額度
提出一個面向玩家的戰役事實性問題，取得附轉錄引用的簡短玩家安全答案。僅限 GM 的內容會由伺服器端的玩家通道排除。使用玩家聊天額度。
範例輸入
{
"campaign_id": "a1b2c3d4-…",
"question": "What do we know about the harbour?"
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| campaign_id | string (uuid) | 要提問的戰役。 |
| question | string | 你的問題。 |
範例輸出
{
"answer_markdown": "The party knows the harbourmaster helped them find the missing crate [1].",
"quotes": [
{
"turn": 104,
"speaker": "Skoll",
"text": "The harbourmaster pointed us to the crate.",
"recap_id": "…"
}
],
"confidence_label": "medium",
"credit_cost": 1
}
欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
| answer_markdown | string | 附引用的答案，含行內 [n] 標記。 |
| citations | array | 支撐每個標記的引用中繼資料。 |
| quotes | array | 作為證據使用的逐字轉錄引文。 |
| confidence_label | string | 粗略的信心區間。 值：high | medium | low |
| credit_cost | number | 此答案所扣的額度。 |
玩家安全範例
正在打造面向玩家的機器人或疊層介面？使用玩家引用工具，讓答案來自玩家通道，其依可見性過濾的帳本絕不會包含僅限 GM 的內容：
{
"tool": "ask_player_campaign_cited",
"arguments": {
"campaign_id": "a1b2c3d4-…",
"question": "What do we know about the harbour?"
}
}
你的資料會去哪裡
當你連接 MCP 用戶端並使用這些工具時，你的戰役內容會傳送給你所選的 AI 用戶端——例如 ChatGPT、Claude 或 Gemini。該供應商的資料使用與訓練條款適用於你傳送給它的內容，而非我們的條款。
Recap Raven 的不訓練保證涵蓋我們自己的流程與我們揭露的模型供應商。它無法涵蓋你連接的用戶端：一旦接上，你就是為你的戰役資料選擇了新的處理者。連接前請先確認該用戶端的條款，並對玩家會看到的任何內容使用 ask_player_campaign_cited 或玩家安全搜尋篩選（並避免僅限 GM 的讀取，如設定資料與編年史）。
有問題或意見回饋？了解 Recap Raven 的運作方式 或在下方邀請機器人。
在你的下一場跑團中使用 Recap Raven
邀請機器人、建立你的戰役，每月免費取得回顧。
無需信用卡 · 僅在取得你同桌同意後錄音 · 隨時刪除或匯出你的資料
有問題或意見回饋？加入我們的 Discord 社群 →
為 Discord 語音而打造。我們為你擷取整場跑團——事後無需登入、無需傳送檔案給我們，也無需猜測誰在說話。記憶方案會在你遊玩時持續更新你可編輯的世界維基，隨時準備回答關於發生了什麼、誰說了什麼、未解伏筆，以及下一步該準備什麼的問題。