Charlotte Open City Data

QueensEstate ♔⛫

一个 MCP 服务，可让大模型使用夏洛特市开放数据门户的官方公开数据，回答夏洛特居民的日常问题 — https://data.charlottenc.gov。

门户位于 data.charlottenc.gov。 这是一个 ArcGIS Hub 站点；其中约 380 个数据集是由夏洛特市和梅克伦堡县运行的 ArcGIS REST 图层。无需 API 密钥。

门户包含什么

对目录（/api/feed/dcat-us/1.1.json）的调查显示，主要主题如下：

主题	示例
公共安全	CMPD 事件（自 2017 年以来超过 87 万起，每日更新）、凶杀案、交通拦查、火灾事件报告、交通事故
城市服务	311 服务请求（340 万条）、固体废弃物收集路线、法规执法案件、道路封闭
规划与分区	分区、重新分区申请、历史街区、2040 年政策地图、洪泛区、地块
交通运输	CATS 公交路线和站点、LYNX 轻轨、停车换乘点、自行车道、人行道、绿道
地点	图书馆、学校、公园、消防／警察局、药店、杂货店、电动汽车充电桩、日托中心
政府	资本项目、预算、员工薪酬、市议会和委员选区
人口统计	人口普查街区组／普查区、生活质量社区概况

工具

这些工具针对居民实际会提出的问题而选定。所有工具均为只读，每个位置参数都接受地址（"600 E 4th St, Charlotte"）或 "latitude,longitude"。

我的地址

工具	可回答的问题示例
get_address_profile	“我的市议会代表是谁？”“负责我所在区域的警察分局和消防站是哪一个？”“我的分区是什么？我是否位于洪泛区或历史街区？”
get_trash_and_recycling_schedule	“哪天收垃圾？这周是回收周吗（GREEN/ORANGE）？”
lookup_address	“这是有效地址吗？它的地块 ID 和所属市镇是什么？”

安全

工具	可回答的问题示例
get_crime_near	“这个月我公寓附近有汽车盗窃案吗？”
summarize_crime	“自 2019 年以来，夏洛特的抢劫案有何变化？”“哪个分局的入室盗窃案最多？”
get_traffic_crashes_near	“我孩子学校附近的十字路口危险吗？”

城市服务与社区变化

工具	可回答的问题示例
get_311_requests_near	“有人已经报告过这个路面坑洞或路灯问题吗？”
get_code_enforcement_cases	“我租住的房子是否有尚未解决的住房法规违规问题？”
get_street_closures	“我通勤路上有道路封闭吗？”
get_capital_projects_near	“我附近在建设什么？何时完工？该联系谁？”
get_pending_rezonings	“有人打算重新规划我所在社区附近的土地吗？”

地点与公共交通

工具	可回答的问题示例
find_nearby_places	最近的图书馆、学校、公园、绿道、药店、杂货店、电动汽车充电桩、轻轨站、公交站、公共 Wi-Fi……（18 类）
get_bus_route	“9 路公交周日晚上多久一班？”

政府透明度

工具	可回答的问题示例
get_city_budget	“市政府为警察部门编列了多少预算？”
get_city_salary_stats	“夏洛特消防员的平均收入是多少？”（仅汇总数据，不含姓名）

目录中的其他内容

工具	用途
search_datasets	搜索整个门户中的关键词
describe_dataset	图层的字段、类型和记录数
query_dataset	从任意图层查询经 SQL 筛选的记录，可选择限定位置
summarize_dataset	在服务器端按字段分组统计数量／总和

设置

需要 Python 3.14（使用 Python 3.14.7 开发）。

~/.pyenv/versions/3.14.7/bin/python -m venv .venv
.venv/bin/python -m pip install -e . --group dev

与 Claude Code 配合使用

claude mcp add queensestate -- /absolute/path/to/queensestate/.venv/bin/queensestate

