STAC MCP

STAC MCP 服务

一个 MCP（模型上下文协议）服务，可访问 STAC（时空资产目录）API，以发现和访问地理空间数据。所有工具均支持两种输出模式（text 和结构化的 json）。

覆盖率徽章会由 CI 工作流在推送到 main 时自动更新。

概述

此 MCP 服务可让 AI 助手和应用程序与 STAC 目录交互，以便：

• 搜索和浏览 STAC 集合
• 查找地理空间数据集（卫星影像、天气数据等）
• 访问元数据和资产信息
• 执行空间和时间查询

功能

可用工具

所有工具都接受可选的 output_format 参数（默认为 "text"，也可以选择 "json"）。JSON 模式会返回单个 MCP TextContent，其 text 字段为精简的 JSON 封装：{ "mode": "json", "data": { ... } }（如果处理程序没有 JSON 分支，则为 { "mode": "text_fallback", "content": ["..."] }）。这在保持向后兼容的同时，也支持结构化消费（参见 ADR 0006 和 ASR 1003）。

• get_root：获取根文档（id/title/description/links/conformance 子集）
• get_conformance：列出所有符合性类别；可选择验证指定 URI
• get_capabilities：获取 STAC API 功能摘要（query、sort、fields、queryables、aggregation、filter）
• search_collections：列出并搜索可用的 STAC 集合
• get_collection：获取特定集合的详细信息
• search_items：使用空间、时间和属性筛选条件搜索 STAC 项目
• get_item：获取特定 STAC 项目的详细信息
• get_queryables：获取集合的可查询属性
• get_aggregations：获取 STAC 项目的聚合结果
• estimate_data_size：使用延迟加载（XArray + odc.stac）估算 STAC 项目的数据大小

搜索参数

search_items 工具支持全面的 STAC API 搜索参数：

• collections：要搜索的一个或多个集合 ID
• bbox：边界框 [西，经度，南纬，东经度，北纬] 或 GeoJSON 几何图形
• datetime：日期时间筛选条件（例如，“2020-01-01/2020-12-31”）
• limit：要返回的最大项目数
• query：用于筛选属性的查询条件
• fields：要包含或排除的字段列表（例如，["id", "properties.datetime"]）
• intersects：用于空间相交查询的 GeoJSON 几何图形
• ids：要检索的特定项目 ID 列表（批量获取）
• sortby：排序顺序（例如，["-properties.datetime"] 表示降序）
• sign_assets：如果为 True 且目录是 Planetary Computer，则为资源 URL 签名，以便直接访问

分页支持

搜索响应包含分页元数据，并提供基于游标的导航链接：

{
  "type": "item_list",
  "count": 10,
  "items": [...],
  "meta": {
    "catalog_url": "https://example.com/stac",
    "parameters": {...},
    "returned": 10,
    "has_more": true,
    "links": [
      {"rel": "next", "href": "https://example.com/stac/search?token=abc123"},
      {"rel": "prev", "href": "https://example.com/stac/search?token=xyz789"}
    ]
  }
}

Planetary Computer 资源签名

使用 Microsoft Planetary Computer 目录时，可以启用资源签名，以获取用于直接访问资源的签名 URL：

{
  "method": "tools/call",
  "params": {
    "name": "search_items",
    "arguments": {
      "collections": ["sentinel-2-l2a"],
      "limit": 5,
      "sign_assets": true
    }
  }
}

能力发现与聚合

新的能力工具（ADR 0004）支持客户端自适应行为：

• 优雅回退：缺少 /conformance、/queryables 或聚合支持时，会返回包含 supported:false 的结构化 JSON，而非硬错误。
• 如果缺少专用端点，get_conformance 会回退到根文档的 conformsTo 数组。
• 如果目录未实现该端点，get_queryables 会返回空集合及相关说明。
• get_aggregations 会构造包含 aggregations 对象的 STAC Search 请求；如果不受支持（HTTP 400/404），则会在保留原始搜索参数的同时返回说明性消息。

