geospatial-mcp

面向 AI Agent 的地理空间 MCP(Model Context Protocol)服务。以 stdio 传输独立运行,不依赖任何特定 Agent、模型或外部配置。

能力概览

• 只读元数据检查:矢量(GeoJSON / GeoPackage / Shapefile)与栅格(GeoTIFF)的图层、CRS、字段、几何与边界信息。

• 有界矢量分析:平面缓冲区、裁剪、空间连接(需启用工作区)。

• 矢量制图:渲染带图例、CRS 与坐标边界的 PNG 地图,不发起任何网络请求。

• 任务与成果管理:每次分析生成隔离任务;成果(GPKG / PNG)通过 MCP resource 以真实字节交付,带 SHA256 校验。

• 受控数据访问:仅通过管理员登记的 dataset_id 引用数据,不接受调用方提供的服务器路径或 URL。

Related MCP server: arcgis-lacounty

工具一览

另提供 resource artifact://{artifact_id},用于读取已完成成果的 GPKG / PNG 二进制内容。完整输入输出契约见 docs/工具参考.md。

安装

推荐在项目目录使用独立环境:

uv sync --locked --python 3.12 --cache-dir .cache/uv

或安装为 Python 包:

python -m pip install . --cache-dir .cache/pip

pip install . 使用声明的直接依赖;需要完整可复现依赖时使用 uv sync --locked。

快速开始

# 生成小型合成演示数据(不下载外部数据)
.\.venv\Scripts\python.exe examples\create_demo_data.py --output examples\data

# 指向数据目录并以 stdio 启动
$env:GEO_DATA_ROOT = (Resolve-Path examples\data).Path
.\.venv\Scripts\geospatial-mcp.exe --transport stdio

stdio 服务通常由 MCP 客户端在连接时自动拉起;手动运行后等待输入属正常行为。也可执行 python -m geospatial_mcp --transport stdio。--help 与 --version 不需要配置数据目录。

配置

数据目录

默认读取 $GEO_DATA_ROOT/datasets.json,由管理员登记可对外暴露的数据集:

{
  "version": 1,
  "datasets": {
    "roads_demo": {"path": "roads.geojson", "kind": "vector"},
    "dem_demo": {"path": "dem.tif", "kind": "raster"}
  }
}

路径必须相对于数据根目录,禁止 ..、绝对路径、URL 与 Windows ADS。目录在启动时加载,变更后需重启;每次调用仍会重新校验实际路径、文件存在性与大小。不要在数据目录中放置模型配置或凭证。

环境变量

不设置 GEO_WORKSPACE_ROOT 时仅提供两个元数据工具;设置后启用全部 9 个工具与成果 resource。

工作区与成果

启用工作区后,每个分析工具创建一个隔离任务,输出 GPKG 或 PNG 成果。流程为:

1. 调用分析工具(如 geo_vector_buffer),返回 task_id 与成果元数据(artifact_id、uri、size_bytes、sha256)。

2. 用 geo_get_task_info / geo_get_artifact_info 查询任务与成果状态。

3. 通过 resources/read 读取 artifact://{artifact_id} 获取真实文件字节,而非服务器文件路径。

矢量成果可在后续分析中作为 artifact_id 输入复用,形成链式分析。

客户端接入

采用 mcpServers 配置格式的客户端示例(按你的实际安装路径替换):

{
  "mcpServers": {
    "geospatial": {
      "command": "<项目目录>/.venv/Scripts/geospatial-mcp.exe",
      "args": ["--transport", "stdio"],
      "env": {
        "GEO_DATA_ROOT": "<数据目录绝对路径>"
      }
    }
  }
}

工具发现与调用不依赖客户端当前工作目录。Hermes 等 Agent 的接入方式见 docs/Hermes接入指南.md。

验证

# 不调用任何 LLM 的普通 stdio 客户端验证
.\.venv\Scripts\python.exe examples\stdio_client.py --data-root $env:GEO_DATA_ROOT

# 单元测试(生成合成数据,不访问模型)
.\.venv\Scripts\python.exe -m unittest discover -s tests -v

也可使用 MCP Inspector 做交互式调试(仅调试用途,非运行依赖):

npx --yes @modelcontextprotocol/inspector --cli -e "GEO_DATA_ROOT=$env:GEO_DATA_ROOT" .\.venv\Scripts\geospatial-mcp.exe --method tools/list

安全边界与限制

• 仅适用于可信管理员维护、客户端不可修改的数据目录;不提供多用户认证授权。

• 目录授权与符号链接检查不构成完整沙箱;不防御管理员并发替换文件的 TOCTOU,也不保证恶意原生格式解析的进程隔离。

• 大小限制是文件大小限制,不是解压或解析内存上限。

• 输入目录应设置为只读;应用不修改输入,但不能替代操作系统权限。

• Shapefile 需完整存放于受控目录;不支持远程 URL、GDAL VRT、压缩归档与不可信 pickle。

• 仅提供 stdio 传输;HTTP、上传、进程级硬超时与资源隔离尚未实现,见 docs/架构与路线图.md。

文档

• docs/工具参考.md:全部工具与 resource 的输入输出契约。

• docs/架构与路线图.md:分层架构、设计原则、安全模型与后续路线。

• docs/工具迁移清单.md:后续扩展规划——旧能力逐项筛选与分批迁移建议(仅规划,不代表已实现)。

• docs/Hermes接入指南.md:复用本机 Hermes 的接入与成果导出。

• dev-log/日志模板.md:开发阶段记录模板。