内容
# 纽约市公开数据资本项目 MCP 服务器
纽约市资本项目仪表盘（CPD）数据集上的本地 [MCP](https://modelcontextprotocol.io) 服务器，位于 [纽约市公开数据](https://opendata.cityofnewyork.us/) 平台上。
它将四个公共 Socrata 数据集摄入到一个本地 DuckDB 中，并公开 **16 个工具**，使 AI 助手能够回答有关纽约市资本项目的进度、预算和生命周期的问题，同时将领域规则（PID↔FMS 多对多、角色感知机构归属、带符号的差异报告）融入工具中，而不需调用者重新发现。
## 源数据集（Socrata）
| ID | 数据集 |
|----|---------|
| `fb86-vt7u` | 全市资本项目详情列表（进度↔预算关联） |
| `gyhf-rsr3` | 全市预算和支出（按财政年度） |
| `qj5n-h5qp` | 全市预算支出历史和差异 |
| `95tx-snak` | 全市进度历史和差异 |
## 什么是 MCP — 为什么使用它？
**MCP（模型上下文协议）** 是一种标准方法，为 AI 助手提供新的、值得信赖的技能。 与其将电子表格粘贴到聊天中，希望模型能正确读取，不如交给它一组预定义的工具来调用，这些工具已经内置了领域规则。 这就像告诉分析师 *"这里有一个电子表格，祝你好运"* 和雇用一个已经 **完全了解数据** 的分析师之间的区别。
**为什么不直接使用 ChatGPT + CSV？** 公开数据在通用聊天机器人无法察觉的方式下是凌乱的。 询问原始 LLM *"纽约市最大的图书馆项目是什么？"* 它会高兴地重复计算一个多个项目共享的预算项目， 将一个已经完成的分支称为 *"仍在建设中"* 因为其资金项目仍然开放， 或者 - 只看到一年中的三个报告期（1 月 / 5 月 / 9 月） - 假设几个月的数据已经丢失。 它听起来很有信心 - 但却是错误的。 这个服务器编码了防护措施一次 - **PID↔FMS 多对多**，**角色感知机构归属**，**每 3 次报告周期**，**带符号的报告** - 因此每个答案都是一致的， 有来源的， 可复制的。
## 单个提示可以构建什么
这不仅仅是一个查询工具。 将 AI 代理指向它，**单个提示生成一个精致的、自成体系的交互式 HTML 报告** - 已经应用了领域规则。 三个真实示例（一个提示 → 一个文件；点击打开实时报告）：
**1 · 进度 ↔ 预算拓扑** — *投资组合的多对多解剖结构*
> 分析纽约市资本项目的进度和预算多对多关系，并生成一个单独的交互式 HTML 报告 - 1:1 与扇出分裂，异常极端，机构分解和预算集中度。
▶ **[打开报告](https://willhsiaonyc.github.io/NYC-Opendata-Capital-Projects-MCP/examples/pid_fms_budget_analysis.html)** — 扇出环，双部分图，“纠缠的少数”异常值（悬停以查看真实的进度和预算线），机构散点图和预算集中度曲线。
**2 · 5000 万美元以上的公园项目** — *每个大项目及其资金*
> 为纽约市公园项目生成一个交互式的单文件 HTML 报告，项目预算超过 5000 万美元。对于每个预算线，显示与其关联的所有进度，包括阶段和预测完成情况。
▶ **[打开报告](https://willhsiaonyc.github.io/NYC-Opendata-Capital-Projects-MCP/examples/parks_over_50m.html)** — 23 个预算线；悬停任意线以显示其链接的进度。 静默应用类别分类法，因此 1.9B 美元的“公园人行桥”路线连接到桥梁，而不是公园。
**3 · 预算和进度变更监视器** — *本期变更情况，按机构*
> 为纽约市资本项目的预算和进度变更生成一个交互式的单文件 HTML 监视器，按管理机构分类，具有每个项目进度和预算历史的点击详细视图。
▶ **[打开报告](https://willhsiaonyc.github.io/NYC-Opendata-Capital-Projects-MCP/examples/cpd_budget_schedule_change_monitor.html)** — 关键绩效指标，趋势图，可排序的观察列表，以及每个项目的弹出窗口，带有进度差异条和堆积预算与支出图表。
> 每个报告都是从所示提示生成的，然后轻轻润色。 图表是 202601 报告期的快照 - 在 [报告画廊](https://willhsiaonyc.github.io/NYC-Opendata-Capital-Projects-MCP/) 中浏览所有三个。
## 🚀 快速开始
如果您的 AI 可以在计算机上运行命令，只需让它为您安装所有内容。
### ✅ 让您的 AI 安装它（最简单）
适用于可以运行终端命令的 AI **代理** - **Claude Code**，**Claude cowork**（Claude Desktop 的本地代理模式），**Codex CLI**，或其他类似 Cursor 的编码代理。
1. 在这台计算机上启动您的 AI 代理。
2. 粘贴下面的消息。
3. 在克隆、安装和连接服务器时，批准每个步骤（**允许** 或按 **y**）。
**要粘贴的消息：**
```
在 https://github.com/WillHsiaoNYC/NYC-Opendata-Capital-Projects-MCP 上安装 MCP 服务器
到这台机器 - 按照其 README 克隆存储库，使用 uv 安装它，运行
`od-cpd init` 将纽约市公开数据的四个数据集下载到本地数据库中，
并将其连接到我的 MCP 客户端配置中。 然后运行一个验证查询以确认其有效。
```
**完成的样子：** 您的 AI 报告加载的报告期（例如
`202601`），确认 `od-cpd` 已与 **16 个工具** 连接，并回答测试问题，例如 *"当前最大的纽约市资本项目是什么？"* 需要几分钟，大部分是数据集下载。
### 🖥️ Claude Desktop（聊天）
Claude Desktop 可以 **使用** 本地服务器但无法自行安装。 运行 [手动安装](#手动安装)，然后将 `od-cpd` 添加到 **其自己的** 配置中（使用 `uv` 的绝对路径）并完全重启 - 请参见
[连接 MCP 客户端](#连接-mcp-客户端)。
### ☁️ claude.ai 或 ChatGPT（网页）
这些仅连接到 **远程** MCP 服务器，而不像这样的本地服务器 - 因此它们无法直接运行 `od-cpd`。 使用上述选项之一。
## 手动安装
需要 [Python ≥ 3.12](https://www.python.org/) 和
[uv](https://docs.astral.sh/uv/)。
```bash
git clone https://github.com/WillHsiaoNYC/NYC-Opendata-Capital-Projects-MCP.git
cd NYC-Opendata-Capital-Projects-MCP
uv sync
uv run od-cpd init # 下载 + 物化所有 4 个数据集 → ./var/cpd.duckdb
uv run od-cpd status # 确认加载的报告期
```
可选： 将 `OD_CPD_SOCRATA_APP_TOKEN` 设置为免费的
[Socrata 应用程序令牌](https://dev.socrata.com/docs/app-tokens)，以避免摄入期间的匿名速率限制。
### 连接 MCP 客户端
服务器使用标准输入输出。 使用 **uv 的绝对路径** （运行 `which uv` 查找）- GUI 应用程序（如 Claude Desktop）不会继承您的 shell `PATH`，因此裸 `uv` 命令会静默失败。
**Claude Code** - 在存储库文件夹内：
```bash
claude mcp add od-cpd --env PYTHONPATH="$(pwd)/src" -- \
"$(which uv)" run --directory "$(pwd)" od-cpd-server
```
**Claude Desktop** - 编辑其配置（macOS：
`~/Library/Application Support/Claude/claude_desktop_config.json`），添加以下块，然后 **完全退出（⌘Q）并重新打开** Claude Desktop：
```json
{
"mcpServers": {
"od-cpd": {
"command": "/absolute/path/to/uv",
"args": ["run", "--directory", "/absolute/path/to/repo", "od-cpd-server"],
"env": { "PYTHONPATH": "/absolute/path/to/repo/src" }
}
}
}
```
（`PYTHONPATH` 在 uv 的可编辑安装不可靠时保持启动的稳健性 - 例如
在 iCloud 同步路径上。）
### 保持数据新鲜
源数据集以 **1 月 / 5 月 / 9 月** 周期报告，Socrata 通常在 **~2.5–3 个月后** 发布每个周期（因此新数据通常在 **4 月，8 月和 12 月** 左右上线）。 `od-cpd update` 在没有更新时为无操作，因此可以随时运行 - 在那些月份周围检查：
```bash
uv run od-cpd status # 当前加载的报告期
uv run od-cpd update # 仅在 Socrata 更新时重新摄入
```
要自动保持更新，请安排 `update` （例如，通过 cron 每月）：
```cron
# 每月 1 日 9 点
0 9 1 * * cd /path/to/repo && uv run od-cpd update
```
## 内部
- **`docs/FEATURES.md`** - 规范清单：所有 16 个工具和服务器编码的每个领域规则。 从这里开始。
主要领域规则，简要：
- **“项目”是不明确的。** PID 标识一个 *进度* ； FMS ID 标识一个 *预算线*。 它们是多对多的（~3% 扇出），因此工具列出所有对应项而不是静默选择一个。
- **机构归属是角色感知的。** “机构 X 的项目”对于普通机构意味着赞助商（所有者）视图，但对于三个施工经理机构（DDC/DCAS/EDC）意味着管理（建设者）视图。
- **值被报告为带符号和中立的** （“延迟 45 天”，“预算增加 210 万美元”）而不是仅显示一个方向。
## 布局
- `src/od_cpd/` - 摄入，物化和 MCP 服务器 + 工具
- `data/` - 整理的机构/类别字典（YAML，跟踪）
- `tests/` - 单元测试 + 黄金评估（`uv run pytest`）
- `var/`，`exports/` - 运行时 DuckDB + 导出（gitignored，可再生）
## 开发
```bash
uv run pytest # 备用：PYTHONPATH=src python -m pytest
```
分类由字典驱动：编辑 `data/agencies.yaml` /
`data/categories.yaml` （非 Python）以调整机构或类别映射，然后重新物化。 参见 `CLAUDE.md` 以获取将物化更改应用于不重新下载的原子交换模式。
## 数据注意事项
本项目为独立项目，与纽约市无关。 数据反映底层 Socrata 数据集在摄入时携带的报告期； 始终检查 `dataset_info` 以获取当前报告期和每个数据集的注意事项。
