doc-extract-mcp

doc-extract-mcp

LLM に構造化データ抽出ワークフロー向けの決定論的なドキュメント処理ツールを提供する、MCP（Model Context Protocol）サーバーです。読み取りと抽出の推論は LLM が行います。このサーバーは、言語モデルに任せるべきではない処理、すなわち信頼性の高いファイルアクセス、解析、チャンク分割、JSON Schema 検証、制限付きのファイル出力を担当します。

Koray Nar が、構築中の AI ドキュメント自動化ワークフローのポートフォリオプロジェクトとして開発しました。対象となるユースケースは、扱いにくい PDF（発注書、請求書、レポート）をスキーマ検証済みの JSON に変換することです。公開ポートフォリオの一部として公開されています。Claude Code や Claude Desktop、およびその他すべての MCP クライアントと連携します。

理由

抽出エージェントは、予測可能な場面で失敗します。ファイルの内容を幻覚し、長いドキュメントの把握を失い、対象スキーマにほぼ合致するだけの JSON を気付かれないまま出力し、好きな場所に出力を書き込みます。このサーバーは、そうした失敗を防ぎます。

• ファイルアクセスは、許可された単一のルート（DOC_EXTRACT_ROOT）に限定されます。
• PDF のテキストには明示的な --- page N --- マーカーが付くため、「3 ページ目」の引用は実際の 3 ページ目を指します。
• 長いドキュメントは、重複部分とページのヒントを付けて決定論的にチャンク分割されます。
• 抽出された JSON は JSON Schema（Draft 2020-12）に照らして検証され、すべてのエラーが JSON Pointer パスとともに報告されます。最初のエラーだけでなく、すべて報告されるため、モデルは一度にすべての誤りを修正できます。
• 出力はサーバーによって（JSON または CSV で）同じルート内に書き込まれ、行数とバイト数を検証できます。

ツール

ツール	引数	説明
list_documents	directory, glob_pattern='*'	許可されたルート内のディレクトリにあるファイルを、サイズと更新日時とともに一覧表示します。**/*.pdf のような再帰的なグロブをサポートします。パターンは相対パスで、.. を含んではいけません。ルート外に解決される一致項目は除外されます。
read_document	path, pages=''	ドキュメントのテキストを返します。.pdf は pypdf で処理し、--- page N --- マーカーと、任意の 1 始まりのページ選択（'3'、'1-5'、'1-3,7'）に対応します。.txt／.md／.json は直接読み込み、.csv は列幅を揃えたテキスト表として表示します。未対応の種類には明確なエラーを返します。
document_info	path	コンテンツ全体を読み込まずにメタデータを返します。種類、サイズ、更新日時に加え、PDF の場合はページ数と PDF メタデータ、テキストファイルの場合は行数を返します。
chunk_document	path, max_chars=4000, overlap=200	ドキュメントを、インデックス、開始オフセット、および（PDF の場合）ページのヒントを含む、順序付けられた重複のあるチャンクに分割します。
validate_json	data, json_schema	JSON Schema（Draft 2020-12）に照らして JSON 文字列を検証します。Draft202012Validator.iter_errors を使い、JSON Pointer パスとともにすべての検証エラーを返します。
save_structured	path, data, format='json'|'csv'	抽出したデータを許可されたルート内に書き込みます。CSV では、フラットなオブジェクトの JSON 配列を指定します。書き込んだパス、行数、バイト数を返します。

すべてのパス引数は解決され、許可されたルートの外に出る場合は拒否されます（パストラバーサル防止）。glob_pattern 引数にも同じ制限が適用されます。絶対パターンと .. を含むパターンは拒否され、ルート外に解決される一致項目（たとえばシンボリックリンク経由のもの）は一覧から黙って除外されます。ガードによる拒否は MCP ツールエラーとして発生するため、呼び出し元のモデルには一般化されたエラーではなく、実際の理由が伝わります。

クイックスタート

Python 3.11 以降と uv が必要です。

git clone https://github.com/koraynar/doc-extract-mcp.git
cd doc-extract-mcp
uv venv
uv pip install -e .

スタンドアロンで実行（stdio トランスポート）：

DOC_EXTRACT_ROOT=/path/to/your/documents uv run doc-extract-mcp

Claude Code

claude mcp add doc-extract --env DOC_EXTRACT_ROOT=/path/to/your/documents \
  -- uv run --directory /absolute/path/to/doc-extract-mcp doc-extract-mcp

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "doc-extract": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/doc-extract-mcp",
        "doc-extract-mcp"
      ],
      "env": {
        "DOC_EXTRACT_ROOT": "/path/to/your/documents"
      }
    }
  }
}

DOC_EXTRACT_ROOT が設定されていない場合、デフォルトではサーバーの作業ディレクトリが使われます。ドキュメントが保存されているフォルダーを設定してください。そのフォルダーの外は読み取りも書き込みもできません。

典型的なワークフロー

1. list_documents(".", "*.pdf") — 請求書を見つけます。
2. document_info("invoice.pdf") — ページ数を確認します。
3. read_document("invoice.pdf", "1-3") または chunk_document(...) — テキストを取得します。
4. LLM がフィールドを JSON に抽出します。
5. validate_json(data, json_schema) — 報告されたエラーをすべて修正し、再検証します。
6. save_structured("out/invoice.json", data, "json") — 結果を書き込みます。

制限事項（率直にお伝えします）

• テキストベースの PDF のみ対応しています。 抽出には pypdf を使用します。スキャン画像のみの PDF では、テキストが空になります。OCR はありません。
• 抽出品質は PDF の作成方法によって異なります。 複雑なレイアウト（複数段組、表が多い場合）では、読み取り順序が不完全になることがあります。これは pypdf の特性であり、このサーバーにも引き継がれています。
• .docx / .xlsx には対応していません。 対応形式は .pdf、.txt、.md、.csv、.json です。
• このサーバーは抽出に関する推論を行いません。 請求書の合計金額を見つけることはありません。抽出を行うモデルが実際のテキストを基に処理し、その結果がスキーマに一致することを確認します。
• これは、私が取り組んでいる AI 自動化の作業向けに構築し、ポートフォリオの一部として公開した実用ツールです。公開されたばかりで、まだ本番環境での実績はありません。テストとパスの制限を守るガード機能はありますが、それ以上の堅牢化は行っていません。機密性の高いディレクトリを対象にする前に、確認してください。

開発

uv venv
uv pip install -e '.[dev]'
uv run pytest

テストスイートでは、メモリ内で 2 ページの PDF フィクスチャ（余分な依存関係を必要としない、最小限の手書き PDF）を作成し、6 つすべてのツール、パストラバーサル防止機能、シンボリックリンクによるパス逸脱を含む glob パターンの制限、ページ範囲エラー、複数エラーのスキーマ検証、CSV の往復処理、MCP サーバーオブジェクトを介したツールの登録とエラー伝播を網羅します。

ライセンス

MIT © 2026 Koray Nar