doc-fine-tuning-mcp — opencode office document fine-tuning annotator

An opencode MCP server: when the LLM needs to make fine-grained modifications to your office documents, use it to visually open the document in a standalone browser app window. You click on a whole paragraph (or drag-select a contiguous string for finer-grained annotation) and enter a modification prompt for each location; you can annotate multiple locations at once. When done, hand it back to the agent, and the LLM executes the modifications one by one based on your prompts. The annotation window automatically closes when the agent is cancelled/exits; for multiple rounds of annotation on the same document, it reuses the same window and auto-reloads.

Supported formats: .docx / .xlsx / .pptx (OOXML). v1 does not support legacy formats (.doc/.xls/.ppt).

Workflow

用户对 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

Architecture

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）

• Location consistency: The position you click on the page (loc) is generated by the JS side traversing the OOXML; the Python engine resolves the location using the same traversal algorithm, and tests/parity tests guarantee that the loc→text mapping is identical on both sides (especially paragraphs inside Word tables and multi-shape PPTs).

• The LLM is the executor: Every step of generating new content is done by the LLM based on your prompts; the MCP server is only responsible for "opening the page, collecting annotations, and reading/writing files by location".

Installation

1. Clone the project and install dependencies

cd D:\develop\doc-fine-tuning-mcp
npm install
# Python 编辑引擎（创建 .venv 并安装 python-docx/openpyxl/python-pptx）
cmd //c scripts\\setup_venv.bat

2. Build

npm run build          # 编译 src → dist/（MCP server）
cd web && npm install && npm run build   # 构建 H5 标注页 → web/dist/

3. Register the MCP server with opencode

Add to the mcp block in ~/.config/opencode/opencode.jsonc (development mode, pointing to the local build output):

"doc-edit": {
  "type": "local",
  "command": ["node", "D:/develop/doc-fine-tuning-mcp/dist/index.js"],
  "enabled": true
}

Release mode (optional): after npm pack generates the tgz, switch to npx -y --package <路径>/doc-fine-tuning-mcp-<版本>.tgz doc-fine-tuning-mcp, consistent with other MCPs in the project.

4. Install the listener plugin

The plugin consists of two files: doc-edit-listener.ts and its dependent detection module lib\detect.ts. The opencode plugin directory automatically scans .ts files under it as plugins, but does not recursively scan subdirectories, so detect.ts placed in the lib\ subdirectory will not be mistakenly loaded as a standalone plugin.

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

⚠️ The plugin module can only export the plugin itself (default). Do not add any named function exports to doc-edit-listener.ts, otherwise opencode will treat them as extra hooks/plugins, causing loading to fail with "Unexpected server error" (after hooks are emptied, it cascades to a Provider.defaultModel crash). Put all detection logic in lib/detect.ts.

The plugin depends on @opencode-ai/plugin (version 1.18.11 is already bundled in ~/.config/opencode/node_modules). It takes effect after restarting opencode.

5. End-to-end self-check

npm test                  # 引擎 / parity / mcp 客户端 / 插件 全部测试
node scripts/e2e-verify.ts   # 输出 PASS 即闭环可用

MCP tool reference

mode: replace / append / prepend / insert_after / delete. style (optional): { bold, italic, sizePt, color }.

Note: template_replace / find_replace use run-level format fidelity — when the replacement range spans multiple runs with different formats, the new text is segmented by source run character weight, with each segment inheriting the corresponding run's format (no longer degrading to keeping only the first run's format).

Location descriptor loc

The loc generated by clicking on the page is the sole credential for "which location to change", with six types:

| { 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 }

Usage notes and tips

• The LLM should: first annotate_document to let the user annotate → wait_for_annotations to get the annotations → read_location for each annotation to verify the original text → generate new content per the prompt → apply_edit. Do not guess the modification location.

• Version history for error correction: Before each apply_edit, the document is snapshotted to <path>.versions/. If you find abnormal content after a modification (the replacement result doesn't match the prompt, or the user is unhappy with a round's result), use list_versions to view snapshots and restore_version to roll back to before the modification, then regenerate. After a rollback, the loc indices of old annotations may become invalid — re-verify with read_location or have the user re-annotate (a rollback in the first round is most valuable — annotations are still based on the original document). The "History" tab in the annotation window sidebar also lets you view the version chain directly (each entry includes operation description/time/size) and roll back with one click. User rollback operations are recorded in the session's user_actions and returned with wait_for_annotations — when the LLM sees user_actions containing restore, it should realize the document has been rolled back and subsequent modifications may be invalid, so verify before continuing.

• Wait polling (never times out): wait_for_annotations never times out by default (waits until the user submits / cancels / closes the window, or the agent exits). Some clients have a timeout cap for a single tool call (about 60s), in which case the single call gets truncated — calling the tool again continues waiting, and the session is not cancelled by the truncation.

• Window closed: If the user closes the annotation window, wait_for_annotations returns closed + reason (window_closed / page_unload / window_lost / agent_cancelled / agent_exited). The LLM should decide based on the reason whether to reopen annotation (call annotate_document again) or ask the user.

