doc-control

doc-control

AI エージェントが Word 文書を変更履歴付きで編集し、執筆者が承諾または拒否できるようにします。

.docx の修正を依頼されたエージェントは、通常ファイルを書き換え、ほかの内容がずれていないことを願うだけです。 このツールは代わりに、決定論的なインターフェースを提供します。段落アドレスで文書を読み取り、変更履歴とコメントとして反映される編集を送信できます。書き込みのたびにバックアップ、検証、取り消しが行われます。閉じたファイルだけでなく、LibreOffice Writer または Windows の Microsoft Word を使えば、執筆者が開いている文書も操作できます。AI は組み込まれていません。判断するのはエージェントで、承認するのは執筆者です。

まだ安定版ではありません。API は今後変更される可能性があります。

クイックスタート

Python（pyproject.toml に記載のバージョン）。ほかの依存関係はありません。

pip install doc-control            # or run without installing: uvx doc-control ...
doc-control text.find --json '{"doc": "story.docx", "query": "rain"}'

Windows で Word をリアルタイムに操作するには、doc-control[live] をインストールしてください（pywin32 が追加されます）。 LibreOffice には追加パッケージは必要ありません。

Python を使わずにインストール（Windows）

最新リリースページの各リリースには、Claude Desktop 拡張機能とインストーラーが含まれています。どちらも現在のユーザー向けにインストールされ、管理者権限は不要で、無料プランを含むすべての Claude アカウントで利用でき、Microsoft Word をリアルタイムに操作できます。詳細なガイド（チェックサム、更新、アンインストール）： docs/install-windows.md。

Claude Desktop 拡張機能（.mcpb）

1. 最新リリースから doc-control-X.Y.Z-windows-x64.mcpb をダウンロードします。
2. ファイルを Claude Desktop の Settings > Extensions ページにドラッグし、Install をクリックします。

Claude Desktop は、この拡張機能がコンピューター上のすべてのファイルにアクセスできると警告します。これはすべてのローカル拡張機能に表示される警告です。ファイルをダブルクリックしてもインストールされません。

インストーラー（-setup.exe）、コマンドライン向け

1. 最新リリースから doc-control-X.Y.Z-windows-x64-setup.exe をダウンロードします。
2. ダブルクリックします。
3. Windows SmartScreen に「Windows によって PC が保護されました」と表示されたら、詳細情報をクリックし、実行をクリックします（インストーラーはコード署名されていません）。
4. インストール、次へ、完了をクリックし、新しいターミナルを開きます。そこで doc-control server.capabilities が動作します。

例

2 つの段落がある story.docx を使用します。単語を検索してから、1 回のバッチで置換し、次の段落にコメントします（長いエンベロープは ... で省略しています。残りは実際の出力です）。

$ doc-control text.find --json '{"doc": "story.docx", "query": "rain"}'
{"api": "1.0", "ok": true, "op": "text.find", ..., "result": {"matches": [{"at": "p1#bfa780f9:4-8",
 "text": "rain", "context": "The rain had not stopped since Tuesday…"}], "total": 1, ...}}

$ doc-control doc.batch --json '{"doc": "story.docx", "ops": [
    {"op": "text.replace", "at": "p1#bfa780f9:4-8", "text": "snow"},
    {"op": "comment.add", "at": "p2#f8b24a64", "text": "Which window?"}]}'
{"api": "1.0", "ok": true, "op": "doc.batch", ..., "result": {"applied": 2, "dry_run": false,
 "preview": [{"op": 0, "at": "p1#bfa780f9:4-8", "before": "rain", "after": "snow"},
             {"op": 1, "at": "p2#f8b24a64", "before": "Ana closed the window and waited.",
              "after": "(comment c0 by Claude: Which window?)"}],
 ..., "author": "Claude", "backup": ".../.doc-control/story.docx/backups/20261020T091845Z-0ff4dc24.docx",
 "op_id": "h-000001"}, "warnings": [], "next": null}

$ doc-control review.list --json '{"doc": "story.docx"}'
{..., "result": {"totals": {"comments": 1, "insert": 0, "delete": 0, "replace": 1, ...},
 "paragraphs": [{"at": "p1#c6f909ff", "text": "The snow had not stopped since Tuesday.",
   "changes": [{"type": "replace", "ids": ["1", "2"], "author": "Claude", "old": "rain", "new": "snow", ...}]},
  {"at": "p2#f8b24a64", "text": "Ana closed the window and waited.",
   "comments": [{"id": "0", "author": "Claude", "text": "Which window?", "quote": "Ana closed the window and waited.", ...}]}]}, ...}

Word では、置換箇所が変更履歴の削除と挿入として表示され、コメントは余白に表示されます。編集後に古いアドレスを再利用すると、推測で処理されるのではなく、エラーになります。

