pdf-extract-mcp

非構造化PDF文書から構造化データを決定的に抽出するModel Context Protocol（MCP）サーバーです。プレーンテキスト抽出に加え、正規表現／ヒューリスティックによるフィールド照合を行い、抽出時にLLM APIを呼び出しません。

特徴

• 本格的なMCPサーバー — 公式のMCP Python SDK（2.x）上に構築され、stdio、SSE、ストリーミング可能なHTTPでプロトコルを話します。公式クライアントで実際のサーバーを駆動するエンドツーエンドテストで検証済みです。

• スキーマ駆動の抽出 — extract_fieldsに任意のJSON Schemaを指定するだけで、要求したフィールドだけを構造化JSONとして取得できます。

• 決定的かつ検証可能 — 正規表現／ヒューリスティックによる照合で、LLM API呼び出しなし、隠れたコストなし、ブラックボックスなし。すべての抽出が再現可能かつ監査可能です。

• 人間が読める検証レポート — validate_against_schemaがフィールドごとに合格・不合格・欠落の理由を説明します。

• 組み込みスキーマ — invoice（請求書）、resume（履歴書）、purchase_order（発注書）がすぐに使える状態で同梱されており、デモ用のサンプルPDFも付属しているため、箱から出してすぐにすべてを実演できます。

• エラー処理が丁寧 — 破損したPDF、存在しないファイル、不正なスキーマに対し、スタックトレースではなく構造化されたエラーを返します。

Related MCP server: StructureAI MCP Server

MCPとは何か、なぜこれが有用か

Model Context Protocolは、AIアシスタント（Claude、Cursorなど）が永続的な双方向接続を介して外部ツールを呼び出せるようにするオープン標準です。PDFのテキストをチャットに貼り付けて「なんとか解釈して」とモデルに頼る代わりに、アシスタントはpdf-extract-mcpを直接呼び出し、あなたが提供したスキーマに一致する構造化JSONを受け取り、それに基づいて行動できます。ここでの抽出は（正規表現＋ヒューリスティックによる）決定的な処理であり、確率的なモデル呼び出しではないため、すべての結果が検証可能で、再現可能で、低コストです。そのため、フィールドがなぜそのように抽出されたかを把握する必要がある自動文書パイプライン（会計向け請求書、ATS向け履歴書、調達向け発注書）に最適です。

インストール

cd pdf-extract-mcp
python3 -m venv .venv
source .venv/bin/activate
make install          # pip install -e ".[dev]"  (installs the console script too)

または、素のpipで:

pip install -e ".[dev]"

このサーバーは公式のMCP Python SDK（mcp >= 2.x、現在のリリースラインであり、MCPServer APIを提供）を使用しています。pdfplumberがテキスト抽出を、jsonschemaが検証を、reportlabがサンプルPDFの生成を担当します。

インストールするとpdf-extract-mcpコンソールスクリプトも提供されるため、どこからでもサーバーを実行できます:

pdf-extract-mcp                     # stdio (default)
pdf-extract-mcp --transport streamable-http --host 127.0.0.1 --port 8000

実行

python server.py

これによりMCPがstdio経由で提供されます（デフォルトであり、Claude Code / Claude Desktopが期待する方式です）。ネットワークサービスとして公開することもできます:

python server.py --transport streamable-http --host 127.0.0.1 --port 8000
python server.py --transport sse --host 127.0.0.1 --port 8001

Claude Code / Claude Desktopに接続

Claude Code — プロジェクトルートに.mcp.jsonを追加します:

{
  "mcpServers": {
    "pdf-extract": {
      "command": "python",
      "args": ["/absolute/path/to/pdf-extract-mcp/server.py"],
      "env": {}
    }
  }
}

Claude Desktop — 同じブロックをClaude Desktopの設定（macOSでは~/Library/Application Support/Claude/にあるclaude_desktop_config.json）に追加します:

{
  "mcpServers": {
    "pdf-extract": {
      "command": "python",
      "args": ["/absolute/path/to/pdf-extract-mcp/server.py"]
    }
  }
}

保存後、クライアントを再起動してください。extract_fields、validate_against_schema、list_supported_document_typesの3つの新しいツールが表示されるはずです。

ツール

extract_fieldsのschema引数には、JSON Schemaオブジェクト、組み込みスキーマの名前（例: "invoice"）、または.jsonスキーマファイルへのパスのいずれかを指定できます。組み込みスキーマはschemas/にあります:

• invoice — vendor_name、invoice_number、total_amount、due_date（必須）+ issue_date、customer_name

• resume — name、email（必須）+ phone、skills

• purchase_order — po_number、vendor_name、total_amount（必須）+ issue_date、customer_name

実例

まずサンプルPDFを生成します（リポジトリにすでに存在します。いつでも再生成できます）:

