{
  "markdown": "# ILO Labour Statistics (ILOSTAT) — MCP Server\n\n![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-1f6feb)\n[![CI](https://github.com/SidneyBissoli/ilo-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/SidneyBissoli/ilo-mcp-server/actions/workflows/ci.yml)\n[![Version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Filo.sidneybissoli.com%2Fstatus&query=%24.version&label=version&color=1f6feb)](https://ilo.sidneybissoli.com/status)\n[![Tools](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Filo.sidneybissoli.com%2Fstatus&query=%24.tools&label=tools&color=2ea44f)](https://ilo.sidneybissoli.com/status)\n[![Resources](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Filo.sidneybissoli.com%2Fstatus&query=%24.resources&label=resources&color=2ea44f)](https://ilo.sidneybissoli.com/status)\n[![Prompts](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Filo.sidneybissoli.com%2Fstatus&query=%24.prompts&label=prompts&color=2ea44f)](https://ilo.sidneybissoli.com/status)\n[![npm](https://img.shields.io/npm/v/ilo-mcp-server?label=npm&color=cb3837)](https://www.npmjs.com/package/ilo-mcp-server)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-blue)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.SidneyBissoli%2Filo-mcp-server/versions)\n[![ilo-mcp-server MCP server](https://glama.ai/mcp/servers/SidneyBissoli/ilo-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/SidneyBissoli/ilo-mcp-server)\n[![smithery badge](https://smithery.ai/badge/sidneybissoli/ilo-mcp-server)](https://smithery.ai/servers/sidneybissoli/ilo-mcp-server)\n[![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE.md)\n[![Status](https://img.shields.io/website?url=https%3A%2F%2Filo.sidneybissoli.com%2Fhealth&up_message=online&down_message=offline&label=status)](https://ilo.sidneybissoli.com/status)\n\n🇧🇷 [Leia em Português](README.pt-BR.md)\n\nA **public, hosted, provenance-first** [MCP](https://modelcontextprotocol.io) server for the\n**International Labour Organization (ILO)** statistics — the **ILOSTAT** database —\n**no installation, no account, no API key**. Point your MCP client at the hosted endpoint and\nask about unemployment, employment, wages, working time and other labour indicators by\ncountry, year, sex and age. It runs on Cloudflare Workers over Streamable HTTP and talks to\nthe official ILOSTAT SDMX REST API.\n\n> **Independent project.** This is an unofficial, community-built client of the ILO's public\n> ILOSTAT API — not affiliated with or endorsed by the International Labour Organization.\n> Data remain © ILO under CC BY 4.0; see [Data license and attribution](#data-license-and-attribution).\n\nEvery response carries a **provenance block** (source URL, data vintage, real retrieval\ntimestamp, license, ILO citation) — exact figures with an audit trail, not numbers guessed\nfrom training data.\n\n## Use it (hosted — no setup)\n\nPoint any MCP client at the Streamable HTTP endpoint:\n\n```\nhttps://ilo.sidneybissoli.com/mcp\n```\n\nClaude Desktop / Claude Code and other clients with native remote support:\n\n```json\n{\n  \"mcpServers\": {\n    \"ilostat\": {\n      \"url\": \"https://ilo.sidneybissoli.com/mcp\"\n    }\n  }\n}\n```\n\nFor clients that launch MCP servers as a command, use the\n[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge:\n\n```json\n{\n  \"mcpServers\": {\n    \"ilostat\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"https://ilo.sidneybissoli.com/mcp\"]\n    }\n  }\n}\n```\n\nThe `ilo-mcp-server.sidneybissoli.workers.dev` hostname is also served, as a secondary.\n\n### ChatGPT (Deep Research)\n\nChatGPT deep research (and company knowledge, and research workflows over the Responses API) only uses an MCP server that exposes exactly `search` and `fetch` — this server does, on top of the `ilo_*` tools. Point the connector at the hosted endpoint, no key required:\n\n```\nhttps://ilo.sidneybissoli.com/mcp\n```\n\n`search` ranks the query against the full ILOSTAT dataflow catalogue (~1,200 SDMX dataflows — employment, unemployment, wages, working time, informality, SDG labour indicators) and returns `{ id, title, url }` (`ind:<DATAFLOW_ID>`, e.g. `ind:DF_UNE_2EAP_SEX_AGE_RT`); `fetch` returns the dataflow as readable Markdown — name, data vintage, dimensions and codelists, the ILO's default selection and how to query it with `ilo_get_data` — with the public ILOSTAT data explorer page as `url`, which is what ChatGPT cites. Both carry the same provenance block as every other tool, in `structuredContent` and `_meta` (the text channel is the contract's JSON). In ChatGPT's developer mode (Settings → Security and login → Developer mode) any tool is callable — the `ilo_*` tools remain the ones to use for data.\n\n## Run locally (stdio)\n\nPrefer not to route queries through a third-party host? The **same server** also runs as a\n**local stdio process** that talks directly to the official ILOSTAT API — same 6 tools, resources and prompts,\nsame limits, same provenance block, no Cloudflare in the loop.\n\nNo install needed — the package is on npm ([`ilo-mcp-server`](https://www.npmjs.com/package/ilo-mcp-server), Node ≥ 20):\n\n```json\n{\n  \"mcpServers\": {\n    \"ilostat\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"ilo-mcp-server\"]\n    }\n  }\n}\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/SidneyBissoli/ilo-mcp-server\ncd ilo-mcp-server\nnpm install\nnpm run build\nnode dist/cli.js   # serves MCP over stdio (Ctrl+C to stop)\n```\n\n(then point the client at `node /path/to/ilo-mcp-server/dist/cli.js`).\n\nDifferences from the hosted server, all due to the absence of Cloudflare bindings: the SDMX\ncache lives in process memory (structures and codelists are reused within a session, not across\nsessions); the search catalogue is downloaded from the official endpoint on the first search\n(its real `retrieved_at` is reported in provenance); no usage metrics, rate limit or auth. Logs\ngo to **stderr** — stdout carries only the JSON-RPC stream. The repository `Dockerfile` builds\nthis runtime (used by the Glama registry).\n\n## Tools\n\n| Tool | What it does | Source |\n|---|---|---|\n| `ilo_search_indicators` | keyword search over ~1,210 dataflows (paginated by `offset`) | local catalogue (no upstream call) |\n| `ilo_get_indicator_metadata` | dimensions, codelists, vintage and default selection of a dataflow | cached structure (miss → upstream) |\n| `ilo_list_dimension_values` | valid codes of one dimension (paginated by `offset`) | cached codelist (miss → upstream) |\n| `ilo_get_data` | observations filtered by dimension and period | 1 live REST call per query |\n| `search` | ChatGPT Deep Research contract: ranks a query against the full dataflow catalogue, returns `{ id, title, url }` (`ind:<DATAFLOW_ID>`) | in-memory index built from the local catalogue (24 h) |\n| `fetch` | ChatGPT Deep Research contract: one dataflow as readable Markdown with the public data explorer page as `url` | cached structure (miss → upstream) |\n\nTypical flow: `ilo_search_indicators` → `ilo_get_indicator_metadata` / `ilo_list_dimension_values`\nto discover valid filter codes → `ilo_get_data` with country and period filters.\n\nEvery response carries the **provenance block v1.0**\n([`@sbissoli/mcp-provenance`](https://www.npmjs.com/package/@sbissoli/mcp-provenance), modes\n`concise`/`detailed` via the `provenance_mode` parameter) on three channels:\n`structuredContent`, namespaced `_meta` (`com.sidneybissoli.ilostat/*`) and a text footer.\n\n## Resources and prompts\n\nThree **resources** (static, `text/markdown`, no upstream call) that a client can attach to the\ncontext before calling tools — they save the 2–3 discovery calls most sessions spend on\n\"which dataflow, which codes\":\n\n| URI | Content |\n|---|---|\n| `ilostat://guide` | tool workflow, stable code conventions (`REF_AREA` ISO3 + `X`-aggregates, `SEX`, `AGE`, `FREQ`, dataflow id suffixes), limits, reporting rules |\n| `ilostat://reference/key-dataflows` | verified dataflow ids by topic (unemployment, employment, participation, wages, hours, informality, NEET, SDG 8, productivity) |\n| `ilostat://reference/provenance` | meaning of every provenance field and how to cite the ILO |\n\nThree **prompts** — ready-made workflows that chain the tools and end with the citation rules\n(arguments are strings; period arguments optional):\n\n| Prompt | Arguments | Result |\n|---|---|---|\n| `ilo_country_labour_profile` | `country`, `start_period`, `end_period` | labour-market profile of one country (unemployment, participation, employment ratio, informality, NEET, earnings, hours) |\n| `ilo_compare_countries` | `countries`, `indicator`, `start_period`, `end_period` | comparison table across countries/aggregates in one data call, flagging modelled estimates vs reported data |\n| `ilo_indicator_trend` | `indicator`, `country`, `start_period`, `end_period` | time series of one indicator with first/last, peak/trough and `OBS_STATUS` breaks |\n\nEvery dataflow id quoted in the resources and prompts is checked against the catalogue seed by\nthe test suite, so the documentation cannot point at an id the search would not find.\n\n## Behaviour and limits\n\n- **`REF_AREA` is required in `ilo_get_data`, up to 30 areas per call.** The ILO gateway times\n  out (HTTP 504) on unrestricted queries, so the server never issues one; for broad panels, split\n  the areas into batches and/or paginate by period (`start_period`/`end_period`). The error\n  message explains how.\n- **One live REST call per data query.** Data is never cached — every `ilo_get_data` result is\n  fetched from ILOSTAT at request time. Dataflow structures (TTL 24 h) and codelists (TTL 7 days,\n  shared across dataflows) are cached.\n- **`data_vintage`** is the dataflow's last-update date as published by the ILO (`LAST_UPDATE`\n  annotation, normalised to ISO).\n- **`retrieved_at` is always the real instant of extraction from ILOSTAT**, preserved alongside\n  any cached value — never the build or response time. Cached responses say so\n  (`served_from_cache: true`).\n- **The indicator catalogue is a local snapshot** (~1,210 dataflows), refreshed periodically; its\n  own `retrieved_at` is reported in the provenance of `ilo_search_indicators`, so its age is\n  always visible.\n- **Every upstream call carries an identifiable User-Agent** (service URL + contact), so ILO\n  administrators can reach the operator.\n- **Language: English; timezone: UTC** (ILO data is published in English).\n\n### Provenance fields\n\n- **`derived`** — `true` only for real transformation (aggregation, server-computed rate,\n  interpolation, harmonisation), always with a `derivation_note`; unit conversion and rounding\n  do not count. This server does not transform values, so `derived` is always `false`.\n- **`notices`** — reproduces the values of `OBS_STATUS` (the SDMX status/disclaimer channel,\n  e.g. \"Break in series\"), verbatim and with counts. Technical per-observation attributes\n  (`DECIMALS` etc.) stay on the rows (`rows[].attributes`).\n\n## Data license and attribution\n\n- ILOSTAT data and metadata: **CC BY 4.0** (since 2023-05-03; license verified 2026-08-04).\n- ILO attribution in every response (`citation` field):\n  `International Labour Organization, ILOSTAT, https://ilostat.ilo.org/data/, accessed <date>.`\n- The ILO logo is not used. This service is not endorsed by the ILO.\n\n## Self-hosting / development\n\nEverything below is only needed to run your own instance — it is **not** required to use the\npublic server.\n\n```bash\nnpm install\nnpm run typecheck && npm test   # 189 offline tests (parsers, key, tools, output contract, resources/prompts, in-memory catalogue, eval fixtures)\nnpm run dev                     # http://localhost:8787/mcp (Worker)\nnpm run build && npm start      # stdio runtime (dist/cli.js)\n\n# Catalogue seed (D1) — required before first use:\nnode scripts/seed-catalog.mjs   # downloads via curl and generates scripts/seed-catalog.sql\nnpx wrangler d1 execute ilostat-catalog --local  --file=scripts/seed-catalog.sql\nnpx wrangler d1 execute ilostat-catalog --remote --file=scripts/seed-catalog.sql\n\nnpm run deploy\nnode scripts/smoke-mcp.mjs      # smoke test against production (initialize → 6 tools → search → fetch → errors)\nnpm run manifest:lhm            # regenerate tools/resources/prompts in lhm.plugin.json from the real server\n# (the seed also writes tests/fixtures/catalog-ids.txt — the versioned id list the tests check resources/prompts against)\n```\n\nBindings (see `wrangler.jsonc`): KV `SDMX_CACHE`, D1 `CATALOG_DB`, Durable Object `USAGE`\n(SQLite-backed usage counters), `CF_VERSION_METADATA`. Optional Bearer auth\n(`wrangler secret put API_KEY`); token-bucket rate limit per IP.\n\nNotes for operators:\n\n- ILOSTAT returns JSON only when negotiated via the `Accept` header\n  (`application/vnd.sdmx.{structure,data}+json`); `?format=` is ignored and returns XML.\n- The ILO gateway answers HTTP 500 (`languageTag1`) to the `Accept-Language: *` header that\n  Node's `fetch` (undici) sends by default; every upstream call therefore sets\n  `Accept-Language: en` explicitly (Cloudflare's runtime sends no such header, so the Worker was\n  never affected). It also expects an identifiable User-Agent.\n- **Catalogue refresh** is manual (no cron): quarterly, or immediately if a dataflow that exists\n  upstream does not show up in search. Procedure: the three seed commands above. Data queries are\n  always live, so only the search catalogue can age — and its age is exposed in provenance.\n\n## Evals\n\n[`@sbissoli/mcp-evals`](https://www.npmjs.com/package/@sbissoli/mcp-evals): 24 fixtures in\n`evals/fixtures/queries.ts`, validated offline in `npm test`. The run with a real model\n(`npm run eval`) uses the Anthropic API and needs `ANTHROPIC_API_KEY` (without it, it exits with\ninstructions). Run of 2026-08-07: **top-1 100% (24/24)** — `evals/results/`.\n\n**End-to-end**: 10 complex questions with a single verifiable answer in `evals/e2e/evaluation.xml`,\nanswers validated manually against production (`evals/e2e/validacao-respostas.md`). Run of\n2026-08-07 (Sonnet): **9/10 exact string; 10/10 substantive** — `evals/results/2026-08-07-e2e.md`.\n\n## Endpoints\n\n| Route | Purpose |\n|---|---|\n| `/` | landing page (service identity + contact — public) |\n| `/health` | liveness |\n| `/status` | version, tool/resource/prompt counts and names, provenance contract version, current deploy (feeds the README badges) |\n| `/metrics` | aggregated usage (MCP endpoint only; no IPs, no query content) |\n| `/mcp` | MCP Streamable HTTP |\n\n## Security\n\nSnyk Agent Scan (2026-08-07): **passed** — report in\n[`security/`](security/2026-08-07-snyk-agent-scan.md).\n\n## License\n\nCode: [MIT](LICENSE.md). Data: ILOSTAT, CC BY 4.0 (see \"Data license and attribution\" above).\n\n## Privacy\n\nPrivacy policy of the hosted service: [PRIVACY.md](PRIVACY.md).\n\n## Contact\n\nSidney da S. P. Bissoli — sbissoli76@gmail.com. This service is not endorsed by the ILO.\n",
  "bytes": 14896,
  "sha": "ed7d99a9f53b0a51c1da23cc7bb7a4306e1c46ba89257de40913262bd94a7b51",
  "repo_slug": "sidneybissoli/ilo-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sidneybissoli_ilo_mcp_server_3b4d1e77/readme"
}