数据大小估算

estimate_data_size 工具可在不下载实际数据的情况下，准确估算地理空间数据集的大小：

• 延迟加载：使用 odc.stac 将 STAC 项目加载到 xarray 数据集中，而不下载数据
• AOI 裁剪：同时提供 bbox 和 AOI GeoJSON 时，自动裁剪到最小区域
• 回退估算：即使 odc.stac 失败，也会提供大小估算
• 详细元数据：返回有关数据变量、空间维度和各个资源的信息
• 批量支持：保留结构化元数据，以便高效进行批处理

用法

MCP 协议 / 服务配置

该服务实现了 Model Context Protocol (MCP)，用于标准化通信。

{
  "stac": {
    "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/wayfinder-foundry/stac-mcp",
      "stac-mcp"
    ],
    "transport": "stdio",
  }
}

已发布的镜像

# With Docker
docker run --rm -i ghcr.io/wayfinder-foundry/stac-mcp:latest

# With Podman
podman run --rm -i ghcr.io/wayfinder-foundry/stac-mcp:latest

示例

示例：基本搜索

{
  "method": "tools/call",
  "params": {
    "name": "search_items",
    "arguments": {
      "collections": ["landsat-c2l2-sr"],
      "bbox": [-122.5, 37.7, -122.3, 37.8],
      "datetime": "2023-01-01/2023-01-31",
      "limit": 5,
      "output_format": "json"
    }
  }
}

服务会返回一个 TextContent，其文本是如下所示的 JSON 字符串：

{
  "type": "item_list",
  "count": 5,
  "items": [{"id": "..."}],
  "meta": {
    "catalog_url": "https://example.com/stac",
    "parameters": {...},
    "returned": 5,
    "has_more": false,
    "links": []
  }
}

示例：使用排序和字段选择进行高级搜索

{
  "method": "tools/call",
  "params": {
    "name": "search_items",
    "arguments": {
      "collections": ["sentinel-2-l2a"],
      "intersects": {
        "type": "Point",
        "coordinates": [-122.4194, 37.7749]
      },
      "sortby": ["-properties.datetime"],
      "fields": ["id", "properties.datetime", "properties.eo:cloud_cover"],
      "limit": 10,
      "output_format": "json"
    }
  }
}

示例：批量获取特定项目

{
  "method": "tools/call",
  "params": {
    "name": "search_items",
    "arguments": {
      "ids": ["item1", "item2", "item3"],
      "output_format": "json"
    }
  }
}

开发

本地开发

git clone https://github.com/wayfinder-foundry/stac-mcp.git
cd stac-mcp
pip install -e ".[dev]"

在本地使用容器进行开发时，可以通过提供的 .devcontainer 配置使用 VS Code 的 Remote Containers 扩展。

测试

pytest -v

测试覆盖率

该项目使用 coverage.py（已添加为依赖项）来衡量语句和分支覆盖率。

快速运行（终端）：

coverage run -m pytest -q
coverage report -m

示例输出（仅供参考）：

Name                                Stmts   Miss Branch BrMiss  Cover
---------------------------------------------------------------------
stac_mcp/observability.py             185      4     42      3    96%
stac_mcp/tools/execution.py            68      2     18      1    94%
... (others) ...
---------------------------------------------------------------------
TOTAL                                 620     20    140      9    96%

生成 HTML 报告（可选）：

coverage html
open htmlcov/index.html  # macOS

