堆栈-MCP

Name: 堆栈-MCP
Author: Wayfinder-Foundry

作者：Wayfinder-Foundry6 星标更新：2025-11-12

安装使用来源：spider==github.com

项目介绍

技术文档摘要

STAC MCP Server

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

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

概览

此 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
search_collections：列出并搜索可用的STAC集合
get_collection：获取特定集合的详细信息
search_items：使用空间、时间和属性过滤器搜索STAC项目
get_item：获取特定STAC项目的详细信息
estimate_data_size：使用惰性加载估算STAC项目的大小（XArray + odc.stac）

功能发现及聚合

新的功能工具（ADR 0004）允许客户端自适应行为：

平滑回退：缺少 /conformance，/queryables 或聚合支持时返回带有 supported:false 的结构化JSON，而不是硬错误。
当专用端点不存在时，get_conformance 回退到根文档的 conformsTo 数组。
如果目录未实现该端点，get_queryables 返回一个带有消息的空集。
get_aggregations 构造一个带有 aggregations 对象的STAC搜索请求；如果不受支持（HTTP 400/404），则返回描述性消息，同时保留原始搜索参数。

数据大小估算

estimate_data_size 工具提供了在不下载实际数据的情况下对地理空间数据集进行准确大小估算的功能：

惰性加载：使用 odc.stac 将STAC项目加载到xarray数据集中而不下载
AOI裁剪：当同时提供bbox和AOI GeoJSON时，自动裁剪到最小区域
备用估算：即使 odc.stac 失败也能提供大小估算
详细元数据：返回关于数据变量、空间维度和单个资产的信息
批量支持：保留结构化元数据以实现高效的批量处理

使用方法

MCP协议/服务器配置

服务器实现了标准化通信的模型上下文协议（MCP）。

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

发布的镜像

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

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

示例

示例：JSON输出模式

以下是一个说明性的（客户端）伪调用，展示了通过MCP客户端消息使用 output_format 参数：

{
  "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字符串，如：

{"mode":"json","data":{"type":"item_list","count":5,"items":[{"id":"..."}]}}

这种封装保持了MCP内容类型的稳定性，同时允许机器可读的链接。

开发

本地开发

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

对于使用容器的本地开发，可以使用VS Code的Remote Containers扩展和提供的.devcontainer配置。

测试

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%
... (其他) ...
---------------------------------------------------------------------
TOTAL                                 620     20    140      9    96%

生成HTML报告（可选）：

coverage html
open htmlcov/index.html  # macOS

配置：.coveragerc 强制执行 branch = True 并忽略 tests/* 和 scripts/version.py。仅在必要时更新忽略模式以保持指标诚实。

建议在打开PR之前的工作流程：

ruff format stac_mcp/ tests/
ruff check stac_mcp/ tests/ --fix
coverage run -m pytest -q
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 中详细的版本增量指南。

手动版本管理

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

# 显示当前版本
python scripts/version.py current

# 根据变更类型递增版本
python scripts/version.py patch    # 修复bug（0.1.0 -> 0.1.1）
python scripts/version.py minor    # 新特性（0.1.0 -> 0.2.0）
python scripts/version.py major    # 重大变更（0.1.0 -> 1.0.0）

# 设置特定版本
python scripts/version.py set 1.2.3

版本系统在以下方面保持一致性：

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

容器开发

为了使用容器进行开发：

# 构建开发镜像
docker build -f Containerfile -t stac-mcp:dev .

# 测试容器
docker run --rm -i stac-mcp:dev

# 使用docker-compose进行开发
docker-compose up --build

# 用于调试，使用交互式shell（需要修改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传输）
后期可以重新引入多阶段/无distro硬化（由潜在的未来ADR跟踪）

文档

FastMCP指南和架构

STAC MCP 包含全面的FastMCP模式和代理地理空间推理文档：

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

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

AI代理关于STAC目录搜索的推理
开发者实现STAC MCP功能
理解计划中的FastMCP集成（问题#69，#78）

额外文档

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

STAC资源

许可证

Apache 2.0 - 详情见LICENSE文件。