Employment Data MCP

面向 Hermes 的只读 FastMCP 服务，提供六个工具：

• get_bls_employment：BLS 非农就业总人数、月新增、失业率及实际发布日期；
• get_adp_employment：ADP 私营就业总人数、月新增及实际发布日期；
• get_employment_release_schedule：未来 BLS、ADP 发布日期及美东/中国时间；
• get_latest_employment_actual_vs_forecast：最近两次非农和 ADP 实际值、预期值对比；
• get_economic_calendar：指定日期的实际值、预期值、前值和 surprise；
• get_employment_release_summary：指定发布日期的 ADP、非农和失业率摘要。

Docker 部署（推荐）

cp .env.example .env
# 编辑 .env，至少设置 BLS_API_KEY 和 FRED_API_KEY
docker compose up -d --build
docker compose logs -f employment-data-mcp

日志除 Uvicorn access log 外，还会输出 JSON 格式的 MCP 审计事件。例如：

{"event":"mcp_request_start","request_id":"7c17f8cf982a","started_at":"2026-08-10T06:30:00.123+00:00","method":"tools/call","message_type":"request","tool":"get_adp_employment","arguments":{"start_year":2025,"end_year":2026}}
{"event":"mcp_request_success","request_id":"7c17f8cf982a","method":"tools/call","duration_ms":1240.51,"tool":"get_adp_employment","result_count":18}

tools/list、initialize 等协议请求也会记录。日志时间为 UTC；参数中的 key、token、 password、authorization、proxy、secret 等敏感字段会自动脱敏。使用同一个 request_id 可配对开始、完成或错误事件。

服务每次启动还会输出 {"event":"mcp_audit_ready",...}。如果看不到该行， 说明当前容器仍在运行旧镜像；用 docker compose up -d --build --force-recreate 重建并替换容器。

默认 MCP 地址是 http://127.0.0.1:8010/mcp，仅监听宿主机回环地址， 不会直接暴露到公网。

如果代理运行在 Docker 宿主机的 11111 端口，容器内不能使用 127.0.0.1:11111，请配置：

FINANCE_PROXY_URL=http://host.docker.internal:11111

compose.yaml 已配置 Linux 所需的 host-gateway。不需要代理时将该变量留空。

Hermes 配置

在 Hermes 的 config.yaml 中加入：

mcp_servers:
  us_employment:
    url: "http://127.0.0.1:8010/mcp"
    enabled: true
    timeout: 120
    supports_parallel_tool_calls: false

不配置 tools.include 时，Hermes 会自动发现服务端当前所有工具，后续新增工具无需手动 维护白名单。

然后执行 hermes mcp test us_employment 验证连接；已经启动的 Hermes 会话中可用 /reload-mcp 重新加载。若 Hermes 自身也在容器中，127.0.0.1 指向 Hermes 容器，应把两个服务接入同一 Docker 网络，并将 URL 改为 http://employment-data-mcp:8010/mcp。

不使用 Docker

服务器已有 Python 3.11+ 和 uv 时：

uv sync --frozen
uv run employment-data-mcp

依赖安装在本项目的 .venv，不污染 Hermes 的 Python 环境。修改监听配置可设置 MCP_HOST、MCP_PORT 和 MCP_PATH。

开发验证

uv sync --extra dev
uv run pytest

API key 和代理地址只放在 .env，不要提交到仓库。经济日历预期值来自第三方日历源， 返回结果中会保留 source；BLS 与 ADP 历史序列可能随官方修订发生变化。