ILO Labour Statistics (ILOSTAT) — MCP Server

🇧🇷 포르투갈어로 읽기

국제노동기구(International Labour Organization, ILO) 통계 — ILOSTAT 데이터베이스 — 를 위한 공개·호스팅·출처(provenance) 우선 MCP 서버입니다. 설치 불필요, 계정 없음, API 키 불필요입니다. 호스팅된 엔드포인트에 MCP 클라이언트를 연결하고 국가, 연도, 성별, 연령별로 실업, 고용, 임금, 노동시간 및 기타 노동 지표를 조회할 수 있습니다. 이 서버는 Streamable HTTP를 통해 Cloudflare Workers에서 실행되며, 공식 ILOSTAT SDMX REST API에 접속합니다.

모든 응답에는 출처(provenance) 블록(소스 URL, 데이터 vintage, 실제 추출 시각, 라이선스, ILO 인용)이 포함됩니다. 이는 훈련 데이터에서 추정된 수치가 아니라, 감사 추적(audit trail)이 뒤따르는 정확한 수치입니다.

사용하기 (호스팅 — 설정 불필요)

Streamable HTTP 엔드포인트에 MCP 클라이언트를 연결하세요:

https://ilo.sidneybissoli.com/mcp

Claude Desktop / Claude Code 및 원격 서버를 기본 지원하는 기타 클라이언트:

{
  "mcpServers": {
    "ilostat": {
      "url": "https://ilo.sidneybissoli.com/mcp"
    }
  }
}

MCP 서버를 명령어로 실행하는 클라이언트를 사용하는 경우에는 mcp-remote 브리지를 이용하세요:

{
  "mcpServers": {
    "ilostat": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://ilo.sidneybissoli.com/mcp"]
    }
  }
}

ilo-mcp-server.sidneybissoli.workers.dev 호스트 이름도 접 등이며 부차적으로 제공됩니다.

Related MCP server: world-bank-economic-mcp

로컬 실행 (stdio)

쿼리를 제3자 호스트로 우회하는 것이 부담스러우신가요? 동일한 서버가 로컬 stdio 프로세스로도 실행되어 공식 ILOSTAT API와 직접 통신합니다 — 동일한 4개의 도구, 리소소 및 프롬프트, 동일한 제한 사항, 동일한 출처 블록을 갖고 있으며 중간에 Cloudflare가 없습니다.

설치 필요 없음 — npm 패키지로 제공됩니다 (ilo-mcp-server, Node ≥ 20):

{
  "mcpServers": {
    "ilostat": {
      "command": "npx",
      "args": ["-y", "ilo-mcp-server"]
    }
  }
}

또는 소스에서 실행:

git clone https://github.com/SidneyBissoli/ilo-mcp-server
cd ilo-mcp-server
npm install
npm run build
node dist/cli.js   # serves MCP over stdio (Ctrl+C to stop)

(그런 다음 클라이언트를 node /path/to/ilo-mcp-server/dist/index.js에 연결하세요).

호스팅 서버와의 모든 차이점은 Cloudflare 바인딩이 없다는 점 때문입니다: SDMX 캐시는 메모리 상에만 존재합니다 (구조와 코드목록(codelist)은 세션 내 에서만 재사용되며 세션 간에는 재사용되지 않습니다); 검색 카탈로그는 첫 검색 시 공식 엔드포인트에서 다운로드됩니다 (실제 retrieved_at 시각은 provenance에 기록됩니다); 사용량 지표나 rate limit·인증은 없습니다. 로그는 stderr로 출력되고 — stdout은 JSON-RPC 스트림만 전달합니다. 리포지토리의 Dockerfile이 이 런타임을 빌드합니다(Glama 레지스트리에서 사용).

도구

일반적인 흐름: ilo_search_indicators → ilo_get_indicator_metadata / ilo_list_dimension_data로 유효한 필터 코드를 확인 → 국가 및 기간 필터와 함께 ilo_get_data 호출.