python sample_pdfs/generate_samples.py

次に、組み込みのinvoiceスキーマ名を使用して、サンプル請求書に対してextract_fieldsを呼び出します。Claude Codeでは「sample_pdfs/invoice.pdfからinvoiceスキーマを使ってフィールドを抽出して」と言うだけで、内部的には以下と同等のツール呼び出しが発行されます:

{
  "name": "extract_fields",
  "arguments": {
    "pdf_path": "/absolute/path/to/pdf-extract-mcp/sample_pdfs/invoice.pdf",
    "schema": "invoice"
  }
}

実際の期待結果:

{
  "ok": true,
  "data": {
    "vendor_name": "Acme Widgets Corp",
    "invoice_number": "INV-2024-0087",
    "total_amount": 1750.0,
    "due_date": "April 1, 2024",
    "issue_date": "March 1, 2024",
    "customer_name": "Globex Industries"
  },
  "text_length": 372
}

同じスキーマでデータをvalidate_against_schemaに渡すと:

{
  "ok": true,
  "valid": true,
  "passed": ["customer_name", "due_date", "invoice_number", "issue_date", "total_amount", "vendor_name"],
  "failed": [],
  "missing": [],
  "summary": "Valid: all 6 present field(s) conform to the schema.",
  "error": null
}

Pythonから直接実行してライブで確認:

import json
from tools.extract import extract_fields
from tools.validate import validate_against_schema

schema = json.load(open("schemas/invoice.json"))
result = extract_fields("sample_pdfs/invoice.pdf", schema)
print(result["data"])
print(validate_against_schema(result["data"], schema))

server.pyにおけるMCPツール登録の仕組み

これがこのプロジェクトの核心なので、SDKが代わりに何をしているかを正確に理解する価値があります。

1. サーバーオブジェクトを作成。

from mcp.server.mcpserver import MCPServer

mcp = MCPServer(
    "pdf-extract-mcp",
    title="PDF Extract MCP",
    description="Deterministic structured-data extraction from PDF documents",
    version="0.2.0",
)

MCPServerはmcp SDK 2.xのサーバークラスです。MCPワイヤープロトコルを実装しており、MCPハンドシェイク中にクライアントが送信するJSON-RPCメッセージ（initialize、tools/list、tools/callなど）に応答する方法を理解しています。コンストラクタ引数はメタデータです。サーバーの名前（プロトコルハンドシェイクに必須）に加え、クライアントがユーザーに表示する可能性のある任意のタイトル／説明／バージョンを指定します。

2. デコレータで各ツールを登録。

@mcp.tool()
def extract_fields(pdf_path: str, schema: dict) -> dict:
    """Extract structured fields from an unstructured PDF ..."""
    return _extract_fields(pdf_path, schema)

デコレータは次の3つの仕事を代行します:

• 名前の登録 — 関数名extract_fieldsが、クライアントが呼び出しに使用するツール名になります（@mcp.tool(name="...")で上書き可能）。

• スキーマの推論 — SDKが関数の型注釈（pdf_path: str、schema: dict）を検査し、ツールのJSON入力スキーマを自動生成します。そのためMCPクライアントは呼び出す前に、pdf_pathが文字列でschemaがオブジェクトであることを認識できます。これはFastAPIと同じパターンです。型それ自体が契約なのです。

• 説明 — docstringがツールの説明になり、Claudeはそれを読んでツールをいつ・どんな引数で呼ぶかを判断します。

つまりクライアントがサーバーに「何ができますか？」（tools/list）と尋ねると、SDKはデコレータが付いた各関数の名前、説明、推論された入力スキーマで応答します。手動で同期を保つ登録テーブルは不要です。

3. 関数本体はただのPythonです。

クライアントがツールを呼び出すと（引数付きのtools/call）、SDKはJSON引数をデシリアライズし、その引数で関数を呼び出し、戻り値をワイヤー経由でシリアライズして返します。戻り値がクライアントの目に見えるものです。そのためツールは常にプレーンなJSON化可能なdictを返し、決して例外を発生させません。例外は不透明なプロトコルエラーになりますが、構造化された{"ok": false, "error": "..."} dictはClaudeが読んで反応できるものだからです。実際の抽出／検証ロジックはtools/extract.pyとtools/validate.pyにあり、MCPクライアントなしでユニットテスト可能な状態を保っています。

4. 実行します。

if __name__ == "__main__":
    main()   # argparse -> mcp.run(transport="stdio")

mcp.run(transport="stdio")はプロトコルループを開始します。stdinから改行区切りのJSON-RPCリクエストを読み取り、登録されたツールにディスパッチし、応答をstdoutに書き込みます。これがサーバーの全体です。HTTPフレームワークもルートも手動のリクエスト処理もありません（streamable-http / sseの場合は、同じrun()呼び出しが内部のASGIアプリを起動します）。

