内容
# scrivener-mcp
本地 MCP 服务器，暴露您的 Scrivener 项目给 Claude（或任何 MCP 兼容的客户端）。从头开始创建新项目，导航绑定器，读取和写入文档内容，并更新元数据 — 所有这些都不需要打开 Scrivener。
## 要求
- Node.js 18 或更高版本
- Scrivener 3 在 macOS 上（`.scriv` 包）
## 安装
```bash
cd scrivener-mcp
npm install
```
## 环境变量
| 变量 | 描述 |
|---|---|
| `SCRIV_DIR` | 包含 `.scriv` 包的目录路径。启用 `list_projects`、`open_project` 和 `create_project`。 |
| `SCRIV_PATH` | 单个 `.scriv` 包的路径。在启动时立即打开它。 |
| `SCRIV_PLATFORM` | `mac`（默认）或 `windows`。控制写入文档内容时使用的 RTF 格式。 |
必须设置 `SCRIV_DIR` 或 `SCRIV_PATH` 之一。两者可以同时设置。
## 手动运行
```bash
# 多项目模式（推荐）
SCRIV_DIR="/path/to/ScrivenerProjects" npm start
# 单项目模式
SCRIV_PATH="/path/to/MyProject.scriv" npm start
```
## 配置 Claude Desktop
编辑 Claude Desktop 配置文件：
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Mac:**
```json
{
"mcpServers": {
"scrivener": {
"command": "node",
"args": ["/absolute/path/to/scrivener-mcp/src/index.js"],
"env": {
"SCRIV_DIR": "/Users/you/Writing/ScrivenerProjects"
}
}
}
}
```
**Windows:**
```json
{
"mcpServers": {
"scrivener": {
"command": "node",
"args": ["C:\\path\\to\\scrivener-mcp\\src\\index.js"],
"env": {
"SCRIV_DIR": "C:\\Users\\you\\Documents\\ScrivenerProjects",
"SCRIV_PLATFORM": "windows"
}
}
}
}
```
保存后重启 Claude Desktop。
## 可用工具
### 项目管理
| 工具 | 描述 |
|---|---|
| `list_projects` | 列出 `SCRIV_DIR` 中的所有 `.scriv` 包。 |
| `open_project(name)` | 按名称打开项目，使其对所有文档工具都处于活动状态。 |
| `create_project(name, ...)` | 创建新项目并打开它。参见下文。 |
### 文档工具（需要打开项目）
| 工具 | 描述 |
|---|---|
| `get_outline(rootUuid?, includeContent?)` | 返回绑定器为嵌套树，包含概要、标签和状态。传递 `rootUuid` 以限定子树，传递 `includeContent: true` 以直接将正文内联到树中（一次调用而不是多次 `get_document` 调用）。理解和处理项目结构的最佳起点。 |
| `list_documents` | 返回绑定器为扁平列表，包含深度指示符。有助于获取 UUID。 |
| `get_document(uuid)` | 返回单个文档的元数据和纯文本内容。 |
| `get_documents(uuids)` | `get_document` 的批量版本 — 返回多个文档的元数据和内容，单次调用。 |
| `add_document(...)` | 向绑定器添加新文档或文件夹。 |
| `move_document(uuid, newParentUuid)` | 将绑定器项目移动到不同父文件夹。 |
| `write_document(uuid, content)` | 向文档写入新纯文本内容（存储为 RTF）。 |
| `update_metadata(uuid, changes)` | 更新标题、概要、标签、状态或编译包含。 |
| `batch_update_metadata(updates)` | `update_metadata` 的批量版本 — 应用多个更改，单次 `.scrivx` 写入。 |
| `search_documents(query)` | 在绑定器中搜索标题和概要。 |
## 创建项目
`create_project` 接受完整的绑定器结构，以便 Claude 可以从一个想法中构建整个项目，单次调用。
### 参数
| 参数 | 类型 | 描述 |
|---|---|---|
| `name` | 字符串 | 项目名称（成为 `.scriv` 包名称）。 |
| `labels` | 数组 | 标签定义。每个标签是字符串或 `{name, color}`。颜色：`red`、`orange`、`yellow`、`green`、`blue`、`purple`、`pink`、`cyan`。 |
| `statuses` | 数组 | 状态名称。默认为：To Do、In Progress、First Draft、Revised Draft、Done。 |
| `manuscript` | 数组 | 草稿（手稿）文件夹中的绑定器项目。 |
| `research` | 数组 | 研究文件夹中的绑定器项目。 |
### 绑定器项目结构
```json
{
"title": "第一章",
"type": "文件夹",
"synopsis": "爱丽丝发现信件并质问鲍勃。",
"content": "可选的初始正文（仅限文本项目）。",
"label": "视角：爱丽丝",
"status": "待办",
"includeInCompile": true,
"children": [...]
}
```
- **`type`**：`"文件夹"` 表示容器（剧本、部分、章节）；`"文本"` 表示文档（场景、笔记）。默认为 `"文本"`。
- **`synopsis`**：虚拟索引卡文本 — 在 Scrivener 的 Corkboard 和 Outliner 视图中显示。写一个 1-3 句的摘要，描述发生了什么或本项目涵盖的内容。
- **`label`** 和 **`status`** 必须与项目的 `labels` 和 `statuses` 数组中的名称匹配。
### 示例
```json
{
"name": "我的小说",
"labels": [
{ "name": "视角：爱丽丝", "color": "blue" },
{ "name": "视角：鲍勃", "color": "red" }
],
"statuses": ["待办", "初稿", "修订", "完成"],
"manuscript": [
{
"title": "第一幕",
"type": "文件夹",
"synopsis": "爱丽丝发现阴谋。",
"children": [
{
"title": "第一章",
"type": "文件夹",
"synopsis": "一个普通的星期二变得奇怪。",
"children": [
{
"title": "信件",
"type": "文本",
"synopsis": "爱丽丝在邮箱里发现了一封没有署名的信。",
"label": "视角：爱丽丝",
"status": "待办"
}
]
}
]
}
],
"research": [
{
"title": "角色",
"type": "文件夹",
"children": [
{
"title": "爱丽丝",
"type": "文本",
"synopsis": "主人公。三十多岁的记者，怀疑但好奇。"
}
]
}
]
}
```
## 协作工作流程
预期的工作模式是与 Claude 合作项目结构和内容，使用 Scrivener 自己的组织功能：
1. **从 `get_outline` 开始** — Claude 在提出或进行任何更改之前读取完整的嵌套结构和概要。这是它理解故事结构的方式。
2. **使用 `add_document` 构建结构** — 在层次结构的任何位置添加场景、章节、剧本或研究笔记。始终包括概要；它是在 Scrivener 的 Corkboard 中显示的内容。
3. **使用 `move_document` 重新组织** — 将项目移动到不同的父文件夹，以重组叙事而不丢失任何内容或元数据。
4. **使用 `write_document` 编写正文** — 一旦结构达成一致，就用内容填充场景。
5. **使用 `update_metadata` 跟踪进度** — 随着工作的进展，更新标签（例如视角、场景类型）和状态（例如初稿、修订）。
## 注意
- **在写入前关闭 Scrivener。** `write_document`、`update_metadata`、`add_document` 和 `move_document` 直接修改项目文件。服务器通过 `Files/user.lock` 文件检测打开的 Scrivener 实例，该文件由 Scrivener 创建，如果存在，则拒绝写入，以免同时编辑损坏项目。请关闭 Scrivener 并重试。
- **突变自动重新读取状态。** 每个突变调用在写入之前都会从磁盘重新加载 `.scrivx`，因此 MCP 调用之间进行的外部编辑不会被覆盖。
- **`binder.autosave` 保持同步。** 每次绑定器写入也会刷新 `Files/binder.autosave`（Scrivener 交叉引用的压缩快照）。如果没有这个，Scrivener 会认为磁盘上的绑定器比预期更新，并将 MCP 添加的项目转移到“恢复的文件”文件夹中。
- `write_document` 生成与 Scrivener 3 兼容的最小 RTF。非 ASCII 字符采用 Unicode 转义。
- 标签和状态 ID 可通过 `list_documents` 查询 — `labelId`/`statusId` 是原始 ID，`label`/`status` 是已解析的名称。
