ILO Labour Statistics (ILOSTAT) — MCP-сервер

🇧🇷 Читать на португальском

Публичный, размещённый provenance-first MCP-сервер для статистики International Labour Organization (ILO) — базы данных ILOSTAT — без установки, без аккаунта, без API-ключа. Подключите своего MCP-клиента к размещённой конечной точке и запрашивайте данные о безработице, занятости, заработной плате, рабочем времени и других показателях труда по стране, году, полу и возрасту. Он работает на Cloudflare Workers через Streamable HTTP и обращается к официальному SDMX REST API ILOSTAT.

Каждый ответ содержит provenance-блок (URL источника, редакцию данных, фактическую временную метку получения, лицензию, ссылку на ILO) — точные цифры с полной историей происхождения, а не числа, угаданные из обучающих данных.

Использование (хостинг — без настройки)

Подключите любого MCP-клиента к конечной точке Streamable HTTP:

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)

Не хотите направлять запросы через сторонний хост? Тот же сервер также работает как локальный процесс stdio, который общается напрямую с официальным API ILOSTAT — те же 4 инструмента, ресурсы и промпты, те же лимиты, тот же provenance-блок, без 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/cli.js).

Отличия от размещённого сервера полностью обусловлены отсутствием привязок Cloudflare: кэш SDMX живёт в памяти процесса (структуры и списки кодов переиспользуются в рамках сессии, но не между сессиями); поисковый каталог загружается с официального endpoint при первом поиске (его фактический retrieved_at указывается в provenance); нет метрик использования, ограничения частоты запросов и авторизации. Логи выводятся в stderr — stdout передаёт только поток JSON-RPC. Файл Dockerfile в репозитории собирает этот runtime (используется реестром Glama).

Инструменты

Типичный сценарий: ilo_search_indicators → ilo_get_indicator_metadata / ilo_list_dimension_values для поиска допустимых кодов фильтров → ilo_get_data с фильтрами по стране и периоду.

Каждый ответ содержит provenance-блок v1.0 (@sbissoli/mcp-provenance, режимы concise/detailed через параметр provenance_mode) в трёх каналах: structuredContent, _meta с пространством имён (com.sidneybissoli.ilostat/*) и текстовый нижний колонтитул.

Ресурсы и промпты

Три ресурса (статические, text/markdown, без обращения к API), которые клиент может подключить к контексту перед вызовом инструментов, — они экономят 2–3 поисковых вызова, которые большинство сессий тратят на выяснение «какой dataflow, какие коды»:

Три промпта — готовые сценарии, которые соединяют инструменты в цепочку и завершаются правилами цитирования (аргументы — строки; аргументы периода необязательны):

Каждый идентификатор dataflow, указанный в ресурсах и промптах, проверяется тестовым набором на соответствие seed-каталогу, поэтому документация не может ссылаться на идентификатор, который поиск не найдёт.

Поведение и ограничения

• В ilo_get_data обязательно указывать REF_AREA; до 30 территорий за вызов. Шлюз ILO завершает запрос по таймауту (HTTP 504) при неограниченных запросах, поэтому сервер никогда их не отправляет; для широких панелей разбивайте территории на пакеты и/или используйте пагинацию по периоду (start_period/end_period). В сообщении об ошибке объясняется, как это сделать.

• Один прямой REST-вызов на каждый запрос данных. Данные никогда не кэшируются — каждый результат ilo_get_data загружается из ILOSTAT в момент запроса. Кэшируются структуры dataflow (TTL 24 ч) и списки кодов (TTL 7 дней, общие для всех dataflow).

• data_vintage — дата последнего обновления dataflow, опубликованная ILO (аннотация LAST_UPDATE, нормализованная к ISO).

• retrieved_at — всегда фактический момент извлечения из ILOSTAT, сохраняется вместе с любым кэшированным значением — никогда не время сборки или ответа. Кэшированные ответы сообщают об этом (served_from_cache: true).

• Каталог показателей — это локальный снимок (~1,210 dataflow), который периодически обновляется; его собственный retrieved_at указывается в provenance у ilo_search_indicators, поэтому его возраст всегда виден.

• Каждый внешний вызов содержит идентифицируемый User-Agent (URL сервиса + контакт), чтобы администраторы ILO могли связаться с оператором.

• Язык: английский; часовой пояс: UTC (данные ILO публикуются на английском).

Поля provenance

• derived — true только при реальном преобразовании (агрегация, вычисление показателя на сервере, интерполяция, гармонизация), всегда с derivation_note; перевод единиц измерения и округление не учитываются. Этот сервер не преобразует значения, поэтому derived всегда false.

• notices — дословно воспроизводит значения OBS_STATUS (канал статусов/дисклеймеров SDMX, например «Разрыв в ряду») с подсчётом. Технические атрибуты наблюдений (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 <date>.

• Логотип 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), CF_VERSION_METADATA. Необязательная Bearer-аутентификация (wrangler secret put API_KEY); ограничение частоты запросов для каждого IP по алгоритму token bucket.

Примечания для операторов:

• ILOSTAT возвращает JSON только при согласовании через заголовок Accept (application/vnd.sdmx.{structure,data}+json); ?format= игнорируется, и возвращается XML.

• Шлюз ILO отвечает HTTP 500 (languageTag1) на заголовок Accept-Language: *, который fetch в Node (undici) отправляет по умолчанию; поэтому каждый внешний вызов явно задаёт Accept-Language: en (среда выполнения Cloudflare не отправляет такой заголовок, поэтому Worker никогда не был затронут). Он также ожидает идентифицируемый User-Agent.

• Обновление каталога выполняется вручную (без cron): раз в квартал либо немедленно, если dataflow, существующий в источнике, не появляется в поиске. Процедура: три указанные выше seed-команды. Запросы данных всегда выполняются в реальном времени, поэтому устаревать может только поисковый каталог — и его возраст указывается в provenance.

Оценки

@sbissoli/mcp-evals: 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/.

Сквозное тестирование: 10 сложных вопросов с одним проверяемым ответом в evals/e2e/evaluation.xml, ответы проверены вручную на соответствие продакшну (evals/e2e/validacao-respostas.md). Прогон от 2026-08-07 (Sonnet): 9/10 точных совпадений строк; 10/10 по существу — evals/results/2026-08-07-e2e.md.

Конечные точки

Безопасность

Сканирование Snyk Agent (2026-08-07): пройдено — отчёт в security/.

Лицензия

Код: MIT. Данные: ILOSTAT, CC BY 4.0 (см. «Лицензия на данные и атрибуция» выше).

Конфиденциальность

Политика конфиденциальности размещённого сервиса: PRIVACY.md.

Контакты

Сидней да С. П. Биссоли — sbissoli76@gmail.com. Этот сервис не одобрен МОТ.