• Automatic window reload (push mode): After each successful apply_edit / template_replace / find_replace / restore_version modification, the server automatically pushes a reload to the annotation window for that document (about 2s debounce, consecutive modifications merged into one), and the window immediately shows the latest modified content — no need for the LLM to manually call annotate_document again.

• Scroll viewport preservation: After reload, the page returns to your previous reading position (viewport anchoring — records content near the top of the viewport and restores by offset, rather than simply scrolling to top), while also keeping the current xlsx worksheet and the current pptx page.

• Window ownership with multi-conversation shared server: Clients like WorkBuddy globally share the same MCP server process, so annotation sessions from all conversations are mixed in the same process. To avoid reloading the window of another conversation after a modification, the LLM should pass the returned session_id as-is to modification tools like apply_edit (the tools already support this optional parameter) after getting annotations from wait_for_annotations; the server then precisely reloads this session's window. When not passed, the server falls back to the "most recently active session", and does not reload when the path is ambiguous (to avoid collateral damage). Annotation windows for the same document are reused under a shared server — it's recommended to operate on the same document in only one conversation at a time.

• Same-document reuse: Calling annotate_document again for the same document reuses the existing window and auto-reloads (the page re-fetches the latest file and clears the previous round's annotations), without opening a new window.

• Multi-round annotation loop: After the agent processes one round of annotations, the window auto-reloads for you to review the changes and continue annotating; the agent should call wait_for_annotations again to wait for the next round. Clicking [Done] in the window without adding any annotations means no further changes are needed for this round; clicking [Cancel] directly closes the window to end the round (wait_for_annotations stops accordingly).

• String-level annotation: Drag-selecting a contiguous string in the Word page makes the annotation precise to that string (loc.range); apply_edit only replaces it.

• Cancel: When the user clicks [Cancel] on the page, or the LLM calls cancel_session, the session is set to cancelled and the annotation window closes directly; when the agent process exits, all annotation windows close automatically.

• Modifications are non-destructive: before the first edit, 文档名.bak-<时间戳> is automatically generated, and before each modification, a snapshot is automatically added to the <path>.versions/ version chain (you can roll back any number of steps with list_versions / restore_version).

Known limitations

• Only .docx / .xlsx / .pptx (OOXML) are supported.

• Word: the docx-preview render order and the body traversal order are assumed to be 1:1 (extreme layout elements may deviate; see the comment at the top of web/src/viewers/docxViewer.ts).

• PPT: shape location falls back to text matching, which may be imprecise when shape text is duplicated.

• Excel: SheetJS + lightweight grid; supports double-click in-page cell editing (the change is handed back to the LLM as an annotation to apply); merged cells other than the top-left are read-only; directly editing a formula cell replaces the formula with a plain value.

• Session state is in memory and is lost when the MCP server restarts.

FAQ

Q: The browser didn't open automatically? A: The annotation page opens in a standalone Chrome/Edge app window (no address bar/toolbar/tabs). If Chrome/Edge can't be found or fails to launch, the tool still returns url, and the LLM will send you the link to open manually (in this case, window-close detection degrades to page heartbeat).

Q: Why does the annotation window close by itself? A: When you cancel the agent with Esc, or the agent/opencode process exits, the server proactively closes the annotation window; after you click [Done] or [Cancel] on the page, the window stays read-only waiting for reuse (the next round for the same document reloads directly).

Q: The annotation page won't open / white screen? A: Make sure you've run cd web && npm run build (the server only returns a placeholder page when web/dist is missing); make sure the document path is an absolute path and the file exists.

Q: Why is the plugin needed? A: The plugin detects the "fine-tune document" intent at the message layer and injects guidance, so the LLM lets you annotate first before making changes, avoiding it guessing locations and editing directly. Note: the plugin only works with opencode; in other MCP clients like WorkBuddy, the LLM's workflow guidance comes from the tool descriptions and the next field returned by wait_for_annotations (which has the multi-round loop convention built in).

Q: After a modification, the window auto-reloads; if I annotate again and click [Done], will the agent continue processing? A: It depends on whether the agent is still waiting:

• If the agent is in the "process annotations → call wait_for_annotations again" loop per the guidance, your newly submitted annotations will be picked up immediately and processed (seamless multi-round handoff);

• If the agent has already ended its turn (no longer calling tools), your annotations are temporarily stored on the server, but the agent is not automatically woken up — in that case, just tell the agent "annotations submitted, please continue processing". This is an inherent boundary of the "LLM is the executor" architecture: the server cannot take over the next round on behalf of the agent.

Q: If two conversations edit the same document at the same time, will the windows get mixed up? A: WorkBuddy globally shares the same server process, so annotation windows for the same document are reused and shared. The post-modification auto-reload is now precisely bound to the session: when the LLM includes the session_id returned by wait_for_annotations in tools like apply_edit, only this conversation's window is reloaded; when not included, it falls back to the most recently active session, and when the path has multiple live sessions, it prefers not reloading over causing collateral damage. It's recommended to operate on the same document in only one conversation at a time.