모든 응답은 provenance 블록 v1.0 (@sbissili/mcp-provenance, provenance_mode 파라미터를 통한 concise/detailed 모드) 을 세 가지 채널로 함께 전달합니다: structuredContent, 네임 스pace닝된 _meta (com.sidneybissoli.ilostat/*), 그리고 텍스트 푸터(footer).

리소스 및 프롬프트

세 개의 리소스 (고정, text/markdown, 업스트림 호출 없음) — 클라이언트가 도구 호출 전에 컨텍스트에 첨부할 수 있는 항목입니다. 대부분의 세션이 "어떤 데이터플로우와 코드를 쓸까"를 알아내기 위해 소비하는 발굴 호출 2–3회를 절약합니다:

세 가지 프롬프트 — 도구들을 체인으로 연결하고 마지막에 인용 규칙을 제시하는 즉시 사용 가능한 워크플로입니다 (인수는 문자열이며, 기간 인수는 선택 사항입니다):

리소소와 프롬프트에 인용된 모든 데이터프로우 ID는 테스트 스위트로 카탈로그 시드와 대조 검증되기 때문에, 문서가 검색 결과에 없는 ID를 가리킬 수 없습니다.

작동 방식 및 제한 사항

• ilo_get_data에는 REF_AREA 필수이며, 호출당 최대 30개 지역까지 허용됩니다. 무한정(제약 없이) 조회 시 ILO 게이트웨이가 시간 초과(HTTP 504)가 발생하므로, 서버는 그런 쿼리를 발행해 주지 않습니다. 넓은 패널이 필요하다면 지역을 배치(batch)로 나누거나 기간(start_period/end_period)으로 페이지를 나누세요. 무엇을 말하는지 오류 메시지에 설명되어 있습니다.

• 데이터 쿼리마다 라이브 REST 호출 1회. 데이터는 절대 캐시되지 않습니다 — 모든 ilo_get_data 결과는 요청 시점에 ILOSTAT에서 가져옵니다. 데이터프로우 구조(TTL 24시간)와 codelist(TTL 7일, 데이터프로우 간 공유)만 캐시됩니다.

• data_vintage 는 데이터프로우의 마지막 업데이트 날짜이며, 이는 ILO가 게시한(LAST_UPDATE 배지 사항)를 ISO로 정규화한 것입니다.

• retrieved_at은 항상 ILOSTAT에서 데이터를 실제로 가져온 순간의 시각입니다 — 캐시된 모든 값의 일부로 보존되며, 빌드 시간이나 응답 시간이 아닙니다. 캐시에서 제공된 응답은 해당 사실을 명시합니다(served_from_cache: true).

• 지표 카탈로그는 로컬 스냅샷 (약 1,210개 데이터플로우)이며 주기적으로 갱신됩니다. 자체 retrieved_at은 ilo_search_indicators의 provenance에서 보고되므로, 카탈로그가 근심이 담긴 오래된 상태인지 항상 확인할 수 있습니다.

• 모든 업스트림 호출에는 식별 가능한 User-Agent (서비스 URL + 연락처)이 이어지며, ILO 관리자들이 운영자에게 연락할 수 있습니다.

• 언어: 영어; 시간대: UTC (ILO 데이터는 영어로 게시).

Provenance 필드

• derived — 진정한 변환(집계, 서버 계산 비율, 보간, 조화 표준화)에 대해서만 true이며, 항상 derivation_note가 함께 제공됩니다. 단위 변환과 반올림은 여기 해당되지 않습니다. 이 서버는 값을 변환하지 않으므로 derived는 항상 false입니다.

• notices — OBS_STATUS(SDMX의 상태·고지 채널, 예: "Break in series")의 값을 원문 그대로 재현하고 개수와 함께 제공합니다. 관측값별 기술 속성(DECIMALS 등)은 행(rows[].attributes)에 그대로 남습니다.

데이터 라이선스 및 출처 표기

• ILOSTAT 데이터 및 메타데이터: CC BY 4.0 (2023-05-03 이후; 라이선스 확인일 2026-08-04).

• 모든 응답의 ILO 출처 표기(citation 필드)는 다음과 같습니다: `International Labour Organization, ILOSTAT, https://ilostat.ilo.org/data/, accessed .

• ILO 로고는 사용하지 않습니다. 이 서비스는 ILO의 포괄을 받은 것과 무관합니다.

자체 호스팅 / 개발

아래 내용 전부는 자체 인스턴스를 구동할 필요가 있는 경우에만 요구됩니다. 공용 서버를 사용할 때에는 필요하지 않습니다.

npm install
npm run typecheck && npm test   # 96 offline tests (parsers, key, tools, output contract, resources/prompts, in-memory catalogue, eval fixtures)
npm run dev                     # http://localhost:8787/mcp (Worker)
npm run build && npm start      # stdio runtime (dist/cli.js)

# Catalogue seed (D1) — required before first use:
node scripts/seed-catalog.mjs   # downloads via curl and generates scripts/seed-catalog.sql
npx wrangler d1 execute ilostat-catalog --local  --file=scripts/seed-catalog.sql
npx wrangler d1 execute ilostat-catalog --remote --file=scripts/seed-catalog.sql

npm run deploy
node scripts/smoke-mcp.mjs      # smoke test against production (initialize → 4 tools → errors)
npm run manifest:lhm            # regenerate tools/resources/prompts in lhm.plugin.json from the real server
# (the seed also writes tests/fixtures/catalog-ids.txt — the versioned id list the tests check resources/prompts against)

바인딩(wrangler.jsonc 참조): KV SDMX_CACHE, D1 CATALOG_DB, Durable Object USAGE (SQLite-G8 기반 사용량 카운터), CF_VERSION_METADATA. 선택적인 Bearer 인증(wrangler secret put API_KEY); IP당 토큰 버킷 rate limit.

운영자 참고 사항:

• ILOSTAT는 Accept 헤더로 협상할 때만 JSON을 반환합니다 (application/vnd.sdmx.{structure,data}+json); ?format=는 사용되지 않고 XML을 반환합니다.

• ILO 게이트웨이는 Node.js fetch(undici)가 기본 전송하는 Accept-Language: * 헤더와 같은 요청에 HTTP 500(languageTag1)을 반환합니다. 따라서 모든 업스트림 호출에는 Accept-Language: en을 자동 설정합니다 (Cloudflare 런타임은 해당 헤더를 보내지 않으므로 Worker는 이 문제에 해당하지 않습니다). 또한 식별 가능한 User-Agent를 기대합니다.

• 카탈로그 갱신은 수동(cron 없음)입니다: 분기마다 수행하거나, 업스트림에 있는 데이터플로우가 검색에서 발견되지 않는 경우 즉시 수행하세요. 절차: 위의 세 시드 명령을 실행합니다. 데이터 조회는 항상 실시간이므로, 오래된버려진 수 있는 것은 검색 카탈로그뿐이며 그 나이는 exposure에 포함됩니다.

평ALS 테스트

@sbissoli/mcp- — 24개의 픽스처를 제공하는 evals/fixtures/queries.ts에 대한 오프라인 테스트는 npm test에서 수행됩니다. 실제 모델로 실행하는 경우(npm run eval)는 Anthropic API를 사용하며ANTHROPIC_API_KEY가 필요합니다(키가 없으면 안내 메시지를 출력하고 종료됩니다). 2026-08-07 실행 결과: top-1 100% (24/24) — evals/results/.

엔드투엔드: evals/e2e/evaluation.xml에 단일 검증 가능한 답변이 있는 복잡한 질문 10개, 답변은 프로덕션(evals/e2e/validacao-respostas.md)에 대해 수동으로 검증되었습니다. 2026-08-07 (Sonnet) 실행: 정확한 문자열 9/10; 실질적 10/10 — evals/results/2026-08-07-e2e.md.

엔드포인트

보안

Snyk Agent Scan (2026-08-07): 통과 — 보고서는 security/에 있습니다.

라이선스

코드: MIT. 데이터: ILOSTAT, CC BY 4.0 (위의 "데이터 라이선스 및 출처 표시" 참조).

개인정보

호스팅 서비스의 개인정보 처리방침: PRIVACY.md.

연락처

Sidney da S. P. Bissoli — sbissoli76@gmail.com. 이 서비스는 ILO의 보증을 받지 않습니다.