# 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](https://modelcontextprotocol.io) tools for any LLM agent. Runs on CPU.

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
![Tools](https://img.shields.io/badge/MCP_tools-16-blue)
![Python](https://img.shields.io/badge/python-3.12%2B-green)

📖 **实战演示**: [docs/DEMO_zh.md](docs/DEMO_zh.md) —— 真实客户端对话记录：一句话驱动 GFM 建筑物提取 + Moran's I + 交互制图
🔧 **踩坑档案**: [docs/PITFALLS.md](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 路线图）

| 族 | 工具 | 功能 | 上游能力 | 本地硬件 |
|---|---|---|---|---|
| 目录 | `list_gfm_models` | 21 个 GFM 目录（名称/模态/任务/年份/HF 仓库） | geoai-py | 秒级 |
| 目录 | `get_model_info` | 模糊查询单模型详情 | geoai-py | 秒级 |
| 推理 | `extract_buildings` | 建筑物轮廓提取 → GeoJSON（CPU 实测 30s/2500px 影像，664 栋） | geoai-py | ✅ CPU |
| 推理 | `segment_water` | 水体提取（NAIP/Sentinel-2 波段可配） | geoai-py | ✅ CPU |
| 推理 | `detect_objects` | 目标检测（solar_panel / ship / car） | geoai-py | ✅ CPU |
| 推理 | `detect_change` | 双时相变化检测（ChangeStar） | geoai-py | ✅ CPU（tile 调小） |
| 推理 | `classify_scene` | CLIP 零样本场景判读（无需训练） | transformers | ✅ CPU |
| 嵌入 | `list_embedding_models` | 20 个嵌入模型清单 + 网络要求标注 | rs-embed | 秒级 |
| 嵌入 | `gfm_embedding` | 任意坐标提取基础模型嵌入：tessera 128维/6s、gse(AlphaEarth) 64维/18s、galileo 192维/20s(GEE) | rs-embed | ✅ 需代理(GEE) |
| 嵌入 | `embedding_similarity` | 两地嵌入余弦相似度（实测 cos=0.9923） | rs-embed | ✅ 需代理 |
| 嵌入 | `embedding_cluster` | 区域网格嵌入 + K-Means 地表形态分区（3×3 实测 222s） | rs-embed | ✅ 需代理 |
| 异步 | `start_job` / `check_task` | 长耗时推理转后台任务（规避客户端超时），轮询取结果 | 自研 | ✅ |
| **域** | `classify_threshold_levels` | 物理阈值+分位数五级分级（源自月球极区光照分类法） | 自研 | ✅ CPU |
| **域** | `dem_precision_fuse` | 双 DEM 精度倒数加权融合（源自 LOLA+CE-2 法） | 自研 | ✅ CPU |
| **域** | `poi_vitality` | POI 活力指数（KDE + Shannon 熵，源自教育资源优化项目） | 自研 | ✅ CPU |
| 路线图 | `finetune_remote`（阶段4） | 触发 Colab 远程微调 | TerraTorch | 云端 |

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

## 快速开始

```bash
# 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` 并注释原因。
6. **异步任务模式**：MCP 客户端对单次调用有超时窗口（Cherry Studio 默认约 60s），
   而 CPU 推理需 1-3 分钟——`start_job` 秒回任务号、后台线程执行、`check_task` 轮询。
   实测：建筑物提取 59.6s 后台完成，客户端零超时。
5. **任务级粒度**：一个工具 = 一个完整地理任务（含模型下载/推理/矢量化/统计），而非一个函数——减少 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](https://github.com/opengeos/geoai)（Qiusheng Wu）、[rs-embed](https://github.com/cybergis/rs-embed)（CyberGIS）
- 协议层：[FastMCP](https://github.com/jlowin/fastmcp)、[Model Context Protocol](https://github.com/modelcontextprotocol)
- 经典空间分析姊妹服务器：[gis-mcp](https://github.com/mahdin75/gis-mcp)
- 本项目 = 协议封装与系统集成（GPL-3.0-or-later，衍生作品须同协议开源并署名），不含任何新模型；价值在"早 + 闭环 + 文档化"。

## 路线图

- [x] 0.1.0 — 11 工具（目录/推理/嵌入三族），CPU 全链路验证
- [x] 0.2.0 — 域工具族 3 个（竞赛方法论工具化：五级分级/DEM 融合/POI 活力），共 14 工具
- [x] 0.2.1 — 异步任务模式（start_job/check_task），共 16 工具，彻底解决客户端超时
- [x] 0.2.2 — 嵌入族代理环境实测通过（128 维/相似度/聚类），坑24 修复（Embedding.data）
- [x] 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，产物回传注册