MCP IATI

Note: 로컬 개념 증명(PoC)입니다. 향후 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): 분야 코드, 이름 및 어휘(vocabulary)를 나열합니다.

• activity_summary(iati_identifier): 한 활동의 주요 정보와 재무 합계를 보여줍니다.

• activity_transactions(iati_identifier, limit=50): 활동의 거래를 연대순으로 나열합니다.

• transaction_totals_by_year(year_from=None, year_to=None): 약정(commitment) 및 지출(disbursement) 합계를 연도, 거래 유형 및 통화별로 그룹화하며, 잘못된 날짜/값은 무시하고 거래 통화가 누락된 경우 활동 기본 통화를 사용합니다.

• transaction_totals_by_organisation(limit=50): 보고 기관별 약정 및 지출 합계를 그룹화하되 거래 유형과 통화를 분리하고, 보고 기관이 활동 데이터의 게시자(publisher)이지 반드시 자금 제공자나 구현 기관은 아님을 명확히 합니다.

• 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 표준 필드(식별자, 상태, 기관, 수원국, 분야, 거래)만 사용하며, Brazil 또는 IADB 특정 로직은 절대 사용하지 않습니다. 즉, 다른 IATI XML에서도 동일하게 작동해야 합니다(아래 구성 변수 참조).

데이터 출처

XML 파일은 Inter-American Development Bank의 공식 IATI 발행물이며, 이 저장소에 버전 관리되지 않습니다: 은행 자체 호스팅인 webimages.iadb.org/iati에서 필요 시 다운로드됩니다(IATI registry가 색인하는 것과 동일한 URL이며, IADB는 매달 갱신합니다). 다운로드된 파일은 사용자 데이터 디렉터리(platformdirs를 통해 Linux에서는 ~/.local/share/mcp-iati/xml/)에 저장되고 구성된 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가 사용하는 것과 동일한 라이브러리지만 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 캐시는 구성된 출처에서 파생된 키를 사용하므로 Argentina, Brazil 및 사용자 정의 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 DataFrame으로 로드됩니다. 반복적인 도구 호출은 동일한 인스턴스를 재사용하며 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에 정의된 중앙 용어집을 공유합니다. 그 목표는 모델이 표준 용어를 일관되게 해석하고, 특히 보고 기관과 자금 제공 기관 및 구현 기관 사이, 그리고 약정(commitment), 지출(disbursement), 실제 지출(expenditure) 사이에서 혼동되기 쉬운 차이점을 설명하도록 하는 것입니다. define_term 도구가 이를 직접 노출하므로 "disbursement의 의미는 무엇인가요?"와 같은 질문은 모델의 자체 지식이 아닌 용어집(IATI 표준을 인용 출처로 사용)에서 답변됩니다.

용어집은 okfn/okfn_iati 라이브러리가 모델링한 전체 IATI 2.03 활동 표준을 다룹니다(해당 라이브러리의 열거형은 IATI 코드리스트를 반영하고 변환기는 각 요소를 CSV로 평탄화합니다). 다음 영역으로 그룹화됩니다:

새 도구를 추가할 때는 관련 용어에 대해 glossary_text(...)를 통해 중앙 모듈의 정의를 재사용하고 docstring에 중복해서 넣지 마세요. 기본 라이브러리가 새로운 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를 실행합니다.