bls-mcp-server

---

概述

美国劳工统计局的劳动力统计数据：就业、失业、工资和通胀。用通俗语言查找数据系列，无需解读 SeriesID；获取完整历史记录或最新值，并对大型多系列结果运行 SQL。

工具

工具	说明
bls_list_surveys	列出 BLS 调查项目（CPI、CPS、CES、JOLTS、PPI、OEWS 等），包括代码、说明和计算支持标记。
bls_search_series	按自然语言、调查、地区或关键词搜索 BLS 系列目录，以解析难以理解的 SeriesID。
bls_get_series	按 SeriesID 获取 1–50 个 BLS 系列的时间序列数据，可选年份范围和逐期计算。
bls_get_latest	返回一个或多个 BLS 系列最近的一条观测值。
bls_dataframe_describe	列出由 bls_get_series 或 bls_dataframe_query 注册的画布数据框——来源信息、TTL、行数和列架构。设置 CANVAS_PROVIDER_TYPE=duckdb 时可用。
bls_dataframe_query	对由 bls_get_series 或先前的 register_as 注册的画布数据框运行 SELECT。支持 JOIN、聚合、窗口函数和 CTE。设置 CANVAS_PROVIDER_TYPE=duckdb 时可用。
bls_dataframe_drop	按名称删除画布数据框。设置 CANVAS_PROVIDER_TYPE=duckdb 且 BLS_DATAFRAME_DROP_ENABLED=true 时可用；默认由 TTL 负责清理。

功能参考

bls_list_surveys _工具

• 可选的 category 按主题筛选调查项目；返回代码、名称和计算支持标志（allowsNetChange、allowsPercentChange、hasAnnualAverages）。
• 数据来自 BLS surveys API，并使用月度缓存。年度平均值支持情况仅供参考；请读取 bls_get_series 的 annualAverageRows，查看实际返回的行。

---

bls_search_series _工具

• 按文本或 SeriesID 搜索，可选指定 survey、area（区域、标题或 SeriesID 的子字符串）和 seasonal_adjustment；空筛选条件会被忽略。limit 范围为 1–50（默认值为 10），并通过 offset 分页。未指定区域筛选时，地名会优先匹配已解码的区域；同一优先级组内得分相同时，全国系列优先。精确匹配的 SeriesID 排名最高。
• 返回已解码的 SeriesID、标题、frequency，以及可单独提供的 startYear、endYear 和 endPeriod 覆盖范围（例如，1982–2005 Q04）。覆盖范围描述的是目录快照，并不表示观测值连续。若 truncated 为 true，请继续使用 nextOffset；capped: true 表示 totalCount 是下限，且分页会在 FTS 候选池处停止。
• 搜索离线 LABSTAT 索引，不消耗 API 配额；OE/OEWS 需通过 BLS_CATALOG_INCLUDE_OES 选择启用。未建立索引的调查仍可通过 SeriesID 获取。

---

bls_get_series _工具

• 每次调用获取 1–50 个 SeriesID，start_year/end_year 时间窗口最多为 20 年；可选指定 calculations 和 annual_average。仅指定起始年份时，结束年份默认为当前年份，且不超过起始年份 + 19；仅指定结束年份会被拒绝。一次批量调用消耗一次 API 查询；计算功能取决于调查是否支持（CPI/PPI 仅返回百分比变化）。
• 返回带有 available 的观测值，保留原始缺失值标记 -，并在混合批次中保留有效系列。补充信息会报告应用的年份窗口、计算项和年度平均值行。
• 当 CANVAS_PROVIDER_TYPE=duckdb 时，大型结果会写入 dataset.name；否则会返回 canvas_unavailable，提示缩小时间窗口。

---

bls_get_latest _工具

• 获取最多 50 个 SeriesID 的最新观测值（建议不超过 10 个）。每个 ID 消耗一次 API 查询；如需更高效地批量获取多个系列，请使用 bls_get_series。
• 在 results[] 中返回成功结果，并在 failed[] 中列出各系列的失败条目。latestObservation.available 用于区分已发布的值与 BLS 的缺失值标记。

---

bls_dataframe_describe _工具

• 可选指定 name，用于描述一个已注册的数据框；省略时会列出租户的活动数据框。需要设置 CANVAS_PROVIDER_TYPE=duckdb。
• 返回来源工具、查询参数、行数、TTL（created_at/expires_at）和 column_schema；BLS 列允许为空。画布支持类型集合以外的已注册查询类型（DECIMAL、HUGEINT、SMALLINT、列表）会报告为 VARCHAR。成功删除画布后，过期条目会被移除。

---

bls_dataframe_query _工具

