MCP IATI

Hinweis: Lokaler Proof of Concept. Ausgangspunkt für ein zukünftiges mcp-server-Plugin, das Dateien nach dem IATI-Standard (Aktivitäten und Organisationen) verarbeitet: dokumentierte Python-Tools, mit plugin_info/instructions/sample_questions, einem no_tool_disponible-Fallback-Tool und einem Tools-Modul getrennt von der Registrierungs-Verdrahtung.

Es definiert Tools zum Erkunden von Aktivitäten, Organisationen, Empfängerländern, Sektoren und Transaktionen aus einer konfigurierten IATI-XML.

Verfügbare Tools:

• search_activities(text, limit=10): Aktivitäten anhand des Titels durchsuchen.

• list_activity_statuses(): Verfügbare Aktivitätsstatus und deren Anzahl auflisten.

• list_reporting_organisations(): Berichtende Organisationen und deren Anzahl an Aktivitäten auflisten.

• list_recipient_countries(): Empfängerländer und Aktivitätszahlen auflisten.

• filter_activities_by_country(country, limit=10): Aktivitäten nach Empfängerland-Code oder -Name filtern.

• list_sectors(limit=100): Sektor-Codes, Namen und Vokabulare auflisten.

• activity_summary(iati_identifier): Die wichtigsten Informationen und Finanzsummen für eine Aktivität anzeigen.

• activity_transactions(iati_identifier, limit=50): Die Transaktionen einer Aktivität in chronologischer Reihenfolge auflisten.

• transaction_totals_by_year(year_from=None, year_to=None): Zusage- und Auszahlungssummen nach Jahr, Transaktionstyp und Währung gruppieren, dabei ungültige Datumsangaben/Werte ignorieren und die Standardwährung der Aktivität verwenden, wenn eine Transaktionswährung fehlt.

• transaction_totals_by_organisation(limit=50): Zusagen und Auszahlungen nach berichtender Organisation gruppieren, wobei Transaktionstypen und Währungen getrennt bleiben und klargestellt wird, dass die berichtende Organisation der Herausgeber der Aktivitätsdaten ist, nicht unbedingt der Geldgeber oder Durchführer.

• transaction_totals_by_country(transaction_type="2", currency=None, limit=50): Zusagen und Auszahlungen nach Empfängerland gruppieren, wobei Transaktionstypen und Währungen getrennt bleiben und ein klares Fallback-Label verwendet wird, wenn Länderinformationen fehlen.

• transaction_totals_by_sector(transaction_type="2", currency=None, vocabulary=None, limit=50): Zusage- oder Auszahlungssummen mithilfe der veröffentlichten Prozentsätze auf Sektoren aufteilen, wobei Vokabulare und Währungen getrennt bleiben und eine Kategorie Unallocated sector hinzugefügt wird, wenn die Prozentsätze nicht 100 % ergeben.

• top_activities_by_amount(transaction_type="2", currency=None, limit=10): Aktivitäten mit den höchsten Zusage- oder Auszahlungssummen auflisten, unabhängig für jede Währung sortiert.

• define_term(term): Einen IATI-Begriff mithilfe des zentralen Glossars erklären.

Leitprinzip: Diese Tools verwenden nur generische IATI-Standardfelder (Identifikatoren, Status, Organisazionen, Empfängerländer, Sektoren und Transazionen), niemals Brasilien- oder IADB-spezifische Logik - sie müssen mit jeder anderen IATI-XML genauso gut funktionieren (siehe die Konfigurationsvariablen unten).

Woher die Daten stammen

Die XML-Dateien sind offizielle IATI-Veröffentlichungen der Interamerikanischen Entwicklungsbank, nicht in diesem Repo versioniert: Sie werden bei Bedarf vom eigenen Hosting der Bank unter webimages.iadb.org/iati heruntergeladen (dieselben URLs, die das IATI-Register indiziert; die IADB aktualisiert sie monatlich) in das Benutzerdatenverzeichnis (~/.local/share/mcp-iati/xml/ unter Linux, über platformdirs) und bei Ablauf der konfigurierten TTL aktualisiert. Die .gitignore schließt vorsichtshalber jede *.xml aus.

Related MCP server: XRPL Data MCP

Wie die XML verarbeitet wird

1. mcp_iati/activities/data.py konvertiert die konfigurierte XML in flache CSVs und verwendet den quellspezifischen Cache bis zum Ablauf seiner TTL erneut, unter Verwendung von okfn_iati.IatiMultiCsvConverter().xml_to_csv_folder(...) (dieselbe Bibliothek, die ckanext-iati-generator in Produktion verwendet, jedoch in Richtung XML -> CSV statt CSV -> XML).

2. Die Tools (mcp_iati/activities/queries.py) fragen diese CSVs mit pandas ab, nicht die XML - das vermeidet das erneute Parsen einer mehrere MB großen Datei bei jedem Aufruf.

