MCP IATI

注記: ローカル用の概念実証です。将来の mcp-server プラグインの出発点となるもので、IATI 標準（活動と組織）に従うファイルを処理します。plugin_info/instructions/sample_questions を備えた文書化されたPythonツール、no_tool_disponible フォールバックツール、および登録のための配線処理から分離されたツールモジュールを備えています。

設定されたIATI XMLから、活動、組織、被援助国、セクター、取引を調査するためのツールを定義します。

利用可能なツール:

• search_activities(text, limit=10): タイトルで活動を検索します。

• list_activity_statuses(): 利用可能な活動ステータスと件数を一覧表示します。

• list_reporting_organisations(): 報告組織とその活動件数を一覧表示します。

• list_recipient_countries(): 被援助国と活動件数を一覧表示します。

• filter_activities_by_country(country, limit=10): 被援助国のコードまたは名前で活動をフィルタリングします。

• list_sectors(limit=100): セクターコード、名前、ボキャブラリーを一覧表示します。

• activity_summary(iati_identifier): 1つの活動の主要情報と財務合計を表示します。

• activity_transactions(iati_identifier, limit=50): 活動の取引を時系列順に一覧表示します。

• transaction_totals_by_year(year_from=None, year_to=None): コミットメントとディスバースメントの合計を、年・取引タイプ・通貨ごとにグループ化します。無効な日付・値は無視し、取引の通貨が欠けている場合は活動のデフォルト通貨を使用します。

• transaction_totals_by_organisation(limit=50): コミットメントとディスバースメントを報告組織ごとにグループ化し、取引タイプと通貨を分けて保持します。また、報告組織は活動データの公開者であり、必ずしも資金提供者や実施者ではないことを明確にします。

• transaction_totals_by_country(transaction_type="2", currency=None, limit=50): コミットメントとディスバースメントを被援助国ごとにグループ化し、取引タイプと通貨を分けて保持します。国の詳細がない場合は明確なフォールバックラベルを使用します。

• transaction_totals_by_sector(transaction_type="2", currency=None, vocabulary=None, limit=50): 公開されているパーセンテージを使用して、コミットメントまたはディスバースメントの合計をセクター間で配分します。ボキャブラリーと通貨を分けて保持し、パーセンテージが100%にならない場合は Unallocated sector バケットを追加します。

• top_activities_by_amount(transaction_type="2", currency=None, limit=10): コミットメントまたはディスバースメントの合計が最も高い活動を一覧表示し、通貨ごとに独立してランク付けします。

• define_term(term): 中央の用語集を使用してIATI用語を説明します。

基本方針: これらのツールは、汎用的なIATI標準フィールド（識別子、ステータス、組織、被援助国、セクター、取引）のみを使用し、ブラジル固有またはIADB固有のロジックは一切使用しません。他のどのIATI XMLでも同様に動作する必要があります（下記の構成変数を参照）。

データの出所

XMLファイルは、Inter-American Development Bank の公式IATI公開データです。このリポジトリではバージョン管理されていません: 銀行自身のホスティング webimages.iadb.org/iati からオンデマンドでダウンロードされ（IATI registry がインデックスするのと同じURLです。IADBは毎月更新します）、ユーザーデータディレクトリ（Linuxでは ~/.local/share/mcp-iati/xml/、platformdirs 経由）に保存され、設定されたTTLが切れると更新されます。.gitignore は念のため *.xml を除外します。

Related MCP server: XRPL Data MCP

XMLの処理方法

1. mcp_iati/activities/data.py は、設定されたXMLをフラットなCSVに変換し、okfn_iati.IatiMultiCsvConverter().xml_to_csv_folder(...) を使用して、ソース固有のキャッシュをTTLが満了するまで再利用します（これは本番環境で ckanext-iati-generator が使用しているのと同じライブラリですが、CSV -> XML ではなく XML -> CSV の方向で使用します）。

2. ツール（mcp_iati/activities/queries.py）は、XMLではなく pandas を使用してそれらのCSVをクエリします。これにより、呼び出しのたびに数MBのファイルを再解析することを回避できます。

