# 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 部署（推荐）

```bash
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 审计事件。例如：

```json
{"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`，请配置：

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

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

## Hermes 配置

在 Hermes 的 `config.yaml` 中加入：

```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 时：

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

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

## 开发验证

```bash
uv sync --extra dev
uv run pytest
```

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