内容
# geeflow
**一款让Claude运行谷歌地球引擎的MCP服务器。**
询问Claude构建一张无云卫星图像，计算植被指数，提取统计数据或分类土地覆盖，它实际上是在谷歌的服务器上完成的。geeflow是实现这一功能的连接器：一个模型上下文协议（MCP）服务器，将地球引擎暴露为一组类型化的工具，以及一个代码工具，允许Claude在需要自定义任务时运行任意地球引擎Python代码。
在MCP服务器之下，是一个完整的Python工具包（可以通过CLI或导入单独使用），因此AI会话执行的任何操作，都可以由人类重现。
## 功能
通过Claude（或任何MCP客户端），geeflow可以：
- **查找数据**：搜索地球引擎目录（880+数据集）并读取数据集元数据
- **构建图像**：无云、协调一致的任意地点和年份（1972年以来）的复合图像。它选择适合该年份的卫星（从Landsat MSS到Sentinel-2），云掩模，将波段重命名为通用方案，并在场景稀少时回落到备份传感器或更宽的日期窗口
- **分析**：光谱指数（NDVI、SAVI、EVI、NDMI、NBR、NDWI、NDBI、红边），区域统计，场景可用性
- **查看**：PNG缩略图链接，您和Claude可以查看结果
- **训练数据**：从ESA WorldCover等土地覆盖产品自动生成标记多边形
- **分类**：完整的土地覆盖分类工作流程，具有诚实、安全的准确性（可选，见下文）
- **导出**：将结果发送到Google Drive或地球引擎资产，并跟踪作业
- **其他功能**：`execute_code`工具运行任意地球引擎Python代码，用于数据集和分析，类型化工具无法涵盖（气候、降雨、温度、地形、自定义缩减器）
## 要求
- **Python 3.10或更新版本**（Windows，macOS，Linux）
- **谷歌地球引擎账户**（免费用于研究和非商业用途，[在此注册](https://earthengine.google.com/)）和具有地球引擎API启用的谷歌云项目
- 除此之外不需要其他东西。所有繁重的计算都在谷歌的服务器上运行，因此不需要大量下载和GPU。您的凭证保留在您的机器上。
## 快速入门（与Claude一起）
```bash
# 1. 安装MCP服务器
pip install "geeflow @ git+https://github.com/prahaladuk2208-arch/geeflow#subdirectory=packages/geeflow"
# 2. 认证地球引擎（打开浏览器）
earthengine authenticate
# 3. 将服务器添加到Claude Code
claude mcp add geeflow -- geeflow-mcp
```
对于Claude Desktop或其他MCP客户端，请指向`geeflow-mcp`命令：
```json
{
"mcpServers": {
"geeflow": { "command": "geeflow-mcp" }
}
}
```
然后启动会话并询问。第一个消息告诉Claude您的项目：
> 使用geeflow。我的地球引擎项目是my-gee-project。构建2022年肯尼亚山周围地区的无云干旱季节复合图像，显示我一个缩略图，然后告诉我平均NDVI。
Claude将按顺序调用`gee_init`、`build_composite`、`compute_indices`、`thumbnail`和`region_stats`，并返回可查看的图像和一个数字。
## 工具
**核心地球引擎工具**（使用`geeflow`安装）：
| 工具 | 功能 |
|------|--------------|
| `gee_init` | 连接到地球引擎（每次会话调用一次） |
| `catalog_search` | 跨数据目录的关键字搜索 |
| `dataset_info` | 数据集ID的元数据 |
| `scene_availability` | 某个地点和日期范围内的场景数量 |
| `build_composite` | 某个年份和月份窗口的无云、协调一致的复合图像 |
| `compute_indices` | 添加光谱指数波段 |
| `thumbnail` | PNG预览URL |
| `region_stats` | 区域内每个波段的平均值/中位数/最小值-最大值/标准差 |
| `sample_polygons` | 从土地覆盖产品中自动生成标记训练多边形 |
| `export_composite` | 导出到Google Drive或地球引擎资产 |
| `export_tasks` | 最近的导出作业及其状态 |
| `execute_code` | 运行任意地球引擎Python代码，以完成上述工具无法涵盖的内容 |
**土地覆盖分类工具** 在安装可选的`lulc-engine`包时自动出现（`lulc_validate`、`lulc_check`、`lulc_feature_stack`、`lulc_analyze`、`lulc_classify`、`lulc_collector_script`）。请参阅 [docs/mcp.md](docs/mcp.md) 以获取完整的会话记录。
## 无需AI的使用
相同的引擎作为普通库和CLI工作，因此没有任何内容依赖于AI在循环中。
Python：
```python
from geeflow import Season
from geeflow.composite.builder import build_composites
from geeflow.features.indices import add_indices
from geeflow.geometry import point_buffer
from geeflow.session import init_ee
init_ee("my-gee-project")
aoi = point_buffer(lat=-0.15, lon=37.31, radius_m=15000)
composites, sensor, bands = build_composites(
2022, aoi, seasons=[Season(name="dry", months=(1, 3))]
)
with_indices, computed = add_indices(composites["dry"], ["NDVI", "NDMI"], bands)
```
从配置文件进行土地覆盖分类（首先安装可选包，`pip install "lulc-engine @ git+https://github.com/prahaladuk2208-arch/geeflow#subdirectory=packages/lulc-engine"`）：
```bash
lulc init --template forest # 脚手架 lulc.yaml + 文件夹
lulc validate -c lulc.yaml # 解析年份为传感器计划
lulc classify -c lulc.yaml --year 2022 # CV，最佳模型，地图，导出
```
## 存储库中有什么
两个可通过pip安装的包：
- **`geeflow`** (`packages/geeflow`)：核心地球引擎工具包和MCP服务器。
- **`lulc-engine`** (`packages/lulc-engine`)：在geeflow基础上构建的土地覆盖分类工作流程。可选的`lulc.yaml`定义整个项目（区域、年份、类别、季节）；它比较随机森林、梯度提升和SVM，并使用多边形分组交叉验证导出地图。将配置文件发送给协作者，他们可以重现您的结果。
## 设计原则
- **类型优先，具有逃脱阀**。每个工具都有一个完整的JSON模式，如果任何工具发送一个空模式，测试将失败。`execute_code`涵盖了长尾巴，因此服务器是一个真正的连接器，而不是一个固定的菜单。
- **没有地理硬编码**。地球上的任何区域，1972年以来的任何年份。传感器时代、规模和云掩模自动解析。
- **本地运行，使用您的凭证**。`execute_code`在您的机器上使用您的地球引擎登录运行，与任何本地Python会话具有相同的信任。不要将服务器暴露给不受信任的客户端。
- **统计诚实**。分类准确性来自多边形分组的交叉验证（来自一个训练多边形的像素从不跨越折叠）+模型之间的McNemar测试。
- **可复制**。工作流程通过配置文件往返，因此无论AI会话执行什么，人类都可以重新运行CLI。
## 测试
69个单元测试在不需要地球引擎账户的情况下运行（`ee`模块被模拟），此外还有可选的实时集成测试，针对真正的地球引擎和端到端MCP协议测试。CI在Windows和Linux上运行Python 3.10到3.14的lint和测试。捆绑的示例在真实图像上分类，准确率约为95%。
## 文档
- [MCP服务器指南](docs/mcp.md)
- [快速入门（分类工作流程）](docs/quickstart.md)
- [配置参考](docs/config-reference.md)
- [训练数据指南](docs/training-data.md)
## 路线图
- **M2**：shapefile / KML / GPX / CSV训练导入，来自公共土地覆盖产品（Dynamic World，ESA WorldCover，Hansen）的训练标签，具有共识逻辑的卫星嵌入式特征，本地GeoTIFF后端。
- **M3**：OpenStreetMap土地利用导入，STAC图像后端，变化检测助手。
欢迎贡献，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
MIT
