Slima MCP

從 Claude / ChatGPT / Cursor / Gemini 讀寫你的 Slima 書

第一次設定 MCP

• 01 什麼是 Slima MCP MCP（Model Context Protocol）是 AI 工具讀寫外部系統的標準。Slima MCP 讓 Claude / ChatGPT / Cursor / Gemini 直接讀寫你 Slima 上的書。
• 02 Slima MCP vs file MCP vs 內建 AI 寫作教練 三條路線怎麼選：Slima MCP（API 接書）、file MCP（指向你電腦上的檔案夾）、內建 AI 寫作教練（Slima 編輯器右側）。
• 03 兩種連接方式：Web vs 本機 Slima MCP 兩條連接路徑：Web（OAuth 跳轉、claude.ai / ChatGPT 用）vs 本機 stdio（要安裝 npm 套件、Claude Desktop / Cursor / Gemini CLI 用）。

Web 連接（OAuth）

• 01 在 claude.ai 連接 Slima（推薦） 在 claude.ai 加 Slima MCP 為 Custom Connector。OAuth 流程、需要的方案（Pro / Max / Team / Enterprise）。
• 02 在 ChatGPT 連接 Slima ChatGPT 連 Slima MCP 需要 Developer Mode（2025.10+）+ Custom MCP Server + OAuth。ChatGPT Plus/Pro 才有 Custom MCP。

本機連接（stdio）

• 01 連接 Claude Desktop Claude Desktop 本機接 Slima MCP：編輯 claude_desktop_config.json + npx slima-mcp@0 + token 環境變數。Mac / Win 路徑。
• 02 連接 Cursor Cursor 加 Slima MCP：Settings → MCP → 加 server + 跑 npx slima-mcp@0。跟 Claude Desktop 類似但 UI 不同。
• 03 連接 Gemini CLI Gemini CLI 加 Slima MCP：gemini mcp add slima --command "npx -y slima-mcp@0"。需要 Gemini CLI ≥ 0.4。
• 04 連接 VS Code VS Code 連 Slima MCP 透過 MCP 擴充套件。常用：MCP Tools / Continue。

Token 管理

• 01 取得 SLIMA_API_TOKEN 兩條路：跑 npx slima-mcp@0 auth 瀏覽器登入並存到 ~/.slima/credentials.json；或在無瀏覽器的 server / CI 手動設 SLIMA_API_TOKEN。
• 02 slima-mcp CLI 指令大全 `slima-mcp` 套件的全部 CLI 指令：auth / status / logout / --help / --version。所有指令說明 + 範例。
• 03 管理已授權應用程式 Account → API tokens / 已授權應用程式：看誰連著你的帳號、上次使用時間、撤銷單一或批次。

版本與升級

• 01 為什麼用 `slima-mcp@0`：版號策略 config 範例都用 slima-mcp@0 而不是 slima-mcp。@0 是 major version pin：自動拿 0.x patch / minor 更新，但 1.0 breaking change 要你手動切。
• 02 從 `npm install -g` 遷移到 `npx` 舊版本用 npm install -g slima-mcp 全域裝。新版改成 npx -y slima-mcp@0。為什麼遷移、怎麼遷移。
• 03 slima-mcp 版本怎麼運作 0.3.0（2026-09-09）。伺服器不擋舊版，舊版只是少工具可呼叫；怎麼確認自己在跑哪一版、怎麼升上去。

工具參考

• 01 書本管理工具（5 個） Slima MCP 提供 5 個書本層級工具：create_book / list_books / get_book / get_book_structure / get_writing_stats。各自輸入輸出 + 範例。
• 02 檔案操作工具 read_file / edit_file / write_file / create_file / delete_file / append_to_file / search_content 的參數與行為，以及哪些檔案型別這一組動不了。
• 03 AI Beta Reader 工具（2 個） 兩個 MCP tool 涵蓋 AI Beta Reader 服務：list_personas、analyze_chapter。輸入輸出 + 跟 Slima 內試讀的對應。
• 04 結構化編輯工具（update_*） update_* 工具怎麼改節拍看板、年表、劇本、關係圖與世界地圖：一次一個操作、op_ref 串接、整批全有全無。
• 05 筆記與評論工具 讓外部 AI 讀寫筆記、參與評論往返：list_notes / create_note / list_comments / create_comment / resolve_comment / reopen_comment。
• 06 語意檢索與全文搜尋 semantic_search 按意思找、search_content 按字面找。什麼問題該用哪一支，以及索引是怎麼建的。

檔案型別與權限

• 01 MCP 對每種檔案能做什麼 完整對照表：散文檔整檔可寫、五種結構化檔走欄位級工具、哪些完全不可寫，以及舊劇本工作室書的路徑規則。
• 02 結構化檔案的保護：拒絕訊息怎麼讀 AI_READONLY_FILE_TYPE / SUBSCRIPTION_REQUIRED / INVALID_PATH / FOLDER_NOT_EMPTY 各是什麼意思，下一步該做什麼。
• 03 哪些工具在特定檔案上會不一樣 read_file、search_content、semantic_search、analyze_chapter、get_writing_stats、create_file、delete_file 的例外行為與補救。

進階：Schema 與 Self-host

• 01 用 schema resource 查精確權限 MCP resource `slima://books/{book_token}/schema` 回傳該書的精確 read-only / writable path 規則：AI 可以用這個確定能不能寫某個路徑。
• 02 Self-host Cloudflare Worker（進階） Slima MCP server 開源在 Cloudflare Worker。可以 fork + 自己部署、改 OAuth flow / 加 middleware。
• 03 指南與寫作技能 get_capabilities、Slima 自己的操作指南與寫作技能：Slima 怎麼把自己的規範餵給你的 AI 工具。
• 04 讓 AI 看見關係圖 view_relationship_map 回一張圖加一段可讀摘要，比讀 .map 原始 JSON 好用；四種你會遇到的回覆。

疑難排解

• 01 MCP 連不上：401 / Authorization header MCP 連不上最常見原因：401 Unauthorized。常見成因：token 過期 / config 沒設好 / WWW-Authenticate flow 失敗。各種診斷步驟。
• 02 Token 過期 / 需要重連 MCP token 由 Slima OAuth 登入發出，會定期過期。過期會回 401；重新授權（Web 端通常自動）即可。怎麼判斷 / 重新拿。
• 03 寫入被拒：怎麼處理 AI_READONLY_FILE_TYPE / SUBSCRIPTION_REQUIRED / INVALID_PATH / FOLDER_NOT_EMPTY 各代表什麼，以及 create_file 成功但檔案是空的那一種。
• 04 進階：Debug OAuth 流程 OAuth 9 步流程：DCR → authorize → callback → token → mcp。用 wrangler tail / curl 追蹤哪一步失敗。