非構造化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: PDF RAG MCP Server
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 8000python 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 8001Claude 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(pdf_path, schema) | JSON Schemaに一致する構造化フィールドをPDFから抽出 -> {"ok": true, "data": {...}} |
validate_against_schema(data, schema) | 抽出データをスキーマに対して検証 -> 人間が読める理由付きの合格／不合格／欠落レポート |
list_supported_document_types() | 事前構築スキーマが同梱されている文書タイプを一覧表示 |
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))これがこのプロジェクトの核心なので、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のみ）で、サーバーレイヤーが利便性のための変換を処理します。
テキスト抽出 — pdfplumberがPDFを開き、全ページからプレーンテキストを取得します。
フィールド照合 — スキーマの各プロパティに対して、順序付けられた正規表現のリストが試行され、最初に一致したものが採用されます（tools/extract.py -> _FIELD_PATTERNS）。パターンは最も具体的なものが先頭に来ており、不明なフィールド名は汎用の「フィールド名: 値」パターンと同義語テーブル（_FIELD_ALIASES）にフォールバックします。
型変換 — 一致した文字列はJSON Schemaの型に変換されます（例: "$1,750.00" -> "type": "number"の場合は1750.0、配列はカンマ区切りで分割）。変換に失敗した場合はデータを失うよりも、生の文字列にフォールバックします。
検証 — 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.txtModuleNotFoundError: 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にパターンを追加してください（または汎用「フィールド名: 値」フォールバックと同義語テーブルに依存します）。
Extract structured fields from an unstructured PDF using regex/heuristics.
Args: pdf_path: Path to the PDF file. schema: JSON Schema describing the fields to extract (must have a non-empty 'properties' object). A built-in schema name (e.g. "invoice") or a path to a .json schema file is also accepted.
Returns: {"ok": True, "data": {...}, "text_length": N} on success, or {"ok": False, "error": "..."} on failure (corrupt PDF, bad schema, ...).
| Name | Required | Description | Default |
|---|---|---|---|
| schema | Yes | ||
| pdf_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It does disclose failure modes (corrupt PDF, bad schema), the exact return contract ({ok: True/False}), and the non-empty properties requirement. However, it omits the side-effect profile (e.g., read-only disk access) and edge behaviors such as empty extraction results, so disclosure is solid but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in a single line, followed by a clean Args/Returns structure that is scannable. Slightly padded by trailing ellipses and the '...' after the failure list, but overall efficient with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description covers the return format, failure modes, and semantic details of both parameters—enough to call the tool correctly. Gaps are minor: no sibling-routing guidance and the meaning of the returned 'text_length' field is undefined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must supply meaning. It adds substantial context: schema may be a JSON Schema object, a built-in name like 'invoice', or a .json file path, and must have a non-empty 'properties'; pdf_path is explained as a path to the PDF. This goes well beyond the bare type declarations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb (extract), a resource (structured fields), and a source/method (unstructured PDF using regex/heuristics). This clearly distinguishes extraction behavior from list_supported_document_types, though it doesn't explicitly name the differentiation from validate_against_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to choose this tool versus its siblings. It doesn't mention when validate_against_schema or list_supported_document_types would be the better pick, and states no preconditions or exclusions beyond the inline schema-constraint note in Args. The agent must infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List document types with pre-built schemas (e.g. invoice, resume, purchase_order).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It weakly implies a read-only operation (listing) but does not explicitly state side effects, authentication requirements, rate limits, or response behavior. The existence of an output schema covers return format, but not behavioral traits. A simple 'List' implies read-only, but for a complete definition more context is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that leads with the action and then clarifies with concrete examples. There is no filler, and every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, an output schema exists, and the purpose is simple, the description covers the essentials. It explains what the tool does and gives representative examples. It could add a note about usage direction (e.g., that these types can be used with extract_fields or validate_against_schema), but such cross-referencing is not required for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is an empty object. According to the rubric, a parameterless tool gets a baseline 4. The description adds no parameter-specific information, but none is needed; the schema is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and a clear resource 'document types with pre-built schemas', including helpful examples (invoice, resume, purchase_order). It clearly conveys the tool's function, though it does not explicitly distinguish it from siblings like extract_fields or validate_against_schema, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the sibling tools. The description does not mention alternatives, typical usage scenarios, or any conditions that would make this tool the right choice. This is a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate extracted data against a JSON Schema.
Args: data: The data to check (e.g. the "data" from extract_fields). schema: JSON Schema to validate against.
Returns: A structured report with passed/failed/missing field lists and a human-readable reason for each failure. Never raises: invalid schemas are reported via the "error" key instead.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | ||
| schema | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behavior: never raises exceptions, invalid schemas are reported via an 'error' key, and the return is a structured report with passed/failed/missing lists and human-readable reasons. This goes beyond a generic 'validates' and gives the agent a clear expectation of failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently formatted with an Args and Returns section, front-loaded with the purpose sentence. It is not verbose—every line contributes to the agent's understanding. It could be tightened (the Returns section is slightly redundant with the behavioral note), but it's well-structured and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two required parameters, no output schema, and no annotations, the description covers the essential context: what the tool does, what each parameter is, how errors are handled, and what the response contains. It references the sibling workflow (extract_fields) which aids routing. The only minor gap is that it doesn't specify the expected shape of 'data' beyond being an object, but the example mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain the parameters. It does: 'data' is explicitly the output of extract_fields, and 'schema' is a JSON Schema. This adds meaning beyond the bare 'object' type in the schema and gives the agent the necessary context for both arguments. It could add more detail about expected structures, but it is sufficient for a two-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Validate extracted data against a JSON Schema.' It names the specific tool and its input, and the example referencing extract_fields ties it to the workflow. It is clearly distinct from the siblings (list_supported_document_types and extract_fields) because validation is an entirely separate operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use it: after extraction, with the 'data' from extract_fields. It implies the pipeline (extract → validate) without explicitly saying 'use this when...' but the example makes the usage obvious. It does not mention when not to use it or name alternatives, so it lacks an explicit exclusion but is not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0extract_fieldslist_supported_document_typesvalidate_against_schemaScored across 3 tools
Each tool serves a clearly distinct purpose: listing supported schemas, extracting fields from a PDF, and validating extracted data against a schema. There is no overlap or ambiguity in tool responsibilities.
All tool names follow a consistent verb_noun pattern in snake_case: list_supported_document_types, extract_fields, validate_against_schema. The convention is uniform and predictable.
With only 3 tools, the set is at the lower end of the well-scoped range but still appropriate for a focused PDF extraction and validation server. Each tool earns its place without redundancy.
The tool surface covers the core workflow: discovering available schemas, extracting fields, and validating results. Minor gaps exist (e.g., no tool to add custom schemas or handle batch processing), but they are not critical for the primary purpose.
High-fidelity PDF to structured Markdown conversion and document field extraction.
Deterministic PDF tools for AI agents: inspect fields, fill forms, merge PDFs, invoices.
Turn PDFs and photos into typed JSON with your own schema. Missing values come back null.
Turn any PDF into structured JSON via AI + OCR: invoices, bank statements, contracts.