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 ---マーカーが付くため、"page 3"を示す場合、それは3ページ目であることが保証されます。

• 長いドキュメントは、オーバーラップとページヒントを使う、決定論的にチャンク分割されます。

• 抽出されたJSONはJSON Schema (Draft 2020-12)に対して検証され、すべてのエラーはJSON Pointerパスで報告されます(最初のエラーだけではありません)。そのため、モデルは1回の修正で全エラーを直せます。

• 出力はサーバーが(JSONまたはCSV)同じルート内に書き出し、行数とバイト数を検証できます。

Related MCP server: BigContext MCP

ツール

すべてのパス引数は、許可ルートの外側に解決される場合に拒否されるよう解決されます(パス・トラバーサル・ガード)。glob_pattern引数も同じ方法で制限されます。..を含むabsoluteパターンやパターンは拒否され、ルート外(たとえシンボリックリンクを通る)に解決される一致は、サイレントにリストから落とされます。ガードで失敗した場合、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. The LLM is JSONにフィールドを抽出する。

5. validate_json(data, json_schema) — 報告されたすべてのエラーを修正し、再検証する。

6. save_structured("out/invoice.json", data, "json") — 結果を書き込む。

制限事項(正直なところ)

• テキストベースのPDFのみ。 抽出はpypdfに依存しており、スキャンや画像のみのPDFは空のテキストになります。OCRはありません。

• 抽出品質は、PDFがどのように作成されたかに依存します。複雑なレイアウト(多カラム、重いテーブル)は、読み順が完璧でohne場合があります。これはpypdfの特性であり、このサーバーはそれを継承しています。

• .docx/.xlsxサポート。対応型は.pdf, .txt, .md, .csv, .json。

• サーバーはまた抽出の推論を行いません。請求書の合計をあなたの代わりに見つけるわけではないのです。モデルが実際のテキストに基づいて作業し、結果がスキーマ不一致ないことを確認します。

• これは、私が取り組んでいるAI自動化ワークフロー用に構築した実動ツールであり、ポートフォリオの一部として公開されています。新しいもので、本番での実績はまだありません。テストとパス・トラバーサル・ガードはありますが、そこに堅牢化はされていません。敏感なディレクトリを指す前にレビューしてください。

開発

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

テスト部のテストスイートは、小規模な2ページのPDFフィクスチャをメモリ内で作成(最小限の手構築PDF、追加依存はありません)し、6つのツールすべて、パス・トラバーサル・ガード、グログパターンの制限(シンボリックリンクの回避を含む)、ページ範囲エラー、複数エラーのスキーマ検証、CSVラウンドトリップ、ツール登録とMCPサーバーオブジェクトを介したエラーの伝播をカバーしています。

ライセンス

MIT © 2026 Koray Nar