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 --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는 로컬에서 코드를 실행하는 것과 같습니다. 신뢰할 수 있는 머신에서만 활성화하고, 쓰기 작업 전에 데이터를 백업하세요.

Related MCP server: ArcGIS Pro Bridge MCP Server

환경 요구 사항

• Windows(ArcGIS Pro는 Windows만 지원)

• ArcGIS Pro가 설치되어 있고 정상적으로 시작할 수 있어야 함

• DeepSeek Harness(개발 미리보기 버전, 이 플러그인은 0.1.0-rc.6으로 검증됨; Node.js >= 22.19)

• uv 설치 권장; uv가 없으면 mcp 패키지가 설치된 Python 3.11+ 사용 가능

설치(권장: GitHub 직접 설치)

이 프로젝트는 순수 ESM JavaScript + vendored Python이며 빌드 단계가 없습니다. 따라서 GitHub 직접 설치에는 빌드 권한이 필요 없습니다. 특정 커밋으로 고정할 것을 권장합니다:

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.0

GitHub 직접 설치 + 빌드 스크립트 없음을 권장하는 이유

DSH 플러그인에는 세 가지 배포 방식이 있습니다: 로컬 디렉터리, npm 패키지, github: 직접 설치. TypeScript + prepare 빌드를 사용하면 GitHub 직접 설치 시 사용자가 자신의 profile에 allowBuilds를 구성해야 하며, 이는 설치 중에 코드를 실행하도록 허용하는 것과 같아 진입 장벽이 더 높습니다. 이 저장소는 의도적으로 순수 JavaScript로 유지되어 세 가지 방식 모두 바로 사용할 수 있고 GitHub 직접 설치 경험이 가장 좋습니다. 나중에 npm에 올릴 때도 구조를 변경할 필요가 없습니다.

GitHub에 게시

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 토픽을 추가하는 것을 권장합니다. 게시한 후에는 위의 설치 명령을 자신의 owner와 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 스키마에 기본값이 있습니다:

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를 통째로 교체하는 것이지 깊은 병합이 아닙니다. 작성하지 않은 필드는 스키마 기본값으로 돌아갑니다.

첫 테스트 순서

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 전략에 따라 재시도합니다.

로컬 검증

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

업스트림 동기화

server/에는 업스트림 저장소의 MIT 라이선스 코드 vendored 복사본이 있으며, 출처와 커밋 번호는 NOTICE에 기록됩니다. 업데이트 시:

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(MIT)에서 가져왔으며, 전체 라이선스는 server/UPSTREAM_LICENSE, 설명은 NOTICE를 참조하세요.