mcp-ooxml-ledger

mcp-ooxml-ledger

Office ドキュメントを編集し、記録されていない編集がある場合は書き込みを拒否する MCP サーバーです。

セッションを封印する前に、記録されたすべての操作をドキュメントのベースラインに対して再実行し、その結果と実際にディスク上にある内容を比較します。どの操作でも説明できない変更があれば、コミットは拒否されます。競合する約18の MCP ドキュメント編集プロジェクトのうち、このチェックを通過しないと書き込みを行わないものはありません。この拒否機能こそが、この製品の特長です。

セットアップ

uv add mcp-ooxml-ledger

.mcp.json（プロジェクト）または claude_desktop_config.json（デスクトップ。絶対パスを使用してください。${CLAUDE_PROJECT_DIR} はここでは展開されません）に追加します。

{
  "mcpServers": {
    "ooxml-ledger": {
      "command": "uv",
      "args": ["run", "--project", "${CLAUDE_PROJECT_DIR}", "ooxml-ledger-mcp"],
      "env": { "OOXML_LEDGER_ROOTS": "${CLAUDE_PROJECT_DIR}" }
    }
  }
}

PATH に uv が必要です。それ以外はグローバルにインストールする必要はありません。ooxml-ledger-mcp スクリプトを直接呼び出すと ENOENT が発生します。スクリプトはシェルの PATH ではなく、プロジェクトの仮想環境内にあります。

OOXML_LEDGER_ROOTS がセキュリティ境界です。 os.pathsep で区切られたリストです。各ツールが受け取るすべてのパスは、この境界内に解決され、境界外では拒否されます。未設定の場合はサーバーの作業ディレクトリが既定値になります。export_receipt はルート内のどこにでも書き込むため、意図的に設定してください。

ツール

	ツール
セッション	open_document · close_document	書き込み
読み取り	describe_structure · find_text	読み取り専用
編集	preview_edits · apply_edits · delete_paragraph · insert_paragraph	書き込み
封印	commit_document	書き込み・ゲートを適用
ステートレス	server_info · digest · verify · list_receipts	読み取り専用
	export_receipt	書き込み
転送	import_document	書き込み — _inbox/ 内のみ
	export_document	読み取り専用

一般的な手順：

open_document → find_text → preview_edits → apply_edits → commit_document → verify

sid = open_document(document="report.docx")["session_id"]
find_text(sid, query="Q3 revenue")                     # → part, para_id, para_hash
preview_edits(sid, edits=[...], author="alice")        # → what WOULD happen; writes nothing
apply_edits(sid, edits=[...], author="alice", mode="tracked")
commit_document(sid)                                   # → refuses if anything is unaccounted for
verify("report.docx")                                  # → verified | unknown | failed

preview_edits は一時コピーに対して apply_edits と同じエンジン関数を実行するため、両者の結果が食い違うことはありません。バッチは全件成功か全件失敗です。編集に失敗した場合、ドキュメントはバイト単位で変更されません。

mode="tracked" は、レビュアーがドキュメント内で確認できる Word の変更履歴マークを出力します。mode="direct" は履歴マークなしでテキストを書き換えますが、編集は完全に記録されます。また、変更履歴に対応したパーツに直接編集が加えられたことがレシートに明記されるため、通常の保存と気づかれないまま区別できなくなることはありません。

チャットおよびホスト型クライアント

チャットにアップロードしたファイルはサーバーのファイルシステムではなく、クライアントのサンドボックスに保存されるため、open_document がそのパスを拒否するのは正しい動作です。OOXML_LEDGER_ROOTS を広げてもアクセスできません。代わりにバイト列を送信してください。

import_document → open_document → … → commit_document → export_document

p = import_document(name="report.docx", content_base64="UEsDB…")["path"]  # → <root>/_inbox/report.docx
sid = open_document(document=p)["session_id"]
...                                                    # edit as usual
commit_document(sid)                                   # → receipt schema ooxml-ledger/2
export_document(document=p)                            # → file + receipt as embedded resources

• 保存先。 import_document はファイル名だけを受け取り、最初のルートの下にある _inbox/<name> に書き込みます。既存のファイルを上書きすることはなく、公開する前にバイト列が実際の Office パッケージであることを検証します。
• 大きなファイル。 モデル自身が base64 を出力する必要があるため、1 回の呼び出しで送れる量は上限よりはるかに少なくなります。チャンクを送信してください。final=false は upload_id を返します。これと offset（受信済みバイト数）を指定して続けてください。final=true の呼び出しにはファイル全体の sha256 を含める必要があります。チャンクの欠落や重複は拒否され、別のドキュメントとして扱われることはありません。
• サイズ上限。 OOXML_LEDGER_IMPORT_MAX_BYTES は、どちらのツールが受け入れるドキュメントにも適用される最大サイズを、デコード後のバイト数で設定します。デフォルトは 25 MiB です。
• 来歴。 このホスト上でインポートされたドキュメントの最初のバイト列は、ユーザーのファイルシステムではなくツール呼び出しから取得されています。そのため、この来歴を引き継ぐすべてのレシートは、チェーンに紐付けられた provenance ブロック（docs/superpowers/specs/receipt-format-v2.md）を持つ ooxml-ledger/2 として封印されます。verify はこれを PROVENANCE 行として出力しますが、判定結果は変わりません。それ以外のすべてのドキュメントのレシートは、以前とバイト単位で同一の ooxml-ledger/1 のままです。
• 取り出し。 export_document は、Office のメディアタイプとレシートを添えて、MCP 埋め込みリソースとしてファイルを返します。デフォルトでは、保存済みのレシートと一致しないドキュメントを拒否するため、封印されていない編集内容が渡されることはありません。上書きするには require_receipt=false を指定してください。

