Flexible Key Value Extracting Mcp Server

柔軟なキーと値の抽出 MCP サーバー

バージョン：0.3.3

この MCP サーバーは、LLM（GPT-4.1-mini）と pydantic-ai を使用して、任意のノイズを含むテキストや非構造化テキストからキーと値のペアを抽出します。 型安全性を確保し、複数の出力形式（JSON、YAML、TOML）をサポートします。どのような入力にも対応し、可能な限りデータを構造化しますが、完全な抽出は保証されません。

---

🤔💡 この MCP サーバーを使う理由

多くの大規模言語モデル（LLM）サービスが構造化出力機能を提供していますが、この MCP サーバーには、特に現実世界の難しいテキストからキーと値を抽出するうえで、独自の利点があります。

• 🔑🔍 キーの自動検出：このサーバーの大きな強みは、事前にキーを定義しなくても、非構造化テキストから関連するキーと値のペアを自律的に特定して抽出できることです。一般的な LLM の構造化出力では通常、検索対象のキーを指定する必要がありますが、このサーバーはキーを検出するため、事前に構造がわからない多様で予測しにくいデータに非常に効果的です。
• 💪🧱 複雑な入力への優れた堅牢性：標準的な LLM の構造化出力では対応が難しい、任意のノイズを含むテキストや非構造化テキストの処理に優れています。複数段階のパイプラインは、不完全なデータを精査し、内容を把握できるように特別に設計されています。
• 🌐🗣️ 高度な多言語前処理：LLM で処理する前に spaCy を活用し、日本語、英語、簡体字・繁体字中国語の固有表現認識（NER）を行います。これにより、文脈が豊富な候補フレーズが得られ、これらの言語での抽出精度が大幅に向上します。
• 🔄✍️ 反復的な改善と型付け：1 回の抽出で終わるのではなく、このサーバーは、LLM による型注釈、LLM による型評価、ルールベースの正規化（必要に応じて LLM にフォールバック）を含む高度なパイプラインを採用しています。これにより、より正確で文脈に適したデータ型を実現します。
• ✅🛡️ 型安全性とスキーマ準拠を保証：Pydantic による最終的な構造化により、出力は構造化されるだけでなく、型安全性が確保され、定義済みのスキーマに照らして検証されます。そのため、後続のアプリケーションで信頼できるデータを利用できます。
• 📊⚙️ 一貫性があり予測可能な出力：抽出が部分的であったり、問題が発生したりしても、適切な形式の応答を常に返すように設計されています。これは、堅牢な自動化システムの構築に不可欠です。

---

リリースノート

v0.3.3

• 修正：stdout に JSON-RPC ストリームの前に JSON 以外の行が 2 行書き込まれていたため、MCP ホスト（Codex CLI など）がサーバーを読み込めない問題を修正しました。診断情報はすべて stderr に出力するようになりました（--log=on の場合はログファイルに出力します）。FastMCP / pydantic-ai のバナーも表示されないようにしました。
• 修正：現在の pydantic-ai で 'AgentRunResult' object has no attribute 'data' が発生し、ツール呼び出しに失敗する問題を修正しました。サーバーは pydantic-ai 2.x API を対象とするようになりました。
• 修正：サーバーのインポート時や --help の実行時に OPENAI_API_KEY が不要になりました。キーが見つからない場合は、インポート時のクラッシュではなく、ツール呼び出し時に明示的なエラーとして報告されます。
• 変更：Smithery との統合（バッジ、インストール手順、smithery.yaml、Smithery が生成した Dockerfile）を削除しました。このサーバーの Smithery 掲載ページにはアクセスできなくなりました（404）。
• 変更：新規の uvx / pipx run で再現性のある依存関係解決が行われるよう、依存関係に上限を設定しました（fastmcp>=4,<5、pydantic-ai>=2,<3、spacy>=3.8,<3.9 など）。Python 3.10 以降が必要です。

v0.3.2

• 修正：FastMCP がエラーを引き起こしていた問題を修正しました。

v0.3.1

• 更新：堅牢な修正のため、型評価プロンプトを改善しました。
• 更新：この MCP サーバーの強みを README.md に追加しました。

v0.2.0

• 修正：zh-cn / zh-tw の言語コードを修正しました。

v0.1.0

• 初回リリース

ツール

• /extract_json：入力テキストから型安全なキーと値のペアを JSON 形式で抽出します。
• /extract_yaml：入力テキストから型安全なキーと値のペアを YAML 形式で抽出します。
• /extract_toml：入力テキストから型安全なキーと値のペアを TOML 形式で抽出します。
  • 注：TOML の仕様上、オブジェクト（辞書）の配列や深くネストされた構造は直接表現できません。詳しくは、以下の「TOML 出力の制限に関する注記」を参照してください。

注：