$ doc-control text.replace --json '{"doc": "story.docx", "at": "p1#bfa780f9:4-8", "text": "fog"}'
{"api": "1.0", "ok": false, "op": "text.replace", "error": {"code": "STALE_ADDRESS",
 "message": "p1#bfa780f9 no longer matches the document",
 "hint": "Re-read the paragraph (para.get) or resolve its anchor, then retry.",
 "details": {"address": "p1#bfa780f9", "current": "p1#c6f909ff"}}}

AI エージェントで使う

MCP サーバー

doc-control mcp は、標準入出力経由で60以上の操作をMCPツールとして提供します。各操作に対して1つのツールがあり（doc.batch は doc_batch になります）、CLIと同じJSONスキーマおよびレスポンスエンベロープを使用します。すべてのツールで outputSchema が宣言されており、呼び出しが成功すると、エンベロープは structuredContent としても返されます。標準ライブラリのみを使用します。

{
  "mcpServers": {
    "doc-control": { "command": "uvx", "args": ["doc-control", "mcp"] }
  }
}

Windows上のWordをライブ操作するには、"args": ["--from", "doc-control[live]", "doc-control", "mcp"] を使用するか、上記の .mcpb 拡張機能をインストールしてください。live_places にはMCP Apps UI（ui:// ページ）も付属しており、そのボタンから live_select を呼び出せます。

グループ	ツール
読み取り	doc_outline, para_list, para_get, para_locate, text_find, doc_stats, doc_segment, review_list, comment_list, revision_list
編集（変更履歴を記録）	doc_batch, text_replace, para_insert, para_delete, comment_add, note_add, term_rename, table_row_insert, table_row_delete
レビュー	revision_accept, revision_reject, doc_diff, doc_compare
レイアウトとフィールド	layout_get, layout_apply, field_list, field_update, toc_insert, caption_add, xref_add, index_mark, index_insert
スタイル	style_*, styleset_*
安全性	history_list, history_undo, history_restore, history_search, ...
ライブウィンドウ	live_status, live_open, live_select, live_places, live_save, live_close, ...
検出	server_capabilities, server_help, recipe_list, recipe_run

{"op": "<name>"} を指定して server_help を呼び出すと、任意の操作のスキーマと概要が返されます。

CLIから

エージェントはCLIを直接操作できます。プロンプトを表示することはなく、--json - を指定した場合にのみ標準入力を読み取ります。標準出力には、{"ok": true, "result": ...} または {"ok": false, "error": {"code", "message", "hint", "details"}} のJSONエンベロープを正確に1つ出力します。 終了コードは、成功が 0、操作エラーが 1、使用方法のエラー（不明な操作または無効なリクエスト）が 2 です。エラーコードの一覧はdocs/errors.mdを参照してください。

想定される手順は、読み取り（doc.outline、para.list、text.find）を行い、1つの doc.batch を作成して、"dry_run": true を指定して実行し、プレビューを確認してから適用し、執筆者にWordの［校閲］ウィンドウを確認してもらうことです。history.undo で書き込みを元に戻せます。

仕組み

• オフセットではなくアドレスを使用します。 p12#a7b2a7b2:4-10 は、段落12、そのテキストのフィンガープリント、文字範囲を表します。段落が変更されると、現在のアドレスとともに STALE_ADDRESS が返されます。anchor.create / anchor.resolve を使うと、編集後に該当箇所を再度見つけられます。
• すべてのコンテンツ変更が変更履歴に記録されます。 作成者は DOC_CONTROL_AUTHOR（既定値は Claude）です。執筆者がすでに承認した編集では、テキスト編集操作と history.restore に "tracked": false を指定します（ファイルエンジンのみ）。
• 安全性レイヤー： ロックファイルとディスク上の変更の検出、各書き込み前のバックアップ、読み戻しによる検証、失敗時の自動復元、取り消し機能付きの操作ログ。
• 1つのAPIでファイルエンジンとライブエンジンに対応します。 ファイルエンジンはPython標準ライブラリを使って、閉じている .docx を編集し、変更が必要な部分のみを書き換えます。読み取りでは .txt、.md、.odt も受け付けます。 ライブエンジンはLibreOffice WriterまたはWord（Windows、COM）で開いているドキュメントを操作します。
• レシピでは修正用のバッチ（スペイン語の組版、引用符、ダッシュ、スペース、空の段落）を提案します。recipe.list を実行し、その後 recipe.run を実行すると、確認して適用できるバッチが返されます。

使い方

操作名は resource.action 形式です。個別の編集操作も、編集1件の doc.batch として実行されます。doc-control server.help <op> を実行すると、操作のスキーマが表示されます。Pythonから使用する場合：

from doc_control import api

with api.open("Novela.docx") as doc:
    for p in doc.paragraphs(normalized=True, pages=True):
        print(p["at"], p["style_name"], p["page"], p["text"][:40])
    chapters = doc.run("doc.segment", {"unit": "chapters"})["chapters"]

脚注、ヘッダー、フッター、表

