doc-fine-tuning-mcp —— opencode-Bürodokument-Feintuning-Markierer

Ein MCP-Server für opencode: Wenn die LLM eine feine Änderung an deinen Bürodokumenten vornehmen muss, öffnet sie das Dokument damit visuell in einem separaten Browser-App-Fenster. Du klickst auf ganze Absätze (oder ziehst eine Auswahl über zusammenhängende Zeichenfolgen für feinere Markierungen) und gibst für jede Stelle einen Änderungsprompt ein – mehrere Stellen können in einem Durchgang markiert werden. Danach wird die Kontrolle an den Agenten zurückgegeben, und die LLM führt die Änderungen anhand deiner Prompts Stelle für Stelle aus. Das Markierungsfenster schließt sich automatisch, wenn der Agent abbricht/beendet wird; bei mehreren Markierungsrunden für dasselbe Dokument wird dasselbe Fenster wiederverwendet und automatisch neu geladen.

Unterstützte Formate: .docx / .xlsx / .pptx (OOXML). v1 unterstützt keine alten Formate (.doc/.xls/.ppt).

Arbeitsablauf

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

Architektur

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）

• Konsistenz der Positionsbestimmung: Die Position, auf die du auf der Seite klickst (loc), wird von der JS-Seite durch Traversieren des OOXML erzeugt; die Python-Engine parst die Position mit demselben Traversierungsalgorithmus, und tests/parity-Tests garantieren, dass die loc→Text-Zuordnung auf beiden Seiten exakt übereinstimmt (insbesondere Absätze in Word-Tabellen, mehrere Formen in PPT).

• Die LLM ist der Ausführende: Jeder Schritt zur Erzeugung neuer Inhalte wird von der LLM basierend auf deinen Prompts durchgeführt; der MCP-Server ist nur für „Seite öffnen, Markierungen sammeln, Dateien positionsbasiert lesen/schreiben" zuständig.

Installation

1. Projekt klonen und Abhängigkeiten installieren

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. MCP-Server in opencode registrieren

Im mcp-Block von ~/.config/opencode/opencode.jsonc hinzufügen (Entwicklungsmodus, zeigt auf lokale Build-Artefakte):

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

Veröffentlichungsmodus (optional): Nach npm pack zur Erzeugung des tgz stattdessen npx -y --package <Pfad>/doc-fine-tuning-mcp-<Version>.tgz doc-fine-tuning-mcp verwenden, konsistent mit den anderen MCPs im Projekt.

4. Listener-Plugin installieren

Das Plugin besteht aus zwei Dateien: doc-edit-listener.ts und dem davon abhängigen Erkennungsmodul lib\detect.ts. Das opencode-Plugin-Verzeichnis scannt automatisch .ts-Dateien darin als Plugins, scannt aber Unterverzeichnisse nicht rekursiv, daher wird detect.ts im Unterverzeichnis lib\ nicht fälschlich als eigenständiges Plugin geladen.

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

⚠️ Das Plugin-Modul darf nur das Plugin selbst exportieren (default). Füge doc-edit-listener.ts keine benannten Funktions-Exporte hinzu, sonst behandelt opencode sie als zusätzliche Hooks/Plugins, was zu einem Ladefehler mit „Unexpected server error" führt (nach dem Leeren der Hooks kaskadiert der Fehler zu Provider.defaultModel-Absturz). Die Erkennungslogik gehört immer in lib/detect.ts.

Das Plugin benötigt @opencode-ai/plugin (in ~/.config/opencode/node_modules ist Version 1.18.11 bereits enthalten). Nach einem Neustart von opencode ist es aktiv.

5. End-to-End-Selbsttest

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

MCP-Tool-Beschreibung

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

