Pure Writer MCP

让 AI 的分散修改，准确落回 Pure Writer 2。

A Windows MCP server for reading and editing Pure Writer 2 manuscripts, with revision checks, exact text patches, backups, native history, and undo. 中文说明见下文；English quick start.

适合小说的文风、对白、叙述和多章零散修改：助手先读上下文，再把多处修改一次提交，保留未改部分的缩进和换行。也支持新建章节、续写、整章更新、分卷和 TXT 导出。

这是独立的社区项目，与 Pure Writer 官方无隶属关系。适配使用 Windows 客户端的本地 SQLite 数据库，不是官方实时编辑接口。目前推荐 Python 3.14，使用 MCP Python SDK 2.3.0，通过 stdio 接入支持 MCP 的助手。

安装

在 Windows PowerShell 中，进入下载或克隆得到的项目目录：

py -3.14 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-lock.txt

数据库目录须同时包含 Room.db 和 History.db。默认查找当前用户的 Documents/PureWriter/App；如果文档文件夹被重定向到 OneDrive 或其他位置，请显式设置路径。

选择 AI 客户端

现有 Codex / Antigravity 接入已扩展为 13 种配置方案：Claude Desktop、Claude Code、Cursor / Cursor CLI、Gemini CLI、VS Code / Copilot、Copilot CLI、Cline、Roo Code、OpenCode、Windsurf 和 Devin Desktop。完整路径、格式及接入命令见 客户端适配指南。

配置助手默认只预览，且默认仅处理 Codex：

.\.venv\Scripts\python.exe configure_clients.py --client codex
.\.venv\Scripts\python.exe configure_clients.py --client codex --apply

--client antigravity 仅处理 Antigravity，--client both 处理两者。脚本仅更新 purewriter 条目，在原配置旁保存备份并保留其他设置。

按需要指定路径和默认书籍，同一组参数先预览，再加 --apply：

.\.venv\Scripts\python.exe configure_clients.py --client codex --data-dir 'C:\Path\To\PureWriter\App' --book '我的小说'

重载 MCP 或重启助手后，调用 pw_get_status。当前版本应为 2.1.0，共 21 个工具。书名可以不预设：先用 pw_list_books 找到书籍 ID，再在工具参数中明确指定 book。

通用配置与环境变量

可用 --list-clients 查看适配器，--print-config 输出所选客户端格式的片段；--project-dir 指定项目，--config-path 指定实际配置文件，--client 可重复选择多个客户端。脚本保留原有权限设置和 JSONC 的其他条目及注释。

将 JSON 配置示例 中的绝对路径改为自己的路径，放进客户端的 MCP 配置。command 必须指向已安装依赖的 Python，args 指向本项目的 purewriter_mcp_server.py。

Related MCP server: Novel Workspace MCP

使用

各类 agent 的参数约定、失败重试和完整改稿规则见 AGENT_WORKFLOW.md。

可以这样请求助手：

读取《我的小说》第一章，把这几处直接说明情绪的句子改成动作和对白，保留人物设定、事实和因果。先检查差异，再通过 Pure Writer MCP 落实，给我修改摘要。

本地稿有更新。对齐书籍和章节，核对正文差异后更新到 Pure Writer；遇到同名章节用 ID 区分，新增或拆章时先说明结构变化。

正式提交前，请在 Pure Writer 中保存并退出。读取和预览可在客户端运行时进行，但未保存的编辑可能尚未出现在数据库中。提交过程中也应保持客户端关闭；服务不会强关或自动重启应用。

推荐工具流程：

1. 用 pw_list_books / pw_get_book_outline 确定书籍和章节 ID。

2. 用 pw_read_chapter / pw_read_chapters 读取上下文和 revision。

3. 用 pw_batch_patch(dry_run=true) 预览。同章的所有修改放在同一个 edits 数组中。

4. 校验通过后，使用相同修改参数、dry_run=false 和唯一 request_id 提交。

5. 保存返回的 operation_id，再次读取正文核对；需要撤销时用 pw_undo_operation。

预览示例（替换占位 ID、版本和原文）：

{
  "book": "书籍ID",
  "changes": [{
    "chapter_id": "章节ID",
    "expected_revision": "读取章节返回的revision",
    "edits": [
      {"old_text": "　　门口很冷。", "new_text": "　　他把手缩进袖口。"},
      {"old_text": "　　他笑了。", "new_text": "　　他扯了一下嘴角。"}
    ]
  }],
  "label": "第一章：动作与对白调整",
  "dry_run": true,
  "request_id": "为本轮生成一个UUID"
}

每条 old_text 都匹配修改前的正文，不能依赖上一条刚生成的文字。原文缺失、匹配多处、范围重叠、跨书籍 ID 或版本冲突都会拒绝整轮提交。需要全局替换时才显式使用 replace_all=true。单次最多 100 章、每章 500 处修改。

网络或进程响应丢失后，重试相同操作应复用 request_id；不同内容使用新 ID。replayed=true 表示返回历史操作收据，并不表示当前稿件仍停留在那个版本。出现版本冲突必须重读核对，不能只替换版本号强行写入。

工具一览

正文写入默认仅预览。现有章节修改要求 expected_revision，实际数据库提交要求 request_id。删除使用软删除。

pw_diff_with_txt 只检查忽略空白后的正文包含关系，不能判断哪份更新，也不能发现 TXT 独有章节。本地稿更新需要助手检查章节映射和实际差异，没有自动双向同步。TXT 导出默认另存，覆盖现有文件须提供其当前 SHA-256。

备份与恢复

• 每轮提交前，通过 SQLite backup API 创建 Room.db 和 History.db 快照，并检查压缩包 CRC。

• 备份位于 <数据目录>/Backups/MCP_Backups/<operation_id>/databases.zip。

• 原生时光机保存修改前后内容；本服务的操作日志位于 <数据目录>/MCP/operations.db。

• 跨进程文件锁串行化 MCP 写入；SQLite 写锁内再次校验版本，事务同时提交正文、历史与操作记录，并核对写入结果。

• 仅支持 rollback journal 模式。遇到 WAL / MEMORY / OFF 会拒绝写入，不修改应用的 journal 设置。

• pw_undo_operation 只回退对应操作涉及的记录，发现后续编辑就停止；不会用整库覆盖的方式撤销一次润色。

• 服务不会修改原生 Buffer.txt 或标签缓存。客户端刷新、移动端和云同步需独立确认；数据库读回成功不能替代这些检查。

备份和日志含有完整私有稿件，请像原稿一样保管。MCP 服务本身没有网络上传代码，但接入的 AI 客户端会收到工具返回的正文，应按所选客户端的数据处理规则使用。

开发与测试

.\.venv\Scripts\python.exe -B -X utf8 -m unittest discover -s tests -v

# 启用真实 stdio 子进程测试，仅写临时合成数据库。
# 需 Windows 进程查询权限，并先退出 Pure Writer。
$env:PW_RUN_PROTOCOL_TEST='1'
.\.venv\Scripts\python.exe -B -X utf8 -m unittest discover -s tests -v

测试全部使用程序生成的示例数据。Windows CI 运行完整测试，包括多章原子写入、冲突拒绝、重试幂等、历史回退、备份和配置保留。贡献说明见 CONTRIBUTING.md。

许可证

MIT。许可证适用于本仓库代码和文档，不包含 Pure Writer 软件本身，也不涵盖使用者的小说或其他稿件。