3. Standardmäßig wird iadb-Brazil.xml verwendet. Um eine andere offizielle IADB-Länderdatei, eine entfernte URL oder eine lokale Datei zu verwenden, ohne den Code zu ändern:

   # 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

Konfiguration

Die Konfiguration wird einmal gelesen, wenn der Prozess startet. Starten Sie den Server neu, nachdem Sie die Quelle, das Datenverzeichnis oder die Cachedauer geändert haben.

Heruntergeladene XML-Dateien und konvertierte CSV-Ordner werden wiederverwendet, solange sie innerhalb dieser TTL liegen. Sobald sie abläuft, wird die XML erneut heruntergeladen und die CSVs werden neu erzeugt. CSV-Caches verwenden einen aus der konfigurierten Quelle abgeleiteten Schlüssel, sodass Argentinien, Brasilien und benutzerdefinierte URLs niemals dieselben konvertierten Dateien teilen. Wenn eine entfernte Aktualisierung fehlschlägt und eine frühere XML vorhanden ist, wird diese veraltete Kopie mit einer Laufzeitwarnung verwendet, anstatt die Tools nicht verfügbar zu machen.

Die Quellenpriorität lautet:

1. MCP_IATI_XML_PATH.

2. MCP_IATI_XML_URL.

3. MCP_IATI_SAMPLE.

4. Das Standard-Beispiel iadb-Brazil.xml.

Beispiel:

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

Vom Plugin verwendete CSV-Tabellen

Die drei CSV-Dateien werden als gemeinsame pandas-DataFrames geladen. Wiederholte Tool-Aufrufe verwenden dieselben Instanzen erneut und laden die XML nicht erneut herunter, führen die Konvertierung nicht erneut aus und lesen die CSV-Dateien nicht erneut.

Die Logik zur Datenaufbereitung und -konvertierung ist getrennt von der Abfragelogik. Weitere CSV-Tabellen können über DATAFRAME_SPECS hinzugefügt werden.

Entwicklung

# 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

Hinzufügen zu einem lokalen mcp-server

Installieren Sie dieses Paket aus dem Ordner mcp-server/ in dieselbe virtuelle Umgebung:

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

Die Tools werden mit dem Präfix mcp_iati_ verfügbar.

IATI-Glossar

Die Tool-Beschreibungen und die Plugin-Anweisungen teilen sich ein zentrales Glossar, das in src/mcp_iati/glossary.py definiert ist. Sein Ziel ist es, dass das Modell die Begriffe des Standards konsistent interpretiert und die Unterscheidungen erklärt, die tendenziell mehrdeutig sind, insbesondere zwischen berichtenden, finanzierenden und durchführenden Organisationen sowie zwischen Zusage, Auszahlung und Ausgabe. Das Tool define_term stellt es direkt bereit, sodass Fragen wie „Was bedeutet ‚disbursement‘?" aus dem Glossar beantwortet werden (mit dem IATI-Standard als zitierter Quelle) statt aus dem eigenen Wissen des Modells.

Das Glossar deckt den gesamten IATI-2.03-Aktivitätsstandard ab, wie er von der Bibliothek okfn/okfn_iati modelliert wird (ihre Enums spiegeln die IATI-Codelisten wider und ihr Konverter flacht jedes Element zu einer CSV ab), gruppiert in die folgenden Bereiche:

Wenn Sie ein neues Tool hinzufügen, verwenden Sie die Definitionen aus dem zentralen Modul erneut, anstatt sie im Docstring zu duplizieren (über glossary_text(...) für die relevanten Begriffe). Wenn die zugrunde liegende Bibliothek ein neues IATI-Element bereitstellt, fügen Sie dessen Begriff in der passenden Gruppe zum Glossar hinzu.

Tests

uv run pytest

Die Tests laufen offline: tests/conftest.py lädt den Daten-Cache mit synthetischen DataFrames vor und setzt MCP_IATI_XML_PATH, sodass nichts heruntergeladen wird. Sie decken Folgendes ab:

• dass das Glossar die Mindestkonzepte enthält und dass die Tool-Beschreibungen dem Modell die relevanten Begriffe offenlegen;

• Regression der Abfragen (Tabellen, Quellen, Leerfälle);

• der Rohdatenvertrag (test_raw_data_in_ai_response.py): das Gateway sendet der KI nur den Text der Antwort, daher muss jedes Tool, das eine Tabelle zurückgibt, diese wörtlich in diesen Text einbetten (erledigt durch helpers.text_result). Beim Hinzufügen eines neuen Tools mit einer Tabelle fügen Sie es zur Liste DATA_TOOLS in diesem Test hinzu.

Auf GitHub führt .github/workflows/python-lint.yml bei jedem Push ruff + pytest aus.