MCP IATI

Примечание: локальная концептуальная демонстрация. Отправная точка для будущего плагина mcp-server, который обрабатывает файлы, следующие стандарту IATI (виды деятельности и организации): документированные Python-инструменты с plugin_info/instructions/sample_questions, запасной инструмент 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): показать основную информацию и финансовые итоги по одному виду деятельности.

• 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): распределение итогов по обязательствам или выплатам по секторам с использованием опубликованных процентных долей, с разделением словарей и валют и добавлением категории Unallocated sector, когда процентные доли не составляют в сумме 100%.

• top_activities_by_amount(transaction_type="2", currency=None, limit=10): список видов деятельности с наибольшими итогами по обязательствам или выплатам, ранжированный отдельно для каждой валюты.

• define_term(term): объяснение термина IATI с помощью центрального глоссария.

Руководящий принцип: эти инструменты используют только общие поля стандарта IATI (идентификаторы, статусы, организации, страны-получатели, секторы и транзакции), но никогда не используют специфичную для Бразилии или IADB логику — они должны одинаково хорошо работать с любым другим IATI XML (см. переменные конфигурации ниже).

Откуда берутся данные

XML-файлы — это официальные публикации IATI от Inter-American Development Bank, не версионируемые в этом репозитории: они загружаются по требованию с собственного хостинга банка по адресу webimages.iadb.org/iati (те же URL-адреса, которые индексирует реестр IATI; IADB обновляет их ежемесячно) в каталог пользовательских данных (~/.local/share/mcp-iati/xml/ в Linux, через platformdirs) и обновляются по истечении настроенного TTL. .gitignore на всякий случай исключает любые *.xml.

Related MCP server: XRPL Data MCP

Как обрабатывается XML

1. mcp_iati/activities/data.py преобразует настроенный XML в плоские CSV-файлы и переиспользует кэш, привязанный к источнику, пока не истечёт его TTL, с помощью okfn_iati.IatiMultiCsvConverter().xml_to_csv_folder(...) (той же библиотеки, которую ckanext-iati-generator использует в продакшене, но в направлении XML -> CSV, а не CSV -> XML).

2. Инструменты (mcp_iati/activities/queries.py) запрашивают эти CSV с помощью pandas, а не XML — это позволяет избежать повторного разбора многомегабайтного файла при каждом вызове.

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. Когда он истекает, 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-файлы заново.

Логика подготовки данных и конвертации отделена от логики запросов. Дополнительные 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 в качестве указанного источника), а не из собственных знаний модели.

Глоссарий охватывает весь стандарт IATI 2.03 для видов деятельности в том виде, в котором он смоделирован библиотекой okfn/okfn_iati (её перечисления отражают кодовые списки IATI, а её конвертер преобразует каждый элемент в CSV), сгруппирован по следующим областям:

При добавлении нового инструмента используйте определения из центрального модуля, а не дублируйте их в его docstring (через glossary_text(...) для соответствующих терминов). Когда нижележащая библиотека начнёт предоставлять новый элемент IATI, добавьте его термин в глоссарий в соответствующую группу.

Тесты

uv run pytest

Тесты работают офлайн: tests/conftest.py предварительно заполняет кэш данных синтетическими DataFrame и задаёт MCP_IATI_XML_PATH, поэтому ничего не загружается. Они покрывают:

• что глоссарий включает минимальный набор понятий и что описания инструментов раскрывают модели соответствующие термины;

• регрессия запросов (таблицы, источники, пустые случаи);

• контракт на необработанные данные (test_raw_data_in_ai_response.py): шлюз отправляет ИИ только текст ответа, поэтому каждый инструмент, возвращающий таблицу, должен встраивать её дословно в этот текст (делается с помощью helpers.text_result). При добавлении нового инструмента с таблицей добавьте его в список DATA_TOOLS в этом тесте.

На GitHub, .github/workflows/python-lint.yml запускает ruff + pytest при каждом пуше.