slima

Slima MCP

适用于 Slima 的 MCP（Model Context Protocol）服务——面向小说作者的 AI 写作 IDE。

将你的 Slima 书籍连接到任何兼容 MCP 的 AI 工具——一个服务，适用于所有平台。

支持的平台

桌面应用（本地 MCP - stdio）

平台	状态	备注
Claude Desktop	✅	原生支持 MCP
ChatGPT Desktop	✅	开发者模式（2025.10+）
Gemini CLI	✅	原生支持 MCP
Cursor	✅	原生支持 MCP
VS Code	✅	通过 MCP 扩展支持

Web 应用（远程 MCP - HTTP）

平台	状态	备注
Claude.ai	✅	OAuth 登录，无需令牌
ChatGPT Web	✅	OAuth 登录，无需令牌

2025 年 12 月，Anthropic、OpenAI 和 Block 在 Linux Foundation 下共同创立 Agentic AI Foundation，MCP 因此成为行业标准。

功能

书籍管理

• 创建新书籍
• 列出并查看你的书籍
• 获取文件／文件夹结构
• 跟踪写作统计数据

文件操作

• 按路径读取任意文件
• 编辑指定文本（搜索并替换）
• 写入（替换）文件内容
• 创建新文件
• 删除文件
• 向文件追加内容
• 搜索所有文件

AI Beta 读者

• 获取虚拟读者角色的反馈
• 从不同读者视角分析章节

快速开始

选择符合你使用 AI 方式的路径：

• ⭐ 在 Web 浏览器中使用 claude.ai / ChatGPT → 推荐：Web 连接器 （仅需设置一次，之后自动更新）
• 在本地使用 Claude Desktop / Cursor / Gemini CLI → 使用 npx 本地安装
• 在隔离网络／企业环境中运行 → 自托管

推荐：claude.ai / ChatGPT Web（自动更新）

如果你在浏览器中使用 Claude 或 ChatGPT 聊天，这是最简单且最具前瞻性的方案。配置一次，即可自动获取每次 Slima MCP 更新——无需运行升级命令，也无需修改配置。

MCP URL： https://mcp.slima.ai/mcp

claude.ai（Pro / Max / Team / Enterprise）

1. 登录 claude.ai。
2. 打开 Settings → Connectors（或根据你的套餐选择 Integrations）。
3. 点击 Add custom connector。
4. 填写：
   • Name： Slima
   • URL： https://mcp.slima.ai/mcp
5. 点击 Connect → 系统会将你重定向到 slima.ai 以进行授权 → 然后返回 claude.ai。
6. 聊天输入框中会显示 Slima 工具图标。设置完成。

ChatGPT（Plus / Pro，开发者模式）

1. 登录 chatgpt.com。
2. 打开 Settings → Connectors → Advanced，并开启 Developer Mode（2025.10+）。
3. 返回 Connectors，点击 Create → Custom MCP Server。
4. 填写：
   • Name： Slima
   • Server URL： https://mcp.slima.ai/mcp
   • Authentication： OAuth
5. 点击 Create → 完成 OAuth 授权流程。

设置完成后，Slima 功能会在你的下一次对话中自动上线。无需重启或重新安装。

---

本地：Claude Desktop / Cursor / Gemini CLI

如果你希望离线使用、加快启动速度，或需要将 MCP 与其他 stdio 服务一起运行，请选择此方案。

推荐配置——固定到主版本，以便自动获取新功能，同时确保 1.0 版本发布时不会出问题：

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "slima": {
      "command": "npx",
      "args": ["-y", "slima-mcp@0"],
      "env": {
        "SLIMA_API_TOKEN": "slima_your_token_here"
      }
    }
  }
}

从 账户设置 → 已授权的应用 获取你的令牌，或运行一次 npx slima-mcp@0 auth 将其保存到磁盘。

Cursor

{
  "mcpServers": {
    "slima": {
      "command": "npx",
      "args": ["-y", "slima-mcp@0"],
      "env": {
        "SLIMA_API_TOKEN": "slima_your_token_here"
      }
    }
  }
}

Gemini CLI

gemini mcp add slima --command "npx -y slima-mcp@0"

也可以将其安装为 Gemini CLI 扩展（只需输入一次 API 令牌，它会将令牌保存在系统密钥链中）：

gemini extensions install https://github.com/slima-ai/slima-mcp