• 対応言語：日本語、英語、中国語（簡体字：zh-cn／繁体字：zh-tw）。
• 抽出には pydantic-ai と LLM を使用します。完全な抽出が保証されるわけではありません。
• 入力文が長いほど処理に時間がかかります。しばらくお待ちください。
• 初回起動時にはサーバーが spaCy モデルをダウンロードするため、処理に時間がかかります。

処理時間の目安

入力トークン数	入力文字数（概算）	実測処理時間（秒）	モデル構成
200	~400	~15	gpt-4.1-mini

実際の処理時間は、API の応答、ネットワーク状況、モデルの負荷によって大きく変わる場合があります。短いテキストでも 15 秒以上かかることがあります。

機能

• 柔軟な抽出：ノイズの多いデータや壊れたデータを含め、あらゆる入力に対応します。
• 日本語／英語／簡体字中国語／繁体字中国語に完全対応：spaCy NER による前処理で言語を自動検出します（対応言語は日本語、英語、中国語［簡体字：zh-cn／繁体字：zh-tw］です。それ以外の言語はエラーになります）。
• 型安全な出力：出力の検証に Pydantic を使用します。
• 複数の形式：結果を JSON、YAML、または TOML 形式で返します。
• 堅牢なエラー処理：失敗時も常に適切な形式の応答を返します。
• 高精度：抽出／注釈付けと型評価の両方に GPT-4.1-mini を使用し、最終的な構造化には Pydantic を使用します。

テスト済みのシナリオ

このサーバーは、以下を含むさまざまな入力でテストされています。

• シンプルなキーと値のペア
• 重要な情報が埋もれているノイズの多いテキストや非構造化テキスト
• 出力形式としてのさまざまなデータ形式（JSON、YAML、TOML）

処理フロー

以下は、server.py に実装されているキーと値の抽出パイプラインの処理フローを示すフローチャートです。

flowchart TD
    A[Input Text] --> B[Step 0: Preprocessing with spaCy Lang Detect then NER]
    B --> C[Step 1: Key-Value Extraction - LLM]
    C --> D[Step 2: Type Annotation - LLM]
    D --> E[Step 3: Type Evaluation - LLM]
    E --> F[Step 4: Type Normalization - Static Rules + LLM]
    F --> G[Step 5: Final Structuring with Pydantic]
    G --> H[Output in JSON/YAML/TOML]

spaCy による前処理（多言語 NER）

このサーバーは、LLM に渡す前に、spaCy と言語の自動検出を使用して入力テキストから固有表現を抽出します。対応言語は日本語（ja_core_news_md）、英語（en_core_web_sm）、中国語（簡体字／繁体字、zh_core_web_sm）です。

• 入力テキストの言語は langdetect を使用して自動検出されます。

• 検出された言語が日本語、英語、中国語のいずれでもない場合、サーバーは Unsupported lang detected エラーを返します。

• 必要に応じて、適切な spaCy モデルが自動的にダウンロードされ、読み込まれます。手動でのインストールは不要です。

• 抽出された語句のリストは、以下のように LLM プロンプトに含められます。

  [前処理で抽出された候補語句（spaCy NER）] 以下は、spaCy の検出された言語のモデルを使用して入力テキストから自動抽出された語句のリストです。 これらの語句は、名前、日付、組織、場所、数値など、検出されたエンティティを表します。 このリストは参考情報であり、無関係または不正確な項目が含まれることがあります。LLM は独自の判断を用い、入力テキスト全体を考慮して、最も適切なキーと値のペアを柔軟に推測します。

各ステップの詳細

このプロジェクトのキーと値の抽出パイプラインは、複数のステップで構成されています。各ステップの詳細は以下のとおりです。

ステップ 0：spaCy による前処理（言語検出 → 固有表現認識）

• 目的：入力テキストの言語を自動検出し、適切な spaCy モデル（例：ja_core_news_md、en_core_web_sm、zh_core_web_sm）を使用して固有表現を抽出します。
• 出力：抽出されたフレーズのリストです。キーと値のペアの抽出精度を高めるためのヒントとして、LLM のプロンプトに含めます。

ステップ 1：キーと値の抽出（LLM）

• 目的：GPT-4.1-mini を使用して、入力テキストと抽出されたフレーズのリストからキーと値のペアを抽出します。
• 詳細：
  • 同じキーが複数回出現する場合、値をリスト形式で返すようプロンプトで指示します。
  • 少数例は、リスト形式の出力を含むように設計されています。
• 出力：例：key: person, value: ["Tanaka", "Sato"]

ステップ 2：型の注釈（LLM）

• 目的：GPT-4.1-mini を使用して、ステップ 1 で抽出された各キーと値のペアのデータ型（int、str、bool、list など）を推論します。
• 詳細：
  • 型注釈のプロンプトには、リストと複数の値への対応を指示する内容が含まれます。
