Skip to main content
Glama
ArcGIS Pro Worker Agent

ArcGIS Pro Worker Agent

ArcGIS Pro Worker Agent — GIS 方向 Super-Agent 的执行层

GIS 方向的 Super-Agent 负责理解意图、拆解任务、调度多个领域的 Worker;本仓库是其中GIS 领域的 Worker Agent: 接收下发的子任务,把「算一下公路 500 米缓冲」这类指令翻译成具体的 arcpy 调用, 执行完把结构化结果交回去。

技术上它是一个本地 MCP Server(16 个工具),运行在 Windows 上,直接驱动本机已授权的 ArcGIS Pro。 不是独立的对话机器人,也不做全局规划——它的价值在于把 GIS 领域的前置判断做对。


项目介绍

为什么要拆出 Worker

GIS 方向的 Super-Agent 要处理的需求往往跨环节:先看数据、判断坐标系、做投影、跑分析、再出图。 如果把这些都塞进一个 Agent 的上下文里,会同时出现两个问题:

  1. 上下文被工具细节淹没。图层名、字段名、地理处理参数、错误码,都会挤占规划所需的空间;

  2. 规划逻辑与具体软件绑定。换一个 GIS 平台(QGIS、PostGIS、GeoServer),上层都要改。

所以按职责切开:Super-Agent 决定「做什么」,Worker 决定「在 GIS 里怎么做成」。 本仓库是后者,一个只负责 GIS 执行的 Worker Agent。

上下两层怎么分工

职责

Super-Agent

本仓库(GIS Worker)

理解用户意图、拆解任务

✅

❌ 只接单个子任务

跨领域编排(GIS / 文档 / 检索…)

✅

❌

选择工具与参数

只给约束

✅ 自行决定

判断坐标系、投影、许可级别等前置条件

❌

✅

处理工程被独占锁定之类的运行时异常

❌

✅

汇总并校验结果

✅

✅ 返回结构化结果与失败原因

接口约定:输入是一个子任务描述加上必要上下文(工程路径、目标图层、约束条件); 输出是结构化结果(要素数、字段、坐标系、输出路径)或明确的失败原因。 传输走 MCP stdio(JSON-RPC),Super-Agent 把它当成一组可调用的工具。

实际表现

给 Worker 一句「算一下公路 500 米缓冲带」,它会先检查坐标系,发现数据是 WGS84 地理坐标系(单位是度), 主动先投影到 CGCS2000 3 度带 再做缓冲,最后溶解并出图。

这一步不做,ArcGIS 会把「500 米」按 0.0000045 度去算,结果完全错误。 Worker 的职责就是不让这种错误流回到 Super-Agent。


Related MCP server: ARCclaude

架构

flowchart TB
    subgraph WA["ArcGIS Pro Worker Agent(本仓库)"]
        S["server.mjs<br/>Node 协议层 · 16 个工具"]
        W["arcpy_worker.py<br/>常驻子进程"]
        S -->|"JSON Lines<br/>stdin / stdout"| W
    end

    U["用户需求"] --> SA["GIS Super-Agent<br/>意图理解 · 任务分解 · 多 Worker 编排"]
    SA -->|"子任务 + 上下文"| S
    W -->|"arcpy.mp / arcpy.ddd"| P["ArcGIS Pro<br/>解释器 + 许可"]
    P --> D[("aprx / gdb / 栅格")]
    W -.->|"结构化结果 / 失败原因"| SA

Worker 内部又分成两段,原因和上层分工无关,是环境逼出来的:

ArcGIS Pro 3.1 自带的是 Python 3.9,而 MCP 官方 SDK 所有版本都要求 >= 3.10, pip install mcp 会被直接拒绝。所以 Node 承担协议层(Node 18+ 无版本问题), Python 只负责执行 arcpy,两者用一行一个 JSON 的管道通信。

这是被环境约束逼出来的设计,不是过度设计。


能力面(暴露给 Super-Agent 的 16 个工具)

共 16 个工具,按用途分五组。这就是 Worker 对上层开放的全部能力—— Super-Agent 只需要知道「有哪些工具、各要什么参数」,不需要知道 arcpy 怎么用、 更不需要知道坐标系该怎么处理。

环境与工程

工具

作用

pro_ping

检查 arcpy 是否可用,返回版本、许可级别、Python 版本

pro_open_project

打开 .aprx 工程并设为当前工程(几乎其他工具的前置)

pro_project_info

工程概况:路径、默认地理数据库、地图与布局列表

pro_list_maps

列出工程内所有地图

数据查看

工具

作用

pro_list_layers

列图层(名称、可见性、几何类型、数据源)

pro_describe

数据集详情:坐标系、范围、字段、要素数

pro_list_fields

字段清单(名称、别名、类型、长度)