与 Claude Desktop 配合使用

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "queensestate": {
      "command": "/absolute/path/to/queensestate/.venv/bin/queensestate"
    }
  }
}

其他传输方式和调试

.venv/bin/queensestate --transport http --port 8000        # http://127.0.0.1:8000/mcp
npx @modelcontextprotocol/inspector .venv/bin/queensestate  # interactive inspector

http 传输方式使用 Google OAuth 对调用者进行身份验证，并且没有公开 URL、Google 客户端和允许列表时会拒绝启动——请参阅托管。要在本地试用：

QUEENSESTATE_PUBLIC_URL=http://localhost:8000 \
QUEENSESTATE_GOOGLE_CLIENT_ID=... QUEENSESTATE_GOOGLE_CLIENT_SECRET=... \
[email protected] \
  .venv/bin/queensestate --transport http --port 8000

托管

托管服务运行在 Google Cloud Run 上，地址为 https://queensestate.adamwanninger.com/mcp，它本身也是 OAuth 2.1 授权服务器：它仅委托 Google 完成登录，以确认调用者所用的账号，然后将该地址与允许列表核对，并签发自己的令牌。Google 的令牌绝不会传递给 MCP 客户端。

claude mcp add --transport http queensestate https://queensestate.adamwanninger.com/mcp

scripts/deploy-gcp.sh 会配置并部署整个服务，重新运行它也是更新服务的方式。请参阅 deploy/GCP.md。

托管仅适用于 HTTP 传输方式。在本地通过 stdio 运行服务无需 Google 账号、允许列表或任何云依赖项。

开发

.venv/bin/pytest                 # unit + in-memory MCP tests; no network access
.venv/bin/ruff format --check . && .venv/bin/ruff check .
.venv/bin/mypy

目录结构：

• src/queensestate/arcgis.py：异步 ArcGIS REST / Hub 客户端（超时、有限重试、主机允许列表）
• src/queensestate/address.py：将地址与县级 Master Address 图层进行匹配
• src/queensestate/catalog.py：专用工具使用的精选图层
• src/queensestate/server.py：MCP 工具

数据说明和限制

• 地理编码使用 Mecklenburg County 的 Master Address 图层，因此只能解析该县范围内的地址。县外坐标会被拒绝。
• 数据更新时效因数据集而异：CMPD 事件、311 请求和法规执法数据会在数日内更新；Budget Report 数据集目前涵盖 FY2018–FY2023。工具会报告门户发布的内容。
• CMPD 位置由部门进行模糊处理以保护隐私。
• 311 数据记录的是收到请求的时间，而不是请求解决的时间。
• 时间戳采用 ISO 8601 格式，以 Charlotte 当地时间表示，并包含 UTC 偏移量（例如 2026-09-06T00:00:00-04:00）。底层服务存储的是 UTC 时间。
• 预算金额包含大额负数项目（例如“00 Non Department”、Charlotte Water），因此 get_city_budget 会同时报告净总额和正数项目总和。
• 统计限制：部分城市地图服务会忽略汇总查询中的 resultRecordCount，因此客户端会自行限制行数。
• 实时公交到站信息不在门户上；请将此服务与 CATS 实时数据源配合使用。find_nearby_places 返回的公交站 ID 与 CATS 站点 ID 匹配。
• 通用工具只能访问提供门户数据集的主机（gis.charlottenc.gov、 meckgis.mecklenburgcountync.gov、services.arcgis.com、gis.ci.charlotte.nc.us）。
• Mecklenburg County 的服务器会拒绝 Python 默认用户代理，因此客户端会发送自定义用户代理。

更多工具的构想

• 按 NPA 划分的社区生活质量指标（收入、年龄、住房、便利设施）
• 按地址街区查询 Charlotte Fire 事故报告
• CMPD 警员交通拦截统计数据
• 地址附近的人行道和自行车网络缺口
• 按社区划分的树冠覆盖率和地表温度

许可证

MIT - 请参阅 LICENSE。