• 出力：例：key: person, value: ["Tanaka", "Sato"] -> list[str]

ステップ 3：型の評価（LLM）

• 目的：GPT-4.1-mini を使用して、ステップ 2 の型注釈を評価し、修正します。
• 詳細：
  • GPT-4.1-mini が、各キーと値のペアについて型注釈の妥当性と文脈を再評価します。
  • 型エラーや曖昧さが検出された場合、GPT-4.1-mini が型を自動的に修正または補足します。
  • 例：数値として抽出された値を文字列に修正する、または値がリストか単一の値かを判断する。
• 出力：型評価済みのキーと値のペアのリストです。

ステップ 4：型の正規化（静的ルール＋LLM によるフォールバック）

• 目的：型評価済みのデータを Python の標準型（int、float、bool、str、list、None など）に変換します。
• 詳細：
  • 静的な正規化ルール（正規表現または型変換関数）を適用し、値を Python の標準型に変換します。
  • 例：カンマ区切りの値をリストに変換する、「true」／「false」を bool に変換する、日付表現を標準形式に変換する。
  • 静的ルールで値を変換できない場合は、LLM による型変換にフォールバックします。
  • 変換できない値は、安全に None または str として処理します。
• 出力：Python 型に正規化されたキーと値のペアのリストです。

ステップ 5：Pydantic による最終構造化

• 目的：Pydantic モデル（KVOut/KVPayload）を使用して、型が正規化されたデータを検証し、構造化します。
• 詳細：
  • 各キーと値のペアを Pydantic モデルに割り当て、型安全性とデータの整合性を確保します。
  • スキーマに従って、単一の値、リスト、null、複合型を検証します。
  • 検証に失敗した場合は、できる限り多くのデータを保持しながらエラー情報を付加します。
  • 最終出力は、指定された形式（JSON、YAML、または TOML）で返されます。
• 出力：型安全性が確保され、検証済みの dict、または指定された形式（JSON/YAML/TOML）の出力です。

---

このパイプラインは、将来的なリスト形式への対応と Pydantic スキーマの拡張を想定して設計されています。

TOML 出力の制限に関する注意

• TOML では、単純な配列（例：items = ["A", "B"]）はネイティブに表現できますが、 オブジェクト（dict）の配列や深くネストされた構造は、TOML の仕様上、直接表現できません。
• そのため、複雑なリストやネストされた構造（例：[{"name": "A"}, {"name": "B"}]）は、 TOML の値に「JSON 文字列」として保存されます。
• これは、TOML の仕様上の制限による情報損失を防ぐための設計上の選択です。
• YAML と JSON では、ネストされた構造をそのまま表現できます。

入出力例

入力：

Thank you for your order (Order Number: ORD-98765). Product: High-Performance Laptop, Price: 89,800 JPY (tax excluded), Delivery: May 15-17. Shipping address: 1-2-3 Shinjuku, Shinjuku-ku, Tokyo, Apartment 101. Phone: 090-1234-5678. Payment: Credit Card (VISA, last 4 digits: 1234). For changes, contact [email protected].

出力（JSON）：

{
  "order_number": "ORD-98765",
  "product_name": "High-Performance Laptop",
  "price": 89800,
  "price_currency": "JPY",
  "tax_excluded": true,
  "delivery_start_date": "20240515",
  "delivery_end_date": "20240517",
  "shipping_address": "1-2-3 Shinjuku, Shinjuku-ku, Tokyo, Apartment 101",
  "phone_number": "090-1234-5678",
  "payment_method": "Credit Card",
  "card_type": "VISA",
  "card_last4": "1234",
  "customer_support_email": "[email protected]"
}

出力（YAML）：

order_number: ORD-98765
product_name: High-Performance Laptop
price: 89800
price_currency: JPY
tax_excluded: true
delivery_start_date: '20240515'
delivery_end_date: '20240517'
shipping_address: 1-2-3 Shinjuku, Shinjuku-ku, Tokyo, Apartment 101
phone_number: 090-1234-5678
payment_method: Credit Card
card_type: VISA
card_last4: '1234'
customer_support_email: [email protected]

出力（TOML、単純なケース）：

order_number = "ORD-98765"
product_name = "High-Performance Laptop"
price = 89800
price_currency = "JPY"
tax_excluded = true
delivery_start_date = "20240515"
delivery_end_date = "20240517"
shipping_address = "1-2-3 Shinjuku, Shinjuku-ku, Tokyo, Apartment 101"
phone_number = "090-1234-5678"
payment_method = "Credit Card"
card_type = "VISA"
card_last4 = "1234"

出力（TOML、複雑なケース）：

