内容
# arcgis-mcp - 服务器MCP与ArcGIS Pro插件
`arcgis-mcp` 将 ArcGIS Pro 3.7 与支持模型上下文协议（MCP）的客户端集成。该项目将 ArcGIS Pro 的 C# 插件与 FastMCP Python 服务器相结合，通过本地 Windows 命名管道公开 ArcGIS Pro 操作作为 MCP 工具。
MCP 包括 65 个 MCP 工具、54 个插件命令、2 个 MCP 资源和 2 个提示模板。
## 描述
- **ArcGIS Pro 插件**：由 ArcGIS Pro 加载的 C# 扩展程序。在 ArcGIS Pro 进程内执行对 ArcGIS Pro SDK 的调用，并通过 `\\.\pipe\ArcGisMcpBridge` 公开命令。
- **Python MCP 服务器**：FastMCP 服务器，注册公共工具、资源和提示。通过本地命名管道客户端与插件通信。
- **IPC 层**：通过命名管道进行本地传输，消息为 JSON 格式，并附有长度、结构化响应、超时、重试和显式错误元数据。
- **验证套件**：Python 测试、代码检查、格式化、插件编译、Git 空格检查和生成的工件扫描。
服务器公开项目、地图、图层、选择、符号、布局、地理数据库、门户元数据、要素服务和地理处理等操作。
## 要求
- Windows。
- ArcGIS Pro 3.7。
- 已安装 ArcGIS Pro .NET SDK 及本地 SDK 程序集。
- .NET 10 SDK。
- Python 3.10 或更高版本。
- `python-server/requirements.txt` 中的 Python 包。
- `python-server/requirements-dev.txt` 中的开发包，用于测试和发布验证。
## 仓库结构
```text
arcgis-mcp/
+- arcgis-addin/
| +- ArcGisMcpAddin.sln
| +- ArcGisMcpAddin/
| +- Config.daml
| +- Module1.cs
| +- PipeServer.cs
| +- CommandHandler.cs
| +- Commands/
| +- Images/
+- python-server/
| +- arcgis_mcp_server.py
| +- pipe_client.py
| +- test_connection.py
| +- tools/
| +- resources/
| +- prompts/
| +- tests/
| +- requirements.txt
| +- requirements-dev.txt
+- docs/
| +- setup-guide.md
| +- release-checklist.md
+- scripts/
| +- validate_release.ps1
+- install_addin.ps1
+- README.md
+- CONTRIBUTING.md
+- SECURITY.md
```
## ArcGIS Pro 插件
插件在 ArcGIS Pro 加载模块时启动本地管道服务器。命令在 ArcGIS Pro 内执行，可以访问活动项目、活动地图、图层、布局、地理数据库、门户状态和地理处理 API。
插件的主要文件：
- `arcgis-addin/ArcGisMcpAddin/Module1.cs`：启动和停止管道服务器。
- `arcgis-addin/ArcGisMcpAddin/PipeServer.cs`：管理本地连接和消息框架。
- `arcgis-addin/ArcGisMcpAddin/CommandHandler.cs`：将 JSON 命令路由到实现模块。
- `arcgis-addin/ArcGisMcpAddin/Commands/`：包含项目、地图、数据、布局、符号、编辑、地理数据库、门户和地理处理等命令组。
- `arcgis-addin/ArcGisMcpAddin/Commands/CoreCommands.cs`：报告插件版本、MCP 版本、命令名称和工具能力。
插件的内部命令包括 `health_check`、`get_capabilities`、`list_maps`、`list_layers`、`save_project`、`publish_web_layer`、`stage_service_definition`、`create_map_series` 和 `ping`。`ping` 命令是内部 IPC 基础设施，不作为公共 MCP 工具公开。
## Python MCP 服务器
Python 服务器注册公共 MCP 接口，并在需要调用 ArcGIS Pro SDK 时将操作委托给插件。
服务器的主要文件：
- `python-server/arcgis_mcp_server.py`：FastMCP 入口点和公共工具、资源、提示的注册。
- `python-server/pipe_client.py`：Windows 命名管道客户端。
- `python-server/tools/`：按功能区域分组的 MCP 工具包装器。
- `python-server/resources/`：具有 ArcPy 和 Add-Ins SDK 引用的 MCP 资源。
- `python-server/prompts/`：用于 ArcPy 和 Add-In 开发的 MCP 模板。
- `python-server/tests/test_operational_contracts.py`：用于工具计数、插件命令覆盖率、发布门控、公共文档和存储库卫生的合同测试。
公共 MCP 工具包括 `spatial_join`、`query_layer`、`export_all_layouts`、`stage_service_definition`、`run_gp_tool`、`search_arcgis_docs`、`query_feature_service`、`publish_web_layer`、`create_basic_layout`、`export_active_map`、`apply_graduated_symbology`、`save_layer_file` 和 `describe_dataset`。
## MCP 配置
使用脚本路径在支持 MCP 的客户端上注册 Python 服务器：
```json
{
"mcpServers": {
"arcgis-mcp": {
"command": "python.exe",
"args": [
"C:/path/to/arcgis-mcp/python-server/arcgis_mcp_server.py"
]
}
}
}
```
如果 `python.exe` 不在 `PATH` 中，请使用首选 Python 可执行文件的绝对路径。
## 安装
从存储库根目录运行 PowerShell：
```powershell
cd C:\path\to\arcgis-mcp
.\install_addin.ps1
```
然后安装 Python 依赖项：
```powershell
cd C:\path\to\arcgis-mcp\python-server
python -m pip install -r requirements.txt
```
安装插件后，关闭并重新打开 ArcGIS Pro 以加载当前 DLL。
## 与 ArcGIS Pro 一起运行
1. 打开 ArcGIS Pro 3.7。
2. 打开或创建项目。
3. 确认“ArcGIS Pro MCP 服务器桥”出现在插件管理器中。
4. 打开地图视图。
5. 确认功能区中已启用“ArcGIS MCP”选项卡。
6. 运行连接测试：
```powershell
cd C:\path\to\arcgis-mcp\python-server
python test_connection.py
```
预期结果：
```text
SUCCESS: Connected to ArcGIS Pro MCP Bridge.
```
## 验证
从存储库根目录运行完整的发布验证：
```powershell
.\scripts\validate_release.ps1
```
发布脚本验证：
- 使用 Ruff 进行 Python 代码检查。
- 使用 Ruff 进行 Python 代码格式化。
- Pytest 和 unittest 测试套件。
- Python 字节码编译。
- 插件格式化。
- 插件编译。
- Git 空格。
- 生成的工件清理和扫描。
GitHub Actions 工作流执行可在本地不安装 ArcGIS Pro SDK 的情况下运行的 Python 端验证。
## 安全模型
插件通过本地命名管道接受命令，并在活动 ArcGIS Pro 会话内执行。 在相同的可信 Windows 用户上下文中运行 ArcGIS Pro 和 MCP 服务器。仅连接可信的 MCP 客户端，因为工具可以检查、编辑、导出、发布和对活动 ArcGIS Pro 项目可用的 GIS 数据进行地理处理。
有关操作指南和漏洞报告，请参阅 `SECURITY.md`。
## 许可
该项目根据 MIT 许可协议分发。有关完整文本，请参阅 `LICENSE`。
## 发布清单
发布前：
1. 运行 `.\scripts\validate_release.ps1`。
2. 确认 `README.md`、`docs/setup-guide.md` 和 `docs/release-checklist.md` 与当前工具合同一致。
3. 确认没有生成工件。
4. 确认不包含个人本地路径或私有项目数据。
5. 确认 `LICENSE` 包含 MIT 许可协议。
6. 配置 Git 作者元数据。
7. 配置 GitHub 远程仓库。
详细清单在 `docs/release-checklist.md` 中。
