GDAL MCP
具有认知推理的地理空间人工智能
GDAL MCP是一种模型上下文协议（MCP）服务器，为AI代理提供地理空间分析功能，同时要求它们 证明他们的方法选择 通过反射中间件系统。
🎉 v1.1.1发布（2025-10-26） --矢量工具奇偶校验+跨域反射验证\ 🧠 反射系统 --超越数据类型的基于领域的认知推理\ ⚡ 75%缓存命中率 --方法论推理贯穿光栅↔ 向量运算
    ](https://pepy.tech/projects/gdal-mcp)
______________________________________________________________________
📚 文档
______________________________________________________________________
🧠 反射系统
是什么让GDAL MCP与众不同？
大多数AI工具系统在收到请求时会立即执行操作。GDAL MCP要求AI 证明方法论决策的合理性 在执行之前，创建一个关于“为什么”的对话，而不仅仅是执行“什么”
传统人工智能工具方法：
User: "Reproject this DEM to Web Mercator"
AI: *silently executes operation*
Result: DEM reprojected (but with what resampling? why that CRS? what tradeoffs?)带反射的GDAL MCP：
User: "Reproject this DEM to Web Mercator for my web map"
AI: *reflection middleware intercepts*
AI: "Before reprojecting to EPSG:3857, let me justify this CRS choice:
Intent: Web Mercator preserves angles (conformal projection),
essential for web tile rendering and navigation
Alternatives considered:
- EPSG:4326 (WGS84) → rejected: not conformal, distorts shapes
- Local UTM → rejected: limited extent, not web-standard
Tradeoffs: Area distortion increases at high latitudes
(acceptable for web visualization)
Confidence: High - this is the standard for web mapping"
*justification stored, operation proceeds*
Result: DEM reprojected with documented methodology为何这很重要
1.利用MCP协议的全部功能
模型上下文协议不仅涉及工具执行，还涉及 主体推理与互动反射系统利用MCP的设计来实现：
- 执行前提示（工具依赖性）
- 结构化推理（模式验证的理由）
- 有状态的工作流（理由缓存）
- 人机交互（咨询提示）
2.防止无声故障
地理空间操作可以在生产的同时成功执行 方法学上不正确的结果:
- 对连续高程数据进行最近邻重采样（创建伪影）
- 用于面积计算的Web Mercator（可能存在40%以上的失真）
- 分类数据上的双线性插值（创建无效的类值）
反射系统 显示这些选项 用于验证。
3.教育性，非限制性
AI没有被阻止执行操作——它 需要证明理解:
- 第一用途：解释推理，教授方法论
- 缓存：即时执行（知识持久）
- 结果：75%以上的缓存命中率，摩擦最小
4.创建审计跟踪
每一个方法决策都记录了：
- 意图（必须保护哪些财产？）
- 替代方案（还考虑了什么？）
- 理由（为什么选择这个？）
- 权衡（限制是什么？）
- 信心（高/中/低）
这使得 可再生地理空间科学.
🎯 示例工作流程
多业务地理空间分析
User: "I need to reproject this DEM to UTM for accurate slope analysis,
then reproject this vector layer to the same CRS for overlay"
AI Workflow:
1. Inspects DEM metadata (raster_info)
2. REFLECTION: Justifies UTM Zone 10N choice (accurate distance/area)
3. REFLECTION: Justifies cubic resampling (smooth gradients for derivatives)
4. Reprojects DEM (raster_reproject)
5. Inspects vector metadata (vector_info)
6. CACHE HIT: Reuses UTM justification (cross-domain!)
7. Reprojects vector (vector_reproject) - instant, no re-prompting
8. Both datasets now aligned in UTM Zone 10N
Result: 2 operations, 2 reflections (not 3!)
Cache hit rate: 50% → Saves time, maintains methodology关键创新： 步骤2中的CRS理由在步骤6中重复使用，因为该方法（为什么是UTM区域10N？） 基于领域，而非基于工具。无论您使用的是光栅数据还是矢量数据，投影选择推理都是一样的。
看 工具参考 查看所有可用工具的详细示例。
⚡ 主要特点
🧠 反射中间件
- CRS选择的预执行推理、重采样方法
- 结构化理由（意图、替代方案、选择、权衡、信心）
- 在多操作工作流中具有75%命中率的持久缓存
- 跨域缓存共享 -CRS对齐适用于光栅和矢量
🛠️ 综合工具集
- 光栅工具： 信息、转换、重新投影、统计、查询
- 矢量工具： 信息、重新投影、转换、剪辑、缓冲、简化、查询
- 看 工具参考 获取完整的文档
🛡️ 生产质量
- 全型安全（mypy严格模式）
- 72项测试通过
- 工作区安全（路径验证中间件）
- Python原生（Rasterio/PyProj/pygrio）
- 通过FastMCP Context API实时反馈
📚 MCP资源
- 用于自主文件发现的工作区目录
- 用于格式检测的元数据智能
- 参考知识库（CRS、重采样方法、压缩选项）
- 用于检查空间查询输出的查询结果资源(
query://result/{id})
📦 快速开始
通过uvx安装（推荐）
# Run directly from PyPI
uvx --from gdal-mcp gdal --transport stdioMCP配置（克劳德桌面）
添加 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"gdal-mcp": {
"command": "uvx",
"args": ["--from", "gdal-mcp", "gdal", "--transport", "stdio"],
"env": {
"GDAL_MCP_WORKSPACES": "/path/to/your/geospatial/data"
}
}
}
}看 QUICKSTART.md 用于：
- 替代安装方法（Docker、本地开发）
- 详细的MCP客户端配置
- 工作区安全设置
- 故障排除指南
看 docs/环境变量.md 对于所有运行时标志 包括工作区范围、工具注册切换(RASTER/VECTOR)，并查询注册表TTL/容量。
🔧 可用工具
GDAL MCP提供13种生产就绪工具，分为三类：
光栅操作
raster_info-检查元数据（CRS、分辨率、波段、节点数据）raster_convert-带压缩和概述的格式转换（COG支持）raster_reproject⚡ - CRS转换（带反射）raster_stats-直方图统计分析raster_query⚡ - 空间窗口查询（bbox或几何体）
向量运算
vector_info-检查元数据（CRS、几何图形、属性）vector_reproject⚡ - CRS转换（带反射）vector_convert-格式迁移（SHP↔ GPKG↔ GeoJSON）vector_clip-空间子集vector_buffer-邻近性分析vector_simplify-几何简化vector_query⚡ - 空间/属性查询（bbox或几何体）
反射系统
store_justification-缓存认知推理（内部使用）- CRS选择、重采样方法和查询范围的咨询提示
⚡ = 已启用反射： 这些工具需要在首次使用时进行方法论证，然后缓存以供即时后续执行。
看 TOOLS.md 获取包含示例和参数的完整文档。
注： 空间查询工具目前仅提供核心查询（阶段3a）。索引/VRT优化推迟到未来阶段。
🧪 测试
# Run all tests
uv run pytest test/ -v
# With coverage
uv run pytest test/ --cov=src --cov-report=term-missing状态: ✅ 72项测试通过，包括反射系统集成
🏗️ 建筑
Python原生堆栈 （ADR-0017）：
- 拉斯特里奥 -光栅I/O和操作
- PyProj -CRS运营和转型
- 平壤 -高性能矢量I/O（fiona回退）
- 形状 -几何运算
- 数值Python -数组操作和统计
- 派丹蒂克 -具有JSON模式的类型安全模型
关键设计决策 (26个ADR 指导开发）：
- ADR-0026：反思体系与认知治理
- ADR-0017：Python本机优于CLI外壳以提高性能
- ADR-0011：需要显式重采样（防止无声数据损坏）
- ADR-0022：安全工作区隔离
🤝 贡献
我们欢迎捐款！看 贡献.md 用于：
- 开发设置
- 代码风格指南（Ruff+mypy）
- 测试要求（pytest+夹具）
- ADR流程
📝 许可证
MIT许可证-请参阅 许可证 了解详情。
🙏 致谢
🗺️ 路线图
当前状态：v1.1.1 -第二阶段完成✅
- 反射中间件运行
- 实现矢量/光栅工具奇偶校验
- 跨域缓存共享已验证（命中率75%）
下一篇：第三阶段-工作流智能（v2.0+）
- 正式的工作流组成
- 多步骤编排
- 分析模式库
看 视觉 完整的长期路线图。
______________________________________________________________________
建于❤️ 面向地理空间人工智能社区
*地理空间操作是思考，而不仅仅是执行。*