dsh-arcgis-pro-bridge

Permite que los modelos en DeepSeek Harness (DSH) llamen directamente a ArcGIS Pro local: leer proyectos, capas, estructura GDB, y ejecutar Buffer / Clip / ArcPy personalizado.

Este proyecto integra el servicio Python MCP de ArcGIS-Pro-Bridge-MCP-Server como plugin bundle de DSH y lo levanta mediante el cliente oficial @deepseek-ai/dsh-mcp-client incluido en DSH vía stdio. Las herramientas visibles para el modelo tienen nombres como:

• 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

Arquitectura

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 子进程执行

Puntos clave:

• Solo se ejecuta en esta máquina, no abre puertos de red.

• ArcPy siempre se ejecuta en el Python incluido con ArcGIS Pro, sin contaminar el entorno Node de DSH.

• El puente MCP oficial de DSH actualmente solo enlaza Tools; los Resources arcgis:// upstream no se registran, usa la Tool del mismo nombre (p.ej. inspect_gdb) para operaciones de lectura.

• execute_arcpy_code equivale a ejecutar código en esta máquina. Habilítalo solo en máquinas de confianza y respalda los datos antes de operaciones de escritura.

Related MCP server: ArcGIS Pro Bridge MCP Server

Requisitos del entorno

• Windows (ArcGIS Pro solo es compatible con Windows)

• ArcGIS Pro instalado y que pueda iniciarse correctamente

• DeepSeek Harness (vista previa de desarrollo; este plugin se verificó con 0.1.0-rc.6; Node.js >= 22.19)

• Se recomienda instalar uv; si no tienes uv, puedes usar Python 3.11+ con el paquete mcp instalado.

Instalación (recomendada: instalación directa desde GitHub)

Este proyecto es JavaScript ESM puro + Python vendored, sin paso de compilación, por lo que la instalación directa desde GitHub no requiere permisos de build. Se recomienda fijar un commit concreto:

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

Verifica que el patch haya entrado en la configuración:

dsh --profile web --dump-config

En la salida deberías ver la línea arcgis-pro-bridge, con name resuelto a este paquete. Luego reinicia completamente dsh web.

Alternativa: instalar tras publicar en npm

El paquete ya incluye la lista blanca files, se puede publicar directamente:

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

Por qué se recomienda instalación directa desde GitHub + sin script de compilación

Los plugins de DSH tienen tres formas de distribución: directorio local, paquete npm, o instalación directa github:. Si usas TypeScript + compilación prepare, la instalación directa desde GitHub exigiría que el usuario configure allowBuilds en su perfil, lo que equivale a permitir ejecutar tu código durante la instalación, un requisito más alto. Este repositorio se mantiene deliberadamente en JavaScript puro; los tres métodos funcionan directamente, y la instalación directa desde GitHub ofrece la mejor experiencia; si luego quieres publicar en npm no necesitas cambiar la estructura.

Publicar en GitHub

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

Se recomienda añadir el topic dsh-plugin al repositorio para facilitar el descubrimiento en el ecosistema. Tras publicar, reemplaza el comando de instalación anterior con tu propio owner y commit:

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

Si también quieres publicar en npm, la lista blanca files del paquete está lista; basta con npm publish; las dos vías de instalación (npm y GitHub) pueden coexistir.

Configuración

La configuración predeterminada está en cordis.patch.yml; normalmente no hay que modificarla. Todos los campos tienen valores predeterminados en el schema Config de index.js:

Valores predeterminados de reconnect: enabled: true, initialDelayMs: 500, maxDelayMs: 30000, maxAttempts: 10.

Ejemplo de sobrescritura por el usuario

En $DSH_HOME/profiles/web/cordis.patch.yml (o con --patch al iniciar), sobrescribe la configuración completa por 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

Nota: la sobrescritura del patch reemplaza todo el bloque config, no es una fusión profunda; los campos no especificados vuelven a los valores predeterminados del schema.

Orden de las primeras pruebas

1. Haz que el modelo llame a mcp__arcgis__ping para confirmar que realmente se entra en la cadena de herramientas.

2. Llama a mcp__arcgis__health_check y luego a mcp__arcgis__doctor, para confirmar que se detecta el Python de ArcGIS Pro y que ArcPy se puede importar.

3. Lee el proyecto actual: mcp__arcgis__list_gis_layers (o pasa una ruta .aprx).

4. Lee la GDB: mcp__arcgis__inspect_gdb.

5. Solo al final prueba mcp__arcgis__buffer_features / clip_features / execute_arcpy_code; respalda antes de operaciones de escritura.

Puedes copiar este prompt al modelo:

No uses shell, no escribas scripts de prueba. Llama directamente a mcp__arcgis__ping si está disponible, luego a mcp__arcgis__health_check, y dime los resultados completos de ambas llamadas.

Solución de problemas

• La herramienta no aparece: ejecuta primero dsh --profile web --dump-config, confirma que la línea arcgis-pro-bridge existe y no hay errores de carga; confirma que reiniciaste dsh web.

• No se encuentra uv: usa where uv (CMD) / Get-Command uv (PowerShell) para confirmar que está en el PATH; de lo contrario, cambia a launcher: python e instala pip install "mcp[cli]>=1.9.4".

• No se detecta ArcGIS Pro: llama a detect_arcgis_environment; o especifícalo explícitamente mediante env.ARCGIS_PRO_PYTHON / ARCGIS_PRO_INSTALL_DIR.

• No puedes leer el proyecto actual: ArcGISProject("CURRENT") depende del contexto de ejecución de ArcGIS Pro; si falla, pasa directamente la ruta .aprx a la herramienta.

• Errores de bloqueo de ArcPy: cierra las capas/sesiones que estés editando, o sal de los programas externos que ocupen los datos y vuelve a intentarlo.

• Registros: dsh imprime los registros de conexión y reconexión de arcgis-pro-bridge y mcp-client(arcgis); cuando la conexión falla y failOnStartupError: false, mcp-client se inicia pero no registra herramientas temporalmente, y reintenta según la política reconnect.

Verificación local

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

Sincronizar con el upstream

server/ contiene una copia vendored del código con licencia MIT del repositorio upstream; el origen y el número de commit se registran en NOTICE. Al actualizar:

npm run sync-upstream

El script clonará de nuevo el código upstream más reciente, sobrescribirá server/*.py, pyproject.toml, uv.lock, y actualizará automáticamente el número de commit en NOTICE. Tras sincronizar, ejecuta primero las verificaciones anteriores y luego haz una prueba de humo ping → health_check → doctor en Windows + ArcGIS Pro.

Licencia

Este repositorio es MIT. El código del servicio Python vendered proviene de Sangwxx/ArcGIS-Pro-Bridge-MCP-Server (MIT); consulta la licencia completa en server/UPSTREAM_LICENSE y la explicación en NOTICE.