• 对已注册的表运行一个 SELECT，可使用 JOIN、聚合、窗口函数或 CTE。row_limit 默认值为 1000，上限为 10000；禁止写入、读取外部文件和访问系统目录。
• 禁止使用引擎设置项（current_setting、current_schema、current_schemas、in_search_path）和 query_table。query() 接受一个纯 SQL 字符串字面量，并会递归检查，最多四层；拒绝经过计算生成的 SQL 字符串。分析时请直接引用暂存表。
• 返回行数据，不消耗 BLS API 配额。可选的 register_as 会为结果暂存并设置新的 TTL，以便串联分析；需要设置 CANVAS_PROVIDER_TYPE=duckdb。

---

bls_dataframe_drop _工具

• 必需的 name 用于标识要删除的 dataframe。仅当 CANVAS_PROVIDER_TYPE=duckdb 且 BLS_DATAFRAME_DROP_ENABLED=true 时可用；默认由 TTL 负责清理。
• 如果表不存在，则返回 dropped: false。删除失败时会返回可重试的 canvas_drop_failed，并保留已注册的 dataframe。

功能

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

BLS 专属功能：

• 支持重试和退避机制并跟踪每日配额的 BLS API v2 客户端
• 基于 LABSTAT 扁平文件的离线序列目录搜索，并建立索引至磁盘上的 SQLite/FTS5 存储库；发现数据不消耗 API 配额；OES/OEWS 工资调查（约 600 万个序列）可通过 BLS_CATALOG_INCLUDE_OES 选择启用
• 针对 BLS 特定故障模式的类型化错误约定，包括配额耗尽、数据库锁定和不支持的计算
• 通过 BLS 自身的服务端标志进行周期环比净变化／百分比变化计算，确保与 BLS 发布的数据一致
• 可选的 DataCanvas 溢写（DuckDB），用于处理大型多序列结果集；无需重新查询 API，即可发现 schema 并通过 SQL 访问数据

便于 Agent 使用的输出：

• 来源信息 — 溢写至 canvas 的结果包含 dataset.name 句柄、行数和过期时间；bls_search_series 会回显 effectiveQuery、catalogSize，以及 FTS 候选池是否被 capped
• 优雅处理部分失败 — bls_get_latest 会在成功的 results[] 旁返回每项失败信息 failed[]（包含 seriesId 和错误），而不是让整个批次失败；如果同一批次中的另一个 SeriesID 无效或为空，bls_get_series 仍会保留有效序列
• 可判别输出 — 每条观测都包含一个 available 布尔值，用于标记 BLS 的缺失值哨兵 -，因此调用方可根据类型化字段进行分支判断，而无需解析原始值
• 可执行的提示 — enrichment.notice 会说明结果为空、发生 canvas 溢写或数据不可用的原因，并给出具体后续步骤（例如使用 bls_search_series 验证 SeriesID）

开始使用

公共托管实例

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

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

自托管／本地使用

将以下内容添加到 MCP 客户端配置文件。免费的 BLS API 密钥可解锁每天 500 次查询额度；请在 bls.gov/developers 注册。没有密钥时，服务每天可处理 25 次请求。

{
  "mcpServers": {
    "bls-labor-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/bls-labor-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "BLS_API_KEY": "your-key-here"
      }
    }
  }
}

也可使用 npx（无需 Bun）：

{
  "mcpServers": {
    "bls-labor-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/bls-labor-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "BLS_API_KEY": "your-key-here"
      }
    }
  }
}

也可使用 Docker：

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

要使用 Streamable HTTP，请设置传输方式并启动服务：

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

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 免费的 BLS API v2 密钥 — 请在 bls.gov/developers 注册。密钥每天可提供 500 次查询额度；没有密钥时，服务每天也可处理 25 次请求。

安装

1. 克隆仓库：

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

2. 进入目录：

cd bls-labor-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set BLS_API_KEY

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。

