内容
# MassGIS MCP 服务器
本仓库包含一个模型上下文协议（MCP）服务器，使 AI 助手能够与马萨诸塞州的 statewide 数据层（MassGIS）交互，以回答复杂的空间查询。服务器使用 MCP 框架（由 Anthropic 创建）构建，并提供一套全面的工具，用于搜索、查询和分析与马萨诸塞州环境评估和规划相关的地理空间数据。
## 概述
模型上下文协议（MCP）是一种开放协议，使 AI 助手与外部数据源或工具之间实现无缝集成。本实现，即 `massgis_mcp.py`，创建一个 MCP 服务器，暴露一套与 MassGIS 网络要素服务（WFS）交互的工具。
服务器允许 AI 助手（如 Claude）执行以下任务：
- 根据关键词搜索可用的数据层
- 检查特定层的 数据架构 以了解其属性
- 使用 ECQL（扩展通用查询语言）执行复杂的空间查询
- 在特定的市镇边界内查找要素
- 生成交互式地图链接，在 MassMapper 中可视化结果
- 使用 "笔记本" 系统存储、管理 和导出查询的大型结果集
MCP 服务器旨在实现交互式地理空间分析，用户可以通过 AI 助手将命令链接在一起。例如，用户可以先搜索 "公园" 层，然后检查所选层的架构，最后执行空间查询以查找特定城镇内的所有公园。
## 快速入门
快速开始：下载 massgis-mcp-*.dxt 版本，安装为 Claude Desktop 或 Cursor 扩展程序，并开始向 Claude 提出地理空间问题。不需要 Python 或手动配置。开发人员仍然可以克隆仓库并直接运行 python server/massgis_mcp.py 进行开发。
### 安装（终端用户）
#### 1 下载扩展程序
从 Releases 页面获取最新的 **massgis-mcp-1.1.0.dxt**。
#### 2 安装
* **Claude Desktop：** *设置 → 扩展程序 → “添加本地扩展程序”* 并选择文件
* **Cursor：** 请参见下面的 Cursor 安装说明
无需其他设置；首次运行时会自动创建内部虚拟环境。
### 安装（开发人员 / 高级）
您仍然可以克隆仓库并使用虚拟环境进行开发，或者解压 .dxt（它只是一个 zip）并在本地编辑：
```bash
dxt unpack massgis-mcp-1.1.0.dxt ./working_copy
cd working_copy && uv venv && uv pip install -e .
```
或使用原始的克隆 / venv / pip install -r requirements.txt 说明。
### 导出位置
- 导出（CSV / JSON）写入扩展程序文件夹内的 `exports/`。在 Windows 上，默认位置是：
`C:\Users\<you>\AppData\Roaming\Claude\Claude Extensions\local.dxt.your-name.massgis-mcp\exports\`
## 可用工具
MCP 服务器通过模型上下文协议公开以下工具：
| 工具 | 描述 |
|------|-------------|
| `search_layers` | 使用关键词和可选类别搜索 MassGIS 数据层 |
| `list_categories` | 列出所有可用的数据类别，以帮助缩小搜索范围 |
| `get_layer_details` | 检索特定数据层的详细元数据和摘要 |
| `describe_layer_schema` | **关键**: 显示层的属性的精确列名和数据类型。对于构建正确的查询至关重要 |
| `query_spatial` | 使用 ECQL 过滤器执行复杂的空间查询（例如，INTERSECTS，DWITHIN）的主要工具 |
| `intersect_with_town` | 一个简化的工具，用于查找位于特定马萨诸塞州城镇内的层的要素 |
| `find_nearby` | 一个备用工具，用于在给定半径内查找特定纬度/经度点的要素 |
| `massmapper_link` | **可视化**: 生成 MassMapper URL，以创建交互式地图，显示分析和要素 |
| `notepad_write` | 将文本或数据（如查询结果）追加到内部笔记本 |
| `notepad_read` | 显示笔记本的内容 |
| `notepad_clear` | 清除笔记本中的所有条目 |
| `notepad_export` | 将收集的笔记本条目导出到文件中（例如 CSV 或 JSON） |
## 处理大数据集：笔记本工作流
此 MCP 服务器的一个关键功能是其处理返回数百或数千个结果的查询的能力 - 远远超过 AI 助手上下文窗口所能容纳的范围。"笔记本" 系统专门为此目的而设计。以下是如何有效地处理大数据集。
AI 助手只能看到大型查询结果的小样本。**不能** 在服务器笔记本中搜索或遍历存储的完整数据集。`notepad_export` 函数是此限制的桥梁。
### 推荐工作流
1. **执行广泛查询并保存到笔记本**: 执行预期返回许多结果的查询时，设置 `use_notepad=True`。这会将完整的查询结果集保存在服务器上。
```python
# 查找所有距离任何通勤铁路站 500m 内的自行车道
query_spatial(
layer_name="GISDATA.BIKETRAILS_ARC",
cql="DWITHIN(shape, collectGeometries(queryCollection('GISDATA.MBTA_NODE', 'shape', \"LINE='COMMUTER RAIL'\")), 500, meters)",
use_notepad=True
)
```
助手只会看到几个样本结果，但所有结果现在都存储在服务器端。
2. **导出完整数据集**: 使用 `notepad_export` 工具将整个存储的结果集写入 CSV 文件。
```python
notepad_export(format="csv", filename_prefix="bike_trails_near_stations")
```
这会在项目文件夹内的 `exports/` 目录中创建一个文件。
3. **外部分析数据**: 作为用户，您现在拥有完整的数据集。打开导出的 CSV 文件，在 Excel、Google Sheets 或 GIS 应用程序等工具中打开。在这里，您可以排序、筛选和分析数据以识别特定的感兴趣的要素。
4. **提出有针对性的后续问题**: 一旦您确定了特定的项目（例如，特定的地块 ID、轨迹名称），您可以向 AI 助手询问更多关于它们的信息。
> "我在导出的 CSV 中看到一个名为 'Minuteman Bikeway' 的轨迹。可以显示我 250 米范围内的学校吗？"
5. **助手执行新的有针对性的查询**: 助手现在将根据您的特定请求执行**全新**查询。它不是搜索笔记本；它正在使用新的精确信息查询实时数据源。
此工作流利用了两个系统的优势：MCP 服务器的大批量数据提取和精确查询能力，以及您使用熟悉的工具分析大数据的能力。
## 示例用法
以下是用户如何使用此 MCP 服务器通过 AI 助手与 MassGIS 数据交互的示例：
### 示例 1：查找 "CAMBRIDGE" 镇的所有公共图书馆
1. 搜索相关层：
```python
search_layers(query="libraries")
```
2. 搜索结果显示一个包含图书馆位置的层。现在，查找剑桥的图书馆：
```python
intersect_with_town(layer_name="GISDATA.LIBRARIES_PT", municipality="CAMBRIDGE")
```
3. 可视化结果：
```python
massmapper_link(municipalities=["CAMBRIDGE"], specific_layers=["GISDATA.LIBRARIES_PT"])
```
### 示例 2：查找 "LEXINGTON" 中所有距离学校 1 公里内的保护区
1. 首先，搜索保护区层：
```python
search_layers(query="conservation open space")
```
找到 `GISDATA.OPENSPACE_POLY` 层。
2. 接下来，搜索学校：
```python
search_layers(query='schools')
```
找到 `GISDATA.SCHOOLS_PT` 层。
3. 对两个层运行 `describe_layer_schema` 以获取几何列名。
4. 查找 Lexington 中任何学校 1 公里范围内的保护区：
```python
query_spatial(
layer_name="GISDATA.OPENSPACE_POLY",
cql="DWITHIN(shape, collectGeometries(queryCollection('GISDATA.SCHOOLS_PT', 'shape', \"town='LEXINGTON'\")), 1000, meters)"
)
```
5. 可视化结果：
```python
massmapper_link(
municipalities=["LEXINGTON"],
specific_layers=["GISDATA.OPENSPACE_POLY", "GISDATA.SCHOOLS_PT"]
)
```
### 示例 3：查找距离通勤铁路站近的自行车道
1. 搜索自行车道层：
```python
search_layers(query="bike trails")
```
2. 搜索通勤铁路站：
```python
search_layers(query="commuter rail mbta")
```
3. 查找所有距离通勤铁路站 500 米范围内的自行车道：
```python
query_spatial(
layer_name="GISDATA.BIKETRAILS_ARC",
cql="DWITHIN(shape, collectGeometries(queryCollection('GISDATA.MBTA_NODE', 'shape', \"LINE='COMMUTER RAIL'\")), 500, meters)",
use_notepad=True
)
```
4. 导出结果进行进一步分析：
```python
notepad_export(format="csv", filename_prefix="bike_trails_near_stations")
```
## 与 AI 助手集成
此 MCP 服务器设计用于与支持模型上下文协议的 AI 助手配合使用。连接后，AI 助手能够对马萨诸塞州数据执行复杂的地理空间分析，使其成为城市规划师、研究人员、教育工作者和任何有兴趣探索马萨诸塞州地理数据的用户们的强大工具。
模型上下文协议确保 AI 助手可以发现可用的工具，了解其参数，并有效地使用它们来回答关于马萨诸塞州地理、基础设施、休闲区和社区资源的复杂空间问题。
- 安装完成后，助手会自动检测扩展程序及其工具、提示和资源 - 无需手动配置。
## 在 Cursor 中安装
Cursor 使用相同的 MCP 服务器，但需要本地 **CLI** 而不是 `.dxt`。
1. **克隆** 此仓库并创建 Python 虚拟环境：
```bash
git clone https://github.com/mmulqu/MassMapper-MCP.git
cd MassMapper-MCP
python -m venv .venv # Windows: python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
2. **创建 `mcp.json`**
将文件放在 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（在项目内）：
```jsonc
{
"mcpServers": {
"massgis-mcp": {
"command": "/absolute/path/to/.venv/bin/python",
"args": [
"/absolute/path/to/MassMapper-MCP/server/massgis_mcp.py"
],
"transport": "stdio"
}
}
}
```
3. **重启 Cursor** → 设置 → *模型上下文协议* → 启用 **massgis-mcp**。
4. **使用工具** 如示例所示（`search_layers`, `query_spatial` 等）。