为什么使用 slima-mcp@0，而不是 slima-mcp / slima-mcp@latest？ 使用 @0 可锁定到当前主版本 — npx 会自动获取新的 0.x.y 版本（因此你能获得新功能和错误修复），但当我们发布含有破坏性变更的 1.0.0 时，如果你不更新配置，它不会悄无声息地升级到该版本。我们会在发行说明中宣布切换到 @1。

⚠️ 只有在你没有同时安装全局版 slima-mcp 时，这才成立。 npx pkg@<range> 会直接使用 PATH 上已有的软件包来满足版本范围，根本不会联系 注册表。以下结果是在 2026-09-09 测得的，当时已安装全局版 0.2.0，而 npm 上有 0.3.0：

命令	解析结果
npx -y slima-mcp@0	0.2.0 — 使用了全局安装版
npx -y slima-mcp	0.2.0 — 同上
npx -y slima-mcp@latest	0.3.0 — dist-tag 会强制查询注册表
npx -y [email protected]	0.3.0 — 全局安装版无法满足指定的较新版本

因此，过时的全局安装会导致 npx 命令悄悄停止升级，而服务仍会提示你升级。请将其移除 — 见下文。

从全局安装迁移

如果你已经使用 npm install -g slima-mcp 进行了全局安装：

# Remove the old global install — REQUIRED, not just tidiness.
# Leaving it in place makes `npx -y slima-mcp@0` resolve to the old global copy
# forever (see the warning above), so you'd stay outdated while being told to upgrade.
npm uninstall -g slima-mcp

# Then change your config `command` from "slima-mcp" to the npx form above, and restart the client.
# Verify: `npx -y slima-mcp@0 --version` must print the version shown by `npm view slima-mcp version`.

⚠️ 请检查你可能安装过它的所有位置。每个 Node 版本管理器环境和每个操作系统都可能存在一个全局安装 — 在 WSL 环境中，常见的情况是 nvm 下有一个，Windows 的 AppData/Roaming/npm 下也有一个，且两者版本不同，而 MCP 客户端实际使用的 PATH 上只有其中一个。

或者，如果你想继续使用全局安装，请记得定期运行：

npm install -g slima-mcp@latest

否则，你的本地客户端将与 Slima 后端提供的 MCP 工具和架构逐渐不一致。

自托管（高级）

你也可以克隆此仓库并自行部署 Cloudflare Worker。请参阅 wrangler.toml + npm run deploy:worker。正常使用无需此操作。

---

远程 MCP 安全性

托管的远程 MCP 服务位于 https://mcp.slima.ai/mcp，使用：

• OAuth 2.0 + PKCE 进行身份验证 — 无需复制粘贴令牌。
• 服务端不存储任何机密 — 凭据绝不会离开 Slima 的身份验证服务器。
• 基于会话：OAuth 令牌存储在 Cloudflare KV 中，并按会话隔离。
• 可随时从账户设置 → 已授权应用撤销：撤销应用后，变更会在其下一次请求时生效。

---

书籍类型：Writing Studio 与 Script Studio

Slima 书籍分为两种类型，由 book_type 字段区分。MCP 对两种类型的处理略有不同：

	📖 Writing Studio（book_type: "book"）	📝 Script Studio（book_type: "script"）
通过 MCP 创建	✅ create_book 可用	❌ 请使用 Slima 应用 UI
读取（任意文件）	✅	✅
写入 / 编辑 / 删除	✅ 任意路径	✅ 仅限 .script_studio/planning/**/*
结构化文件（series.json、*.character、*.scene、*.storyline、*.note、*.location、season.json、episode.json）	不适用	❌ 通过 MCP 只读 — 编辑必须通过 Script Studio UI 进行
analyze_chapter（AI Beta Reader）	✅	❌ 尚不支持结构化场景
search_content	所有文件	默认排除结构化文件；传入 include_structured: true 可包含这些文件

有关每本书的详细信息，请让你的 AI 客户端读取资源 slima://books/{book_token}/schema — 它会返回 JSON 规范，准确说明该书哪些路径可写、哪些只读。

list_books 会为每本书添加其工作室图标（📝 / 📖），让你（以及 AI）一眼就能区分它们。

---

可用工具

39 个工具。R = 只读（绝不会更改你的书）；W = 会更改内容，并在描述中说明。读取和写入始终使用不同的工具。

从这里开始（教学）

