劳动力市场情报 — 远程 MCP 服务器

一个只读的远程 MCP 服务器，将 U.S. Bureau of Labor Statistics (BLS) 和 FRED (Federal Reserve Bank of St. Louis) 的数据以自定义连接器的形式提供给 Claude——用于职业与劳动力市场研究：就业趋势、失业率、职位空缺、招聘、离职、工资、职业前景展望以及行业比较。

运行在 Cloudflare Workers 上。成本：$0/month，位于 Cloudflare 的免费套餐。

它是以一个经过完全验证的实施计划为基础逐步构建的——本代码库中引用的每一个 BLS 和 FRED 端点、序列 ID 以及数据形态上的特殊之处，在实现之前都对照实时 API 进行了验证（而非仅凭文档臆测）。

状态

全部 10 个实现检查点已完成，并已在已部署的 Cloudflare Worker 上通过线上验证。89 个单元测试、类型检查干净通过，全部 16 个工具已确认能针对真实 BLS/FRED 数据正常工作。

连接到 Claude

1. 在 Claude 中，进入 Settings → Connectors → Add custom connector。

2. Remote MCP server URL：https://<your-worker>.<your-subdomain>.workers.dev/mcp/<MCP_PATH_TOKEN>——请把此 URL 视为凭据；该令牌是唯一授权访问的东西。

3. OAuth 客户端 ID / Secret：两个都留空。该服务器是无认证（authless）的——密钥路径 就是 凭据本身，Claude 原生支持无认证的远程 MCP 服务器。

4. 传输方式：Streamable HTTP（SSE 作为旧版回退方案）。

工具（共 16 个）

底层源数据工具——对 BLS/FRED 的轻量、忠实的透传

研究工具——组合型、更高级的分析

每个工具都标注了 readOnlyHint: true，并由自动化测试（test/unit/server.test.ts）强制执行——没有任何工具可以更改状态，也都不接受调用方提供的 URL 来抓取内容。

每个数据源实际提供什么

已验证的结果来自对实时 API 的数据，而非仅仅来自文档：

• FRED 提供了宏观环境（GDP、利率、衰退指标），单位换算和全文本搜索。它还以统一整洁的节奏重新发布许多 BLS 序列（UNRATE、PAYEMS、JOLTS 指标）。

• BLS 对职业相关的权威来源：Employment Projections (EP, 前景/空缺/工资) 和 OEWS (OE, 当前工资) 仅存在于 BLS 一处——FRED 不携带 National Employment Matrix。

• OEWS 通过 API 无历史数据——每个序列恰好只返回一个参照年份，这一点已通过请求 10 年范围却得到 9 条"No Data Available"消息和 1 个数据点的方式确认。职业工资趋势无法从该 API 获得；请使用 get_occupation_outlook 获取当前年份工资中位数快照。

• Employment Projections 不是时间序列——只有一个基础年加一个预测年（目前是大约 10 年后），最多每年更新两次。

• 年度空缺数值包含替代需求（工人因离开或转岗而腾出的职位），而不仅仅指净就业增长——这是一个常见的误读。

• 不存在官方的 BLS 序列搜索 API。 search_indicators/ search_occupations 由一个资料目录支撑，该目录源自 BLS 自身的平面文件，并在构建过程中进行了交叉验证（见 scripts/build-catalog.ts），并非手写或猜出来的。

版权声明

每个来自 BLS 的响应都会携带检索时间戳以及 BLS 服务条款所要求的准确免责声明："BLS.gov cannot vouch for the data or analyses derived from these data after the data have been retrieved from BLS.gov." 来自 FRED 的响应则携带自身的数据来源说明。

本服务器计算的任何内容（百分比变化、复合年增长率、环比变化）都会在独立的 computedByServer 字段下返回，并明确标注为服务器计算所得——绝不会以官方 BLS 或 FRED 统计数据的身份呈现。工具指令会引导 Claude 两处信息在回答时都保留。

安全模型

• 只读。 没有工具会修改状态，也不接受调用方提供的 URL 来抓取。

• 秘密路径认证。 端点为 /mcp/<256-bit token>。Claude 的连接器 UI 接受 URL 但原生不支持自定义请求头，因此凭据放在路径中。恒定的时间地进行 SHA-256 摘要比较；任何失败情况（token 错误、缺少 token、未知路由）都返回一致的 404——不会给攻击者任何猜测判断的依据。

• 入站速率限制。 每个 IP 约 60 次请求/分钟（使用 Cloudflare 设置且客户端无法伪造的 cf 连接的 IP 标识），并 在认证之前 进行检查，以便洪泛攻击无法占用 CPU 做 token 比较。由 Workers KV 提供支撑；若无 KV 绑定，则自动放行（allow）.