読み取りの対象は本文です。stories に "notes"（脚注、文末脚注）または "headers"（ヘッダー、フッター）を追加すると、読み取り範囲が広がります。これらの段落にはプレフィックス付きのアドレス（fn3/p1#0c9e0c9e、hdr1.default/...）が付与され、編集時にも使用できます。

doc-control para.list --json '{"doc": "Tesis.docx", "stories": ["body", "notes"]}'
doc-control text.replace --json '{"doc": "Tesis.docx", "at": "fn3/p1#0c9e0c9e:4-10", "text": "2019"}'
doc-control note.add --json '{"doc": "Tesis.docx", "at": "p40#c0ffee00:17", "kind": "footnote", "text": "Ver el cap. 2."}'
doc-control table.row.insert --json '{"doc": "Tesis.docx", "table": 1, "after_row": 2, "cells": ["a", "b"]}'

ページレイアウトとフィールド

layout.get はセクションごとのページ構成（開始位置、改ページ、ページ番号、種類ごとのヘッダーとフッター）を返し、layout.apply は同じ形式の構成をドキュメントに適用します。この例では、小説のタイトルページにはページ番号を付けず、その後、第1章を右ページからページ番号1で開始し、奇数ページのヘッダーには章タイトル、偶数ページには書名を表示します。

doc-control layout.apply --json '{"doc": "Novela.docx", "untracked": true, "plan": {
  "version": 1, "two_sided": true, "mirror_margins": true,
  "sections": [
    {"from": "p1#ea7412aa", "break": "nextPage",
     "numbering": {"shown": false, "start": 1, "format": "lowerRoman"},
     "header": {"default": "", "even": ""}, "footer": {"default": "", "even": ""}},
    {"from": "p2#5fac7aad", "break": "oddPage",
     "numbering": {"shown": true, "start": 1, "format": "decimal"},
     "header": {"default": "{chapter}", "even": "La casa del río"},
     "footer": {"default": "{PAGE}", "even": "{PAGE}"}}]}}'

{PAGE}、{NUMPAGES}、{chapter} はフィールドになります。改ページとページ番号は追跡されますが、新しいヘッダー部分と両面設定は Word では追跡できないため、untracked: true になります。まず "dry_run": true を試してください。field.list、toc.insert、caption.add、xref.add、index.insert はフィールドを扱い、field.update はヘッドレスの LibreOffice を通じてフィールドを更新します。

ライブ：執筆者が開いているドキュメント

doc-control live.open --json '{"doc": "Novela.docx"}'
doc-control doc.batch --json '{"doc": "Novela.docx", "engine": "live", "ops": [
  {"op": "comment.add", "at": "p40#c0ffee00", "text": "¿Seguro?"}]}'
doc-control live.close --json '{"doc": "Novela.docx", "save": true}'

ライブの doc.batch は comment.add、text.replace、para.insert を受け付けます。利用可能なアプリがない場合は、理由とともに ENGINE_UNAVAILABLE を返します。live.status は検出されたアプリを一覧表示し、LibreOffice については、UNO ブリッジに必要な Python も表示します。終了しても未保存の作業が失われることはありません。

環境変数

変数	効果
DOC_CONTROL_AUTHOR	変更履歴とコメントの作成者（デフォルトは Claude）
DOC_CONTROL_STORE	appdata を指定すると、バックアップと履歴をドキュメントと同じ場所の .doc-control/ ではなく、ユーザーストアに保存します
DOC_CONTROL_STORE_DIR	ストアのルートを上書きします
DOC_CONTROL_HOME	ユーザーストアとレシピのフォルダー
DOC_CONTROL_UPDATE_CHECK	1 にすると、GitHub Releases を1日最大1回確認し、新しいバージョンがあれば server.capabilities で通知します。ダウンロードは行いません

すべてローカルで実行されます。アップデート確認をオフ（デフォルト）のままにしておけば、マシンの外に何かが送信されることはありません。

対象外

• AI ではありません。モデルの呼び出しも判断も行わず、エージェントから送られた内容を実行します。
• macOS ではまだライブ制御に対応していません。ライブの doc.batch が対応する編集の種類は一部のみです。
• インデックスは Word が作成します（F9）。引用フィールドは変更されません。

ドキュメント

• コードから生成された操作リファレンスとエラーリファレンス
• Windows へのインストール
• 実際の Word で結果を確認する
• 設計上の判断

開発

uv sync
make check     # ruff, mypy, pytest, hygiene script

作業は claude-arsenal を使い、ゲート付きタスクとして計画されています。CLAUDE.md を参照してください。

関連プロジェクト

• claude-arsenal — 仕様駆動の Claude Code ワークフローと、ゲート付きタスクキューです。
• drawspec — 宣言型の図表仕様から、クリーンな SVG／PNG／テキストを生成します。LLM が書き込み可能で、MCP サーバーも含まれています。
• literary-critic — プロの編集者のように原稿を分析する LLM です。
• integral-job-search — Claude Code で実行する、候補者中心の求人検索です。

ライセンス

MIT — LICENSE を参照してください。