工具	R/W	描述
get_capabilities	R	此服务支持的内容：可写入的文件类型、内容类型、工具和指南
list_guides	R	列出 Slima 指南及各指南的加载时机
load_guide	R	完整加载一份指南
list_writing_skills	R	列出写作技巧流程（塑造角色、修改场景等）
load_writing_skill	R	完整加载一项写作技巧

书籍管理

工具	R/W	描述
create_book	W	在你的资料库中创建一本新的 Writing Studio 书籍
list_books	R	列出你资料库中的书籍（分页）
get_book	R	获取指定书籍的详细信息
get_book_structure	R	获取书籍的文件／文件夹结构
get_writing_stats	R	获取书籍的总字数

文件操作

工具	R/W	描述
read_file	R	按路径读取任意文件的内容
get_chapter	R	按路径或文件名读取章节
edit_file	W	替换指定文本片段（搜索并替换）
write_file	W	替换现有文件的全部内容
create_file	W	在书籍中创建新文件
delete_file	W	删除文件或空文件夹
append_to_file	W	在文件末尾追加内容
search_content	R	搜索所有文件中的文本
semantic_search	R	按含义而非精确词语查找段落

每次写入都会成为书籍版本历史中的一次提交，因此可以审核和撤销。

结构化文件（一次处理一个字段）

工具	R/W	描述
view_relationship_map	R	将 .map 关系图以图像和易读摘要的形式查看
update_relationship_map	W	修改关系图（.map）
update_beat_board	W	修改节拍板（.beats）
update_timeline	W	修改时间线（.timeline）
update_script	W	修改剧本（.script）
update_world_map	W	修改世界地图（.geomap）

笔记和评论

工具	R/W	描述
list_notes	R	查看作者对书籍的边注
create_note	W	在手稿旁添加笔记（不会修改正文）
list_comments	R	查看编辑评论串，包括未解决和已解决的评论
create_comment	W	添加编辑评论
resolve_comment	W	标记评论串已处理
reopen_comment	W	重新打开已解决的评论串

AI 测试读者

工具	R/W	描述
list_personas	R	列出虚拟读者角色
analyze_chapter	W	以某个角色的视角运行 AI 测试读者的章节反馈（会消耗作者的额度）
get_reader_test	R	获取仍在运行的测试读者报告

团队

工具	R/W	描述
list_teams	R	列出此账户所属的团队
get_team	R	获取某个团队的信息：成员和角色
list_team_rules	R	查看团队的指导规则（风格规范）
list_team_memories	R	查看团队已确立的内容：常驻角色、命名惯例和决策
list_team_skills	R	查看团队自己的写作流程

使用示例

配置完成后，你可以向 AI 提问：

书籍与内容：

• “创建一本名为 ‘My Novel’ 的新书”
• “列出我在 Slima 中的书籍”
• “显示我的小说结构”
• “阅读我书中的第 3 章”
• “我的写作统计数据是什么？”

文件操作：

• “读取主角的人物简介”
• “编辑第 1 章，将 ‘John’ 改为 ‘James’”
• “创建一个名为 worldbuilding.md 的新文件，记录魔法系统相关笔记”
• “搜索我书中所有提到 ‘blue eyes’ 的地方”
• “将这段新段落追加到第 5 章”

AI 反馈：

• “从年轻读者的角度评价第 5 章”
• “从评论家的角度分析我的开场场景”

CLI 命令

slima-mcp auth      # Authenticate with browser (recommended)
slima-mcp status    # Check authentication status
slima-mcp logout    # Remove saved credentials
slima-mcp --help    # Show help
slima-mcp --version # Show version

令牌保存在 ~/.slima/credentials.json 中，并采用安全权限设置。

环境变量

变量	必需	默认值	描述
SLIMA_API_TOKEN	否*	-	你的 Slima API 令牌
SLIMA_API_URL	否	https://api.slima.ai	API 端点（用于开发）
DEBUG	否	false	启用调试日志

*如果你已使用 slima-mcp auth，则不需要设置。

开发

本地 CLI 开发

# Clone the repository
git clone https://github.com/slima-ai/slima-mcp.git
cd slima-mcp

# Install dependencies
npm install

# Build CLI
npm run build

# Run tests
npm test

# Run in development mode
npm run dev

Cloudflare Worker 开发

# Build the Worker
npm run build:worker

# Run Worker locally
npm run dev:worker

# Deploy to Cloudflare
npm run deploy:worker

# Deploy to the test environment (test-mcp.slima.ai)
npm run deploy:worker:test

