slima-mcp: Instructions file for Claude Code

CLAUDE.md - Slima MCP

此文件提供 Claude Code 理解專案的必要上下文。

專案概述

Slima MCP (slima-mcp on npm) 是一個 MCP (Model Context Protocol) 伺服器，讓所有支援 MCP 的 AI 工具都能與 Slima 書籍管理和 AI Beta Reader 功能互動。

支援平台（MCP 已成為業界標準）

平台	狀態	備註
Claude Desktop	✅	原生支援
ChatGPT Desktop	✅	Developer Mode (2025.10+)
Gemini CLI	✅	原生支援
Cursor	✅	原生支援
Clawdbot	✅	Via Skills
VS Code	✅	Via MCP extensions

2025.12 MCP 捐給 Linux Foundation (AAIF)，由 Anthropic + OpenAI + Block 共同創立。

架構定位

┌─────────────────┐     MCP (STDIO)     ┌─────────────────┐     HTTP/REST     ┌─────────────────┐
│  Claude Desktop │                     │                 │                   │                 │
│  ChatGPT        │ ◄─────────────────► │   slima-mcp     │ ◄───────────────► │   slima_rails   │
│  Gemini CLI     │                     │   (npm 套件)    │                   │   (API)         │
│  Cursor / etc.  │                     │                 │                   │                 │
└─────────────────┘                     └─────────────────┘                   └─────────────────┘
     AI 工具                              Thin Client                          業務邏輯

Thin Client 架構：

• MCP Server 只負責協議轉換，不包含業務邏輯
• 所有資料驗證、權限控制、AI 處理都在 Rails API 端
• 保持 MCP Server 輕量，易於維護和升級

---

技術棧

類別	技術	版本
Runtime	Node.js	20+
Language	TypeScript	5.x
MCP SDK	@modelcontextprotocol/sdk	1.x
Validation	Zod	3.x
Build	tsup	8.x
Testing	Vitest	2.x

---

目錄結構

slima-mcp-server/
├── src/
│   ├── api/
│   │   ├── client.ts      # Slima API Client (HTTP 請求)
│   │   ├── types.ts       # TypeScript 型別定義
│   │   └── index.ts       # 匯出
│   ├── tools/
│   │   ├── books.ts       # 書籍工具 (4 tools)
│   │   ├── content.ts     # 內容工具 (1 tool)
│   │   ├── beta-reader.ts # Beta Reader 工具 (2 tools)
│   │   ├── files.ts       # 檔案操作工具 (6 tools)
│   │   └── index.ts       # 匯出
│   ├── utils/
│   │   ├── errors.ts      # 錯誤類別和格式化
│   │   └── logger.ts      # 日誌 (輸出到 stderr)
│   ├── server.ts          # MCP Server 工廠
│   └── index.ts           # CLI 入口點
├── tests/
│   ├── api/
│   │   └── client.test.ts # API Client 測試
│   ├── tools/
│   │   ├── books.test.ts        # 書籍工具測試
│   │   ├── content.test.ts      # 內容工具測試
│   │   └── beta-reader.test.ts  # Beta Reader 測試
│   └── server.test.ts     # Server 初始化測試
├── dist/                  # 編譯輸出 (gitignored)
├── package.json
├── tsconfig.json
├── tsup.config.ts         # Build 設定 (含 shebang)
├── vitest.config.ts       # 測試設定
└── README.md              # 使用者文件