dsh-arcgis-pro-bridge

Arcgis Pro Bridge

通过 ArcGIS Pro Bridge MCP Server 连接 ArcGIS Pro 的 DeepSeek Harness 插件（工具显示为 mcp__arcgis__*）。

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:y0urday/dsh-arcgis-pro-bridge#d348e15eb288796dc0414cbf05410003181b2457

兼容性与来源证明

Arcgis Pro Bridge 以 dsh-arcgis-pro-bridge 发布，当前版本为 0.1.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: any
发布来源: github
Registry 更新时间: 2026/9/23

版本

0.1.1stable

2026/9/23

README

dsh-arcgis-pro-bridge

让 DeepSeek Harness (DSH) 里的模型直接调用本机 ArcGIS Pro：读取工程、图层、GDB 结构，并执行 Buffer / Clip / 自定义 ArcPy。

本项目把 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 --locked --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（开发预览版，本插件按 0.1.7-alpha.2 验证；Node.js >= 22.19）
推荐安装 uv；没有 uv 时可用已装 mcp 包的 Python 3.11+（见下节版本约束）

依赖与版本约束

依赖	约束	为什么
`@deepseek-ai/schemastery`	`~3.18.4`	本插件是 bundle，schema 由宿主 DSH 的 cordis loader 校验。DSH 内置包统一声明 `~3.18.4`；用 `^` 会在 profile 里装出第二份旧副本（实测 `^3.18.1` 解析到 3.18.2，与宿主的 3.18.4 不一致）。
`mcp[cli]`（vendored `server/`）	`>=1.9.4,<2`	关键约束。 MCP Python SDK 2.x 删除了 `mcp.server.fastmcp`（`FastMCP` → `mcp.server.mcpserver.MCPServer`），而 vendored 服务 `from mcp.server.fastmcp import FastMCP`。没有上界时，任何一次 relock 都会静默解析到 2.x，服务启动即 `ModuleNotFoundError`。
`uv.lock`（vendored `server/`）	锁定，启动时 `--locked`	`--locked` 让"pyproject + lock 固定"这个承诺真正生效：uv 拒绝重新解析，不会在启动时悄悄换到未经测试的依赖组合。
Node.js	`>=22.19`	与 DSH 宿主一致。

Python 侧的实际锁定值见 server/uv.lock（uv tree 可查看）。升级依赖的正确姿势：

cd server && uv lock --upgrade && uv lock --check   # 有 <2 兜底，不会跳到 mcp 2.x

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

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

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

验证 patch 已进入配置：

dsh --profile web --dump-config

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

备选：发布到 npm 后安装

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

npm publish
dsh plugin --profile web add dsh-arcgis-pro-bridge@0.1.1

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

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

发布新版本

仓库首次发布（已完成，仅作记录）：

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

之后每发一版走这套流程：

# 1. 改 package.json 的 version，并在 CHANGELOG.md 记录变更
# 2. 本地校验
npm run check && npm test
(cd server && uv lock --check)
# 3. 打标签并推送（标签名 = v + version）
git add -A && git commit -m "release: v0.1.1"
git tag -a v0.1.1 -m "v0.1.1"
git push origin main --follow-tags
# 4. 打包并挂到 GitHub Release（git 安装不需要 tgz，Release 附件是给 npm 用户和留档用的）
npm pack
gh release create v0.1.1 dsh-arcgis-pro-bridge-0.1.1.tgz --title v0.1.1 --notes-file CHANGELOG.md

建议给仓库加上 dsh-plugin topic，方便生态发现。用户侧固定到某个 commit 安装：

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 覆盖整行配置：

- 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 默认值。

首次测试顺序

