Servidor MCP de Estadísticas Laborales de la OIT (ILOSTAT)

🇧🇷 Leia em Português

Un servidor MCP público, alojado y con prioridad de procedencia para las estadísticas de la Organización Internacional del Trabajo (OIT) — la base de datos ILOSTAT — sin instalación, sin cuenta, sin clave API. Apunta tu cliente MCP al endpoint alojado y pregunta sobre desempleo, empleo, salarios, tiempo de trabajo y otros indicadores laborales por país, año, sexo y edad. Se ejecuta en Cloudflare Workers sobre Streamable HTTP y se comunica con la API REST oficial de ILOSTAT SDMX.

Cada respuesta incluye un bloque de procedencia (URL de origen, antigüedad de los datos, marca de tiempo real de recuperación, licencia, cita de la OIT) — cifras exactas con un rastro de auditoría, no números adivinados a partir de datos de entrenamiento.

Úsalo (alojado — sin configuración)

Apunta cualquier cliente MCP al endpoint Streamable HTTP:

https://ilo.sidneybissoli.com/mcp

Claude Desktop / Claude Code y otros clientes con soporte remoto nativo:

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

Para clientes que lanzan servidores MCP como un comando, usa el puente mcp-remote:

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

El nombre de host ilo-mcp-server.sidneybissoli.workers.dev también se sirve, como secundario.

Related MCP server: world-bank-economic-mcp

Ejecutar localmente (stdio)

¿Prefieres no enrutar consultas a través de un host de terceros? El mismo servidor también se ejecuta como un proceso stdio local que se comunica directamente con la API oficial de ILOSTAT — las mismas 4 herramientas, recursos y prompts, los mismos límites, el mismo bloque de procedencia, sin Cloudflare en el camino.

No se necesita instalación — el paquete está en npm (ilo-mcp-server, Node ≥ 20):

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

O desde el código fuente:

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)

(luego apunta el cliente a node /path/to/ilo-mcp-server/dist/cli.js).

Diferencias con el servidor alojado, todas debidas a la ausencia de bindings de Cloudflare: la caché SDMX vive en la memoria del proceso (las estructuras y listas de códigos se reutilizan dentro de una sesión, no entre sesiones); el catálogo de búsqueda se descarga del endpoint oficial en la primera búsqueda (su retrieved_at real se informa en la procedencia); sin métricas de uso, límite de tasa ni autenticación. Los registros van a stderr — stdout lleva solo el flujo JSON-RPC. El Dockerfile del repositorio construye este runtime (usado por el registro Glama).

Herramientas

Flujo típico: ilo_search_indicators → ilo_get_indicator_metadata / ilo_list_dimension_values para descubrir códigos de filtro válidos → ilo_get_data con filtros de país y período.