Hinweis: Die Ersetzung von template_replace / find_replace erfolgt mit Run-Ebene-Formattreue – wenn der Ersetzungsbereich mehrere Runs mit unterschiedlichen Formaten überspannt, wird der neue Text nach Zeichengewichtung der Quell-Runs segmentiert und erbt segmentweise das Format des jeweiligen Runs (keine Degradierung mehr auf nur das Format des ersten Runs).

Positionsdeskriptor loc

Das durch Klicken auf der Seite erzeugte loc ist der einzige Nachweis für „welche Stelle geändert werden soll", mit sechs Typen:

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

Verwendungshinweise und Tipps

• Die LLM sollte: zuerst annotate_document aufrufen, damit der Benutzer markieren kann → wait_for_annotations für die Markierungen → für jede Markierung read_location zur Überprüfung des Originaltexts → neue Inhalte gemäß dem Prompt erzeugen → apply_edit. Nicht die Änderungsposition raten.

• Korrektur über Versionsverlauf: Vor jedem apply_edit wird das Dokument nach <path>.versions/ gesnapshotet. Falls nach der Änderung der Inhalt auffällig ist (Ersetzungsergebnis entspricht nicht dem Prompt, Benutzer ist mit einer Runde unzufrieden), mit list_versions die Snapshots ansehen, mit restore_version auf den Stand vor der Änderung zurückrollen und neu generieren. Nach dem Zurücksetzen können die loc-Indizes alter Markierungen ungültig sein – erneut mit read_location prüfen oder den Benutzer neu markieren lassen (das Zurücksetzen in der ersten Runde ist am wertvollsten – die Markierungen basieren noch auf dem Originaldokument). Der „Verlauf"-Tab in der Seitenleiste des Markierungsfensters zeigt ebenfalls die Versionskette (jeder Eintrag mit Operationsbeschreibung/Zeit/Größe) und ermöglicht das Zurücksetzen mit einem Klick. Vom Benutzer durchgeführte Zurücksetzungen werden in der Sitzung unter user_actions protokolliert und mit wait_for_annotations zurückgegeben – wenn die LLM in user_actions ein restore sieht, sollte sie erkennen, dass das Dokument zurückgerollt wurde und spätere Änderungen ungültig sein können, und nach Prüfung fortfahren.

• Wartepolling (nie Timeout): wait_for_annotations hat standardmäßig kein Timeout (wartet, bis der Benutzer abschickt / abbricht / das Fenster schließt, oder der Agent beendet wird). Manche Clients haben ein Timeout-Limit für einzelne Tool-Aufrufe (ca. 60s); dann wird der einzelne Aufruf abgeschnitten – ein erneuter Aufruf des Tools setzt das Warten fort, die Sitzung wird durch den Abbruch nicht beendet.

• Fensterschließen: Wenn der Benutzer das Markierungsfenster schließt, gibt wait_for_annotations closed + reason zurück (window_closed / page_unload / window_lost / agent_cancelled / agent_exited). Die LLM sollte je nach Grund entscheiden, ob sie das Markieren neu öffnet (erneut annotate_document) oder den Benutzer fragt.

• Automatisches Neuladen des Fensters (Push-Modus): Nach jeder erfolgreichen Änderung durch apply_edit / template_replace / find_replace / restore_version schiebt der Server automatisch ein Neuladen an das Markierungsfenster dieses Dokuments (ca. 2s Entprellung, aufeinanderfolgende Änderungen werden zu einem zusammengefasst), und das Fenster zeigt sofort den neuesten Inhalt nach der Änderung – ohne dass die LLM manuell erneut annotate_document aufrufen muss.

• Erhalt des Scroll-Bereichs: Nach dem Neuladen kehrt die Seite zu deiner vorherigen Leseposition zurück (Sichtanker – der Inhalt nahe dem oberen Rand des Viewports wird aufgezeichnet und per Offset wiederhergestellt, nicht einfach zurück zum Seitenanfang), wobei das aktuelle Arbeitsblatt bei xlsx und die aktuelle Seite bei pptx erhalten bleiben.