项目结构

slima-mcp/
├── src/
│   ├── core/           # Shared core modules
│   │   ├── api/        # Slima API Client
│   │   ├── tools/      # MCP Tool implementations
│   │   └── utils/      # Utilities and errors
│   ├── cli/            # CLI entry point (stdio transport)
│   │   ├── index.ts    # CLI main
│   │   ├── auth.ts     # Authentication commands
│   │   └── server.ts   # MCP Server for CLI
│   └── worker/         # Cloudflare Worker (HTTP transport)
│       ├── index.ts    # Worker entry point
│       └── oauth.ts    # OAuth 2.0 + PKCE client
├── wrangler.toml       # Cloudflare Worker config
├── tsup.config.ts      # CLI build config
└── tsup.worker.config.ts # Worker build config

安全

• API 令牌保存在本地，绝不会共享
• 与 Slima API 的所有通信都使用 HTTPS
• 可随时在 Slima 设置中撤销令牌

发布与部署

npm（自动）

将带有版本号变更的内容合并到 main 后，会通过 GitHub Actions 自动发布到 npm。

# 1. Bump version on dev branch
npm version patch   # 0.1.10 → 0.1.11

# 2. Merge to main
git checkout main && git merge dev && git push

# 3. CI runs tests → publish.yml publishes to npm + creates git tag

Cloudflare Worker（手动）

Worker 部署与 npm 发布相互独立，不会由任何操作自动触发。 发布到 npm 不会更新 mcp.slima.ai。远程客户端（claude.ai / ChatGPT 连接器）会连接 Worker，因此在有人手动执行以下操作之前，它们会继续使用旧的工具集：

npm run deploy:worker:test   # Test  (test-mcp.slima.ai -> test-api.slima.ai)
npm run deploy:worker        # Prod  (mcp.slima.ai      -> api.slima.ai)

先部署到测试环境，并在部署到生产环境之前检查 curl https://test-mcp.slima.ai/ | jq .version；对 mcp.slima.ai 执行同样的一行命令，即可判断 Worker 是否落后于 npm 版本。

2026-09-09：Worker 停留在 0.2.0 版本长达四个半月——它上次部署的日期正是 npm 发布 0.2.0 的当天，因此此后所有变更都只对 npm 用户生效，没有触达任何连接器用户。目前没有相关告警；版本端点是唯一的信号。

以前有一个 deploy:worker:preview 脚本，指向 [env.preview] 区块。它已于 2026-09-09 移除：其 KV ID 是字面上的占位符字符串，staging-api.slima.ai 无法解析，更严重的是，它没有定义任何 routes。在 wrangler 中，routes 是可继承的键，因此该命令会继承顶层的 mcp.slima.ai 自定义域名，并将生产环境的主机名指向预览版 Worker。真正的预发布环境是 [env.test]。

MCP Registry（手动）

要在 MCP Registry 上发布或更新服务列表：

mcp-publisher login github
mcp-publisher publish

需要在 package.json 中包含 mcpName，并在仓库根目录中包含 server.json。

运维说明

调试 Worker OAuth

排查 claude.ai 或 ChatGPT 连接器问题时：

# Live logs from production Worker
wrangler tail slima-mcp

所有 OAuth 端点都会记录关键参数（client_id、redirect_uri、令牌前缀等），以帮助追踪流程。

Worker OAuth 流程（claude.ai / ChatGPT）

Client POST /mcp → 401 + WWW-Authenticate header
  → Client GET /.well-known/oauth-protected-resource
  → Client GET /.well-known/oauth-authorization-server
  → Client POST /register (DCR)
  → Client redirects user to GET /authorize
    → Worker redirects to Rails OAuth
    → User authorizes → Rails redirects to Worker /callback
    → Worker issues auth code → redirects to client callback
  → Client POST /token (exchange code for access_token)
  → Client POST /mcp (Authorization: Bearer {access_token})

已知限制

• Worker 的 Bearer 令牌验证会接受所有非空令牌（不限于 slima_ 前缀），以支持通过 OAuth 签发的令牌。实际验证由 Rails API 执行。
• getTokenFromSession() 会先检查 Authorization 标头，然后回退到 Cookie 会话。
• MCP Inspector（npx @modelcontextprotocol/inspector）可用于独立测试完整的 OAuth 流程。

许可证

MIT

Links

• Slima Website
• Slima App
• MCP Documentation
• MCP Registry
• Report Issues