gfm-mcp

把地理空间基础模型（GFM）的推理能力封装为 MCP 工具，让任何 LLM 智能体"动嘴"调用遥感深度学习。

EN: Expose Geospatial Foundation Model (GFM) inference — building extraction, water segmentation, object detection, change detection, zero-shot scene classification, and GFM embeddings — as Model Context Protocol tools for any LLM agent. Runs on CPU.

📖 实战演示: docs/DEMO_zh.md —— 真实客户端对话记录：一句话驱动 GFM 建筑物提取 + Moran's I + 交互制图 🔧 踩坑档案: docs/PITFALLS.md —— 23 条真实排障记录（Windows / CPU-only / 国内网络）

本项目是一次开源空白的填补尝试：MCP（协议）× GIS Copilot（对话式 GIS）× GFMs（地理空间基础模型） 三方向的交汇处，截至 2026-08 没有成熟的完整开源实现（GitHub 相关检索最大 star 仅为 5 的雏形项目，"gfm mcp"关键词甚至被 GitHub Flavored Markdown 占据）。gfm-mcp 用 11 个任务级工具补上这块拼图。

你: "帮我对这张影像做建筑物提取，再把结果做空间自相关分析"
        │
LLM 智能体（Cherry Studio / Claude Desktop / ...）
        │ MCP 协议
        ├─< gis-mcp（经典空间分析：98 工具，缓冲区/Moran's I/NDVI/数据下载）
        └─< gfm-mcp（本项目：GFM 推理 11 工具，建筑物/水体/检测/变化/嵌入）

工具清单（11 + 1 路线图）

⚠️/✅ 需代理 = 嵌入数据托管在 Google 基础设施。2026-08-29 已在代理环境下全量实测通过（128 维向量/6s、相似度、聚类）；无代理环境返回结构化错误 + 换网络建议（门控设计，不崩会话）。

Related MCP server: WEATHGARDS

快速开始

# 1) 宿主环境（Python 3.12+，本包的重量级上游）
uv pip install fastmcp geoai-py rs-embed

# 2) 安装本包
uv pip install -e ./gfm-mcp

# 3) MCP 客户端配置（Claude Desktop / Cherry Studio / Cursor 通用）
{
  "mcpServers": {
    "gfm-mcp": {
      "command": "<venv路径>/python.exe",
      "args": ["-m", "gfm_mcp"]
    }
  }
}

# 4) 测试（可选: 下载示例影像供 heavy 组使用，国内走镜像约 6s/12.7MB）
curl -L -o tests/data/naip_train.tif https://hf-mirror.com/datasets/giswqs/geospatial/resolve/main/naip_train.tif

python tests/test_gfm_mcp.py fast     # 快测: 目录/清单/门控（无需数据，~1min）
python tests/test_gfm_mcp.py domain   # 域工具+异步模式（自动合成数据）
python tests/test_gfm_mcp.py heavy    # 影像推理组（需测试影像，含模型首下载）
python tests/test_gfm_stdio.py        # stdio 握手 + 16 工具清点

国内网络注意：本包在 import 时自动设置 HF_ENDPOINT=https://hf-mirror.com 兜底（用户环境变量已设时不覆盖）。

设计决策（踩坑驱动）

1. 惰性导入：geoai/torch 等重库只在工具被调用时 import——服务器冷启动 2.9s（对照 gis-mcp 全量 extras 冷启动 8s+，它把导入放在了模块顶层）。

2. 实现/装饰器分离：所有逻辑是普通函数（*_impl），MCP 工具只是薄封装——绕开 FastMCP FunctionTool 不可直接调用的坑，函数级测试无需走 MCP 协议。

3. 网络门控：嵌入族工具对 Google 数据源不可达返回 {"status":"error","hint":"..."} 而非异常，保证智能体会话不崩。

4. 上游 bug 绕过：geoai 0.42.0 masks_to_vector(regularize=True) 触发 arctan2 类型错误，工具内部固定 regularize=False 并注释原因。

5. 异步任务模式：MCP 客户端对单次调用有超时窗口（Cherry Studio 默认约 60s）， 而 CPU 推理需 1-3 分钟——start_job 秒回任务号、后台线程执行、check_task 轮询。 实测：建筑物提取 59.6s 后台完成，客户端零超时。

6. 任务级粒度：一个工具 = 一个完整地理任务（含模型下载/推理/矢量化/统计），而非一个函数——减少 LLM 的工具选择负担（对照 gis-mcp 的 98 个函数级工具，两台服务器正好互补）。

数据流示例（Claude 客户端实测语句）

"对 C:/geoai_demo/naip_v2.tif 提取建筑物"
  → extract_buildings → {"count": 664, "median_area_m2": 215, "output": ".../naip_v2_buildings.geojson"}

"这张影像最像以下哪类: 机场/农田/居民区/森林?"
  → classify_scene → {"top": "residential area", "confidence": 0.71, ...}

已验证环境

Windows 11 x64 · Python 3.12.14 (uv venv) · CPU-only（AMD Ryzen 7 8745H / 16GB RAM，无独立 GPU）· geoai-py 0.42.0 / torch 2.13.0+cpu / fastmcp 2.13.1 / rs-embed 0.2.1。 建筑物提取实测：2503×1126 NAIP 影像 664 栋 / 52-71s（CPU）。

致谢与定位

• 模型与推理引擎：geoai-py（Qiusheng Wu）、rs-embed（CyberGIS）

• 协议层：FastMCP、Model Context Protocol

• 经典空间分析姊妹服务器：gis-mcp

• 本项目 = 协议封装与系统集成（GPL-3.0-or-later，衍生作品须同协议开源并署名），不含任何新模型；价值在"早 + 闭环 + 文档化"。

路线图

• 0.1.0 — 11 工具（目录/推理/嵌入三族），CPU 全链路验证

• 0.2.0 — 域工具族 3 个（竞赛方法论工具化：五级分级/DEM 融合/POI 活力），共 14 工具

• 0.2.1 — 异步任务模式（start_job/check_task），共 16 工具，彻底解决客户端超时

• 0.2.2 — 嵌入族代理环境实测通过（128 维/相似度/聚类），坑24 修复（Embedding.data）

• 0.2.3 — GEE 全线贯通：OAuth→非商业注册→项目绑定→galileo on-the-fly 嵌入（192维/20s）+ GSE/AlphaEarth（64维/18s）；坑25/26

• GEE 认证后扩展 on-the-fly 模型嵌入（galileo/prithvi 等非预计算路径）

• 0.3.0 — finetune_remote：TerraTorch 微调任务下发到 Colab，产物回传注册