pro_query_attributes

读属性表,支持 SQL 条件筛选与行数限制

空间分析

工具

作用

pro_run_geoprocessing

万能入口,可调 ArcToolbox 里绝大多数工具

pro_buffer

缓冲区分析,自动处理输出路径

pro_clip

按边界裁剪

pro_project_data

投影转换(支持 EPSG 或 WKT)

成果输出

工具

作用

pro_export_map

地图导出 PNG / JPG / PDF

pro_export_layout

布局导出

pro_save_project

保存工程到 .aprx

兜底

工具

作用

pro_run_python

执行任意 arcpy 代码片段,预置 project / active_map / gdb 变量

除此之外 arcpy.ddd(3D Analyst)也可通过 pro_run_geoprocessing / pro_run_python 调用, 已实测 FeatureTo3DByAttribute、InterpolateShape、SurfaceVolume、Skyline、LineOfSight 等。


环境说明

组件

要求

说明

操作系统

Windows 10 / 11

未在 Linux / macOS 验证

ArcGIS Pro

3.x(本机验证于 3.1)

必须安装且有可用许可,Basic 许可部分工具受限

Node.js

>= 18(推荐 20+)

承担 MCP 协议层

Python

3.9,用 Pro 自带的 arcgispro-py3

不要用系统 Python,它没有 arcpy

arcgispro-py3 的典型位置(脚本会自动探测):

C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe
D:\ArcGIS\bin\Python\envs\arcgispro-py3\python.exe

也可以用环境变量显式指定:

set ARCGIS_PRO_PYTHON=C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe

部署步骤

1. 准备环境

安装 ArcGIS Pro(并登录使许可生效)+ Node.js 18 以上。

2. 拉取代码并安装依赖

git clone https://github.com/xiaohuajia2005/arcgis-pro-mcp-demo.git
cd arcgis-pro-mcp-demo
npm install

3. 运行自检

node doctor.mjs

正常输出:

1. 检查运行环境
  [OK]   Node v24.22.2
  [OK]   ArcGIS Pro Python: D:\ArcGIS\bin\Python\envs\arcgispro-py3\python.exe
  [OK]   server.mjs 存在

2. 启动 MCP 服务并握手
  [OK]   MCP 握手成功

3. 检查工具注册
  [OK]   工具数量 16

4. 检查 arcpy 是否可用
  [OK]   arcpy 可用 {"arcpy":"3.1.5","license":"ArcInfo",...}

全部通过,服务可用。

失败时会指出断在哪一层,对照 docs/TROUBLESHOOTING.md 处理。

4. 把 Worker 注册到 Super-Agent 侧

Worker 自己不是客户端,它由上层 Super-Agent 以 MCP 客户端身份拉起(stdio 子进程)。 在 Super-Agent 的 MCP 配置里加上这一段即可。

通用格式参考 config/mcp-config.example.json,DeepSeek Harness 参考 config/deepseek-harness.example.yml。

以 Harness 为例,编辑 %USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml,追加:

- insert:
    - id: "mcp-arcgis-pro"
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: "arcgis-pro"
        transport: "stdio"
        command: 'C:\Program Files\nodejs\node.exe'   # 换成你的 node 路径
        args:
          - 'D:\arcgis-pro-mcp-demo\server.mjs'       # 换成你的实际路径

5. 重启客户端

配置必须重启才会加载。重启后在对话里说「用 pro_ping 检查一下 ArcGIS 环境」,能返回 arcpy 版本即接通。

6. 开始使用

帮我打开 D:\data\demo.aprx,看看有哪些图层

演示截图

公路 500 米缓冲区(Worker 独立执行)

公路500米缓冲分析

这张图是 Worker 接到一个子任务后独立走完整个流程产出的,中间没有任何手动干预:

步骤

Worker 的判断

调用工具

1

先看图层清单,确认数据在哪

pro_list_layers

2

检查坐标系,发现是 WGS84(单位:度)

pro_describe

3

判断直接按米缓冲会出错,先投影到 CGCS2000 3 度带

pro_project_data

4

做 500 米缓冲并溶解(否则会碎成 7943 个独立面)

pro_buffer

5

导出成图

pro_export_map

第 3 步是重点:如果不投影,ArcGIS 会把「500 米」当成 0.0000045 度去算,结果完全错误。 Worker 自己发现了这一点。


已知局限

如实说明,这些不是"待优化项",是当前架构下的硬性限制:

1. 只能本地运行

stdio 子进程模型,没有网络服务、没有鉴权、没有并发控制。单用户单会话可用,不能部署成多人共享服务。

2. 强依赖 ArcGIS Pro 授权

没有 Pro 和有效许可,import arcpy 直接失败。这不是能靠代码绕过的限制——arcpy 的几何运算和地理处理都跑在 Esri 的运行时里。

