arcgis-mcp-bridge 是一个安全、本地优先的 MCP 服务器，通过 stdio JSON-RPC 将 ArcGIS Pro 的 ArcPy 引擎暴露给 Claude Desktop 和其他 MCP 主机。它要求 Windows 系统、已授权的 ArcGIS Pro 安装以及 Python 3.11 或更高版本。
用途
该项目旨在让 AI 助手（如 Claude）能够安全地调用 ArcGIS Pro 的地理处理能力，而无需手动操作 ArcGIS Pro 界面。它通过 MCP 协议将 ArcPy 引擎封装为可调用的工具，支持自然语言驱动的 GIS 工作流。
主要能力
- 100 个声明式地理处理工具：通过一个通用代理工厂在 Layer A 中生成所有目录 MCP 端点，并由 Layer B 中的通用 run_tool 调度器提供服务。目录与三个核心端点一起暴露：health_check、list_layers 和 execute_spatial_tool。
- 双进程隔离架构：Layer A 为异步事件驱动服务器（arcgis_mcp/server.py），基于 FastMCP，负责 stdio 通道、Pydantic v2 契约验证和异步调度，不包含任何模块级 arcpy 或 cv2 导入。Layer B 为子进程 ArcPy 隔离工作器（arcgis_mcp/worker.py），在授权的 ArcGIS Pro 解释器（ARCPY_PYTHON_PATH）中按任务生成，是唯一允许 import arcpy 的地方。
- 安全框架 PathGuard：每个契约中的文件系统参数都声明其角色（read、write 或 read_list），并通过共享的 validate_read 和 validate_write 函数在两个进程中强制执行。validate_read 要求路径完全解析并包含在配置的 allowed_roots 目录内，支持 GDB 内部数据集；validate_write 额外执行 ArcGIS 合法数据集命名和覆盖纪律。任何逃逸模式（遍历、UNC、NUL 字节、保留设备名、根外目标）都会立即引发 PathSecurityError。
- 破坏性变更安全底线：十个状态变更工具在没有显式 confirm: true 负载令牌时拒绝运行。calculate_field 默认使用 ARCADE 表达式语言，PYTHON3 在 Layer-A 契约边界被拒绝，除非显式提供 confirm: true。raster_calculator 表达式受限于纯地图代数语法。
- 错误分类：跨进程边界的每个失败都被分类为 validation、security、not_found、license、geoprocessing 或 internal，并返回结构化错误帧。
- 草图转 GIS 管道：支持手绘地块边界照片通过 ORB+RANSAC 图像配准和 HSV 墨水分割，直接提交到地理数据库要素类，无需手动数字化。
使用方式
安装需要 Windows、已授权的 ArcGIS Pro 和 Python 3.11+。提供两种安装路径：
- Path A：纯 PyPI 安装（推荐 Windows 用户）：使用引导包安装，然后克隆 ArcGIS Pro 的 Python 环境。推荐配置对 Layer A（MCP 服务器）和 Layer B（ArcPy 工作器）使用相同的 arcgis-mcp-env\python.exe。
- Path B：Git 克隆与确定性开发（GIS 贡献者）：Layer A 在封闭开发环境中，ArcPy 工作在单独克隆的授权 arcgis-mcp-env 工作器中运行。
环境变量包括 ARCPY_PYTHON_PATH（必需，指向授权解释器）、ARCGIS_MCP_ALLOWED_ROOTS（可写目录）、ARCGIS_MCP_SCRATCH_GDB（现有文件地理数据库）。配置 Claude Desktop 后，重启 MCP 主机并首先调用 health_check 验证服务器到工作器的 IPC 路径。
适用场景
- 通过自然语言驱动 ArcGIS Pro 地理处理任务
- 草图转 GIS 管道：手绘边界照片自动注册并提交到地理数据库
- 需要安全沙箱隔离的本地 GIS 自动化工作流
- 与 Claude Desktop 等 MCP 主机集成进行空间分析
限制
- 仅支持 Windows 系统
- 需要已授权的 ArcGIS Pro 安装
- 需要 Python 3.11 或更高版本
- 自动化质量门当前包含 86 个单元测试，覆盖 PathGuard 边界、Pydantic 契约、注册表路径守卫和注册不变量、工作器错误边界映射以及 Settings 环境验证，但不声称对 100 个地理处理工具本身进行多场景验证，因为这些工具在授权的 ArcGIS 运行时上执行，而 CI 运行器没有该运行时。
- 许可运行时证据在 benchmarks/ 方法卡中单独报告，使用真实 ArcGIS Pro 工作器和专用临时 GDB，不与模拟单元测试计数合并。
- 首次 Windows 安装推荐统一环境配置，分离服务器和工作器环境仍支持开发，但工作器解释器必须包含自己的兼容安装。
