内容
# 本地城市MCP
`local-{city}-mcp` 家族的家园：规格、已构建的城市列表以及用于构建新城市的模板仓库——所有这些都集中在一个地方。
`local-{city}-mcp` 是一个MCP服务器，为AI助手提供对官方、公开、无需密钥的单个大都市地区数据的纯英文访问——财产记录、许可证、市民数据、学校、环境、公共安全以及（在维护者拥有权限的情况下）房地产列表。
**在您触及任何代码之前，请阅读 [STANDARD.md](STANDARD.md)**。这是规格：硬性规则、工具合约、测试标准和许可模式。这里的其他内容只告诉您如何机械地使用模板；而STANDARD.md告诉您为什么要这样构建。
参考实现：[local-austin-mcp](https://github.com/mindwear-capitian/local-austin-mcp)（43个工具，生产环境中运行）。
## 列表
| 城市 | 仓库 | 工具 | 维护者 | CI |
|---|---|---|---|---|
| 奥斯汀, TX | [local-austin-mcp](https://github.com/mindwear-capitian/local-austin-mcp) | 43 | [Ed Neuhaus](https://neuhausre.com) | [](https://github.com/mindwear-capitian/local-austin-mcp/actions/workflows/ci.yml) |
| 达拉斯, TX | [local-dallas-mcp](https://github.com/mindwear-capitian/local-dallas-mcp) | 3 | [Ed Neuhaus](https://edneuhaus.com) | [](https://github.com/mindwear-capitian/local-dallas-mcp/actions/workflows/ci.yml) |
| 休斯顿, TX | [local-houston-mcp](https://github.com/mindwear-capitian/local-houston-mcp) | 2 | [Ed Neuhaus](https://edneuhaus.com) | [](https://github.com/mindwear-capitian/local-houston-mcp/actions/workflows/ci.yml) |
| 圣安东尼奥, TX | [local-san-antonio-mcp](https://github.com/mindwear-capitian/local-san-antonio-mcp) | 3 | [Ed Neuhaus](https://edneuhaus.com) | [](https://github.com/mindwear-capitian/local-san-antonio-mcp/actions/workflows/ci.yml) |
*（您的城市尚未在此？请在下面构建一个，然后打开一个PR添加一行。）*
### 使用
将以下内容添加到您的Claude Desktop配置（或任何MCP客户端的配置）：
```jsonc
{
"mcpServers": {
"local-austin": {
"command": "npx",
"args": ["-y", "github:mindwear-capitian/local-austin-mcp"]
}
}
}
```
替换为上表中的任意城市仓库。
## 构建新城市
1. **使用此模板** — GitHub的“使用此模板”按钮，或：
```bash
gh repo create local-{city}-mcp --template mindwear-capitian/local-city-mcp-template
```
> 这会复制此仓库中的所有内容，包括此README的列表表格。用您自己的城市README替换此README（参见步骤5）——上面的表格是此仓库的索引，而不是您城市的文档。
2. **替换所有占位符。** 每个需要每城市值的每个文件都使用裸`{{TOKEN}}`标记（无前导 `$` — 刻意为之，以免与 `.github/workflows/ci.yml` 中的 `${{ }}` GitHub Actions表达式语法冲突，您应保持不变）。使用以下命令查找它们：
```bash
grep -rl '{{[A-Z_]*}}' --include='*.js' --include='*.json' --include='*.md' .
```
| Token | 示例 | 用途 |
|---|---|---|
| `{{CITY}}` | `Denver` | 显示名称，用于正文 |
| `{{CITY_SLUG}}` | `denver` | 工具前缀，包名，仓库名 |
| `{{CITY_SLUG_UPPER}}` | `DENVER` | 环境变量名 (`LOCAL_DENVER_MCP_TIER`) |
| `{{MAINTAINER_NAME}}` | `Jane Doe` | 属性，package.json作者 |
| `{{MAINTAINER_URL}}` | `https://janedoe.com` | 属性，首页 |
| `{{GITHUB_USER}}` | `janedoe` | 仓库URL |
| `{{DEFAULT_LAT}}` / `{{DEFAULT_LNG}}` | `39.74`, `-104.99` | 示例NWS工具的默认地图中心 |
单次sed传递对于第一次传递来说效果很好 — 只需在提交之前检查差异，因为几个标记（如句子中的`{{CITY}}`）故意区分大小写。
3. **运行：**
```bash
npm install
npm start # 运行MCP到stdio
npm test # 单元测试
npm run test:contract # 启动服务器，通过真正的MCP层调用每个工具
```
4. **构建您的第一个真正工具。** 参见CONTRIBUTING.md — 复制 `tools/environment/nws-alerts.js` （适用于任何美国城市，无需修改即可使用）作为您的模式参考，或 `tools/meta/about.js` 作为最小形状。
5. **当它真正运行时：** 用您自己的城市README替换此README（工具表，“真实来源”表，架构部分 — 参见 [local-austin-mcp的README](https://github.com/mindwear-capitian/local-austin-mcp#readme) 了解您拥有超过两个工具时的形状）。
6. **获取列表：** 当 `test:contract` 在CI中变为绿色且您满足STANDARD.md §2时，对 **此仓库** 打开一个PR，在上表添加一行。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 已经为您构建的内容
| 文件 | 为每个工具提供的内容 |
|---|---|
| `lib/register.js` | 中央注册：默认MCP注释，错误→友好框架包装，`structuredContent` 自动提升，层级控制 |
| `lib/retry.js` | `retryFetch()`，带有抖动回退 + `UpstreamError` + LLM友好错误文本（“MCP正常，上游有问题”） |
| `lib/request-context.js` | 将MCP请求的 `AbortSignal` 传播到下游的每个 `fetch`，通过 `AsyncLocalStorage`，以便客户端取消实际上会取消进行中的调用 |
| `lib/output-schemas.js` | 共享Zod形状（`searchShape`，`openObjectShape`等）用于 `outputSchema` |
| `lib/geocode.js` | 美国人口普查地理编码器 — 免费，无需密钥，全国范围内有效 |
| `lib/soda.js` | 通用Socrata（SODA）开放数据客户端 — 适用于任何城市或州的Socrata门户，而不仅仅是您自己的（已验证：同一个客户端，零更改，为Austin提供许可/311/犯罪数据，为TX TEA提供全州数据集，为Dallas提供311） |
| `lib/arcgis.js` | 通用ArcGIS FeatureServer/MapServer客户端 — 许多城市在不在Socrata上时都会以这种方式发布311，GIS和属性层（已验证：为Austin提供县评估 + FEMA洪水工具，为San Antonio提供311） |
| `lib/semaphore.js` | 命名每个源的并发上限（`withLimit`），以便工具组合不会轰炸上游 |
| `lib/logger.js` | stderr + MCP日志通知记录器 |
| `lib/tiers.js` | 可选的`core`/`all`工具层级控制，当您拥有20+工具时 |
| `tools/meta/about.js` | 最小工具示例 + 必需的`about`功能工具 |
| `tools/environment/nws-alerts.js` | 真实的示例工具（国家气象服务警报） — 复制其形状 |
| `test/mcp-all-tools.js` | 必需的契约测试（STANDARD.md §6） |
| `.github/workflows/ci.yml` | 每次推送时在Node 20 + 22上运行单元测试。跳过清理（不是失败）当针对原始的，未填充的模板运行时。 |
| `.github/workflows/contract.yml` | 实时上游契约测试，按每日计划 + 手动调度 — 故意不在每次推送时运行（会使PR在第三方正常运行中变得脆弱）。 |
所有这些都不是推测性的 — 它是从一个已经交付40+工具的生产服务器中复制的。阅读 `lib/register.js` 和 `lib/retry.js` 文件顶部的注释，如果您想知道某个部分存在的原因。
## 许可证
模板代码（`lib/`，`tools/`，`index.js`，测试，CI）是Apache License 2.0（参见 [LICENSE](LICENSE)）— 使用它，fork它，在其上构建商业产品。填写 `NOTICE` 和 `TRADEMARK.md`，然后再发布；这些文件中的占位符是示例，而不是您继承的默认值。本README的列表管理文本不单独获得许可 — 它不是代码，您可以随心所欲地处理它。