3. デフォルトでは iadb-Brazil.xml を使用します。コードに触れずに、別の公式IADBカントリーファイル、リモートURL、またはローカルファイルを使用するには:

   # another IADB country file from https://webimages.iadb.org/iati/
   export MCP_IATI_SAMPLE=iadb-Argentina.xml
   
   # or any remote IATI XML
   export MCP_IATI_XML_URL=https://example.org/activities.xml
   
   # or any local file (downloads nothing)
   export MCP_IATI_XML_PATH=/path/to/another-iati-file.xml

設定

設定はプロセスの起動時に一度だけ読み込まれます。ソース、データディレクトリ、またはキャッシュ期間を変更した後は、サーバーを再起動してください。

ダウンロードしたXMLファイルと変換したCSVフォルダは、このTTL内にある限り再利用されます。TTLが満了すると、XMLが再度ダウンロードされ、CSVが再生成されます。CSVキャッシュは設定されたソースから導出されたキーを使用するため、アルゼンチン、ブラジル、およびカスタムURLが同じ変換ファイルを共有することはありません。 リモート更新に失敗し、以前のXMLが存在する場合、ツールを利用不能にする代わりに、その古いコピーが実行時警告付きで使用されます。

ソースの優先順位は次のとおりです:

1. MCP_IATI_XML_PATH。

2. MCP_IATI_XML_URL。

3. MCP_IATI_SAMPLE。

4. デフォルトの iadb-Brazil.xml サンプル。

例:

export MCP_IATI_XML_URL=https://example.org/iadb-Argentina.xml
export MCP_IATI_DATA_DIR=/var/cache/mcp-iati
export MCP_IATI_CACHE_TTL_SECONDS=2592000
uv run mcp-server

プラグインが使用するCSVテーブル

3つのCSVファイルは共有のpandas DataFrameとして読み込まれます。ツールを繰り返し呼び出しても、同じインスタンスが再利用され、XMLのダウンロード、変換の実行、CSVファイルの再読み込みは行われません。

データ準備・変換ロジックは、クエリロジックから分離されています。追加のCSVテーブルは DATAFRAME_SPECS を通じて追加できます。

開発

# Install dependencies (mcp-server from git, okfn-iati from PyPI;
# the dev extra brings ruff and pytest)
uv sync --extra dev

# Lint
uv run ruff check src

ローカル mcp-server への追加

mcp-server/ フォルダから、このパッケージを同じ仮想環境にインストールします:

uv pip install -e ../mcp-iati
uv run mcp-server

ツールは mcp_iati_ プレフィックス付きで利用可能になります。

IATI用語集

ツールの説明とプラグインの指示は、src/mcp_iati/glossary.py で定義された中央の用語集を共有します。その目的は、モデルが標準の用語を一貫して解釈し、曖昧になりがちな区別を説明することです。特に、報告組織と資金提供組織と実施組織の間の区別、およびコミットメント、ディスバースメント、支出の間の区別です。define_term ツールはそれを直接公開するため、「'disbursement' とはどういう意味ですか？」のような質問には、（引用元としてIATI標準を使用して）モデル自身の知識ではなく用語集から回答されます。

この用語集は、okfn/okfn_iati ライブラリがモデル化するIATI 2.03活動標準全体を対象としています（そのenumはIATIコードリストを反映し、コンバーターは各要素をCSVにフラット化します）。次の領域にグループ化されています:

新しいツールを追加するときは、関連する用語について、docstringで定義を重複させるのではなく、中央モジュールの定義を（glossary_text(...) を介して）再利用してください。基盤となるライブラリが新しいIATI要素を公開し始めたら、その用語を一致するグループの用語集に追加してください。

テスト

uv run pytest

テストはオフラインで実行されます: tests/conftest.py がデータキャッシュを合成DataFrameで事前読み込みし、MCP_IATI_XML_PATH を設定するため、何もダウンロードされません。対象は次のとおりです:

• 用語集が必要最小限の概念を含んでおり、ツールの説明が関連する用語をモデルに 公開していること;

• クエリの回帰 (テーブル、ソース、空のケース);

• 生データ契約 (test_raw_data_in_ai_response.py): ゲートウェイはAIに 応答のテキストのみを送信するため、テーブルを返すすべてのツールは、その テキストにテーブルをそのまま埋め込む必要があります (helpers.text_result によって行われます)。テーブルを返す新しいツールを 追加する場合は、そのテストの DATA_TOOLS リストに追加してください。

GitHubでは、.github/workflows/python-lint.yml がすべてのプッシュで ruff + pytestを実行します。