让模型调用 mcp__arcgis__ping，确认真正进入了工具链路。
调用 mcp__arcgis__health_check，再调 mcp__arcgis__doctor，确认能发现 ArcGIS Pro Python、ArcPy 可导入。
读取当前工程：mcp__arcgis__list_gis_layers（或传 .aprx 路径）。
读取 GDB：mcp__arcgis__inspect_gdb。
最后才试 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,<2"（必须带 <2，原因见下节）。
启动即报 No module named 'mcp.server.fastmcp'：这个解释器里装的是 MCP Python SDK 2.x。2.x 把 FastMCP 改名为 mcp.server.mcpserver.MCPServer 并删除了旧导入路径，而 vendored 服务用的是 1.x API。请改装 pip install "mcp[cli]>=1.9.4,<2"，或改用默认的 launcher: uv（包内 uv.lock 已锁在 1.x，且启动时带 --locked，不会自动漂移）。
发现不了 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 策略重试。

本地校验

npm run check          # node --check index.js
npm test               # 清单/补丁/依赖约束一致性测试
uv run --locked --project server server/arcgis_mcp_server.py   # 直接启动服务，应进入等待状态

同步上游

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

npm run sync-upstream

脚本会重新克隆上游最新代码、覆盖 server/*.py、pyproject.toml、uv.lock，然后：

重新打上本仓库唯一的本地补丁 —— 给 mcp[cli] 加上 <2 上界。该步骤是幂等的；如果上游已把服务迁到 MCPServer（不再 import mcp.server.fastmcp），脚本会自动跳过打补丁。
用 uv lock --check 校验 lock 与打补丁后的 pyproject 是否一致，不一致就 uv lock --upgrade 刷新（有 <2 兜底，不会跳到 mcp 2.x）。
自动更新 NOTICE 里的 commit 号。

同步后请先跑上面的校验，再在 Windows + ArcGIS Pro 上做一次 ping → health_check → doctor 冒烟。

本地补丁内容记录在 NOTICE；除 pyproject.toml 的 mcp[cli] 上界和据此重新生成的 uv.lock 外，server/ 与上游逐字节一致。

许可

本仓库 MIT。vendored Python 服务代码来自 Sangwxx/ArcGIS-Pro-Bridge-MCP-Server（MIT），完整许可见 server/UPSTREAM_LICENSE，说明见 NOTICE。

README

dsh-arcgis-pro-bridge

让 DeepSeek Harness (DSH) 里的模型直接调用本机 ArcGIS Pro：读取工程、图层、GDB 结构，并执行 Buffer / Clip / 自定义 ArcPy。

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 --locked --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（开发预览版，本插件按 0.1.7-alpha.2 验证；Node.js >= 22.19）
推荐安装 uv；没有 uv 时可用已装 mcp 包的 Python 3.11+（见下节版本约束）

依赖与版本约束

依赖	约束	为什么
`@deepseek-ai/schemastery`	`~3.18.4`	本插件是 bundle，schema 由宿主 DSH 的 cordis loader 校验。DSH 内置包统一声明 `~3.18.4`；用 `^` 会在 profile 里装出第二份旧副本（实测 `^3.18.1` 解析到 3.18.2，与宿主的 3.18.4 不一致）。
`mcp[cli]`（vendored `server/`）	`>=1.9.4,<2`	关键约束。 MCP Python SDK 2.x 删除了 `mcp.server.fastmcp`（`FastMCP` → `mcp.server.mcpserver.MCPServer`），而 vendored 服务 `from mcp.server.fastmcp import FastMCP`。没有上界时，任何一次 relock 都会静默解析到 2.x，服务启动即 `ModuleNotFoundError`。
`uv.lock`（vendored `server/`）	锁定，启动时 `--locked`	`--locked` 让"pyproject + lock 固定"这个承诺真正生效：uv 拒绝重新解析，不会在启动时悄悄换到未经测试的依赖组合。
Node.js	`>=22.19`	与 DSH 宿主一致。

Python 侧的实际锁定值见 server/uv.lock（uv tree 可查看）。升级依赖的正确姿势：

cd server && uv lock --upgrade && uv lock --check   # 有 <2 兜底，不会跳到 mcp 2.x

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

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

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

验证 patch 已进入配置：

dsh --profile web --dump-config

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

备选：发布到 npm 后安装

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

npm publish
dsh plugin --profile web add dsh-arcgis-pro-bridge@0.1.1

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

发布新版本

仓库首次发布（已完成，仅作记录）：

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

之后每发一版走这套流程：

# 1. 改 package.json 的 version，并在 CHANGELOG.md 记录变更
# 2. 本地校验
npm run check && npm test
(cd server && uv lock --check)
# 3. 打标签并推送（标签名 = v + version）
git add -A && git commit -m "release: v0.1.1"
git tag -a v0.1.1 -m "v0.1.1"
git push origin main --follow-tags
# 4. 打包并挂到 GitHub Release（git 安装不需要 tgz，Release 附件是给 npm 用户和留档用的）
npm pack
gh release create v0.1.1 dsh-arcgis-pro-bridge-0.1.1.tgz --title v0.1.1 --notes-file CHANGELOG.md

建议给仓库加上 dsh-plugin topic，方便生态发现。用户侧固定到某个 commit 安装：

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 覆盖整行配置：

- 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 默认值。

首次测试顺序

让模型调用 mcp__arcgis__ping，确认真正进入了工具链路。
调用 mcp__arcgis__health_check，再调 mcp__arcgis__doctor，确认能发现 ArcGIS Pro Python、ArcPy 可导入。
读取当前工程：mcp__arcgis__list_gis_layers（或传 .aprx 路径）。
读取 GDB：mcp__arcgis__inspect_gdb。
最后才试 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,<2"（必须带 <2，原因见下节）。
启动即报 No module named 'mcp.server.fastmcp'：这个解释器里装的是 MCP Python SDK 2.x。2.x 把 FastMCP 改名为 mcp.server.mcpserver.MCPServer 并删除了旧导入路径，而 vendored 服务用的是 1.x API。请改装 pip install "mcp[cli]>=1.9.4,<2"，或改用默认的 launcher: uv（包内 uv.lock 已锁在 1.x，且启动时带 --locked，不会自动漂移）。
发现不了 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 策略重试。

本地校验

npm run check          # node --check index.js
npm test               # 清单/补丁/依赖约束一致性测试
uv run --locked --project server server/arcgis_mcp_server.py   # 直接启动服务，应进入等待状态

同步上游

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

npm run sync-upstream

脚本会重新克隆上游最新代码、覆盖 server/*.py、pyproject.toml、uv.lock，然后：

重新打上本仓库唯一的本地补丁 —— 给 mcp[cli] 加上 <2 上界。该步骤是幂等的；如果上游已把服务迁到 MCPServer（不再 import mcp.server.fastmcp），脚本会自动跳过打补丁。
用 uv lock --check 校验 lock 与打补丁后的 pyproject 是否一致，不一致就 uv lock --upgrade 刷新（有 <2 兜底，不会跳到 mcp 2.x）。
自动更新 NOTICE 里的 commit 号。

同步后请先跑上面的校验，再在 Windows + ArcGIS Pro 上做一次 ping → health_check → doctor 冒烟。

本地补丁内容记录在 NOTICE；除 pyproject.toml 的 mcp[cli] 上界和据此重新生成的 uv.lock 外，server/ 与上游逐字节一致。

许可

本仓库 MIT。vendored Python 服务代码来自 Sangwxx/ArcGIS-Pro-Bridge-MCP-Server（MIT），完整许可见 server/UPSTREAM_LICENSE，说明见 NOTICE。

Arcgis Pro Bridge

兼容性与来源证明

版本

相关插件

Arcgis Pro Bridge

README

dsh-arcgis-pro-bridge

架构

环境要求

依赖与版本约束

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

备选：发布到 npm 后安装

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

发布新版本

配置

用户覆盖示例

首次测试顺序

排查

本地校验

同步上游

许可

兼容性与来源证明

版本

相关插件

相关插件

相关插件

README

dsh-arcgis-pro-bridge

架构

环境要求

依赖与版本约束

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

备选：发布到 npm 后安装

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

发布新版本

配置

用户覆盖示例

首次测试顺序

排查

本地校验

同步上游

许可