配置：.coveragerc 强制启用 branch = True，并排除 tests/* 和 scripts/version.py。仅在必要时更新排除模式，以确保指标真实可靠。

提交 PR 前的推荐工作流：

1. ruff format stac_mcp/ tests/
2. ruff check stac_mcp/ tests/ --fix
3. coverage run -m pytest -q
4. coverage report -m（确保没有意外下降）

代码检查

ruff format stac_mcp/ tests/
ruff check stac_mcp/ tests/ --fix --no-cache

版本管理

该项目采用语义化版本控制（SemVer），并根据 PR 标签或分支命名自动管理版本，此功能在 .github/workflows/container.yml 中实现。

自动版本管理

将 PR 合并到 main 时，工作流会通过 PR 标签或分支前缀确定版本增量：

PR 标签（推荐用于自动化工具）

标签的优先级高于分支前缀。为 PR 添加以下任一标签：

• bump:patch 或 bump:hotfix → 增加补丁版本（0.1.0 → 0.1.1），用于修复 Bug
• bump:minor 或 bump:feature → 增加次要版本（0.1.0 → 0.2.0），用于添加新功能
• bump:major 或 bump:release → 增加主要版本（0.1.0 → 1.0.0），用于包含重大变更

分支前缀（供人工贡献者使用）

如果没有版本升级标签，工作流会改为检测分支前缀：

• hotfix/、fix/、copilot/fix- 或 copilot/hotfix/ 分支 → 增加补丁版本（0.1.0 → 0.1.1），用于修复 Bug
• feature/ 或 copilot/feature/ 分支 → 增加次要版本（0.1.0 → 0.2.0），用于添加新功能
• release/ 或 copilot/release/ 分支 → 增加主要版本（0.1.0 → 1.0.0），用于包含重大变更

有关版本升级的详细指南，请参阅 CONTRIBUTING.md。

手动版本管理

你也可以使用版本脚本手动管理版本（通常无需这样做，除非要进行协调发布）：

# Show current version
python scripts/version.py current

# Increment version based on change type
python scripts/version.py patch    # Bug fixes (0.1.0 -> 0.1.1)
python scripts/version.py minor    # New features (0.1.0 -> 0.2.0)  
python scripts/version.py major    # Breaking changes (0.1.0 -> 1.0.0)

# Set specific version
python scripts/version.py set 1.2.3

版本系统会确保以下内容保持一致：

• pyproject.toml（项目版本）
• stac_mcp/__init__.py（version）
• stac_mcp/server.py（MCP 初始化中的 server_version）

容器开发

使用容器进行开发：

# Build development image
docker build -f Containerfile -t stac-mcp:dev .

# Test the container
docker run --rm -i stac-mcp:dev

# Using docker-compose for development
docker-compose up --build

# For debugging, use an interactive shell (requires modifying Containerfile)
# docker run --rm -it --entrypoint=/bin/sh stac-mcp:dev

当前 Containerfile（单阶段）说明：

• 基于 python:3.12-slim，以广泛兼容各种 wheel（rasterio、shapely 等）
• 安装 rasterio/odc-stac 所需的 GDAL/PROJ 系统库
• 使用 pip install . 安装软件包
• 入口点：python -m stac_mcp.server（stdio MCP 传输）
• 之后可以重新引入多阶段构建/Distroless 加固（已通过潜在的未来 ADR 跟踪）

文档

FastMCP 指南与架构

STAC MCP 提供了全面的 FastMCP 模式和 Agentic 地理空间推理文档：

• FastMCP 文档：STAC 工作流中 MCP 装饰器、资源、工具和提示词的完整指南
  • DECORATORS.md：为 STAC 操作选择合适的装饰器
  • GUIDELINES.md：FastMCP 架构和使用模式
  • PROMPTS.md：Agentic STAC 搜索推理与方法
  • RESOURCES.md：STAC 目录发现与元数据模式
  • CONTEXT.md：使用上下文进行日志记录和进度跟踪

这些文档为以下方面提供指导：

• 对 STAC 目录搜索进行推理的 AI Agent
• 实现 STAC MCP 功能的开发者
• 了解计划中的 FastMCP 集成（issues #69、#78）

其他文档

• 测试覆盖率策略：测试方法和覆盖率目标

STAC 资源

• STAC 规范
• pystac-client 文档
• Microsoft Planetary Computer
• AWS Earth Search

许可证

Apache 2.0 — 详情请参阅 LICENSE 文件。