Writing MCP

mcp-writing

一款 MCP 服务，用于辅助 AI 推理和编辑长篇小说项目。

专为 OpenClaw 设计，也兼容任何支持 MCP 的 AI 网关。

快速启动

对于本地 stdio MCP 客户端，可直接运行已发布的软件包：

WRITING_SYNC_DIR=/path/to/sync-dir DB_PATH=./writing.db npx -y @hanna84/mcp-writing

CLI 包装器默认使用 stdio 传输方式，并会在需要时自动添加 Node 22 SQLite 标志。

VS Code 扩展

对于 VS Code 原生设置流程（包括散文风格指南设置），请使用：

• hannasdev/mcp-writing-vscode

功能

mcp-writing 不会将整部手稿交给 AI 并寄望它能装进上下文窗口，而是根据场景文件构建结构化索引。AI 会先查询该索引，查找相关角色、情节点和剧情梗概，然后只加载所需的具体文本。

当前状态：

• 核心平台已完成： 已实现元数据优先分析、以 SQLite 为规范来源的结构和关系元数据、兼容性旁路文件维护、带确认和 git 历史的 AI 辅助文本编辑、审阅包，以及 Scrivener Direct 提取。
• 近期已完成： Human Input Forgiveness 让选定的请求边界输入更宽容，明确了关键词元数据搜索的边界，并记录了临时测试夹具回放验证，同时保留稳定的规范 ID。
• 积极开发中： 当前未选定任何计划。
• 延期的待办事项： OpenClaw 集成、与客户端无关的设置、分部和嵌入搜索。
• 想法和待解决问题： 单独跟踪，避免未来探索影响当前路线图。

适用对象

• 创作长篇小说的小说家和写作团队，作品包含大量场景、角色和连续性约束。
• 希望通过定向检索上下文，而非提示整部手稿的 AI 辅助编辑工作流。
• 需要可追溯、可撤销的编辑，并确保元数据随草稿演进保持同步的项目。

文档

指南	描述
docs/guides/setup.md	前置条件、首次设置、Scrivener 导入、本机同步格式
mcp-writing-vscode	用于客户端原生设置流程的 VS Code 扩展
docs/guides/docker.md	Docker Compose、部署操作、MCP 网关说明
docs/guides/backup-recovery.md	项目备份文件、诊断和明确的恢复工作流
docs/guides/sidecar-compatibility.md	Sidecar 兼容角色、迁移策略和日常工作中的权限边界
docs/foundations/managed-structure-contract.md	结构变更、生成视图、导入和维护工作流的设计边界
docs/agents/tools.md	完整工具参考——根据源代码自动生成
docs/agents/README.md	面向 Agent 的指南、示例和启动文件索引
docs/agents/use-cases.md	面向 Agent 的对话记录和提示词/工具示例
docs/guides/development.md	本地运行、测试、环境变量、故障排除

破坏性变更

describe_workflows 接口重新设计

describe_workflows 现在提供以结果为先、以发现为先的工作流地图。如果你的提示词或自动化依赖此前的工作流 ID 或排序，这是一项破坏性变更；新增的 recommended_next_actions 层级为附加内容，会显示在完整目录之前。

根据以下映射更新集成：

• manuscript_exploration -> question_driven_discovery（如果任务是检查散文，则使用 targeted_scene_reading）
• prose_editing -> safe_scene_revision
• character_management -> character_understanding
• place_management -> place_understanding
• review_bundle -> review_preparation

新增的工作流 ID：

• thread_understanding
• parity_recovery

风格指南工作流仍然可用，但不再被列为主要日常工作流的一部分。

find_scenes 和 get_arc 响应结构标准化

find_scenes 和 get_arc 现在始终返回结构化封装，包括非分页调用。

• 封装字段：results、total_count。
• 分页启用时会包含分页字段。
• 相关时会包含 warning / next_step。

如果你的集成此前会将非分页调用的原始数组作为响应处理，请更新集成，使其始终按封装格式解析。

安全解析模式：

const parsed = JSON.parse(toolText);
if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
const scenes = parsed.results ?? [];
const totalCount = parsed.total_count ?? scenes.length;
const warning = parsed.warning ?? null;
const nextStep = parsed.next_step ?? null;

get_character_sheet、get_place_sheet、list_scene_references、get_relationship_arc 响应结构标准化

这些元数据读取工具现在返回结构化封装，而不是扁平对象或原始数组。

• get_character_sheet 和 get_place_sheet：此前返回字段值的扁平对象；现在返回 { results: [row], total_count: 1, next_step }。
• list_scene_references：此前返回 { references, scene_id, project_id }；现在返回 { results, total_count, scene_id, project_id }。
• get_relationship_arc：此前返回原始 JSON 数组；现在返回 { results, total_count, from_character, to_character }。

表单工具的安全解析模式：

const parsed = JSON.parse(toolText);
if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
const sheet = parsed.results?.[0] ?? {};
const nextStep = parsed.next_step ?? null;

列表/弧线工具的安全解析模式：

const parsed = JSON.parse(toolText);
if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
const items = parsed.results ?? [];
const totalCount = parsed.total_count ?? items.length;

规范 ID 与宽容输入

稳定 ID 仍是项目、章节、场景、角色、地点和关系写入的规范标识。已知 ID 时，请准确传入。

现在，有些请求边界字段接受明确无歧义、符合人类习惯的输入，例如场景标题、角色名称、地点名称或大小写变体。成功调用的工具仍会写入并返回规范 ID；如果输入解析自非规范值，还会提供 resolved_from 详情。对于有歧义的匹配、相近匹配或仅供建议的值，工具会失败或返回建议，但不会修改规范状态。