变量	描述	默认值
BLS_API_KEY	BLS v2 API 密钥。可选——不使用时每天 25 次请求，使用时每天 500 次请求。可在 bls.gov/developers 免费注册。	—
BLS_BASE_URL	BLS API v2 基础 URL。	https://api.bls.gov/publicAPI/v2
BLS_CATALOG_BASE_URL	LABSTAT 平面文件基础 URL。可覆盖此项以指向本地镜像。	https://download.bls.gov/pub/time.series
BLS_CATALOG_DB_PATH	磁盘上的 SQLite 目录索引——按需查询，并在重启后保留。留空时使用内存数据库（每次启动都会重新采集）。在容器中请在此处挂载卷。	.cache/bls-catalog.db
BLS_CATALOG_CACHE_TTL_HOURS	目录新鲜度窗口（小时）——索引过期后重新采集；启动时及运行期间每小时检查一次。	168（7 天）
BLS_CATALOG_INCLUDE_OES	包含 OES/OEWS 工资调查（约 600 万个序列 / 约 1.2 GB；首次采集需要数分钟）。默认关闭——仍可按 ID 获取 OES 序列。	false
BLS_OBSERVATIONS_MIRROR_ENABLED	从本地 SQLite 镜像提供观测数据，而非使用实时 API（需要一次性引导——见下文）。	false
BLS_DATASET_TTL_SECONDS	为画布注册表设置的表的每数据帧 TTL，单位为秒。	86400（24 小时）
BLS_DATAFRAME_DROP_ENABLED	暴露 bls_dataframe_drop。默认由 TTL 处理清理。	false
CANVAS_PROVIDER_TYPE	设置为 duckdb 以启用 DataCanvas，为大型结果集提供表格数据溢出处理。	none
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	会话模式。此服务使用 stateless；有效的模式值为 auto、stateful 和 stateless。模式默认值 auto 会解析为 stateful。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
OTEL_ENABLED	启用 OpenTelemetry 检测。	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于跟踪和指标的 OTLP 基础 URL；特定信号的端点会覆盖此项。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	可选的 OTLP 日志端点。基础 URL 不会启用日志导出。	—
LOG_TOOL_FAILURE_PAYLOADS	记录失败调用的参数和结果，并按键名进行脱敏；自由格式值中的机密信息仍会保留。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	每个失败负载日志的 UTF-8 字节上限。	16384

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

观测数据镜像（可选）

对于高负载工作负载，可选择启用本地镜像，通过内嵌的 SQLite 存储而非 BLS API 提供 bls_get_series / bls_get_latest 服务，从而消除每日 500 次的配额上限。默认关闭。启用方法：

1. 设置 BLS_OBSERVATIONS_MIRROR_ENABLED=true（并查看 .env.example 中的 BLS_OBSERVATIONS_MIRROR_* 变量）。

2. 在带外运行一次性引导程序——它会下载完整的 LABSTAT 观测数据集，可能需要一些时间：

   node dist/services/bls-observations/subprocess.js --init
   

镜像会抓取目录调查列表中的每项调查——包括 OE，具体取决于 BLS_CATALOG_INCLUDE_OES 的设置——因此也涵盖 CM 和 CI（cm.data.* / ci.data.* 文件约 55 MB）。增量刷新只读取镜像上次读取后发布的文件，因此，在 CM 和 CI 纳入之前完成引导的镜像，会在 BLS 下次发布时读取每个文件；在此之前，如果启用了回退，这些序列会从实时 API 获取。引导完成前，请求会回退到实时 API（除非 BLS_OBSERVATIONS_MIRROR_FALLBACK_LIVE=false）。如果实时回退失败——配额耗尽或 BLS 无法访问——仍会返回镜像提供的序列，并且 enrichment.notice 会列出每个未提供的 SeriesID，以及失败原因和恢复方法。镜像行不包含 BLS 计算结果：当 calculations: true 时，镜像提供的序列不会返回计算字段，enrichment.calculationsApplied 为 false，且 notice 会列出该序列。在 HTTP 传输模式下，增量刷新按 BLS_OBSERVATIONS_MIRROR_REFRESH_CRON 计划运行。在容器中，请在 BLS_OBSERVATIONS_MIRROR_PATH 挂载持久卷。

升级现有镜像。 在开始存储哨兵行之前完成引导的镜像，缺少 BLS 使用 - 缺失值标记发布的时段。打开此类镜像时，会清除其同步检查点一次，因此下次刷新会重新读取所有 LABSTAT 文件并补全这些数据——除等待刷新运行外，操作员无需采取其他操作；该过程耗时与完整读取相同。镜像在整个过程中会持续提供服务。

运行服务

本地开发

• 构建并运行：

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

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t bls-labor-mcp-server .
docker run --rm -e BLS_API_KEY=your-key -e MCP_TRANSPORT_TYPE=http -p 3010:3010 bls-labor-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/bls-labor-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具并初始化服务。
src/config	使用 Zod 解析和验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/services/bls-api	BLS API v2 服务——批量获取、最新值 GET、调查元数据。
src/services/bls-catalog	LABSTAT 平面文件目录——离线序列索引和搜索。
src/services/bls-observations	可选的 LABSTAT 观测数据镜像——内嵌 SQLite 存储、导入器和刷新子进程。
src/services/bls-periods	API 和镜像路径共用的年度平均时段语义（M13/Q05/S03）。
src/services/canvas-bridge	DataCanvas 桥接——数据帧注册、SQL 门控和生命周期管理。
docs/design.md	完整的工具接口规范、服务架构和错误约定。
tests/	与 src/ 对应的单元测试和集成测试。

开发指南

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

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求级日志，使用 ctx.state 存储租户级数据
• bls_search_series 是核心工具——设计工作流时，应在调用 API 工具前先调用它
• 封装 BLS API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。