3. 运行时必须分开,不能合并成一个进程

Node 跑协议、Python 跑 arcpy。原因见上文:Pro 自带的 Python 3.9 装不上 MCP SDK。 理论上可以用独立 Python 3.10+ 环境跑 MCP,但那个环境里没有 arcpy,仍然要跨进程调用,复杂度不会更低。

4. 操作的是 .aprx 文件,不是你正打开的 Pro 窗口

arcpy.mp.ArcGISProject("CURRENT") 只在 Pro 进程内部有效,外部进程拿不到。 而且 Pro 打开工程时会独占锁定 .aprx,此时外部写入会失败(OSError)。 实践建议:只在 Pro 关闭工程时让 Worker 写入;只读类操作(查询、统计、临时分析)不受影响。

5. 无法精确控制出图范围

独立进程没有渲染视图,view.camera 的读写会失效甚至让进程挂死,改 CIM 相机也无效。 现在的做法是新建地图让其自动贴合图层范围,所以只能出「整层范围」的图,做不了局部特写裁剪。

6. 部分工具性能差

实测 Buffer3D 处理 234 条线耗时 429 秒(同样数据做 2D 缓冲不到 1 秒), 它要逐要素构造 MultiPatch 实体。大数据量的 3D 操作需要先抽样验证。

7. 验证范围有限

只在 Windows + ArcGIS Pro 3.1 + ArcInfo 许可 上完整跑通过。 其他版本、Standard/Basic 许可下的工具可用性未逐一验证。

8. 一次只处理一个子任务

底层是单进程 stdio 管道,请求串行执行。Super-Agent 若拆出多个 GIS 子任务,需要自己控制下发顺序; 长任务(如 Buffer3D 处理 234 条线要 7 分钟)会阻塞后续请求。


技术难点记录

这部分是这个项目真正的价值所在——都是实际卡住过、最后解决掉的问题。

问题

现象

解决方式

Python 版本卡死

pip install mcp 全部版本被拒,提示要求 >= 3.10

改双进程架构,Node 承担协议层

协议通道被污染

arcpy 大量向 stdout 打印,JSON 通道被冲垮,客户端解析失败

worker 启动时把 fd 1 复制给协议专用流,再把真正的 stdout 重定向到 stderr

图层名不被 GP 工具接受

GetCount("湖泊") 报"数据集不存在"

服务端把图层名自动解析成数据源路径再传入

独立进程拿不到活动地图

project.activeMap 返回 None

兜底取第一个地图,并在文档中提示显式传 map_name

Buffer 参数顺序记错

报 ERROR 000800,边类型收到 NONE

查证第 4 位是边类型、第 5 位才是端点样式,修正调用

视图对象不能缓存

导出空白图(7 KB)

每次导出重新获取 defaultView

保存工程失败

OSError: <aprx 路径>

Pro 独占锁导致,改为提示用户先关闭工程


目录结构

arcgis-pro-mcp-demo/
├── server.mjs                    # MCP 协议层,16 个工具的定义与调度(Node)
├── arcpy_worker.py               # arcpy 执行进程,一行一个 JSON(Python 3.9)
├── doctor.mjs                    # 分层自检脚本,排查"看不到工具"
├── start-mcp.bat                 # 一键启动,用于手动验证
├── package.json
├── config/
│   ├── mcp-config.example.json   # 通用 MCP 客户端配置样例
│   └── deepseek-harness.example.yml  # DeepSeek Harness 配置片段
├── docs/
│   ├── TROUBLESHOOTING.md        # 常见故障与处理
│   └── screenshots/
│       └── buffer-500m.png
└── README.md

说明

本项目是 GIS 方向 Super-Agent 系统中的 Worker Agent 层,只承担 GIS 执行职责: 把子任务翻译成 arcpy 调用、处理领域前置条件、返回结构化结果。

不包含 Super-Agent 侧的任务规划、意图理解与多 Worker 调度代码——那部分不属于本仓库。

代码以「跑通链路、验证可行性」为目标,未做生产级加固(无测试覆盖、无错误重试策略、无并发处理)。

示例数据为公开的 OpenStreetMap 道路与水系,以及公开 DEM,不含任何敏感信息。

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Exposes ArcGIS Pro geoprocessing capabilities to LLMs via the arcpy library, enabling automated spatial analysis and data management. It provides a comprehensive suite of tools for vector geoprocessing, terrain analysis, and raster operations designed for GIS workflows.
      4
      -
    • A
      license
      B
      quality
      B
      maintenance
      Lets AI assistants control a live ArcGIS Pro session through arcpy, including layer management, attribute queries, geoprocessing, symbology, and export.
      114
      76
      AGPL 3.0