eurostat-mcp

Eurostat 데이터에 접근하는 MCP 서버로, 로컬 모델용으로 설계되었습니다 (Qwen3.8-27B로 테스트됨): 4개의 도구, 좁은 스키마, 서버 측 검증, 압축된 출력.

아키텍처

Modèle (Qwen3.8-27B via vLLM / llama.cpp + harness MCP)
   │  tool calls
   ▼
server.py        4 tools : search_datasets, get_structure, list_codes, query_data
   │             validation DSD + suggestions difflib + plafond 400 cellules
   ▼
store.py         SQLite : catalogue en FTS5 (TTL 24h), structures DSD (TTL 24h)
   ▼
eurostat_client.py   API dissémination Eurostat (catalogue TSV + Statistics JSON-stat)

모델은 SDMX URL을 결코 구성하지 않습니다. 모든 요청은 query_data를 거치며, 캐시된 DSD에 대해 차원과 코드를 검증하고 실행 가능한 오류를 반환합니다 (Code 'FRA' inconnu. Vouliez-vous : FR ?).

Related MCP server: DuckDB Eurostat MCP Server

설치

pip install "mcp>=1.2" httpx pyarrow duckdb   # SDK mcp 1.x et 2.x
python -m territorial_mcp.server                      # stdio
MCP_TRANSPORT=http python -m territorial_mcp.server   # streamable HTTP

MCP 클라이언트 구성 (stdio):

{
  "mcpServers": {
    "eurostat": {
      "command": "python",
      "args": ["-m", "territorial_mcp.server"],
      "cwd": "/chemin/vers/eurostat-mcp"
    }
  }
}

모델 측 일반적인 시퀀스

1. search_datasets("GDP quarterly") → 후보 코드

2. get_structure("namq_10_gdp") → 차원, 잘린 코드

3. list_codes("namq_10_gdp", "geo", contains="fr") 필요한 경우

4. query_data("namq_10_gdp", {"geo": "FR+BE", "na_item": "B1GQ", "unit": "CP_MEUR"}, time_from="2022")

Qwen3.8-27B 참고: 중간/낮은 추론 수준을 설정하세요 (기본 xhigh는 단순한 도구 연쇄를 과도하게 생각합니다).

완전 오프라인 모드

# 1. (en ligne) construire le miroir — TOC-driven, idempotent
python -m territorial_mcp.mirror --datasets nama_10_gdp,une_rt_m
python -m territorial_mcp.mirror --all        # tout le catalogue, ~24 Go compressés
python -m territorial_mcp.mirror --resync     # cron quotidien : ne retélécharge
                                           # que ce que le TOC signale comme modifié

# 2. (hors ligne) servir uniquement depuis le miroir + caches
EUROSTAT_OFFLINE=1 python -m territorial_mcp.server

• 데이터: Parquet zstd long format (dims, time, value, flag), 데이터셋별 파일 하나, DuckDB로 조회. query_data는 오프라인 모드가 아니어도 미러를 우선 제공하며, 데이터 날짜를 표시합니다 ("로컬 미러, JJ.MM.AAAA 기준 Eurostat 데이터").

• 구조 + 카탈로그: 동기화 때마다 업데이트되며, 오프라인 모드에서는 TTL 없이 제공됩니다. Eurostat에 연결할 수 없을 때는 serve-stale-on-error.

• 무효화는 TTL이 아니라 TOC의 last update of data 열에 의해 제어됩니다. --resync는 수정된 데이터셋만 건드립니다.

골격의 한계와 발전 방향

• 검색: FTS5/BM25만 사용. 모호한 요청을 위해 임베딩을 활용한 하이브리드 검색(예: sqlite-vec의 bge-m3)을 추가.

• 구조: Statistics API에서 lastTimePeriod=1 트릭을 통해 가져옴. 매우 큰 데이터셋의 경우 전용 파싱과 함께 SDMX 2.1 datastructure 엔드포인트(XML)로 전환.

• 데이터 캐시: 구조만 캐시됨. query_data 응답 캐시를 추가 (TTL 24시간 — Eurostat은 11시/23시에 게시).

• 집계: store.py를 DuckDB로 마이그레이션하여 모델에 원시 데이터를 보내는 대신 서버 측 집계(평균, 성장률)를 제공.

• HTTP 다중 사용자: streamable HTTP 전송 앞에 인증(bearer)과 rate limiting을 추가.