Slima MCP

第一次設定 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；或手動到 Account → API tokens 拿。

• 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。為什麼遷移、怎麼遷移。

工具參考

• 01

  書本管理工具（5 個）

  Slima MCP 提供 5 個書本層級工具：create_book / list_books / get_book / get_book_structure / get_writing_stats。各自輸入輸出 + 範例。

• 02

  檔案操作工具（7 個）

  讀寫檔案層的 7 個 tool：read_file / edit_file / write_file / create_file / delete_file / append_to_file / search_content。權限規則 + 範例。

• 03

  AI 讀者工具（2 個）

  兩個 MCP tool 涵蓋 AI Beta Reader 服務：list_personas、analyze_chapter。輸入輸出 + 跟 Slima 內試讀的對應。

寫作 vs 劇本工作室

• 01

  兩個工作室的 MCP 行為對照表

  Writing Studio vs Script Studio 在 MCP 下的行為對照——哪些路徑可寫、哪些唯讀、結構化檔案的特殊處理。

• 02

  劇本工作室結構化檔案保護

  劇本工作室所有結構化檔案（場景 / 角色 / 故事線 / 季 / 集）在 MCP 下唯讀。只有 `.script_studio/planning/**/*` 可寫。為什麼這樣 + 怎麼繞過（不繞）。

• 03

  劇本工作室特定工具的限制

  search_content 預設排除結構化檔案、analyze_chapter 不支援場景檔案。這些限制怎麼繞過 / 怎麼補救。

進階：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。

疑難排解

• 01

  MCP 連不上：401 / Authorization header

  MCP 連不上最常見原因：401 Unauthorized。常見成因：token 過期 / config 沒設好 / WWW-Authenticate flow 失敗。各種診斷步驟。

• 02

  Token 過期 / 需要重連

  Token 有 TTL—— OAuth 30 天、personal token 90 天。過期會回 401 + reauth_url。怎麼判斷 / 重新拿。

• 03

  寫入被拒：怎麼處理

  MCP 寫入失敗 400 INVALID_PATH 多半是劇本工作室結構化檔案——改去 Slima app UI 或寫到 .script_studio/planning/。

• 04

  進階：Debug OAuth 流程

  OAuth 9 步流程：DCR → authorize → callback → token → mcp。用 wrangler tail / curl 追蹤哪一步失敗。