MCP IATI

**注意：**本地概念验证。未来 mcp-server 插件的起点，用于处理遵循 IATI 标准（活动和组织）的文件：文档化的 Python 工具，包含 plugin_info/instructions/sample_questions、一个 no_tool_disponible 回退工具，以及一个与注册装配分离的工具模块。

可用工具：

• 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)：显示单个活动的主要信息和财务总计。

• 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 使用 okfn_iati.IatiMultiCsvConverter().xml_to_csv_folder(...) 将配置的 XML 转换为扁平 CSV，并在 TTL 到期前复用特定于来源的缓存（生产环境中 ckanext-iati-generator 使用的同一个库，但方向是 XML -> CSV，而不是 CSV -> XML）。

2. 工具（mcp_iati/activities/queries.py）使用 pandas 查询这些 CSV，而不是 XML——这样可以避免每次调用都重新解析一个数 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 表

这三个 CSV 文件作为共享的 pandas DataFrames 加载。重复的工具调用会复用相同的实例，不会重新下载 XML、运行转换或再次读取 CSV 文件。

数据准备和转换逻辑与查询逻辑保持分离。可以通过 DATAFRAME_SPECS 添加其他 CSV 表。

开发

# 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 活动标准（其枚举与 IATI 代码表一一对应，其转换器将每个元素扁平化为 CSV），并按以下领域分组：

添加新工具时，请复用中央模块中的定义，而不是在其 docstring 中重复它们（通过 glossary_text(...) 获取相关术语）。当底层库开始暴露新的 IATI 元素时，请将其术语添加到匹配组中的词汇表。

测试

uv run pytest

测试离线运行：tests/conftest.py 使用合成 DataFrames 预加载数据缓存，并设置 MCP_IATI_XML_PATH，因此不会下载任何内容。它们涵盖：

• 术语表包含最基础的概念，且工具描述 向模型暴露相关术语；

• 查询的回归测试（表、数据源、空用例）；

• 原始数据契约（test_raw_data_in_ai_response.py）：网关 仅向 AI 发送响应的文本，因此每个返回表的工具 都必须将该表逐字嵌入到该文本中（由 helpers.text_result 完成）。 添加返回表的新工具时，将其添加到该测试中 的 DATA_TOOLS 列表。

在 GitHub 上，.github/workflows/python-lint.yml 会在每次 push 时运行 ruff + pytest。