MCP IATI

Nota: Prueba de concepto local. Punto de partida para un futuro plugin mcp-server que procesa archivos siguiendo el estándar IATI (actividades y organizaciones): herramientas Python documentadas, con plugin_info/instructions/sample_questions, una herramienta de reserva no_tool_disponible y un módulo de herramientas separado del cableado de registro.

Define las herramientas para explorar actividades, organizaciones, países receptores, sectores y transacciones a partir de un XML IATI configurado.

Herramientas disponibles:

• search_activities(text, limit=10): busca actividades por título.

• list_activity_statuses(): enumera los estados de actividad disponibles y sus recuentos.

• list_reporting_organisations(): enumera las organizaciones informantes y su número de actividades.

• list_recipient_countries(): enumera los países receptores y los recuentos de actividades.

• filter_activities_by_country(country, limit=10): filtra actividades por código o nombre de país receptor.

• list_sectors(limit=100): enumera códigos, nombres y vocabularios de sectores.

• activity_summary(iati_identifier): muestra la información principal y los totales financieros de una actividad.

• activity_transactions(iati_identifier, limit=50): enumera las transacciones de una actividad en orden cronológico.

• transaction_totals_by_year(year_from=None, year_to=None): agrupa los totales de compromisos y desembolsos por año, tipo de transacción y moneda, ignorando fechas/valores no válidos y usando la moneda predeterminada de la actividad cuando falta la moneda de una transacción.

• transaction_totals_by_organisation(limit=50): agrupa los compromisos y desembolsos por organización informante, manteniendo por separado los tipos de transacción y las monedas y aclarando que la organización informante es la publicadora de los datos de la actividad, no necesariamente la financiadora o la ejecutora.

• transaction_totals_by_country(transaction_type="2", currency=None, limit=50): agrupa los compromisos y desembolsos por país receptor, manteniendo por separado los tipos de transacción y las monedas y usando una etiqueta de reserva clara cuando faltan los datos del país.

• transaction_totals_by_sector(transaction_type="2", currency=None, vocabulary=None, limit=50): distribuye los totales de compromisos o desembolsos entre los sectores usando los porcentajes publicados, manteniendo por separado los vocabularios y las monedas y añadiendo una categoría Unallocated sector cuando los porcentajes no suman el 100%.

• top_activities_by_amount(transaction_type="2", currency=None, limit=10): enumera las actividades con los mayores totales de compromiso o desembolso, clasificadas de forma independiente para cada moneda.

• define_term(term): explica un término IATI usando el glosario central.

Principio rector: estas herramientas solo usan campos genéricos del estándar IATI (identificadores, estados, organizaciones, países receptores, sectores y transacciones), nunca lógica específica de Brasil o de IADB; deben funcionar igual de bien con cualquier otro XML IATI (consulta las variables de configuración más abajo).

De dónde provienen los datos

Los archivos XML son publicaciones oficiales IATI del Inter-American Development Bank, no versionados en este repositorio: se descargan bajo demanda del propio alojamiento del banco en webimages.iadb.org/iati (las mismas URL que indexa el registro IATI; el IADB los actualiza mensualmente) en el directorio de datos de usuario (~/.local/share/mcp-iati/xml/ en Linux, mediante platformdirs) y se actualizan cuando expira el TTL configurado. El .gitignore excluye cualquier *.xml por si acaso.

Related MCP server: XRPL Data MCP

Cómo se procesa el XML

1. mcp_iati/activities/data.py convierte el XML configurado a archivos CSV planos y reutiliza la caché específica de la fuente hasta que expire su TTL, usando okfn_iati.IatiMultiCsvConverter().xml_to_csv_folder(...) (la misma librería que ckanext-iati-generator usa en producción, pero en la dirección XML -> CSV en lugar de CSV -> XML).