• Fensterzuordnung bei mehreren Dialogen mit gemeinsamem Server: Clients wie WorkBuddy teilen global denselben MCP-Serverprozess, alle Markierungssitzungen aller Dialoge laufen im selben Prozess. Um zu vermeiden, dass nach einer Änderung das Fenster eines anderen Dialogs neu geladen wird, sollte die LLM nach Erhalt der Markierungen aus wait_for_annotations die zurückgegebene session_id unverändert an apply_edit und andere Änderungstools weitergeben (die Tools unterstützen diesen optionalen Parameter bereits); der Server lädt damit präzise das Fenster dieser Sitzung neu. Wird sie nicht übergeben, greift der Server auf „zuletzt aktive Sitzung" als Fallback zurück; bei mehrdeutigen Pfaden mit mehreren lebenden Sitzungen wird nicht neu geladen (um Fehlschüsse zu vermeiden). Das Markierungsfenster desselben Dokuments wird unter einem gemeinsamen Server wiederverwendet – es wird empfohlen, dasselbe Dokument zu einem Zeitpunkt nur in einem Dialog zu bearbeiten.

• Wiederverwendung desselben Dokuments: Ein erneutes annotate_document für dasselbe Dokument verwendet das vorhandene Fenster wieder und lädt es automatisch neu (die Seite holt die neueste Datei, leert die Markierungen der vorherigen Runde), ohne ein neues Fenster zu öffnen.

• Mehrrunden-Markierungsschleife: Nachdem der Agent eine Runde Markierungen verarbeitet hat, lädt das Fenster automatisch neu, damit du die Änderungen prüfen und weiter markieren kannst; der Agent sollte erneut wait_for_annotations aufrufen, um auf die nächste Runde zu warten. Im Fenster auf【Fertig】klicken und keine Markierungen hinzufügen bedeutet, dass in dieser Runde keine weiteren Änderungen nötig sind; auf【Abbrechen】klicken schließt das Fenster direkt und beendet die Runde (wait_for_annotations stoppt entsprechend).

• Zeichenfolgen-Ebene-Markierung: Auf der Word-Seite eine zusammenhängende Zeichenfolge auswählen, die Markierung ist dann auf diese Zeichenfolge präzise (loc.range); apply_edit ersetzt nur sie.

• Abbrechen: Wenn der Benutzer auf der Seite auf【Abbrechen】klickt oder die LLM cancel_session aufruft, wird die Sitzung auf cancelled gesetzt und das Markierungsfenster direkt geschlossen; wenn der Agentenprozess beendet wird, schließen sich alle Markierungsfenster automatisch.

• Änderungen sind nicht destruktiv: Vor der ersten Bearbeitung wird automatisch Dokumentname.bak-<Zeitstempel> erzeugt, und vor jeder Änderung wird automatisch ein Snapshot in die <path>.versions/-Versionskette geschrieben (mit list_versions / restore_version kann beliebig weit zurückgerollt werden).

Bekannte Einschränkungen

• Nur .docx / .xlsx / .pptx (OOXML) werden unterstützt.

• Word: Die Renderreihenfolge von docx-preview und die body-Traversierungsreihenfolge werden als 1:1 angenommen (bei extremen Layout-Elementen kann es Abweichungen geben, siehe Kommentar oben in web/src/viewers/docxViewer.ts).

• PPT: Die Formpositionierung nutzt Textabgleich als Fallback; bei doppelten Formtexten kann es ungenau sein.

• Excel: SheetJS + leichtes Grid; Doppelklick auf eine Zelle zur Bearbeitung innerhalb der Seite wird unterstützt (Änderungseinträge werden als Markierungen an die LLM zur Umsetzung zurückgegeben); nicht-obere-linke Zellen bei zusammengeführten Zellen sind schreibgeschützt; bei Formelzellen ersetzt die direkte Bearbeitung die Formel durch einen normalen Wert.

