ilostat-mcp-server

---

概述

来自 ILOSTAT 的劳动统计数据。ILOSTAT 是国际劳工组织的数据库。查找指标，获取国家、地区和收入群体的观测数据，比较不同区域并构建劳动力市场概况；每个数值都会标明是报告值、模型估算值还是预测值。无需 API 密钥。

工具

工具	描述
ilostat_search_indicators	按自然语言词语和筛选条件搜索指标目录；每条结果都会列出各可用频率对应的数据集 ID
ilostat_describe_indicator	说明一个数据集：定义、单位和倍率、使用中的分类代码、涵盖的地区，以及数值的分类方式
ilostat_query_indicator	每次调用最多获取 3 个数据集的观测值，可按地区或地区组、性别、分类代码、来源和时期筛选
ilostat_get_country_profile	一个地区的主要劳动力市场数据：并列显示最新报告值和最新 ILO 模型估算值
ilostat_compare_geographies	按一个数据集的一个切片，在共同或最新时期对地区排名，并可选择计算 N 年间的变化
ilostat_list_reference	解读 ILOSTAT 的代码体系：地区、地区组、数据库、主题、性别、分类、来源、状态标记和注释
ilostat_dataframe_describe	按名称说明一个暂存的 df_<id> 数据框，或列出所有数据框（使用 none 身份验证时，在 HTTP 下禁用），并提供来源、覆盖范围、basis 计数和列架构
ilostat_dataframe_query	对暂存的数据框运行一条只读 SQL SELECT，也可选择将结果存储为新数据框
ilostat_dataframe_drop	在暂存数据框的 TTL 到期前将其删除

除非设置 ILOSTAT_DATAFRAME_DROP_ENABLED=true，否则 ilostat_dataframe_drop 处于禁用状态；设置 CANVAS_PROVIDER_TYPE=none 会禁用全部三个数据框工具。

功能参考

ilostat_search_indicators _工具

• 自然语言 query（每个词都必须与一个单词或词语前缀匹配；不区分大小写和重音，并将 labour/labor 视为相同）以及 frequency、database、subject、breakdown、measure 和 aggregates_only 筛选条件；省略 query 可按筛选条件浏览
• 每页最多显示 50 条结果（默认 10 条；如果 limit 更大，则按 50 处理并显示通知），可使用 next_cursor 获取后续结果；每条结果对应一个指标，包含各频率对应的 dataset_id、覆盖年份、n_ref_area、last_update 和 has_aggregates；facets 统计整个匹配结果集
• 未识别的 database、subject、breakdown 或 measure 代码会导致 unknown_filter_code 错误

---

ilostat_describe_indicator _工具

• 一个 dataset_id（UNE_DEAP_SEX_AGE_RT_A）或一个不带限定的指标代码；后者会说明该指标的所有频率；未知代码会返回 found: false 和 guidance
• 定义、unit 及其 multiplier、频率变体、breakdowns（性别代码，以及带有 is_total 总计标记的 classif1 / classif2 代码）、default_slice、涵盖的 ref_areas、basis_rule，以及前 20 个 related_datasets 和 related_total
• 当 SDMX API 无法提供答案时，structure_status 为 unavailable，且不会返回分类、单位和地区信息，而不是导致调用失败

---

ilostat_query_indicator _工具

• 最多可提供 100 个 dataset_ids；每次查询前 3 个不同的数据集，其余数据集会作为 remaining_dataset_ids 返回，以供后续调用。可按 ref_areas（最多 300 个）和/或 area_group、sex、classif1、classif2、sources 以及时期筛选：指定一个确切的 time、time_from / time_to 年份范围、latest_only，或同时指定两者
• latest_only 会保留每个序列各自的最新时期；如果一次调用无法读取请求的全部历史数据，则会改为返回每个地区和数据集的最新时期，并在通知和 applied_filters.latest_mode 中说明
• source_selection 默认为 best，也可以选择 all 或 secondary；行中包含 source、obs_status、notes 和 basis，并在 legend 中提供解码结果；applied_filters 会回显发送的每个参数
• 超出内联预览范围的结果会完整暂存为 df_<id> dataframe；超过 ILOSTAT_MAX_ROWS 的请求会报错：未筛选时为 request_too_broad，已筛选时为 result_too_large

---

ilostat_get_country_profile _工具

