Flexible Key-Value Extracting MCP Server

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

バージョン: 0.3.1

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

🤔💡 この MCP サーバーを使用する理由は何ですか?

多くの大規模言語モデル (LLM) サービスは構造化された出力機能を提供していますが、この MCP サーバーは、特に難しい現実世界のテキストからのキー値抽出に明確な利点を提供します。

• 🔑🔍自動キー検出：その強みは*、事前定義されたキーを必要とせずに、非構造化テキストから関連するキーと値のペアを自律的に識別・抽出する*能力です。一般的なLLM構造化出力では、探しているキーを指定する必要がありますが、このサーバーはキーを自動的に検出するため、構造が事前に不明な多様で予測不可能なデータに対して非常に効果的です。
• 💪🧱複雑な入力に対する優れた堅牢性：LLMの標準的な構造化出力では問題が発生する可能性のある、任意のテキスト、ノイズの多いテキスト、または非構造化テキストに対しても優れた性能を発揮します。マルチステップパイプラインは、不完全なデータを精査し、意味を解釈するために特別に設計されています。
• 🌐🗣️高度な多言語前処理: LLM 処理の前に、日本語、英語、中国語 (簡体字/繁体字) の固有表現抽出 (NER) に spaCy を活用し、コンテキストが豊富な候補フレーズを提供することで、これらの言語の抽出精度を大幅に向上させます。
• 🔄✍️反復的な改良と型付け：シングルパス抽出とは異なり、このサーバーは、LLMベースの型アノテーション、LLMベースの型評価、ルールベース/LLMフォールバック正規化を含む高度なパイプラインを採用しています。これにより、より正確で文脈に適したデータ型が保証されます。
• ✅🛡️型の安全性とスキーマ準拠の保証: Pydantic による最終的な構造化により、出力は構造化されるだけでなく、型安全であり、定義されたスキーマに対して検証され、下流のアプリケーションに信頼できるデータが提供されることが保証されます。
• 📊⚙️一貫性があり予測可能な出力: サーバーは、抽出が部分的であったり問題が発生したりした場合でも、常に適切な形式の応答を返すように設計されており、これは堅牢な自動化システムの構築に重要です。

リリースノート

バージョン0.3.1

• 更新: 堅牢な修正のためにタイプ評価プロンプトを改善しました。
• 更新: README.md にこの MCP サーバーの長所を追加しました

バージョン0.2.0

• 修正: zh-cn / zh-tw の言語コード。

バージョン0.1.0

• 初回リリース

ツール

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

注記：

• 対応言語：日本語、英語、中国語（簡体字：zh-cn / 繁体字：zh-tw）。
• 抽出はpydantic-aiとLLMに依存しています。完全な抽出は保証されません。
• 入力した文章が長い場合は、処理に時間がかかります。しばらくお待ちください。
• 最初の起動時に、サーバーは spaCy モデルをダウンロードするため、最初はプロセスに時間がかかります。

推定処理時間サンプル

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

特徴

• 柔軟な抽出: ノイズの多いデータや壊れたデータを含むあらゆる入力を処理します。
• JP / EN / ZH-CN / ZH-TW 完全サポート: 自動言語検出による spaCy NER による前処理 (日本語、英語、中国語 [簡体字: zh-cn / 繁体字: zh-tw] をサポート、その他はエラーで拒否されます)。
• 型安全な出力: 出力検証に Pydantic を使用します。
• 複数の形式: 結果を JSON、YAML、または TOML として返します。
• 堅牢なエラー処理: 失敗した場合でも、常に適切な形式の応答を返します。
• 高精度: 抽出/注釈と型評価の両方に GPT-4.1-mini を使用し、最終的な構造化には Pydantic を使用します。

テスト済みのシナリオ

サーバーは、次のようなさまざまな入力でテストされています。

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

処理フロー

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

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

このサーバーは、自動言語検出機能を備えたspaCyを使用して、入力テキストから固有表現を抽出し、LLMに渡します。サポートされている言語は、日本語（ 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」をブール値に変換したり、日付式を標準形式に変換したりします。
  • 静的ルールで値を変換できない場合は、LLM ベースの型変換フォールバックを使用します。
  • 変換できない値は None または str として安全に処理されます。
• 出力: Python 型正規化されたキーと値のペアのリスト。

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

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

このパイプラインは、将来のリスト形式のサポートと Pydantic スキーマ拡張に対応するように設計されています。

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

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

入力/出力の例

入力：

出力（JSON）：

出力（YAML）:

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

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

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

ツール

1. extract_json

• 説明: 任意のノイズの多いテキストからキーと値のペアを抽出し、型セーフな JSON (Python 辞書) として返します。
• 引数:
  • 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\"" }

使用法

Smithery経由でインストール

Smithery経由で Claude Desktop 用の kv-extractor-mcp-server を自動的にインストールするには:

要件

• Python 3.9以上
• OpenAI モデルの API キー ( envの下のsettings.jsonで設定)

サーバーの実行

サーバーを手動で実行したい場合。

MCPホスト構成

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

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

例: ログ記録が無効

例: ログ記録が有効 (ログファイルの絶対パスが必要)

注記：

• ログ記録を有効にすると、ログは指定された絶対ファイルパスにのみ書き込まれます。相対パスを指定したり、 --logfileを省略したりするとエラーが発生します。
• ログ記録が無効になっている場合、ログは出力されません。
• 必要な引数が欠落しているか無効である場合、サーバーは起動せず、エラー メッセージが表示されます。
• ログ ファイルは、MCP サーバー プロセスによってアクセスおよび書き込み可能である必要があります。
• このサーバーの実行に問題がある場合は、古いバージョンのkv-extractor-mcp-serverがキャッシュされている可能性があります。以下の設定で、最新バージョンのkv-extractor-mcp-server（ xyzを最新バージョンに設定）で実行してみてください。

ライセンス

GPL-3.0以降

著者

KunihiroS（および貢献者）