• 出站 BLS 配额保护器。 一个断路器，默认将已注册 BLS 密钥的每日 500 次配额使用到 450 次——配额耗尽时会在发出任何网络请求 先 失败，从而避免失控循环消耗真实配额。

• 密钥绝不出服务器。 BLS_API_KEY、FRED_API_KEY 和 MCP_PATH_TOKEN 仅作为 Workers secrets 存在——永远不会出現在工具响应中，永远不会被记录日志。src/lib/logging.ts 会从每条日志记录中禁用已知的密钥值和所有 api_key=/registrationkey= 模式；这是由单元测试断言的，而非仅仅意图 .

  • 已知限制： Cloudflare 自己的平台请求日志（以及 wrangler tail）会记录完整的请求 URL，包括路径中的 token ——这一点不在应用代码可控制的范围内。不要公开发布原始日志；如果不小心，请继续替换 token（执行 wrangler secret put MCP_PATH_TOKEN，然后把新 URL 粘贴回 Claude）。

缓存

Workers KV 两层：根据下表的 TTL 存储一个"新鲜"条目，并一遍计时写入一份 35 天的"过期备份"，在每次成功调用时一并写入。如果实时调用失败或发生 BLS 配额耗尽，则会提供过期备份而不是直接失败——并在响应的 limitations 字段中明确标记出来，这样 Claude 永远不会在未说明的情况下旧数据当作当前数据。

缓存键仅由工具及其参数派生，永远不来自环境变量或密钥——从而没有任何密钥材料会泄漏到缓存键中。

项目结构

src/
  index.ts               Worker entry: routing, auth, rate limiting
  server.ts               MCP server construction + tool registration
  env.ts                  Env typing + secret names
  errors.ts                Typed error hierarchy (network/timeout/429/5xx/BLS-200-with-error-body)
  sources/
    http.ts               Shared fetch: timeout, retry/backoff
    bls.ts                BLS v2 client
    fred.ts               FRED client
  catalog/
    occupations.json      1,113 SOC occupations -> EP series ID (build-generated, validated)
    industries.json        423 EP industries -> series ID (build-generated, validated)
    indicators.ts           ~13 curated headline indicators (individually live-verified)
    search.ts               Shared token-matching + relevance-ranking search
  tools/
    source/                Thin passthrough tools
    research/               Composed analysis tools
  lib/
    cache.ts               Workers KV two-tier cache
    ratelimit.ts             BLS daily budget guard + inbound per-IP limiter
    envelope.ts              Response envelope: citations, timestamps, disclaimers
    stats.ts                 Deterministic trend math
    logging.ts                Structured logs with secret redaction
scripts/
  build-catalog.ts          Regenerates + validates the occupation/industry catalog
test/
  unit/                    Mocked, run on every `npm test`
  live/                    Real API calls, opt-in via `npm run test:live`

本地开发

npm install
cp .dev.vars.example .dev.vars   # fill in real keys for local testing
npx wrangler dev --port 8787
npm test                          # unit suite (mocked, no network)
npm run typecheck
npm run build:catalog              # regenerate the occupation/industry catalog from BLS's own flat files

如需在本地验证对真实 BLS/FRED 数据（绝不提交密钥，也不记录密钥）：

BLS_API_KEY=your_key FRED_API_KEY=your_key npm run test:live

部署

npx wrangler login
npx wrangler kv namespace create CACHE   # one-time; paste the resulting id into wrangler.toml
npx wrangler secret put BLS_API_KEY
npx wrangler secret put FRED_API_KEY
npx wrangler secret put MCP_PATH_TOKEN     # generate with: openssl rand -hex 32
npx wrangler deploy
curl https://<your-worker>.<your-subdomain>.workers.dev/health

密钥和 KV 绑定在 wrangler deploy 之后依然有效——只需设置一次，而不用每次部署都重新设置。

已知限制

• Employment Projections 和 OEWS 是单一参照年度，不是时间序列——每个研究工具都会明确检测并报告这一点（trend: null并附带解释，而不是根据单个数据点编造趋势）。

• BLS Employment Projections 的行业代码与 BLS 月度 CES 行业就业序列之间不存在经过验证的桥梁（二者属于不同分类体系）——analyze_industry_employment 只覆盖长期展望；要和 fred_search_series + analyze_labor_market_trend 来查询当前月度行业就业。

• SOC 职业代码在 Employment Projections 的版本迭代之间会变化——跨 vintage 重建目录前后对同一职业进行比较并不可靠。

• 入站速率限制器是一个尽力而为的固定窗口计数器（在读取后写入时存在一两个请求欠计数的竞态可能性）——这不是精度保证，而是低用量个人连接器的一个可取舍。