もう1つ注目すべき詳細: extract_fieldsは、スキーマdict、組み込みスキーマ名、ファイルパスのいずれかを受け入れる小さなヘルパー_load_schemaを使用しています。つまり同じツールが"invoice"でも完全なスキーマオブジェクトでも機能します。実際の抽出関数は厳密なまま（dictのみ）で、サーバーレイヤーが利便性のための変換を処理します。

抽出の仕組み（決定的・検証可能）

1. テキスト抽出 — pdfplumberがPDFを開き、全ページからプレーンテキストを取得します。

2. フィールド照合 — スキーマの各プロパティに対して、順序付けられた正規表現のリストが試行され、最初に一致したものが採用されます（tools/extract.py -> _FIELD_PATTERNS）。パターンは最も具体的なものが先頭に来ており、不明なフィールド名は汎用の「フィールド名: 値」パターンと同義語テーブル（_FIELD_ALIASES）にフォールバックします。

3. 型変換 — 一致した文字列はJSON Schemaの型に変換されます（例: "$1,750.00" -> "type": "number"の場合は1750.0、配列はカンマ区切りで分割）。変換に失敗した場合はデータを失うよりも、生の文字列にフォールバックします。

4. 検証 — validate_against_schemaはjsonschemaパッケージで抽出データを再チェックし、フィールドごとに合格か、不合格か（人間が読める理由付き）、または完全に欠落しているかを報告します。

すべてのステップがプレーンなコードであるため、フィールドが抽出されたか否かを正確に追跡できます。ブラックボックスはありません。

エラー処理

3つのツールはすべて、あらゆる経路で構造化JSONを返します。MCP境界を越えてスタックトレースを発生させることは決してありません:

• 破損／読み取り不能なPDF -> {"ok": false, "error": "Could not read PDF ..."}

• 存在しないファイル -> {"ok": false, "error": "PDF not found: ..."}

• 抽出可能なテキストを含まないPDF -> {"ok": false, "error": "... contains no extractable text."}

• 不正なスキーマ（空、propertiesなし、または無効なJSON Schema） -> 構造化されたエラーキー

• 必須フィールドの欠落 -> "missing"に一覧表示、不正な値 -> 理由付きで"failed"に一覧表示

テスト

pytest tests/ -v

以下をカバーする19のテスト:

• 3種類すべての文書タイプ（invoice、resume、purchase_order）の抽出成功

• 必須フィールドが欠落したPDF（ネガティブ抽出）

• 不正なフィールド型、必須フィールドの欠落、enum/pattern違反を検出するスキーマ検証

• エラーパス: 破損PDF、存在しないファイル、テキストなしPDF、不正なスキーマ

• 実際のエンドツーエンドMCPテスト（tests/test_mcp_end_to_end.py）— server.pyをサブプロセスとして起動し、公式MCPクライアントでstdio経由で接続し、3つのツールすべてをワイヤー越しに呼び出します。これにより、ライブラリを装ったものではなく、本物のMCPサーバーであることが証明されます

サンプルPDFは、欠落している場合にtests/conftest.pyによって自動再生成されます。

リポジトリ構成

pdf-extract-mcp/
  server.py                    # MCP server: MCPServer + tool registration + transports
  tools/
    __init__.py
    extract.py                 # pdfplumber text extraction + regex field matching
    validate.py                # jsonschema validation with structured reports
  schemas/
    invoice.json               # pre-built schema: invoice
    resume.json                # pre-built schema: resume
    purchase_order.json        # pre-built schema: purchase_order
  sample_pdfs/
    generate_samples.py        # reportlab generator for the 4 sample PDFs
    invoice.pdf
    invoice_missing_fields.pdf
    resume.pdf
    purchase_order.pdf
  tests/
    conftest.py                # auto-generates sample PDFs if missing
    test_tools.py              # unit tests for extract/validate
    test_mcp_end_to_end.py     # end-to-end test over the real MCP stdio transport
  README.md
  requirements.txt

トラブルシューティング

• ModuleNotFoundError: No module named 'mcp' — 仮想環境に入っていません: source .venv/bin/activateを実行するか（または./.venv/bin/python server.pyを使用）、仮想環境を有効にしてください。

• FastMCP importエラー — server.pyはmcp 2.x API（MCPServer）を対象としています。環境にmcp 1.xがある場合は、pip install -U "mcp>=2.0"で再インストールしてください。

• Claudeにツールが表示されない — 設定編集後にクライアントを再起動し、"args"がserver.pyの絶対パスを指していることを確認してください。必要に応じてコマンドにvenvのpythonを使用します。

• フィールドの抽出漏れ — tools/extract.pyの_FIELD_PATTERNSにパターンを追加してください（または汎用「フィールド名: 値」フォールバックと同義語テーブルに依存します）。