# ArcMap Desktop 10.8 MCP Bridge

一个面向 ArcMap Desktop 10.8（ArcPy / Python 2.7）的本地 MCP 桥接原型。MCP 服务运行于现代 Python，ArcPy 操作始终由 ArcMap 自带的 Python 2.7 子进程执行。

## 状态

当前版本已实现文件式 JSON 桥接、目录白名单、任务超时和下列只读工具：

- `health_check`
- `search_arcpy_tools`
- `describe_mxd`
- `list_mxd_layers`
- `describe_dataset`
- `list_fields`
- `get_feature_count`
- `query_features`
- `get_server_capabilities`
- `export_mxd_to_png`
- `export_mxd_to_pdf`
- `copy_mxd_with_layer_visibility`

它还提供受控的 `run_geoprocessing`，目前仅允许 `Buffer_analysis`、`Clip_analysis`、`CopyFeatures_management`、`Dissolve_management`、`Erase_analysis`、`Intersect_analysis`、`Merge_management` 与 `Project_management`。`export_mxd_to_png` 与地理处理工具一样需要 `confirm=true`，并且仅能写到 scratch 目录。`query_features` 默认至多返回 100 条，硬性上限为 1,000 条，以免意外占满 MCP 上下文。

`Project_management` 的 `parameters.out_coor_system` 可接受 ArcGIS 坐标系字符串、PRJ 路径或 `EPSG:3857` 这种 EPSG 写法。

`copy_mxd_with_layer_visibility` 从不修改输入 MXD：它只在 scratch 目录创建副本，再修改副本中匹配名称的图层可见性。

`get_server_capabilities` 让 MCP 客户端在执行前读取实际启用的 ArcMap 10.8 工具目录、确认门槛、路径白名单与并发限制；不要根据 ArcGIS Pro 的工具名称假设 Desktop 10.8 也可用。

## 高级工具模式

高级模式默认关闭。设置 `ARCMAP_MCP_ADVANCED_TOOL_ALLOWLIST` 为英文分号分隔的 ArcPy 工具名，例如 `Union_analysis;SpatialJoin_analysis;Near_analysis`，才会显示 `run_advanced_geoprocessing`。设置为 `ALL` 可调用任意非破坏性 GP 工具；`Delete_*`、`Truncate*`、`Compact*`、`Remove*` 等工具始终拒绝。

高级调用必须传入 `args`、`kwargs`，并在 `input_paths` 与 `output_paths` 中逐项声明其中全部绝对路径。输出路径必须在 scratch 内，且所有高级调用都需要 `confirm=true`。这使高级模式仍无法越过数据路径边界。

先用 `search_arcpy_tools` 搜索本机实际安装的工具名，例如 `query="spatialjoin"`、`query="raster"` 或 `query="network"`，再用 `run_advanced_geoprocessing` 执行其中一个允许的工具。

> 本机未安装 ArcMap 时可以使用 `ARCMAP_MCP_MOCK=1` 运行协议验证；真实 ArcPy 操作必须在已授权的 ArcMap Desktop 10.8 Windows 环境中运行。

## 安装（MCP 主服务）

使用 Python 3.10+：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
```

## 配置

复制配置样例并填写 ArcMap 的 Python 路径：

```powershell
Copy-Item .env.example .env
```

常见的 ArcMap Desktop 10.8 Python 路径为 `C:\Python27\ArcGIS10.8\python.exe`，但请以实际安装位置为准。`ARCMAP_MCP_ALLOWED_ROOTS` 必须包含数据和项目所在目录；工具会拒绝访问白名单外的路径。

## 启动

```powershell
$env:ARCMAP_MCP_PYTHON = 'C:\Python27\ArcGIS10.8\python.exe'
$env:ARCMAP_MCP_ALLOWED_ROOTS = 'D:\GIS\Data;D:\GIS\Projects'
arcmap-mcp
```

MCP 客户端配置示例：

```json
{
  "mcpServers": {
    "arcmap-10-8": {
      "command": "C:\\path\\to\\.venv\\Scripts\\arcmap-mcp.exe",
      "env": {
        "ARCMAP_MCP_PYTHON": "C:\\Python27\\ArcGIS10.8\\python.exe",
        "ARCMAP_MCP_ALLOWED_ROOTS": "D:\\GIS\\Data;D:\\GIS\\Projects",
        "ARCMAP_MCP_SCRATCH": "D:\\GIS\\Scratch"
      }
    }
  }
}
```

## 一键诊断

在 PowerShell 中运行：

```powershell
.\scripts\diagnose.ps1
```

脚本不会读写 GIS 数据；它只检查项目虚拟环境、ArcMap Python 路径、访问白名单，并调用 `health_check` 返回 ArcPy 与许可状态。可传入可选的副本数据路径进行只读计数：

```powershell
.\scripts\diagnose.ps1 -Dataset .\work\changlong-test\points.shp
```

## 审计日志

设置 `ARCMAP_MCP_LOG_FILE` 后，服务记录操作名、成功/失败、耗时与简短错误信息；不记录工具参数或要素内容。日志文件必须位于 `ARCMAP_MCP_SCRATCH` 内。

## 并发保护

默认 `ARCMAP_MCP_MAX_WORKERS=1`，同一 MCP 服务实例会串行执行 ArcPy 任务，以保护 ArcMap 10.8 的 32 位运行时与许可。可设置为 1–4；`ARCMAP_MCP_QUEUE_TIMEOUT_SECONDS` 控制任务等待空闲 worker 的最长时间。

## 首次真实环境验收

启动后先调用 `health_check`。它应返回 `arcpy.GetInstallInfo()`、Python 版本和许可状态；之后使用 `list_mxd_layers` 对一个副本 MXD 测试。默认不允许写操作，地理处理工具会要求 `confirm=true` 且输出目录必须在白名单内。