• 一个 ref_area，包含年度数据；可指定 ISO3 国家（KEN）或 X 编码的汇总地区（X01 表示世界、地区、收入组），以及 sex（默认值为 SEX_T，也可为 SEX_M 或 SEX_F）
• 九项主要指标（劳动力参与率、就业人口比、失业率、青年失业率、青年非就业、非就学、非培训率（NEET）、非正规就业、就业、劳动收入份额、工作贫困），分别列出该切片最新的 reported 值和最新的非预测 modelled 估计值
• 缺失的报告值仍保持缺失，并列在 reported_missing 中；汇总地区仅包含模型值

---

ilostat_compare_geographies _工具

• 一个 dataset_id 和一个切片（sex、classif1、classif2，默认使用数据集的总计）；可从 ref_areas（最多 300 个）和/或 area_group 指定地区，且至少需要提供其中一项
• period 可将所有地区设为同一时期；未提供时，每个地区取 lookback_years（默认 10）内的最新值；除非指定 include_projections，否则排除预测值；change_years（1–30）会为每个值附加该时间跨度内的变化
• 变化项沿用较早值的来源、依据、状态和备注，并带有 source_changed、basis_changed 和 break_in_series 标记；通知会统计不可直接比较的变化数量
• 行包含 rank、value、period、basis 和 source；没有值的地区会列在 missing 中，并附上 reason；comparability 会报告 mixed_periods、basis_counts 和 distinct_sources

---

ilostat_list_reference _工具

• topic：ref_areas、area_groups、databases、subjects、sexes、classifications、classification_types、sources、obs_status、notes 或 frequencies
• 文本 filter 或最多 100 个精确 codes（未找到的项列在 not_found 中；精确查询 area_groups 时会列出成员国家）；ref_area 可缩小 sources 的范围，classification_type 可缩小 classifications 的范围
• 每页最多 500 个条目（默认 50；较大的 limit 会按 500 处理，并附带通知），可通过 next_cursor 继续获取

---

ilostat_dataframe_describe _工具

• 传入一个 df_XXXXX_XXXXX，或省略 name 以按最新优先的顺序列出所有暂存的数据框（在启用身份验证 none 的 HTTP 模式下不提供列表功能；请使用确切名称）
• 每个条目包含生成它的 source_tool 及其 query_params、datasets、coverage、basis_counts、attribution、created_at / expires_at、row_count，以及用于编写 SQL 的 column_schema
• 每个数据集都会在 unit 旁保留完整单位信息：unit_measure、unit_type、unit_type_label、unit_multiplier 和 unit_multiplier_label；数值不会重新缩放

---

ilostat_dataframe_query _工具

• 对 df_<id> 表执行一条 DuckDB SELECT（可使用连接、聚合、窗口函数、CTE），最多 20,000 个字符；会拒绝写入操作、DDL、多语句 SQL、文件引用和文件读取函数、引擎设置读取以及系统目录查询
• row_limit 限制物化的行数（默认 1,000；每次调用最多 10,000 行，达到上限时会设置 row_count_capped 标记）；preview 限制内联返回的行数，且还会受 ILOSTAT_PREVIEW_CHARS 限制；applied_limits 会回显应用的限制值，BIGINT 值以字符串形式返回
• register_as 会将完整结果存储为一个具有新 TTL 的数据框；结果超过 1,000,000 行时会以 register_as_too_large 错误失败；evicted 会列出为腾出空间而删除的较早数据框

---

ilostat_dataframe_drop _工具

• 在 TTL 到期前，按 name 删除一个暂存的数据框；操作幂等，未匹配到任何数据框时返回 dropped: false
• 仅当 ILOSTAT_DATAFRAME_DROP_ENABLED=true 且数据框功能已启用时才会列出；这是唯一的破坏性工具

功能

基于 @cyanheads/mcp-ts-core：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

ILOSTAT 专属功能：

• 两个无需密钥的 ILO API：ILOSTAT 数据 API 提供目录、代码字典和观测值；ILO SDMX API 提供每个数据集的细分代码、默认切片和单位
• 目录和代码字典保存在内存中，并按 ILOSTAT_CATALOG_REFRESH_HOURS 的间隔重新检查；工具接收的每个代码都会在请求上游前进行验证
• 为每个上游主机设置请求节流器；429 响应或质询页面会作为可重试的 upstream_busy 错误返回给调用方，并附带 retryAfter。最多 5,000 行的数据响应会按 ILOSTAT_CACHE_TTL_SECONDS 缓存
• 默认启用数据帧：长度超过 ILOSTAT_PREVIEW_CHARS 的查询或比较结果会完整暂存为 DuckDB df_<id> 表，保留 ILOSTAT_DATASET_TTL_SECONDS，每个租户最多可存储 100 个数据帧、共 1,000,000 行（较旧的数据帧会被逐出，并列入 evicted）。设置 CANVAS_PROVIDER_TYPE=none 或使用 .mcpb bundle（不含 DuckDB 绑定）时，结果仅包含内联预览，并会说明这一点
• ILOSTAT 数据和元数据依据 ILO Open Access 政策，以 CC BY 4.0 许可发布；每个数据响应都带有 attribution，应与数据一同保留

