内容
# Slima MCP
[](https://www.npmjs.com/package/slima-mcp)
[](https://opensource.org/licenses/MIT)
MCP（模型上下文协议）服务器，适用于 [Slima](https://slima.ai) - 面向小说作者的 AI 写作 IDE。
将您的 Slima 书籍连接到 **任何支持 MCP 的 AI 工具** - 一个服务器，所有平台。
## 支持的平台
### 桌面应用程序（本地 MCP - stdio）
| 平台 | 状态 | 备注 |
|----------|--------|-------|
| Claude 桌面版 | ✅ | 原生 MCP 支持 |
| ChatGPT 桌面版 | ✅ | 开发人员模式（2025.10+） |
| Gemini CLI | ✅ | 原生 MCP 支持 |
| Cursor | ✅ | 原生 MCP 支持 |
| VS Code | ✅ | 通过 MCP 扩展 |
### Web 应用程序（远程 MCP - HTTP）
| 平台 | 状态 | 备注 |
|----------|--------|-------|
| Claude.ai | ✅ | OAuth 登录，无需令牌 |
| ChatGPT 网页版 | ✅ | OAuth 登录，无需令牌 |
> MCP 在 2025 年 12 月成为行业标准，当时 Anthropic、OpenAI 和 Block 共同在 Linux 基金会下成立了 Agentic AI 基金会。
## 功能
### 书籍管理
- **创建**新书籍
- 列出和查看您的书籍
- 获取文件/文件夹结构
- 跟踪写作统计数据
### 文件操作
- **读取**任意文件路径
- **编辑**特定文本（搜索和替换）
- **写入**（替换）文件内容
- **创建**新文件
- **删除**文件
- **追加**内容到文件
- **搜索**所有文件
### AI 测试读者
- 从虚拟读者角色获取反馈
- 分析章节并具有不同的读者视角
## 快速入门
**选择适合您的使用方式：**
- ⭐ 使用 **claude.ai / ChatGPT 在网页浏览器中** → [推荐：网页连接器](#recommended-claudeai--chatgpt-web-auto-updating) *(一次性设置，永久自动更新)*
- 使用 **Claude 桌面版 / Cursor / Gemini CLI 本地运行** → [本地安装 `npx`](#local-claude-desktop--cursor--gemini-cli)
- 在隔离/企业环境中运行 → [自托管](#self-host-advanced)
### 推荐：claude.ai / ChatGPT 网页版（自动更新）
如果您在浏览器中与 Claude 或 ChatGPT 聊天，这是最简单和最具未来证明的选项。**配置一次，您将自动获得 Slima MCP 的所有更新** - 无需升级命令，无需配置编辑。
**MCP URL:** `https://mcp.slima.ai/mcp`
#### claude.ai （专业版/Max/团队版/企业版）
1. 在 [claude.ai](https://claude.ai) 登录。
2. 打开 **设置 → 连接器** （或 **集成**，取决于您的计划）。
3. 点击 **添加自定义连接器**。
4. 填写：
- **名称：** `Slima`
- **网址：** `https://mcp.slima.ai/mcp`
5. 点击 **连接** → 您将被重定向到 slima.ai 进行审批 → 返回 claude.ai。
6. Slima 工具图标出现在您的聊天输入中。完成。
#### ChatGPT （Plus/Pro，开发人员模式）
1. 在 [chatgpt.com](https://chatgpt.com) 登录。
2. 打开 **设置 → 连接器 → 高级** 并启用 **开发人员模式** （2025.10+）。
3. 返回 **连接器**，点击 **创建 → 自定义 MCP 服务器**。
4. 填写：
- **名称：** `Slima`
- **服务器网址：** `https://mcp.slima.ai/mcp`
- **身份验证：** OAuth
5. 点击 **创建** → 批准 OAuth 流。
设置完成后，Slima 功能将在您的下一次对话中自动推出。无需重启，无需重新安装。
---
### 本地：Claude 桌面版 / Cursor / Gemini CLI
如果您想要离线友好操作、更快的启动速度，或者需要在其他 stdio 服务器旁边运行 MCP，请使用此选项。
**推荐配置** — 固定为主版本，以便您自动获得新功能，但永远不会在 `1.0` 版本上出现故障：
#### Claude 桌面版
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows）：
```json
{
"mcpServers": {
"slima": {
"command": "npx",
"args": ["-y", "slima-mcp@0"],
"env": {
"SLIMA_API_TOKEN": "slima_your_token_here"
}
}
}
}
```
从 [Slima 设置](https://app.slima.ai/settings/api-tokens) 获取您的令牌，或运行 `npx slima-mcp@0 auth` 一次以将其保存到磁盘。
#### Cursor
```json
{
"mcpServers": {
"slima": {
"command": "npx",
"args": ["-y", "slima-mcp@0"],
"env": {
"SLIMA_API_TOKEN": "slima_your_token_here"
}
}
}
}
```
#### Gemini CLI
```bash
gemini mcp add slima --command "npx -y slima-mcp@0"
```
> **为什么使用 `slima-mcp@0` 而不是 `slima-mcp` / `slima-mcp@latest`？** 使用 `@0` 固定在当前主版本 - npx 仍然会自动获取新的 `0.x.y` 版本（因此您会获得功能 + 错误修复），但当我们发布具有破坏性更改的 `1.0.0` 时，您不会在不更新配置的情况下悄悄获取。 我们将在发布说明中宣布 `@1` 切换。
#### 从全局安装迁移
如果您已经使用 `npm install -g slima-mcp` 全局安装：
```bash
# 删除旧的全局安装（可选但更干净）
npm uninstall -g slima-mcp
# 将您的配置 `command` 从 "slima-mcp" 更改为上面的 npx 形式，然后重启客户端。
```
或者，如果您想继续使用全局安装，请记得定期运行：
```bash
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 中，按会话范围限定。
- **随时可撤销** 从 [Slima 设置](https://app.slima.ai/settings/api-tokens)。
---
## 书籍类型：写作工作室 vs 脚本工作室
Slima 书籍有两种类型，由 `book_type` 字段区分。MCP 对每种类型略有不同：
| | 📖 写作工作室 (`book_type: "book"`) | 📝 脚本工作室 (`book_type: "script"`) |
|---|---|---|
| **通过 MCP 创建** | ✅ `create_book` 有效 | ❌ 使用 Slima 应用 UI |
| **读取** （任意文件） | ✅ | ✅ |
| **写入 / 编辑 / 删除** | ✅ 任意路径 | ✅ 仅在 `.script_studio/planning/**/*` 下 |
| 结构化文件 (`series.json`, `*.character`, `*.scene`, `*.storyline`, `*.note`, `*.location`, `season.json`, `episode.json`) | n/a | ❌ 通过 MCP 只读 - 编辑必须通过脚本工作室 UI |
| `analyze_chapter` （AI 测试读者） | ✅ | ❌ 暂不支持结构化场景 |
| `search_content` | 所有文件 | 默认情况下排除结构化文件；传递 `include_structured: true` 以包含它们 |
对于每本书的详细信息，请要求您的 AI 客户端读取资源 `slima://books/{book_token}/schema` - 它返回一个 JSON 规范，说明哪些路径对该特定书籍是可写的/只读的。
`list_books` 将每本书标记为其工作室图标（📝 / 📖），以便您（和 AI）可以一目了然地区分它们。
---
## 可用工具
### 书籍管理
| 工具 | 描述 |
|------|-------------|
| `create_book` | 在您的图书馆中创建一本新书 |
| `list_books` | 列出 Slima 图书馆中的所有书籍 |
| `get_book` | 获取特定书籍的详细信息 |
| `get_book_structure` | 获取书籍的文件/文件夹结构 |
| `get_writing_stats` | 获取书籍的写作统计数据 |
### 文件操作
| 工具 | 描述 |
|------|-------------|
| `read_file` | 读取任意文件路径的内容 |
| `edit_file` | 使用搜索和替换编辑特定文本 |
| `write_file` | 替换文件的整个内容 |
| `create_file` | 在书籍中创建新文件 |
| `delete_file` | 从书籍中删除文件 |
| `append_to_file` | 在文件末尾追加内容 |
| `search_content` | 在所有文件中搜索文本 |
### AI 测试读者
| 工具 | 描述 |
|------|-------------|
| `list_personas` | 列出可用的测试读者角色 |
| `analyze_chapter` | 获取 AI 测试读者对章节的反馈 |
## 使用示例
配置完成后，您可以询问您的 AI：
**书籍和内容：**
- “创建一个名为‘我的小说’的新书”
- “在 Slima 中列出我的书籍”
- “显示我的小说的结构”
- “读取我的书的第 3 章”
- “我的写作统计数据是多少？”
**文件操作：**
- “读取我的主角人物简介”
- “编辑第 1 章并将‘John’更改为‘James’”
- “创建一个名为 worldbuilding.md 的新文件，包含有关魔法系统的笔记”
- “在我的书中搜索所有‘蓝眼睛’的提及”
- “将此新段落追加到第 5 章”
**AI 反馈：**
- “从年轻读者角度获取第 5 章的反馈”
- “从评论家角度分析我的开场场景”
## CLI 命令
```bash
slima-mcp auth # 使用浏览器身份验证（推荐）
slima-mcp status # 检查身份验证状态
slima-mcp logout # 删除保存的凭证
slima-mcp --help # 显示帮助
slima-mcp --version # 显示版本
```
令牌存储在 `~/.slima/credentials.json` 中，具有安全的权限。
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `SLIMA_API_TOKEN` | 否* | - | 您的 Slima API 令牌 |
| `SLIMA_API_URL` | 否 | `https://api.slima.ai` | API 端点（用于开发） |
| `DEBUG` | 否 | `false` | 启用调试日志 |
*如果您使用了 `slima-mcp auth`，则不必要
## 开发
### 本地 CLI 开发
```bash
# 克隆仓库
git clone https://github.com/slima-ai/slima-mcp.git
cd slima-mcp
# 安装依赖
npm install
# 构建 CLI
npm run build
# 运行测试
npm test
# 在开发模式下运行
npm run dev
```
### Cloudflare Worker 开发
```bash
# 构建 Worker
npm run build:worker
# 在本地运行 Worker
npm run dev:worker
# 部署到 Cloudflare
npm run deploy:worker
# 部署到预览环境
npm run deploy:worker:preview
```
### 项目结构
```
slima-mcp/
├── src/
│ ├── core/ # 共享核心模块
│ │ ├── api/ # Slima API 客户端
│ │ ├── tools/ # MCP 工具实现
│ │ └── utils/ # 实用程序和错误
│ ├── cli/ # CLI 入口点（stdio 传输）
│ │ ├── index.ts # CLI 主入口
│ │ ├── auth.ts # 身份验证命令
│ │ └── server.ts # CLI 的 MCP 服务器
│ └── worker/ # Cloudflare Worker（HTTP 传输）
│ ├── index.ts # Worker 入口点
│ └── oauth.ts # OAuth 2.0 + PKCE 客户端
├── wrangler.toml # Cloudflare Worker 配置
├── tsup.config.ts # CLI 构建配置
└── tsup.worker.config.ts # Worker 构建配置
```
## 安全
- API 令牌存储在本地，从未共享
- 与 Slima API 的所有通信都使用 HTTPS
- 令牌可以从 Slima 设置中随时撤销
## 发布和部署
### npm（自动）
将版本提升到 `package.json` 中的 `main` 分支，触发自动 npm 发布 via GitHub Actions。
```bash
# 1. 在 dev 分支上提升版本
npm version patch # 0.1.10 → 0.1.11
# 2. 合并到 main
git checkout main && git merge dev && git push
# 3. CI 运行测试 → publish.yml 发布到 npm + 创建 git 标签
```
### Cloudflare Worker（手动）
Worker 部署与 npm 分开。在代码更改后部署：
```bash
npm run deploy:worker # 生产环境（mcp.slima.ai）
npm run deploy:worker:preview # 预览环境
```
### MCP 注册表（手动）
要发布/更新 [MCP 注册表](https://registry.modelcontextprotocol.io/) 上的服务器列表：
```bash
mcp-publisher login github
mcp-publisher publish
```
需要在 `package.json` 中填写 `mcpName` 和仓库根目录下的 `server.json`。
## 操作说明
### 调试 Worker OAuth
在排查 claude.ai 或 ChatGPT 连接器问题时：
```bash
# 生产环境的实时日志
wrangler tail slima-mcp
```
所有 OAuth 端点都记录关键参数（client_id、redirect_uri、token prefix 等）以帮助跟踪流程。
### Worker OAuth 流（claude.ai / ChatGPT）
```
客户端 POST /mcp → 401 + WWW-Authenticate 头
→ 客户端 GET /.well-known/oauth-protected-resource
→ 客户端 GET /.well-known/oauth-authorization-server
→ 客户端 POST /register (DCR)
→ 客户端重定向用户到 GET /authorize
→ Worker 重定向到 Rails OAuth
→ 用户授权 → Rails 重定向到 Worker /callback
→ Worker 发出 auth 代码 → 重定向到客户端回调
→ 客户端 POST /token（交换代码为 access_token）
→ 客户端 POST /mcp（Authorization: Bearer {access_token}）
```
### 已知约束
- Worker Bearer 令牌验证接受所有非空令牌（不仅限于 `slima_` 前缀）以支持 OAuth 发出的令牌。Rails API 执行实际验证。
- `getTokenFromSession()` 首先检查授权头，然后回落到 cookie 会话。
- MCP Inspector (`npx @modelcontextprotocol/inspector`) 有助于独立测试完整的 OAuth 流。
## 许可证
MIT
## 链接
- [Slima 网站](https://slima.ai)
- [Slima 应用](https://app.slima.ai)
- [MCP 文档](https://modelcontextprotocol.io)
- [MCP 注册表](https://registry.modelcontextprotocol.io/)
- [报告问题](https://github.com/slima-ai/slima-mcp/issues)
