Skip to main content
Glama
deenesjakoruzh
xyyyang97

doc-agent-mcp

by xyyyang97
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

doc-agent-mcp

CI PyPI Python License: MIT

AIエージェントに、生のテキストをシャッフルさせる代わりに、文書に対する安定した意味論的な操作を提供するModel Context Protocolサーバー。

Human ─────┐
           ↓
        Document          ← Markdown (.md/.markdown) and DOCX today,
           ↑                 Tiptap / SuperDoc / Shimo / Google Docs tomorrow
AI Agent ──┘

LLMエージェントが文書を1つの大きな文字列として編集すると、問題が発生します。見えない書式を壊し、画像やコメントを失い、「セクション3の後に段落を挿入」と表現できません。doc-agent-mcpは文書を正規化され、アドレス可能な構造（見出し、段落、リスト項目、安定したIDを持つテーブル）として公開し、エージェントが安全なループで作業できるようにします：

read  →  propose change  →  inspect diff  →  apply  →  export

これが解決する問題

生テキスト編集（現在の典型的な方法）

doc-agent-mcp

エージェントが1語を変更するためにファイル全体を書き換える

エージェントが1つのブロック内の正確な文字範囲を置換する

テキストコンバーターを介したDOCXの往復変換でスタイル/コメントが破壊される

編集は元のOOXMLパッケージ内で適用され、未変更のコンテンツはそのまま通過する

変更前に何が変わるかを確認する方法がない

すべての編集は統一されたdiffでステージングされ、適用は明示的

人間が同時に編集するときのサイレントな競合

コンテンツハッシュによる楽観的ロック。古い編集は拒否される

プロンプトにハードコードされた形式固有のハック

1つのツールサーフェス、任意のバックエンド

Related MCP server: docx-mcp-server

アーキテクチャ

MCP interface (13 tools)
        ↓
Document operation layer      ← staging, diffs, hashes, search, sessions
        ↓                          (doc_agent_mcp/service.py)
Normalized document model     ← Block(h-0, p-1, li-2, tbl-0), Comment,
        ↓                          ProposedChange   (core/model.py)