便于 Agent 使用的输出：

• 每个值都标明依据：每行的依据为 reported、modelled_estimate 或 projection，结果附带 basis_counts。国家概况会在不同字段中分别返回报告值和模型值，绝不会用其中一类填充另一类
• 溯源和解码：每行保留 source、obs_status 和注释代码，并附带用于解码这些代码的 legend；查询和比较响应会回显 applied_filters，包括默认值
• 将未命中作为数据返回：未知数据集会返回 found: false 和 guidance；没有对应值的比较区域会列入 missing，并附带类型化的 reason
• 类型化错误：失败时会附带原因（unknown_code、request_too_broad、upstream_busy，等等）和恢复提示

开始使用

公共托管实例

公共实例位于 https://ilostat.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "ilostat-mcp-server": {
      "type": "streamable-http",
      "url": "https://ilostat.caseyjhand.com/mcp"
    }
  }
}

托管实例的所有调用方共用每个 ILO API 的一个请求节流器和一个数据帧工作区，因此 ilostat_dataframe_describe 在此处需要提供表的确切名称；列表功能已关闭。

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "ilostat-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/ilostat-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "ilostat-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/ilostat-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "ilostat-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/ilostat-mcp-server:latest"]
    }
  }
}

对于 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥或账户：两个 ILO API 均开放使用。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/ilostat-mcp-server.git

2. 进入目录：

cd ilostat-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# every variable is optional; see Configuration below

配置

变量	描述	默认值
ILOSTAT_CATALOG_REFRESH_HOURS	检查目录刷新的间隔小时数（1–168）。	6
ILOSTAT_MAX_ROWS	单次查询可返回或暂存的行数上限（1,000–1,000,000）。	500000
ILOSTAT_PREVIEW_CHARS	内联预览的序列化字符数预算（至少 1,000）；较大的结果会暂存为数据框。	40000
ILOSTAT_CACHE_TTL_SECONDS	上游数据响应（最多 5,000 行）的缓存秒数；0 表示禁用缓存。	900
ILOSTAT_DATASET_TTL_SECONDS	暂存数据框的单表 TTL，单位为秒（至少 60）。	86400
ILOSTAT_DATAFRAME_DROP_ENABLED	设置为 true 以启用 ilostat_dataframe_drop。	false
CANVAS_PROVIDER_TYPE	暂存数据框的 DataCanvas 引擎：duckdb；或设置为 none 以关闭数据框及三个数据框工具。	duckdb
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的可选覆盖项列表请参见 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

项目结构

目录	用途
src/index.ts	createApp() 入口。默认启用数据框，注册工具并启动目录加载。
src/config	使用 Zod 解析并验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）及其共用的输入和渲染辅助工具。共九个工具。
src/services/rplumber、src/services/sdmx	ILOSTAT 数据 API 和 ILO SDMX API 的客户端，使用 src/services/upstream 中带速率控制和重试的 HTTP 层。
src/services/catalog	内存中的目录快照、指标搜索、参考列表和分页。
src/services/structure	每个指标的 SDMX 结构和单位，并进行缓存。
src/services/observations	请求验证、大小预检、行解码、比较和响应缓存。
src/services/profile	国家概况摘要。
src/services/basis	将每个值分类为报告值、模型估算值或预测值的规则。
src/services/canvas-bridge	DataCanvas 适配器：df_<id> 暂存、来源信息、SQL、删除。
tests/	与 src/ 结构对应的 Vitest 测试套件，包含记录的上游测试固件。

开发指南

开发指南和架构规则请参见 CLAUDE.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 进行存储
• 在 src/mcp-server/tools/definitions/index.ts 的 buildToolDefinitions() 中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；切勿伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证授权。详情请参见 LICENSE 文件。工具返回的 ILOSTAT 数据归国际劳工组织所有，并依据 CC BY 4.0 发布；请注明 ILOSTAT 和数据集 ID。