标签和 Save the Cat 节拍仍属于自由编辑词汇。find_scenes 可以匹配现有标签和节拍的大小写变体，元数据更新也可以建议相近的现有词汇，但除非你有意修改，否则提供的标签和节拍文本会保持原样。

search_metadata 是针对已索引标题、梗概、标签、角色、地点和版本的关键词／全文搜索。它不是语义搜索，也不会搜索正文文本；元数据搜索或结构化筛选找到可能的场景后，请使用 get_scene_prose。语义／正文搜索仍列在 Embedding-Based Search 待办事项中。

使用场景

1) 在将章节发送给测试读者前进行连续性检查

目标：分享页面前发现不一致之处。

1. 在最近一次写作后运行 sync。
2. 使用 find_scenes 查找涉及特定角色或标签的场景（例如所有标记为 injury 或 promise 的场景）。仍建议优先使用规范 ID，但角色／视角筛选器可以解析项目范围内无歧义的角色名称，标签和节拍筛选器可以建议相近匹配项，而 chapter_id 接受精确 ID 或无歧义的大小写变体。
3. 使用 get_arc 查看该角色在整部手稿中的有序发展历程。
4. 仅使用 get_scene_prose 加载可疑场景。
5. 对需要修正连续性的场景，使用 flag_scene 添加后续备注。

结果：你可以一次检查一条叙事线，而不必重读整部小说来查找矛盾。

2) 修订期间规划和追踪副线节拍

目标：确保副线有意推进，并按时收束。

1. 对项目运行 list_threads。
2. 使用 get_thread_arc 检查每条副线的场景顺序和节拍标签。
3. 缺少节拍时，调用 track_thread_arc，在正确场景中添加或更新节拍。
4. 重新运行 get_thread_arc，确认节奏和覆盖情况。

结果：副线结构清晰可见且便于审查，从而减少后期草稿中副线遗漏的情况。

3) 大幅改写正文后收紧场景元数据

目标：保持索引准确，无需手动重新标记所有内容。

1. 重写场景后，调用 enrich_scene，从当前正文中重新推导轻量级元数据。
2. 使用 update_scene_metadata 更新有意设置的编辑字段（例如节拍、视角、状态和标签）。标签和节拍仍为自由格式；工具会保留提供的文本，并在值与现有词汇相似时返回建议。该工具会拒绝场景 characters 和 places；当场景能证明成对的、由资料表支持的角色／地点证据时，请使用 connect_character_place_evidence；仅有角色证据时使用 connect_scene_character_evidence；仅有地点证据时使用 connect_scene_place_evidence。这些关系证据工具优先使用规范 ID，但也接受明确无歧义的场景标题、角色名、地点名和大小写变体；匹配结果有歧义或仅为建议时，操作会失败且不会更改状态。对于保留的 sidecar／frontmatter 关系字段，请使用 audit_relationship_metadata。对于章节归属和排序，请使用 list_chapters，并配合 assign_scene_to_chapter 或 move_scene。
3. 使用 search_metadata，在已索引的标题、梗概、标签、角色、地点和版本中执行关键词／FTS 元数据搜索；使用 find_scenes 验证是否能通过结构化筛选条件找到场景。确定可能的场景后，使用 get_scene_prose 查看正文上下文。

结果：AI 助手能够可靠地找到合适的场景，同时不偏离手稿内容。

4) 安全地使用 AI 辅助逐行编辑并支持回滚

目标：让 AI 提议正文编辑，同时不失去对草稿的控制。

1. 要求 AI 针对特定场景调用 propose_edit。
2. 检查暂存的差异。
3. 使用 commit_edit 接受，或使用 discard_edit 拒绝。
4. 使用 list_snapshots（以及可选的 snapshot_scene）检查或保留修订历史。

结果：你可以享受 AI 的速度，同时明确审批每项更改，并为所有已应用的更改保留可恢复的历史记录。

5) 导入或大幅改写后刷新场景与角色的关联

目标：在导入正文更改或元数据漂移后，以可控方式重建场景与角色的关联。

1. 从 enrich_scene_characters_batch 开始，使用默认的 dry_run=true，预览针对项目、章节或明确指定场景列表推断出的关联。
2. 轮询 get_async_job_status，直到批处理作业完成，然后检查 job.result.results 中的已更改场景、歧义匹配和部分失败。
3. 如果更改涉及重要的连续性内容或角色众多的章节，请使用 get_scene_prose 抽查几个受影响的场景。
4. 预览结果看起来正确后，使用 dry_run=false 重新运行 enrich_scene_characters_batch。
5. 如果你希望破坏性覆盖而非增量合并，请谨慎使用 replace_mode=replace 和 confirm_replace=true。

结果：角色关联维护将成为一种先预览再修复关系的操作，而不再是一次性的正则表达式脚本或手动清理 sidecar。

6) 旧版迁移警告后的升级恢复

目标：当旧版升级警告表明有歧义的行被跳过时，快速恢复对索引的信心。

1. 首先检查 get_runtime_config（或 describe_workflows），确认 db_migration_warnings 是否包含 LEGACY_JOIN_ROWS_SKIPPED。
2. 如果存在，请立即运行 sync，根据兼容性 sidecar 和正文元数据重建场景关系。
3. 继续正常发现流程（find_scenes、get_arc、get_thread_arc），并留意过时元数据警告。
4. 处理过时场景时，运行 enrich_scene(scene_id, project_id)，逐步恢复元数据一致性。
5. 如果仍有许多场景过时，请改用 enrich_scene_characters_batch（先运行试运行）进行更大范围的追赶更新。

结果：与升级相关的数据丢失风险将转化为明确且对操作人员可见的恢复工作流，而不是无声的状态不一致。

许可证

AGPL-3.0-only