items = '[{"name": "A", "qty": 2}, {"name": "B", "qty": 5}]'
addresses = '[{"city": "Tokyo", "zip": "160-0022"}, {"city": "Osaka", "zip": "530-0001"}]'

注：オブジェクトの配列やネストされた構造は、TOML では JSON 文字列として保存されます。

ツール

1. extract_json

• 説明：任意のノイズを含むテキストからキーと値のペアを抽出し、型安全な JSON（Python の dict）として返します。
• 引数：
  • input_text（文字列）：ノイズを含むデータ、または非構造化データを含む入力文字列です。
• 戻り値：{ "success": True, "result": ... } または { "success": False, "error": ... }
• 例：

  {
    "success": true,
    "result": { "foo": 1, "bar": "baz" }
  }
  

2. extract_yaml

• 説明：任意のノイズを含むテキストからキーと値のペアを抽出し、型安全な YAML（文字列）として返します。
• 引数：
  • input_text（文字列）：ノイズを含むデータ、または非構造化データを含む入力文字列です。
• 戻り値：{ "success": True, "result": ... } または { "success": False, "error": ... }
• 例：

  {
    "success": true,
    "result": "foo: 1\nbar: baz"
  }
  

3. extract_toml

• 説明：任意のノイズを含むテキストからキーと値のペアを抽出し、型安全な TOML（文字列）として返します。
• 引数：
  • input_text（文字列）：ノイズを含むデータ、または非構造化データを含む入力文字列です。
• 戻り値：{ "success": True, "result": ... } または { "success": False, "error": ... }
• 例：

  {
    "success": true,
    "result": "foo = 1\nbar = \"baz\""
  }
  

使用方法

要件

• Python 3.10+
• OpenAI モデル用の API キー（MCP ホストの設定で env に設定）。キーがなくてもサーバーは起動してツールの一覧を表示しますが、キーが設定されるまでは、すべてのツール呼び出しで {"success": false, "error": "OPENAI_API_KEY is not set. ..."} が返されます。

サーバーの実行

python server.py

サーバーを手動で実行する場合に使用します。

MCP ホストの設定

この MCP サーバーを実行する際は、ログ出力モードと（ログを有効にする場合は）ログファイルの絶対パスを、コマンドライン引数で明示的に指定する必要があります。

• --log=off：すべてのログを無効にします（ログは書き込まれません）
• --log=on --logfile=/absolute/path/to/logfile.log：ログを有効にし、指定した絶対パスにログを書き込みます
• ログを有効にする場合は、両方の引数が必須です。いずれかが指定されていない場合、パスが絶対パスでない場合、または無効な値が指定された場合、サーバーはエラーで終了します。

例：ログを無効にする

"kv-extractor-mcp-server": {
  "command": "pipx",
  "args": ["run", "kv-extractor-mcp-server", "--log=off"],
  "env": {
    "OPENAI_API_KEY": "{apikey}"
  }
}

例：Codex CLI（~/.codex/config.toml、uvx を使用）

[mcp_servers.kv-extractor-mcp-server]
command = "uvx"
args = ["kv-extractor-mcp-server==0.3.3", "--log=off"]

[mcp_servers.kv-extractor-mcp-server.env]
OPENAI_API_KEY = "{apikey}"

例：ログを有効にする（ログファイルの絶対パスが必要）

"kv-extractor-mcp-server": {
  "command": "pipx",
  "args": ["run", "kv-extractor-mcp-server", "--log=on", "--logfile=/workspace/logs/kv-extractor-mcp-server.log"],
  "env": {
    "OPENAI_API_KEY": "{apikey}"
  }
}

注：

• ログを有効にすると、ログは指定した絶対パスにのみ書き込まれます。相対パスを指定した場合や、--logfile を省略した場合はエラーになります。
• ログを無効にすると、ログは出力されません。
• stdout は MCP JSON-RPC ストリーム専用です。診断情報（起動メッセージや、--log=on の場合のログストリーム）は stderr に書き込まれるため、MCP ホストのトランスポートに影響しません。
• 必須の引数が不足している場合や無効な場合、サーバーは起動せず、エラーメッセージを出力します。
• ログファイルは、MCP サーバープロセスからアクセスおよび書き込み可能である必要があります。
• このサーバーの実行に問題がある場合、古いバージョンの kv-extractor-mcp-server がキャッシュされている可能性があります。以下の設定で kv-extractor-mcp-server の最新バージョン（x.y.z を最新バージョンに置き換えてください）を実行してみてください。

"kv-extractor-mcp-server": {
  "command": "pipx",
  "args": ["run", "kv-extractor-mcp-server==x.y.z", "--log=off"],
  "env": {
    "OPENAI_API_KEY": "{apikey}"
  }
}

ライセンス

GPL-3.0-or-later

作成者

KunihiroS（およびコントリビューター）