形式の対応表

形式	検証	編集
Word .docx	はい	はい — 変更履歴あり＋直接編集、段落の挿入／削除
PowerPoint .pptx	はい	直接編集のみ — PresentationML には変更履歴モデルがないため、編集のたびに必須の開示が伴います
Excel .xlsx	はい	いいえ — 編集用の動詞は形式名を示して拒否します

検証、ダイジェスト、ゲート、レシートモデルは形式に依存しません。形式ごとに異なるのは編集エンジンのみです。wml.py（Word）と pml.py（PowerPoint）です。

読み取り専用のデプロイ

OOXML_LEDGER_READ_ONLY=1 では、server_info、digest、verify、list_receipts、export_document だけが利用できます。 ほかのツールは単に非表示になるのではなく、呼び出すと Unknown tool が返されます。ルート内には書き込み可能なインターフェースが一切ありません。

CLI

ooxml-ledger verify report.docx    # exit 0 only when verified

サーバーもセッションも不要です。ファイルのダイジェストを計算し、コンテンツアドレスからレシートを検索して検証します。CI または pre-commit フックに組み込めば、記録されていない変更があるとビルドが失敗します。

デスクトップバンドル（.mcpb）

すべての GitHub リリースには .mcpb ファイルが添付されます。これは Claude Desktop にワンクリックでインストールできるファイルです。アプリにドラッグすると、Desktop は uv run --directory <bundle> --frozen --no-dev ooxml-ledger-mcp で起動します。バンドルには何も同梱されず、含まれるのは manifest.json、pyproject.toml、uv.lock、 README.md、LICENSE、src/ だけです。ホストでは uv が PATH 上に必要です。初回起動時には、uv.lock で固定された正確な依存関係のバージョンを PyPI から取得するため、ネットワークアクセスが必要です。 --frozen により、テストスイートで実行されたものとまったく同じバージョンがインストールされ、新たに依存関係が解決されることはありません。また、--no-dev により、開発グループ（pytest、ruff、pre-commit）はインストール対象から除外されます。mcpb/manifest.json では、ドキュメントルートと読み取り専用の切り替えを環境変数ではなくインストール時の設定として公開します。ツール一覧は stdio サーバーのものと一致します。

CI は macos-latest のみでバンドルをビルドしてスモークテストを行い、マニフェストの compatibility.platforms も darwin のみを宣言しています。このバンドルのビルドと動作が確認されているのは macOS/arm64 だけで、それ以外は対象外です。 何も同梱されていないため、uv 自体が requires-python = ">=3.13" を満たす Python を選び、uv.lock で固定された、pydantic-core や cryptography などのネイティブなものも含む、ホストのプラットフォーム向けのホイールをインストールします。この部分は darwin 固有ではありませんが、ここでエンドツーエンドの動作が実証されているのは darwin の起動経路だけです。

制限事項について

• 署名のないレシートは、不注意による変更を検出できますが、改ざんは検出できません。 エージェントが汎用的なファイル書き込みにフォールバックした場合や、Office で再保存された場合、不注意な共同作業者による変更は検出できますが、ドキュメントと一緒にレシートも書き換える人による変更は検出できません。そのハッシュを保持者が管理できない場所（git commit、DOI、投稿ポータルなど）に記録すれば、改ざんを検出できるようになります。
• インポートした来歴情報は _inbox/ の隣に保存されます。 インポート記録は、インポートしたファイルとともにストアに格納されます。最初のコミット前にそのファイルを _inbox/ から移動すると、記録が失われるため、最初のレシートは v1 として書き込まれます。コミット後は、来歴情報がレシートストアとともに維持されます。来歴記録が示すのは受け取ったファイルの内容であり、それがユーザーの元のアップロードと一致することではありません。必要であれば、別途 sha256 を比較してください。
• v0.3.0 の検証ツールは ooxml-ledger/2 を拒否します。 これは意図的な動作です。genesis ルールを検証できないため、理解できないチェーンを黙って受け入れるより、拒否するほうが適切です。
• verify は再実行しません。 ダイジェストとレシートの内部整合性を確認します。再実行はコミット時に一度だけ行われ、verify はそれを再計算せず、その判定結果を報告します。
• pptx と xlsx には、人が目で確認できる記録がありません。 Word の変更履歴はドキュメント内の第 2 の記録層ですが、この 2 つの形式にはそれがないため、台帳が唯一の記録となります。
• Word エンジンが対象とするのは段落テキストのみです（w:p／w:r／w:t）。スタイル、番号付け、設定、リレーションシップは編集できず、説明責任の確認のみで対象となります。

コントリビューションとセキュリティ

CONTRIBUTING.md では、セットアップ、CI で適用されるブランチ名とコミット名の規則、リリースフローについて説明しています。SECURITY.md では、脆弱性を非公開で報告する方法を説明し、このプロジェクトで文書化されている制限のうち、設計上のものと不具合のものを明確に区別しています。

MIT ライセンスです。設計メモと仕様は docs/superpowers/ にあります。