dsh-arcgis-pro-bridge

Readme

# dsh-arcgis-pro-bridge

让 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 里的模型直接调用本机 ArcGIS Pro：读取工程、图层、GDB 结构，并执行 Buffer / Clip / 自定义 ArcPy。

本项目把 [ArcGIS-Pro-Bridge-MCP-Server](https://github.com/Sangwxx/ArcGIS-Pro-Bridge-MCP-Server) 的 Python MCP 服务内置进一个 DSH bundle 插件，并通过 DSH 自带的官方 `@deepseek-ai/dsh-mcp-client` 以 stdio 方式拉起。模型看到的工具名形如：

- `mcp__arcgis__ping`
- `mcp__arcgis__health_check`
- `mcp__arcgis__doctor`
- `mcp__arcgis__detect_arcgis_environment`
- `mcp__arcgis__debug_runtime_context`
- `mcp__arcgis__list_gis_layers`
- `mcp__arcgis__inspect_project_context`
- `mcp__arcgis__inspect_gdb`
- `mcp__arcgis__buffer_features`
- `mcp__arcgis__clip_features`
- `mcp__arcgis__execute_arcpy_code`
- `mcp__arcgis__build_gis_resource_uri`
- `mcp__arcgis__generate_sync_plan`

## 架构

```
DSH (Node.js)
  └─ 本插件 bundle（cordis.patch.yml，插入两行）
       ├─ dsh-arcgis-pro-bridge：提供 arcgisProBridge 服务（启动配方）
       └─ @deepseek-ai/dsh-mcp-client（DSH 官方内置桥接，注入该服务）
            └─ stdio: uv run --project <包内 server/> arcgis_mcp_server.py
                 └─ ArcPy 逻辑通过 ArcGIS Pro 自带 Python 子进程执行
```

要点：

- 只在本机运行，不开放网络端口。
- ArcPy 永远在 ArcGIS Pro 自带 Python 里执行，不污染 DSH 的 Node 环境。
- DSH 官方 MCP 桥目前只桥接 **Tools**；上游的 `arcgis://` Resources 不会被注册，读取操作请用同名 Tool（如 `inspect_gdb`）。
- `execute_arcpy_code` 等于在本机执行代码。请只在可信机器上启用，写操作前先备份数据。

## 环境要求

- Windows（ArcGIS Pro 只支持 Windows）
- ArcGIS Pro 已安装且可正常启动
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（开发预览版，本插件按 `0.1.0-rc.6` 验证；Node.js >= 22.19）
- 推荐安装 [uv](https://docs.astral.sh/uv/)；没有 uv 时可用已装 `mcp` 包的 Python 3.11+

## 安装（推荐：GitHub 直接安装）

本项目是纯 ESM JavaScript + vendored Python，**没有构建步骤**，因此 GitHub 直装不需要 build 权限。建议固定到具体 commit：

```bash
dsh plugin --profile web add github:y0urday/dsh-arcgis-pro-bridge#<commit-sha>
```

验证 patch 已进入配置：

```bash
dsh --profile web --dump-config
```

输出中应能看到 `arcgis-pro-bridge` 这一行，`name` 解析为本包。然后完全重启 `dsh web`。

### 备选：发布到 npm 后安装

包内已带 `files` 白名单，可直接发布：

```bash
npm publish
dsh plugin --profile web add dsh-arcgis-pro-bridge@0.1.0
```

### 为什么建议 GitHub 直装 + 无构建脚本

DSH 插件有三种分发方式：本地目录、npm 包、`github:` 直装。若使用 TypeScript + `prepare` 构建，GitHub 直装会要求用户在自己的 profile 里配置 `allowBuilds`，等于允许安装期执行你的代码，门槛更高。本仓库刻意保持为纯 JavaScript，三种方式都能直接用，GitHub 直装体验最好；以后要上 npm 也无需改动结构。

### 发布到 GitHub

```bash
cd dsh-arcgis-pro-bridge
git remote add origin git@github.com:y0urday/dsh-arcgis-pro-bridge.git
git push -u origin main
```

建议给仓库加上 `dsh-plugin` topic，方便生态发现。发布后把上面的安装命令换成你自己的 owner 和 commit：

```bash
dsh plugin --profile web add github:y0urday/dsh-arcgis-pro-bridge#<commit-sha>
```

若要同时发布 npm，包内 `files` 白名单已就绪，`npm publish` 即可；npm 与 GitHub 两套安装方式可以并存。

## 配置

默认配置已写入 `cordis.patch.yml`，一般无需修改。所有字段都在 `index.js` 的 `Config` schema 中带默认值：

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| `serverName` | `arcgis` | 模型侧工具前缀 `mcp__<serverName>__*` |
| `launcher` | `uv` | `uv`：用包内 pyproject + lock 启动；`python`：用 `pythonExecutable` 直接运行脚本（该解释器需已安装 `mcp`） |
| `pythonExecutable` | `python` | 仅 `launcher: python` 时使用；这是运行 MCP 服务的普通 Python，ArcPy 仍由服务自动发现 |
| `extraArgs` | `[]` | 追加给 Python 服务进程的参数 |
| `env` | `{}` | 额外环境变量，例如 `ARCGIS_PRO_PYTHON` / `ARCGIS_PRO_INSTALL_DIR` |
| `toolCallTimeoutMs` | `300000` | 单次 ArcGIS 工具调用超时（毫秒） |
| `failOnStartupError` | `false` | 首次连接失败是否让插件激活失败 |
| `reconnect.*` | 见下 | 子进程断开后的指数退避重连策略 |

`reconnect` 默认值：`enabled: true`、`initialDelayMs: 500`、`maxDelayMs: 30000`、`maxAttempts: 10`。

### 用户覆盖示例

在 `$DSH_HOME/profiles/web/cordis.patch.yml`（或启动时用 `--patch`）里按 `id` 覆盖整行配置：

```yaml
- id: arcgis-pro-bridge
  config:
    serverName: arcgis
    launcher: python
    pythonExecutable: python
    failOnStartupError: true
    env:
      ARCGIS_PRO_PYTHON: C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe
```

> 注意：patch 覆盖是整段替换 `config`，不是深度合并；未写出的字段会回到 schema 默认值。

## 首次测试顺序

1. 让模型调用 `mcp__arcgis__ping`，确认真正进入了工具链路。
2. 调用 `mcp__arcgis__health_check`，再调 `mcp__arcgis__doctor`，确认能发现 ArcGIS Pro Python、ArcPy 可导入。
3. 读取当前工程：`mcp__arcgis__list_gis_layers`（或传 `.aprx` 路径）。
4. 读取 GDB：`mcp__arcgis__inspect_gdb`。
5. 最后才试 `mcp__arcgis__buffer_features` / `clip_features` / `execute_arcpy_code`，写操作前备份。

可以复制这段提示词给模型：

> 不要使用 shell，不要写测试脚本。直接调用可用的 `mcp__arcgis__ping`，再调用 `mcp__arcgis__health_check`，把两次返回结果完整告诉我。

## 排查

- **工具没出现**：先跑 `dsh --profile web --dump-config`，确认 `arcgis-pro-bridge` 行存在且没有加载错误；确认已重启 `dsh web`。
- **`uv` 找不到**：`where uv`（CMD）/ `Get-Command uv`（PowerShell）确认在 PATH；否则改用 `launcher: python` 并安装 `pip install "mcp[cli]>=1.9.4"`。
- **发现不了 ArcGIS Pro**：调 `detect_arcgis_environment`；或通过 `env.ARCGIS_PRO_PYTHON` / `ARCGIS_PRO_INSTALL_DIR` 显式指定。
- **读不到当前工程**：`ArcGISProject("CURRENT")` 依赖 ArcGIS Pro 运行上下文，失败时直接给工具传 `.aprx` 路径。
- **ArcPy 锁错误**：关闭正在编辑的图层/会话，或退出占用数据的外部程序后重试。
- **日志**：`dsh` 会打印 `arcgis-pro-bridge` 与 `mcp-client(arcgis)` 的连接、重连日志；`mcp-client` 在连接失败且 `failOnStartupError: false` 时会启动但暂不注册工具，并按 `reconnect` 策略重试。

## 本地校验

```bash
npm run check          # node --check index.js
npm test               # vendored 文件清单一致性测试
uv run --project server server/arcgis_mcp_server.py   # 直接启动服务，应进入等待状态
```

## 同步上游

`server/` 内为上游仓库 MIT 许可代码的 vendored 副本，来源与提交号记录在 `NOTICE`。更新时：

```bash
npm run sync-upstream
```

脚本会重新克隆上游最新代码、覆盖 `server/*.py`、`pyproject.toml`、`uv.lock`，并自动更新 `NOTICE` 里的 commit 号。同步后请先跑上面的校验，再在 Windows + ArcGIS Pro 上做一次 `ping → health_check → doctor` 冒烟。

## 许可

本仓库 MIT。vendored Python 服务代码来自 [Sangwxx/ArcGIS-Pro-Bridge-MCP-Server](https://github.com/Sangwxx/ArcGIS-Pro-Bridge-MCP-Server)（MIT），完整许可见 `server/UPSTREAM_LICENSE`，说明见 `NOTICE`。