• Der Sitzungszustand liegt im Speicher und verfällt beim Neustart des MCP-Servers.

FAQ

F: Der Browser öffnet sich nicht automatisch? A: Die Markierungsseite wird in einem separaten App-Fenster von Chrome/Edge geöffnet (ohne Adressleiste/Werkzeugleiste/Tabs). Falls Chrome/Edge nicht gefunden wird oder der Start fehlschlägt, gibt das Tool trotzdem url zurück; die LLM schickt dir den Link, und du öffnest ihn manuell (in diesem Fall degradiert die Fenster-Schließ-Erkennung zu einem Seiten-Herzschlag).

F: Warum schließt sich das Markierungsfenster von selbst? A: Wenn du den Agenten mit Esc abbrichst oder der Agent/opencode-Prozess beendet wird, schließt der Server das Markierungsfenster aktiv; nachdem du auf der Seite auf【Fertig】oder【Abbrechen】geklickt hast, bleibt das Fenster schreibgeschützt und wartet auf Wiederverwendung (bei derselben Runde des Dokuments wird es direkt neu geladen).

F: Die Markierungsseite lässt sich nicht öffnen / weißer Bildschirm? A: Stelle sicher, dass cd web && npm run build ausgeführt wurde (der Server gibt bei fehlendem web/dist nur eine Platzhalter-Hinweisseite zurück); stelle sicher, dass der Dokumentpfad absolut ist und die Datei existiert.

F: Warum wird ein Plugin benötigt? A: Das Plugin erkennt auf Nachrichtenebene die Absicht „Dokument fein ändern" und injiziert eine Führung, damit die LLM dich vor dem Handeln markieren lässt, statt Positionen zu raten und direkt zu ändern. Hinweis: Das Plugin wirkt nur bei opencode; in anderen MCP-Clients wie WorkBuddy kommt die Prozessführung der LLM aus der Tool-Beschreibung und dem next-Feld, das wait_for_annotations zurückgibt (die Mehrrunden-Schleifenkonvention ist eingebaut).

F: Nach Abschluss der Änderung lädt das Fenster automatisch neu; wenn ich erneut markiere und auf【Fertig】klicke, verarbeitet der Agent das weiter? A: Hängt davon ab, ob der Agent noch wartet:

• Wenn der Agent gemäß der Führung in der Schleife „Markierungen verarbeitet → erneut wait_for_annotations" ist, erhält er deine neu eingereichten Markierungen sofort und verarbeitet sie weiter (nahtloser Mehrrunden-Übergang);

• Wenn der Agent seine Runde bereits beendet hat (keine Tools mehr aufruft), werden deine Markierungen auf dem Server zwischengespeichert, aber der Agent wird nicht automatisch geweckt – sag dem Agenten dann einfach „Markierungen eingereicht, bitte weiterverarbeiten". Das ist die inhärente Grenze der Architektur „Die LLM ist der Ausführende": Der Server kann die nächste Runde nicht anstelle des Agenten aktiv übernehmen.

F: Wenn zwei Dialoge gleichzeitig dasselbe Dokument bearbeiten, vermischen sich die Fenster? A: WorkBuddy teilt global denselben Serverprozess; das Markierungsfenster desselben Dokuments wird gemeinsam wiederverwendet. Das automatische Neuladen nach Änderungen ist jetzt präzise an die Sitzung gebunden: Wenn die LLM in apply_edit und anderen Tools die von wait_for_annotations zurückgegebene session_id mitgibt, wird nur das Fenster dieses Dialogs neu geladen; ohne Angabe greift der Fallback auf die zuletzt aktive Sitzung, und bei mehreren lebenden Sitzungen für denselben Pfad wird lieber nicht neu geladen, um Fehlschüsse zu vermeiden. Es wird empfohlen, dasselbe Dokument zu einem Zeitpunkt nur in einem Dialog zu bearbeiten.