Cada respuesta lleva el bloque de procedencia v1.0 (@sbissoli/mcp-provenance, modos concise/detailed mediante el parámetro provenance_mode) en tres canales: structuredContent, _meta con espacio de nombres (com.sidneybissoli.ilostat/*) y un pie de página de texto.

Recursos y prompts

Tres recursos (estáticos, text/markdown, sin llamada upstream) que un cliente puede adjuntar al contexto antes de llamar a las herramientas — ahorran las 2–3 llamadas de descubrimiento que la mayoría de las sesiones gastan en "qué dataflow, qué códigos":

Tres prompts — flujos de trabajo listos que encadenan las herramientas y terminan con las reglas de cita (los argumentos son cadenas; los argumentos de período son opcionales):

Cada id de dataflow citado en los recursos y prompts se verifica contra la semilla del catálogo mediante el conjunto de pruebas, por lo que la documentación no puede apuntar a un id que la búsqueda no encontraría.

Comportamiento y límites

• REF_AREA es obligatorio en ilo_get_data, hasta 30 áreas por llamada. La pasarela de la OIT agota el tiempo (HTTP 504) en consultas sin restricciones, por lo que el servidor nunca emite una; para paneles amplios, divide las áreas en lotes y/o pagina por período (start_period/end_period). El mensaje de error explica cómo.

• Una llamada REST en vivo por consulta de datos. Los datos nunca se almacenan en caché — cada resultado de ilo_get_data se obtiene de ILOSTAT en el momento de la solicitud. Las estructuras de dataflow (TTL 24 h) y las listas de códigos (TTL 7 días, compartidas entre dataflows) se almacenan en caché.

• data_vintage es la fecha de última actualización del dataflow publicada por la OIT (anotación LAST_UPDATE, normalizada a ISO).

• retrieved_at es siempre el instante real de extracción de ILOSTAT, conservado junto con cualquier valor en caché — nunca el tiempo de compilación o de respuesta. Las respuestas en caché lo indican (served_from_cache: true).

• El catálogo de indicadores es una instantánea local (~1,210 dataflows), actualizada periódicamente; su propio retrieved_at se informa en la procedencia de ilo_search_indicators, por lo que su antigüedad siempre es visible.

• Cada llamada upstream lleva un User-Agent identificable (URL del servicio + contacto), para que los administradores de la OIT puedan contactar al operador.

• Idioma: inglés; zona horaria: UTC (los datos de la OIT se publican en inglés).

Campos de procedencia

• derived — true solo para transformación real (agregación, tasa calculada por el servidor, interpolación, armonización), siempre con una derivation_note; la conversión de unidades y el redondeo no cuentan. Este servidor no transforma valores, por lo que derived siempre es false.

• notices — reproduce los valores de OBS_STATUS (el canal de estado/descargo de responsabilidad de SDMX, p. ej. "Break in series"), textualmente y con recuentos. Los atributos técnicos por observación (DECIMALS, etc.) permanecen en las filas (rows[].attributes).

Licencia de datos y atribución

• Datos y metadatos de ILOSTAT: CC BY 4.0 (desde 2023-05-03; licencia verificada 2026-08-04).

• Atribución de la OIT en cada respuesta (campo citation): International Labour Organization, ILOSTAT, https://ilostat.ilo.org/data/, accessed <date>.

• El logotipo de la OIT no se utiliza. Este servicio no está respaldado por la OIT.

Autoalojamiento / desarrollo

Todo lo siguiente solo es necesario para ejecutar tu propia instancia — no es necesario para usar el servidor público.

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)

Bindings (ver wrangler.jsonc): KV SDMX_CACHE, D1 CATALOG_DB, Durable Object USAGE (contadores de uso respaldados por SQLite), CF_VERSION_METADATA. Autenticación Bearer opcional (wrangler secret put API_KEY); límite de tasa de token-bucket por IP.

Notas para operadores:

• ILOSTAT devuelve JSON solo cuando se negocia mediante el encabezado Accept (application/vnd.sdmx.{structure,data}+json); ?format= se ignora y devuelve XML.

• La pasarela de la OIT responde HTTP 500 (languageTag1) al encabezado Accept-Language: * que el fetch de Node (undici) envía por defecto; por lo tanto, cada llamada upstream establece explícitamente Accept-Language: en (el runtime de Cloudflare no envía tal encabezado, por lo que el Worker nunca se vio afectado). También espera un User-Agent identificable.

• La actualización del catálogo es manual (sin cron): trimestral, o inmediatamente si un dataflow que existe upstream no aparece en la búsqueda. Procedimiento: los tres comandos de semilla anteriores. Las consultas de datos siempre están en vivo, por lo que solo el catálogo de búsqueda puede envejecer — y su antigüedad se expone en la procedencia.

Evaluaciones

@sbissoli/mcp-evals: 24 fixtures en evals/fixtures/queries.ts, validadas sin conexión en npm test. La ejecución con un modelo real (npm run eval) usa la API de Anthropic y necesita ANTHROPIC_API_KEY (sin ella, sale con instrucciones). Ejecución del 2026-08-07: top-1 100% (24/24) — evals/results/.

De extremo a extremo: 10 preguntas complejas con una única respuesta verificable en evals/e2e/evaluation.xml, respuestas validadas manualmente contra producción (evals/e2e/validacao-respostas.md). Ejecución del 2026-08-07 (Sonnet): 9/10 cadena exacta; 10/10 sustancial — evals/results/2026-08-07-e2e.md.

Endpoints

Seguridad

Snyk Agent Scan (2026-08-07): superado — informe en security/.

Licencia

Código: MIT. Datos: ILOSTAT, CC BY 4.0 (consulte "Licencia de datos y atribución" más arriba).

Privacidad

Política de privacidad del servicio alojado: PRIVACY.md.

Contacto

Sidney da S. P. Bissoli — sbissoli76@gmail.com. Este servicio no está respaldado por la OIT.