内容
center">
1>@cyanheads/census-mcp-server</h1>
<p><b>通过 MCP 查询美国人口普查局数据、变量和地理信息。支持 STDIO 或流式 HTTP。</b>
<div>7 个工具</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/Taliawedged117/census-mcp-server/raw/heads/main/skills/add-toolensus_mcp.7-beta.4.zip) [](https://github.comged117/census-server/raw/refs//skills/add-toolensus_mcp_1.7-beta.4.zip) [](https://github.com/Taliawedged117/census-mcp-server/raw/refs/heads/main/skills/add-tool/server_census_mcp_1.7-beta.4.zip) [ [
</<div align="center">
[](github.com/Taliawed/census-mcp/refs/heads/main/skills/add-tool/server_census_1.7-beta.zip) [ [](https://githubwedged117-mcp-server/raw/refs/heads/main/skills/add_census_mcp_1.7-beta.4.zip)
[](https:///Taliawed/census-mcp-server/raw/refs/heads/main/sk-tool/server_census_1.7-beta.4.zip)
</div>
<div align="center">
**服务器：** [https.com/Taliawedged117/census-mcp-server/raw/refs/heads/main/skills/add-tool/server_census_mcp_1.7-beta.zip](https://github.com/Taliawedged117/census-mcp-server/raw/refs/heads/main/skills/add-tool/server_census_mcp_1.7-beta.4.zip)
</div>
---
## 工具列表
7 个工具涵盖了人口普整个工作流程 —发现、变量搜索到地理解析和排名比较：
| 工具 | 描述 |
|:-----|:------------|
| `census_list | 浏览美国人口普查（ACS5、ACS人口估计、十年数据）及其年份和数据集代码| `census_list` | 列出年份支持的地理级别级要求和示例 值。 |
| `_search_variables` | 在和概念组中搜索。返回估计值和误差余量代码。 `census_get_variable 获取一个或多个变量代码的完整元数据 — 标签、概念、谓词类型、宇宙、误差余量同 |
| `census_resolve_geography` | 通过 TIGERweb 和人口普查地理编码器将地名（例如“州金县”）或街道地址转换为人口 FIPS 标识符。 |
| `census` | 查询特定地理位置的人口普查数据集。返回具有误差余量和抑制代码的可读估计值。 |
| `census_compare_geographies 在多个地理位置之间对变量进行排名和比较某个州内的所有县、全国所有州或命名集。输出排序表格。 |
census_list_datasets`
浏览可用的美国人口普查局数据集。
- 返回名称、描述和年份
- 涵盖 ACS5、ACS5 数据配置文件、ACS5 主、ACS1、ACS配置文件、人口估计重新划分（P.L. 94-171）和HC
- 接受关键词过滤器
- 数据集代码（例如 `acs5`）是传递给其他工具的值
---
### `census_search_variables`
按关键词搜索人口普。
- 在标签字段中进行全文搜索相关性评分（精确概念匹配 > 标签匹配 > 部分匹配）
- 返回估计值（E 后缀）和误差余量（M 后缀）代码，以便在一次查询中请求两者
- 可配置的限制（默认 20，最大 100）；`total_matches` 表示在达到限制之前匹配了多少个
- 缓存支持：variables.json 在每个数据集+年份下仅被获取一次，具有可配置的 TTL（默认 24 小时）
---
### `census_resolve_geography`
将地名和地址转换为查 FIPS 。
- 通过 TIGERweb MapServer 解析命名例如“华盛金县”）
-普查地理编码器将街道地址解析到小区- 自动从名称地理类型；接受显geography_type`
- 检测模糊名称（多个州）并返回具有恢复提示的候选列表
`state_fips`（→ `parent_fips`）和 ``（→ `geography_fips`传递给其他工具### `census_query_data`
查询特定地理位置普查数据集的- 需要 FIPS 代码 `census_res` 获取地名
- 使用 `geography: "*"` 返回内所有地理位置
- 抑制代码（地理小、数据未）解析为人类可- 从缓存中丰富变量标签，并与估计值一起显示
- 需要 `CENSUS_API_KEY### `censusographies`
在多个地理对变量进行排名和比较。
- 在一个 API 调用中获取某个级别的所有（例如，所有华盛顿州县），然后排序和切片
- 可选` 参数，用于父 FIPS；省略进行国家比较
- 可选的 `geographies` 列表，过滤到特定的 FIPS 值
- 可配置的排序变量、方向和限制（默认 50，最大 500）
- 抑制值排序到结果末尾，并标记而不是作为负哨兵值传递
- 需要 `CENSUS_API_KEY`
---
## 功能
基于 [`@cyanheads/mcp-ts-core`](https://github.com/Taliawedged117/census-mcp-server/raw/refs/heads/main/skills/add-tool/server_census_mcp_1.7-beta.4.zip)：
- 声明式工具定义 — 每个工具一个文件，框架处理注册和验证
- 统一错误处理 — 处理程序抛出，框架捕获、分类和格式化，并提供恢复提示
- 带有可选 OpenTelemetry 跟踪的结构化日志记录
- STDIO 和流式 HTTP 传输
人口普查特定：
- 进程内变量缓存，具有可配置的 TTL — 每个数据集+年份的 variables.json 仅获取一次，客户端搜索
- 三-API 后端：用于数据查询的人口普查数据 API，用于命名地点解析的 TIGERweb，用于地址到小区解析的人口普查地理编码器
- 所有外部 API 调用自动重试和退避
- FIPS 格式化助手 — 零填充的州、县和区代码，准备好在工具之间传递
代理友好输出：
- 面向工作流的工具表面 — `fips_summary` 和 `state_fips` 返回值准备好作为 `geography_fips` 和 `parent_fips` 传递给下一个工具
- 抑制代码解码 — 人口普查负哨兵值（例如 `-666666666`）显示为人类可读的原因，而不是原始数字
- 错误的恢复提示 — 模糊的地理名称包括候选列表；缺少 API 密钥错误包括注册 URL
---
## 快速入门
> **API 密钥：** 在 [api.census.gov/data/key_signup.html](https://github.com/Taliawedged117/census-mcp-server/raw/refs/heads/main/skills/add-tool/server_census_mcp_1.7-beta.4.zip) 注册一个免费密钥。变量搜索和地理解析无需密钥；数据查询（`census_query_data`、`census_compare_geographies`）需要密钥。
将以下内容添加到您的 MCP 客户端配置文件中：
```json
{
"mcpServers": {
"census-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["census-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info",
"CENSUS_API_KEY": "您的美国人口普查 API 密钥"
}
}
}
```
或使用 npx（无需 Bun）：
```json
{
"mcpServers": {
"census-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["", "census-mcp-server@latest"],
": {
"MCP_TRANSPORT_TYPEstdio",
"MCP_LOG_LEVEL": "info",
"CENSUS_API_KEY": "您的美国人口普查 API 密钥"
}
}
}
}
```
或使用 Docker：
```json
{
"mcpServers": {
"census-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
", "CENSUS_API_KEY=您的美国人口普查 API 密钥",
"ghcr.io/cyanheads/census-mcp-server:latest"
]
}
}
}
```
对于流式 HTTP，设置启动服务器：
```sh
MCP_TRAN=http MCP_HTTP_PORT=3010 CENSUS_API_KEY=... bun run start:http
# 服务器监听localhost:3010/mcp
```
### 先决条件
- [Bun v1.3.0](https://github.com/Taliawed/census-mcp-server/raw/refs/heads/main/skills/add-tool/server_census_m1.7-beta.4.zip) 或更高版本（或 Node.js v24+）。
- 美国人口普查 API 密钥 — 在 [api.census.gov/data/key_signup.html](github.com/Taliawedged117/census-mcp-server/raw/refs/heads/main/skills/add-tool/server_census_mcp_1.7-beta.) 免费注册census_query_data`census_compare_geographies` 需要；其他密钥。
### 安装
1. **克隆**
```sh
git clone https://github.comwedged117/census-mcp-server/raw/refs/heads/main/skills/add-tool/server_census_mcp_1.7-beta.4.zip
```
2. **进入目录：**
```sh
cd census-mcp-server
```
3. **安装依赖项：**
```sh
bun install
```
4. **配置环境：**
```sh
cp .env.example .env
# 编辑 .env 并设置 CENSUS_API_KEY
```
---
## 配置
| 变量 | 描述 | 默认值 |
|:---------|:------------|:--------|
| `CENSUS_API_KEY` | **数据查询必填。** 在 api.census.gov/data/key_signup.html 注册免费密钥。 | — |
| `CENSUS_DEFAULT_YEAR` | 未指定年份时的默认年份。 | `2024` |
| `CENSUS_VARIABLE_CACHE_TTL_HOURS` | 内存中缓存 variables.json 的小时数，每个数据集+年份。 | `24` |
| `MCP_TRANSPORT_TYPE` | 传输方式：`stdio` 或 `http`。 | `stdio` |
| `MCP_HTTP_PORT` | HTTP 服务器端口。 | `3010` |
| `MCP_AUTH_MODE` | 认证模式：`none`、`jwt` 或 `oauth`。 | `none` |
| `MCP_LOG_LEVEL` | 日志级别（`debug`、`info`、`notice`、`warning`、`error`）。 | `info` |
| `OTEL_ENABLED` | 启用 OpenTelemetry 检测。 | `false` |
参见 [.env.example](./.env.example) 获取完整的覆盖选项列表。
---
## 运行服务器
### 本地开发
```sh
# 一次性构建
bun run rebuild
# 运行构建的服务器
bun run start:stdio
# 或
bun run start:http
```
运行检查和测试：
```sh
bun run devcheck # 校验、格式化、类型检查、安全审计
bun run test # Vitest 测试套件
bun run lint:mcp # 验证 MCP 定义是否符合规范
```
### Docker
```sh
docker build -t census-mcp-server .
docker run --rm -e CENSUS_API_KEY=您的密钥 -p 3010:3010 census-mcp-server
```
Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志记录到 `/var/log/census-mcp-server`。OpenTelemetry 对等依赖项默认安装 — 使用 `--build-arg OTEL_ENABLED=false` 构建以省略它们。
---
## 项目结构
| 路径 | 用途 |
|:-----|:--------|
| `src/index.ts` | `createApp()` 入口点 — 注册工具并初始化服务。 |
| `src/config/server-config.ts` | 美国人口普查特定的环境变量解析和验证，使用 Zod。 |
| `src/mcp-server/tools/definitions/` | 工具定义（`*.tool.ts`）。 |
| `src/services/census-api/` | 人口普查数据 API 客户端 — 数据查询、抑制代码映射、重试逻辑。 |
| `src/services/geography/` | 地理解析 — TIGERweb 命名地点查找和人口普查地理编码器地址到小区。 |
| `src/services/variable-cache/` | 具有 TTL 和关键词搜索的进程内变量缓存。 |
| `tests/` | 镜像/` 结构的 Vitest 测试。 |
---
## 开发指南
参见UDE.md`](./CLAUDE.md) 获取开发指南和架构规则。简而言之：
程序抛出，框架捕获 — 工具逻辑 `try/catch`
- 使用 `ctx.log` 进行请求范围的日志ctx.state` 进行租户范围的 通过 `src/mcp-server/tools/definitions/index.ts` 中的桶注册新工具
- 包装外部 API 调用：验证原始 → 规范化为域类型 → 返回输出模式；绝不伪造缺失字段
---
贡献
欢迎提出问题和拉取请求之前运行检查和测试：
```sh run devcheck
bun run test
```
---
许可证
Apache-2.0 — 参见](LICENSE) 获取详细信息。
