STAC MCP

STAC MCP サーバー

地理空間データの検索とアクセスのために、STAC（SpatioTemporal Asset Catalog）APIへのアクセスを提供するMCP（Model Context Protocol）サーバーです。すべてのツールで、2つの出力モード（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／タイトル／説明／リンク／適合性のサブセット）
• get_conformance：すべての適合クラスを一覧表示します。特定の URI を任意で検証できます
• get_capabilities：STAC API の機能（クエリ、ソート、フィールド、クエリ可能な項目、集約、フィルター）の概要を取得します
• 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：検索する 1 つ以上のコレクション ID
• bbox：バウンディングボックス [west, south, east, north]、または 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"
    }
  }
}

サーバーは、次のような JSON 文字列をテキストとして含む単一の TextContent で応答します。

{
  "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）を採用しており、.github/workflows/container.yml に実装された PR ラベルまたはブランチ名に基づくバージョン管理を自動化しています。

自動バージョン管理

PR が main にマージされると、ワークフローは PR ラベルまたはブランチのプレフィックスを使って、バージョンの増分を判定します。

PR ラベル（自動化ツールに推奨）

ラベルはブランチのプレフィックスより優先されます。PR に次のいずれかのラベルを追加してください。

• bump:patch または bump:hotfix → バグ修正のためのパッチ増分（0.1.0 → 0.1.1）
• 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）
• 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（単一ステージ）に関する注意事項：

• 幅広いホイールとの互換性（rasterio、shapely など）のため、python:3.12-slim をベースにしています
• rasterio/odc-stac に必要な GDAL/PROJ システムライブラリをインストールします
• pip install . でパッケージをインストールします
• エントリーポイント：python -m stac_mcp.server（stdio MCP トランスポート）
• マルチステージ化／distroless による強化は、後から再導入できます（将来の ADR の候補として記録されています）

ドキュメント

FastMCP のガイドラインとアーキテクチャ

STAC MCP には、FastMCP のパターンとエージェントによる地理空間推論に関する包括的なドキュメントが含まれています。

• FastMCP ドキュメント：STAC ワークフロー向けの MCP デコレーター、リソース、ツール、プロンプトに関する完全なガイド
  • DECORATORS.md：STAC 操作に適したデコレーターの選び方
  • GUIDELINES.md：FastMCP のアーキテクチャと使用パターン
  • PROMPTS.md：エージェントによる STAC 検索の推論と手法
  • RESOURCES.md：STAC カタログの検出とメタデータのパターン
  • CONTEXT.md：ロギングと進捗追跡のためのコンテキストの使用方法

これらのドキュメントでは、次の内容を説明しています。

• STAC カタログ検索について推論する AI エージェント
• STAC MCP の機能を実装する開発者
• 計画中の FastMCP 統合について（イシュー #69、#78）

その他のドキュメント

• テストカバレッジ戦略：テストの方針とカバレッジの目標

STAC リソース

• STAC 仕様
• pystac-client ドキュメント
• Microsoft Planetary Computer
• AWS Earth Search

ライセンス

Apache 2.0。詳しくは LICENSE ファイルを参照してください。