Backend adapters              ← parse() + serialize() per format
        ↓                          (adapters/*_adapter.py)
Markdown · DOCX · future editors (Tiptap, SuperDoc, Shimo, Google Docs)

重要な特性：MCPツールは、その下にあるバックエンドを一切知りません。 新しいエディターバックエンドを追加するには、2つのメソッドを実装するだけです — ADAPTER_GUIDE.md を参照してください。

インストール

PyPIから（ユーザー推奨）：

pip install doc-agent-mcp

Python 3.10以上が必要です。

ソースから（開発用）：

git clone https://github.com/xyyyang97/doc-agent-mcp.git
cd doc-agent-mcp

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

確認：

doc-agent-mcp --version
# doc-agent-mcp 0.1.0

MCP設定

サーバーはstdio上で標準MCPを話します。

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "doc-agent": {
      "command": "/absolute/path/to/doc-agent-mcp/.venv/bin/doc-agent-mcp",
      "args": ["--roots", "/Users/you/Documents"]
    }
  }
}

Claude Code / Codex CLI

claude mcp add doc-agent -- /absolute/path/to/doc-agent-mcp/.venv/bin/doc-agent-mcp --roots ~/Documents

汎用MCPクライアント（JSON）

{
  "mcpServers": {
    "doc-agent": {
      "command": "/absolute/path/to/doc-agent-mcp/.venv/bin/doc-agent-mcp",
      "args": [],
      "env": {}
    }
  }
}

--roots DIR [DIR ...] は、すべての読み書きをそれらのディレクトリに制限します（推奨）。これがない場合、サーバーはプロセスが到達できる任意のパスにアクセスできます — サーバー設定をファイルシステムの資格情報のように扱ってください。

利用可能なツール

読み取り操作（変更しない）

ツール

目的

read_document(path, section_id?, include_spans?, doc_hash?)

ID付きの構造化ブロック。オプションで単一セクション表示。unmodeled_featuresを報告

get_outline(path, doc_hash?)

見出しのフラットリストとパス付きのネストされたツリー

find_text(path, query, scope_element_id?, is_regex?, case_sensitive?, doc_hash?)

(element_id, start, end)オフセット付きの正確な出現箇所。propose_replace_textに使用可能。テーブルヒットはeditable: falseとフラグ付け

get_comments(path, doc_hash?)

ネイティブコメント（著者、本文、アンカー要素、引用範囲）

提案操作（変更をステージング。まだ何も書き込まれない）

ツール

目的

propose_replace_text(path, element_id, start, end, text)

1つのブロック内の文字範囲を置換。diffプレビューを返す

propose_insert_block(path, anchor_id, position, kind, text, level?)

任意の要素の前後に段落/見出し/リスト項目を挿入（挿入前/後/追加をカバー）

propose_delete_block(path, element_id)

1つのブロック全体を削除

propose_add_comment(path, anchor_id, body, quote?, author?)

ネイティブWordコメント（DOCX）。Markdownではセッションのみ（制限事項を参照）

コミットとレビュー

ツール

目的

get_changes(path)

統一されたdiff付きのすべてのステージングされた変更

discard_changes(path, change_ids?)

ステージングされた変更を破棄（すべてまたは選択）

apply_changes(path, change_ids?, doc_hash?)

アトミックにディスクに書き込む。新しいdoc_hashと警告を返す

export_document(path, target_format, output_path?, title?)

モデルを介して変換：md↔docxの双方向

list_backends()

登録されたバックエンドとサポートされている変換

すべての変更/読み取り呼び出しは、前回の呼び出しで取得したdoc_hashを受け入れます。ファイルが（別のプロセスによっても）変更された場合、{"code": "stale_document", ...}が返され、ステージングされた変更は破棄されます — 最初に再読み取りしてください。

ワークフロー例

これはexamples/demo_workflow.pyが（実際のファイルに対して）実行する正確なループです：

from doc_agent_mcp.service import DocumentService

svc = DocumentService()                      # same facade the MCP tools wrap

# 1. Understand the document
outline = svc.get_outline("brief.md")
summary = next(h for h in outline["headings"] if h["title"] == "Executive Summary")
section = svc.read_document("brief.md", section_id=summary["id"])

# 2. Locate exact text
hit = svc.find_text("brief.md", "30 percent")["matches"][0]

# 3. Stage a change (file is untouched)
proposal = svc.propose_replace_text(
    "brief.md", hit["element_id"], hit["start"], hit["end"],
    "at least 30 percent (validated with finance)",
)

# 4. Review the diff
changes = svc.get_changes("brief.md")
print(changes["changes"][0]["diff"])

# 5. Commit, then export
svc.apply_changes("brief.md", doc_hash=proposal["doc_hash"])
svc.export_document("brief.md", "docx", output_path="brief.docx")

MCP上では、同じ手順がそれぞれ1つのツール呼び出しになります — 上記のツール表を参照してください。

完全なデモを実行（Markdown + DOCX + エクスポート + 古いガード、すべて検証済み）：

.venv/bin/python examples/demo_workflow.py

サンプル文書はexamples/documents/にあります：sample.mdとsample.docx（後者には2つのネイティブWordコメントがあり、scripts/make_sample_docx.pyで再生成可能）。

エラー処理

すべてのエラーは構造化JSONです — ワイヤー上にトレースバックはありません：

{
  "code": "element_not_found",
  "message": "Element 'p-99' not found. Call get_outline ...",
  "details": {"element_id": "p-99"}
}

コード

意味

document_not_found

パスが存在しない

unsupported_format

この拡張子に対応するバックエンドがない

element_not_found

古い/不明な要素ID

match_not_found / ambiguous_match

検索で何も見つからない / 曖昧さ回避用に予約

validation_error

不正な範囲、不正な引用アンカー、テーブルセル置換、ルート外のパス...

stale_document

スナップショット以降にファイルが変更された。ステージングされた変更は破棄された

change_not_found

不明または既に破棄されたchange_id

export_error

サポートされていない変換ペア

テスト

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest                 # unit + integration + MCP protocol tests
.venv/bin/ruff check src tests   # lint
.venv/bin/ruff format --check .  # formatting
.venv/bin/mypy                   # strict type checking

スイートには、DOCX往復テスト（保存されたファイルをpython-docxで再オープンし、生のOOXMLレベルで編集を検証）と、stdio上でサーバーを起動して実際のプロトコルメッセージを話すエンドツーエンドのMCPテストが含まれています。

制限事項（偶然ではなく設計による）

正規化モデルは、MarkdownとDOCXの両方が確実に表現できるものをカバーしています。それ以外のものは、すべての読み取りでunmodeled_featuresとして明示的に表面化されます — 決して静かに破壊されることはありません：

  • DOCX: 画像/図形、ヘッダーとフッター、脚注/文末脚注、コンテンツコントロール、ソースに存在する変更履歴は、変更されずに保持されますが、モデルには見えません。テーブルはプレーンテキストのセルです（セルの書式はモデル化されていません）。replace_textはハイパーリンクを含む段落を拒否します（書き換えで破壊されるため）。

  • Markdown: シリアライゼーションはモデル忠実であり、バイト忠実ではありません — コンテンツは往復を生き延びますが、元の行折り返し/マーカースタイルは維持されない場合があります。ブロッククォートはその段落にフラット化されます（フラグ付き）。参照スタイルのリンク定義は解決されインライン化されます。コメントにはネイティブな場所がありません：propose_add_commentはセッションのみに保存し、その旨を明示します。

  • テーブル: 検索可能（editable: falseとフラグ付け）ですが、セルレベルの編集はまだ実装されていません — 代わりに削除/再挿入してください。

  • 並行エージェント: ファイルごとに最後の書き込みが優先され、ハッシュチェックで保護されます。マージエンジンはありません。

ロードマップのアイデア

  • テーブルセル操作（update_table_cell）

  • Tiptap/SuperDocアダプター（それらのJSONモデル上）

  • Drive APIを介したGoogle Docsアダプター（コメントはネイティブにマップ）

  • Markdown用のアンカー付き提案モード（<!-- suggestion -->ブロック）

  • マルチファイルワークスペースとリネーム安全なセッション

ライセンス

MIT

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • writespace-mcp

    Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.

  • TablaCognita

    MCP-native collaborative markdown editor with real-time AI document editing

  • superdocs

    AI document editing for agents: draft, edit, export .docx/PDF. 37 MCP tools; agent self-signup.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xyyyang97/doc-agent-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server