2. Las herramientas (mcp_iati/activities/queries.py) consultan esos CSV con pandas, no el XML; esto evita reanalizar un archivo de varios MB en cada llamada.

3. Por defecto usa iadb-Brazil.xml. Para usar otro archivo oficial de país del IADB, una URL remota o un archivo local, sin tocar código:

# 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

Configuración

La configuración se lee una vez al arrancar el proceso. Reinicia el servidor tras cambiar la fuente, el directorio de datos o la duración de la caché.

Los archivos XML descargados y las carpetas CSV convertidas se reutilizan mientras permanezcan dentro de este TTL. Una vez que expira, el XML se descarga de nuevo y los CSV se regeneran. Las cachés CSV usan una clave derivada del origen configurado, de modo que Argentina, Brasil y las URL personalizadas nunca comparten los mismos archivos convertidos. Si un refresco remoto falla y existe un XML anterior, se usa esa copia obsoleta con una advertencia en tiempo de ejecución en lugar de dejar las herramientas no disponibles.

La precedencia de fuentes es:

1. MCP_IATI_XML_PATH.

2. MCP_IATI_XML_URL.

3. MCP_IATI_SAMPLE.

4. La muestra predeterminada iadb-Brazil.xml.

Ejemplo:

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

Tablas CSV usadas por el plugin

Los tres archivos CSV se cargan como DataFrames pandas compartidos. Las llamadas repetidas a las herramientas reutilizan las mismas instancias y no vuelven a descargar el XML, ejecutar la conversión ni leer los archivos CSV.

La lógica de preparación y conversión de datos se mantiene separada de la lógica de consulta. Se pueden añadir tablas CSV adicionales mediante DATAFRAME_SPECS.

Desarrollo

# 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

Cómo añadir esto a un mcp-server local

Desde la carpeta mcp-server/, instala este paquete en el mismo entorno virtual:

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

Las herramientas quedan disponibles con el prefijo mcp_iati_.

Glosario IATI

Las descripciones de las herramientas y las instrucciones del plugin comparten un glosario central definido en src/mcp_iati/glossary.py. Su objetivo es que el modelo interprete los términos del estándar de forma coherente y explique las distinciones que suelen ser ambiguas, especialmente entre organizaciones informantes, financiadoras y ejecutoras, y entre compromiso, desembolso y gasto. La herramienta define_term lo expone directamente, de modo que preguntas como «¿qué significa 'desembolso'?» se responden desde el glosario (con el estándar IATI como fuente citada) en lugar de desde el conocimiento del propio modelo.

El glosario cubre todo el estándar de actividad IATI 2.03 según lo modela la librería okfn/okfn_iati (sus enumeraciones reflejan las listas de códigos IATI y su conversor aplana cada elemento a un CSV), agrupado en estas áreas:

Al añadir una nueva herramienta, reutiliza las definiciones del módulo central en lugar de duplicarlas en su docstring (mediante glossary_text(...) para los términos relevantes). Cuando la librería subyacente empiece a exponer un nuevo elemento IATI, añade su término al glosario en el grupo correspondiente.

Pruebas

uv run pytest

Las pruebas se ejecutan sin conexión: tests/conftest.py precarga la caché de datos con DataFrames sintéticos y establece MCP_IATI_XML_PATH, de modo que no se descarga nada. Cubren:

• que el glosario incluya los conceptos mínimos y que las descripciones de las herramientas expongan los términos relevantes al modelo;

• regresión de las consultas (tablas, fuentes, casos vacíos);

• el contrato de datos brutos (test_raw_data_in_ai_response.py): la puerta de enlace envía a la IA solo el texto de la respuesta, por lo que toda herramienta que devuelva una tabla debe incrustarla textualmente en ese texto (hecho por helpers.text_result). Al añadir una nueva herramienta con una tabla, añádela a la lista DATA_TOOLS en ese test.

En GitHub, .github/workflows/python-lint.yml ejecuta ruff + pytest en cada push.