doc-fine-tuning-mcp
doc-fine-tuning-mcp —— opencode 办公文档精细修改标注器
一个 opencode 的 MCP server:当 LLM 需要对你做办公文档的精细修改时,用它在独立的浏览器应用窗口里可视化地打开文档, 由你点击整段(或拖选连续的字符串进行更精细的标注)并输入每个位置的修改提示词,可一次标注多处;完成后交回 agent, LLM 依据你的提示词逐处执行修改。标注窗口会随 agent 的取消/退出自动关闭,同一文档多轮标注时复用同一窗口自动重载。
支持的格式:.docx / .xlsx / .pptx(OOXML)。v1 不做旧格式(.doc/.xls/.ppt)。
工作流程
用户对 opencode 说:把 D:\报告.docx 的第 3 段和标题改得更正式
│
▼
opencode 插件 doc-edit-listener 检测到"文档精细修改意图",注入引导
│
▼
LLM 调用 doc-edit_annotate_document("D:\报告.docx")
│ → 本地 HTTP 服务启动,独立浏览器应用窗口打开标注页 http://127.0.0.1:<port>/?session=xxx
│ (同一文档再次标注:复用该窗口自动重载,不重开新窗口)
▼
你在页面上:看到文档 → 点击整段/单元格/形状(或拖选连续字符串)→ 输入提示词 → 继续标注下一处 → 点【完成】
│ (标注以 loc + prompt 形式提交给服务端;完成后 agent 窗口重新聚焦)
▼
LLM 调用 doc-edit_wait_for_annotations 拿到全部标注
│ (若窗口被关闭:返回 status=closed + reason,LLM 据此决定重开或询问你)
▼
LLM 对每个标注:doc-edit_read_location 读取原文 → 依据提示词生成新内容
│ → doc-edit_apply_edit 应用修改(首次自动备份 .bak-<时间戳>)
▼
标注窗口自动重载(服务端推送),展示修改后的最新文档供你检查
│ → LLM 再次 doc-edit_wait_for_annotations 等待下一轮标注(多轮循环)
▼
你点【完成】且无标注 / 点【取消】/ 关闭窗口 → 修改流程结束Related MCP server: word-mcp-live
架构
opencode
├─ 插件 doc-edit-listener(监听消息 → 检测修改意图 → 注入引导)
└─ MCP 客户端 ──stdio──► doc-edit MCP server(Node/TS, @modelcontextprotocol/sdk)
├─ 标注工具:annotate_document / wait_for_annotations / cancel_session
├─ 编辑原语:read_structure / read_location / apply_edit
├─ 本地 HTTP 服务(127.0.0.1:动态端口)→ H5 标注页 + API
└─ Python 编辑引擎(python-docx / openpyxl / python-pptx)位置定位的一致性:页面上你点击的位置(
loc)由 JS 侧遍历 OOXML 生成,Python 引擎用同一遍历算法解析定位, 并有tests/parity测试保证两侧 loc→文本映射完全一致(尤其 Word 表格内段落、PPT 多形状)。执行者是 LLM:生成新内容的每一步都由 LLM 基于你的提示词完成;MCP server 只负责"打开页面、收集标注、按位置读写文件"。
安装
1. 克隆项目并安装依赖
cd D:\develop\doc-fine-tuning-mcp
npm install
# Python 编辑引擎(创建 .venv 并安装 python-docx/openpyxl/python-pptx)
cmd //c scripts\\setup_venv.bat2. 构建
npm run build # 编译 src → dist/(MCP server)
cd web && npm install && npm run build # 构建 H5 标注页 → web/dist/3. 注册 MCP server 到 opencode
在 ~/.config/opencode/opencode.jsonc 的 mcp 块添加(开发模式,指向本地构建产物):
"doc-edit": {
"type": "local",
"command": ["node", "D:/develop/doc-fine-tuning-mcp/dist/index.js"],
"enabled": true
}发布模式(可选):
npm pack生成 tgz 后,改用npx -y --package <路径>/doc-fine-tuning-mcp-<版本>.tgz doc-fine-tuning-mcp,与项目内其他 MCP 一致。
4. 安装监听插件
插件分两个文件:doc-edit-listener.ts 与其依赖的检测模块 lib\detect.ts。
opencode 插件目录会自动扫描其下的 .ts 文件作为插件,但不会递归扫描子目录,
因此 detect.ts 放在 lib\ 子目录中不会被误当成独立插件加载。
copy plugin\doc-edit-listener.ts %USERPROFILE%\.config\opencode\plugin\doc-edit-listener.ts
mkdir %USERPROFILE%\.config\opencode\plugin\lib
copy plugin\lib\detect.ts %USERPROFILE%\.config\opencode\plugin\lib\detect.ts⚠️ 插件模块只能导出插件本身(default)。不要给
doc-edit-listener.ts添加任何具名函数导出, 否则 opencode 会把它们当作额外钩子/插件,导致加载失败并报 "Unexpected server error" (hooks 被置空后级联到 Provider.defaultModel 崩溃)。检测逻辑一律放在lib/detect.ts。
插件依赖 @opencode-ai/plugin(~/.config/opencode/node_modules 已内置 1.18.11)。重启 opencode 后生效。
5. 端到端自检
npm test # 引擎 / parity / mcp 客户端 / 插件 全部测试
node scripts/e2e-verify.ts # 输出 PASS 即闭环可用MCP 工具说明
工具 | 入参 | 说明 |
|
| 打开独立标注窗口,创建/复用标注会话,返回 |
|
| 阻塞至 |
|
| 取消标注会话 |
|
| 文档大纲(docx 逐段 / xlsx 每 sheet 抽样 / pptx 每页形状) |
|
| 指定位置原文 + 相邻上下文(docx |
|
| 应用修改(docx |
|
| 批量替换 |
|
| 全文查找替换(仅 docx,普通字符串非正则;返回 |
|
| 批量预览修改(内存应用不写盘,返回每处 |
|
| 列出版本历史(每次 |
|
| 回滚到指定版本(回滚前先快照当前状态,可逆) |
mode: replace / append / prepend / insert_after / delete。
style(可选): { bold, italic, sizePt, color }。
注:
template_replace/find_replace的替换采用 run 级格式保真——替换区间跨越多个不同格式的 run 时,新文本按源 run 字符权重分段、逐段继承对应 run 的格式(不再退化为只保留首 run 格式)。
位置描述符 loc
页面点击生成的 loc 是"改哪一处"的唯一凭据,六个类型:
| { kind: "docx-paragraph", paraIndex } // Word 段落(body 文档序,0-based)
| { kind: "docx-cell", tableIndex, rowIndex, colIndex, paraIndex } // Word 表格内段落
| { kind: "xlsx-cell", sheet, row, col } // Excel 单元格(1-based,同 A1)
| { kind: "xlsx-range", sheet, row1, col1, row2, col2 }
| { kind: "pptx-shape", slideIndex, shapeIndex } // PPT 形状(1-based)
| { kind: "pptx-shape-paragraph", slideIndex, shapeIndex, paraIndex }使用说明与提示
LLM 应当:先
annotate_document让用户标注 →wait_for_annotations取标注 → 对每个标注read_location核对原文 → 依提示词生成新内容 →apply_edit。不要猜测修改位置。版本历史纠错:每次
apply_edit前文档都会快照到<path>.versions/。若修改后发现内容异常(替换结果与提示词不符、用户对某轮结果不满意),用list_versions查看快照、restore_version回退到修改前再重新生成。回退后旧标注的 loc 索引可能失效,应重新read_location核对或让用户重新标注(第一轮里回退最有价值——标注仍基于原始文档)。标注窗口侧栏的**「历史」Tab** 也可直接查看版本链(每条含操作描述/时间/大小)并一键回退。用户回退的操作会记入会话user_actions,随wait_for_annotations返回——LLM 看到user_actions含 restore 时应意识到文档已回退、之后的修改可能失效,核对后再继续。等待轮询(永不超时):
wait_for_annotations缺省永不超时(一直等到用户提交 / 取消 / 关闭窗口,或 agent 退出)。部分客户端对单次工具调用有超时上限(约 60s),此时单次调用会被截断——再次调用该工具即可继续等待,会话不会被截断而取消。窗口关闭:若用户关闭了标注窗口,
wait_for_annotations返回closed+reason(window_closed/page_unload/window_lost/agent_cancelled/agent_exited)。LLM 应据原因决定重开标注(再次annotate_document)或询问用户。窗口自动重载(推模式):每次
apply_edit/template_replace/find_replace/restore_version修改成功后,服务端会自动向该文档的标注窗口推送重载(约 2s 防抖,连续修改合并为一次),窗口立即展示修改后的最新内容——不依赖 LLM 再手动调用annotate_document。滚动视野保持:重载后页面会回到你之前的阅读位置(视野锚定——记录视口顶部附近的内容并按偏移恢复,而非简单回顶),同时保持 xlsx 当前工作表与 pptx 当前页。
多对话共享 server 的窗口归属:WorkBuddy 等客户端全局共享同一个 MCP server 进程,所有对话的标注会话混在同一进程里。为避免修改后重载到别的对话的窗口,LLM 应在
wait_for_annotations拿到标注后,把返回的session_id原样传给apply_edit等修改工具(工具已支持该可选参数),服务端据此精确重载本会话的窗口;未传时服务端按"最近活跃会话"兜底,路径有歧义则不重载(避免误伤)。同一文档的标注窗口在共享 server 下是复用的——建议同一时刻只在一个对话里操作同一文档。同文档复用:对同一文档再次
annotate_document会复用现有窗口自动重载(页面重新拉取最新文件、清空上轮标注),不会重开新窗口。多轮标注循环:agent 处理完一轮标注后,窗口自动重载供你检查修改并继续标注;agent 应再次调用
wait_for_annotations等待下一轮。在窗口里点【完成】且不加任何标注,即表示本轮无需再修改;点【取消】则直接关闭窗口结束本轮(wait_for_annotations据此停止)。字符串级标注:在 Word 页面里拖选连续的字符串,标注即精确到该字符串(
loc.range);apply_edit只替换它。取消:用户在页面点【取消】,或 LLM 调用
cancel_session,会话置cancelled且标注窗口直接关闭;agent 进程退出时,所有标注窗口自动关闭。修改是非破坏性的:首次编辑前自动生成
文档名.bak-<时间戳>,且每次修改前自动快照到<path>.versions/版本链(可用list_versions/restore_version任意步回退)。
已知限制
仅支持
.docx/.xlsx/.pptx(OOXML)。Word:docx-preview 渲染序与 body 遍历序假定 1:1(极端排版元素可能有偏差,见
web/src/viewers/docxViewer.ts顶部注释)。PPT:形状定位以文本匹配兜底,形状文本重复时可能不精确。
Excel:SheetJS + 轻量网格;支持双击单元格页面内编辑(修改项作为标注交回 LLM 落地);合并单元格非左上角只读;公式单元格直接编辑会替换公式为普通值。
会话状态在内存中,MCP server 重启即失效。
FAQ
Q:浏览器没有自动打开?
A:标注页在 Chrome/Edge 的独立应用窗口打开(无地址栏/工具栏/标签页)。若找不到 Chrome/Edge 或启动失败,工具仍会返回 url,LLM 会把链接发给你,手动打开即可(此时窗口关闭检测退化为页面心跳)。
Q:为什么标注窗口会自己关掉? A:当你用 Esc 取消 agent,或 agent/opencode 进程退出时,服务端会主动关闭标注窗口;你在页面上点【完成】或【取消】后窗口会保持只读等待复用(同一文档下一轮直接重载)。
Q:标注页打不开 / 白屏?
A:确认已执行 cd web && npm run build(服务端在 web/dist 缺失时只返回占位提示页);确认文档路径是绝对路径且文件存在。
Q:为什么需要插件?
A:插件在消息层检测"精细修改文档"的意图并注入引导,让 LLM 在动手前先让你标注,避免它猜位置直接改。注意:插件仅对 opencode 生效;在 WorkBuddy 等其他 MCP 客户端中,LLM 的流程引导来自工具描述与 wait_for_annotations 返回的 next 字段(已内置多轮循环约定)。
Q:修改完成后窗口会自动重载,我再标注并点【完成】,agent 会继续处理吗? A:取决于 agent 是否仍在等待:
若 agent 按引导处于"处理完标注 → 再次
wait_for_annotations"的循环中,你提交的新标注会被它立刻拿到并继续处理(多轮无缝衔接);若 agent 已经结束回合(不再调用工具),你的标注会暂存在服务端,但不会自动唤醒 agent——此时再跟 agent 说一句"标注已提交,请继续处理"即可。 这是"执行者是 LLM"架构的固有边界:服务端无法代替 agent 主动接管下一轮。
Q:两个对话同时编辑同一文档,窗口会串吗?
A:WorkBuddy 全局共享同一个 server 进程,同一文档的标注窗口会被复用共享。修改后的自动重载现在精确绑定会话:LLM 在 apply_edit 等工具中带上 wait_for_annotations 返回的 session_id,就只会重载本对话的窗口;未带时按最近活跃会话兜底,路径有多个存活会话时宁可不重载也不误伤。建议同一时刻只在一个对话里操作同一文档。
Available Tools
11 toolsannotate_documentA
打开文档标注页面(H5):创建标注会话并启动本地 HTTP 服务,在独立浏览器应用窗口打开标注页(无地址栏/工具栏/标签页)。若同一文档已有存活窗口则直接复用(原位重载、清空上轮标注),不重新开窗。返回 {session_id, url}。多轮循环:窗口会在文档被修改后自动重载最新内容(apply_edit 成功后服务端主动推送),无需每次手动调用本工具;也可在本轮开始或需要立即刷新时主动调用。同一文档重复调用会复用现有窗口。
Inputs: path (required).
apply_editA
对指定位置应用修改(首次编辑前自动生成 .bak-<时间戳> 备份;同一标注轮次内只有第一次编辑会快照到版本历史,其余编辑复用该版本——一轮多个标注只产生一个版本,版本描述会汇总本轮全部修改)。mode 缺省 replace;引擎错误返回结构化错误。返回 {ok, loc, new_content, version}(version 为 null 表示本轮已快照过、未新增版本;version.desc 表达该快照为'修改前/该轮标注前的状态'——会话场景为'第 N 轮标注前的状态(本轮修改:…)',无会话为'修改前:<编辑摘要>',回退到该版本即恢复为此内容)。修改成功后,该文档的标注窗口会自动重载展示最新内容(无需再手动调用 annotate_document);用户检查后可能继续标注,此时应再次调用 wait_for_annotations 获取下一轮标注。若修改后发现内容异常,可用 list_versions / restore_version 回退到修改前再重新生成。
Inputs: loc (required), path (required), mode, style, +2 more.
cancel_sessionB
取消标注会话(用户点了“取消”)。返回 {session_id, status}。
Inputs: session_id (required).
find_replaceA
在 docx 文档中全文查找并替换字符串(普通字符串,非正则;匹配范围含表格内单元格)。match_case=false 时大小写不敏感,替换文本原样插入。返回 {matched, replaced, locations}。
Inputs: find (required), path (required), replace (required), match_case, +1 more.
list_versionsA
列出文档的版本历史(.versions/ 快照链:同一标注轮次内多个编辑合并为一个版本,即每轮首个编辑前快照;新版本在前)。返回 [{index, path, size, mtime, kind?, desc?, ts?}],无版本时返回 []。每条 desc 表达'修改前/该轮标注前的状态'(如'第 1 轮标注前的状态'或'修改前:替换…'),回退到该版本即恢复为该内容。配合 restore_version 实现任意步回退。
Inputs: path (required).
preview_editsA
批量预览修改(仅内存计算,不写盘):按顺序在内存中对同一文档应用 edits 列表,返回每处的 {loc, before, after}。适合在真正 apply_edit 前检查一批修改是否符合预期。edits 元素为 {loc, new_content?, mode?, style?}。返回 [{loc, before, after}]。
Inputs: path (required), edits (required).
read_locationA
读取指定位置的原文与相邻上下文,供生成新内容前核对。返回 {loc, text, context}。
Inputs: loc (required), path (required).
read_structureA
读取文档大纲:docx 逐段 {loc,text};xlsx 每 sheet 维度与抽样;pptx 每页形状文本。返回 {format, items|sheets|slides}。
Inputs: path (required), max_items.
restore_versionA
将文档直接回退到 list_versions 给出的某个版本(回到该版本锚点:文档被覆盖为该版本内容,回退前不会快照当前状态,因此版本记录不会增加)。⚠️ 警告:该版本之后的全部修改将丢失,且回退本身不可通过新快照撤销(但既有版本链仍保留,可再回退到其它版本)。回退后旧标注的 loc 索引可能失效,应重新 read_structure 遍历后再继续编辑。返回 {restored_index, path, version_path, versions}。
Inputs: path (required), index (required), session_id.
template_replaceA
批量替换 docx 文档中的 {{变量}} 模板占位符。variables 为 {变量名: 值} 映射;未提供值的变量保持原样并在 missing_vars 中列出。同段落多处占位符按从右到左应用保证坐标正确;跨 run 断裂的占位符也能正确替换。返回 {matched, replaced, missing_vars, applied}。
Inputs: path (required), variables (required), session_id.
wait_for_annotationsA
阻塞等待标注会话完成 / 取消 / 窗口关闭,返回用户提交的标注列表。返回 {session_id, status, reason?, annotations, next?},status 为 done | cancelled | closed | timeout。缺省永不超时(timeout_seconds 不传则一直等待直到用户提交/取消/关闭窗口,或 agent 退出);如客户端对单次调用有超时上限,可传 timeout_seconds 设一个安全值,被截断或超时后再次调用本工具继续等待即可(会话在服务端持续存在,不会因单次调用被截断而取消)。status=closed 表示标注窗口已关闭:reason=window_closed/page_unload 是用户主动关闭——本轮标注流程已结束,不要再调用本工具或 annotate_document(除非用户明确要求继续),直接总结结果即可;reason=window_lost(窗口崩溃/被强杀)或 agent_cancelled/agent_exited 时才考虑询问用户是否重开。status=done 且存在标注时:处理这些标注时请在 apply_edit / template_replace / find_replace / restore_version 中带上本返回值中的 session_id(确保标注窗口重载到正确的会话,多对话共享同一 server 时尤为重要);处理完后(窗口会自动重载修改后的内容)应再次调用本工具等待用户下一轮标注。status=done 且标注为空:用户确认本轮无需修改,标注流程已结束(窗口已自动关闭),不要再调用本工具或 annotate_document,直接总结结果即可。
Inputs: session_id (required), timeout_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have clearly distinct roles in the read-annotate-edit-version workflow. The main ambiguity is among apply_edit, find_replace, and template_replace, which all modify documents, though their descriptions clarify different use cases.
Tool names are consistently lowercase snake_case and mostly follow a verb_noun pattern like read_location, apply_edit, and list_versions. template_replace and find_replace deviate slightly from the verb-first style, but the naming remains predictable and readable.
11 tools is well within the ideal range, and each tool covers a necessary part of the fine-tuning workflow: reading, annotating, waiting, editing, previewing, and versioning. There are no obvious filler or redundant tools.
The toolset covers the full annotation loop: open a session, wait for annotations, apply edits, preview changes, and roll back via versions. Features like document creation or export are outside the stated fine-tuning purpose, so no significant gaps are apparent.
Maintenance
Related MCP Connectors
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
Online office suite for AI agents: edit docs, sheets, slides and PDFs in browser or via MCP.
Create and improve live, shared interactive documents with your agent.
Real Word and Excel for agents: open your .docx/.xlsm, read, propose, apply, get it back intact.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to directly read, edit, and manipulate Word documents, supporting image and table operations, paragraph editing, and search/replace.202MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to edit Microsoft Word documents in real time, supporting tracked changes, comments, formatting, and per-action undo across 124 tools.MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to create and edit Office documents, presentations, and spreadsheets, as well as generate diagrams, charts, citations, and research project structures.14ISC
- AlicenseAqualityBmaintenanceEnables automation, inspection, and modification of Excel, Word, and PowerPoint documents through natural language, with safety features such as sandboxing, snapshots, and automatic rollback.19MIT