GeoCroissant MCP Server

Model Context Protocol (MCP)-Server für GeoCroissant und seine georäumliche Erweiterung.

Funktionen

• EO-Datensatzsuche – Stichwort-/Themensuche über STAC-Sammlungen und räumliche Szenensuche (Bounding Box + Datum/Uhrzeit + Wolkembedeckung) gegen die planetare84-Earth-Search-API (https://earth-search.aws.element84.com/v1, AWS Open Data), mit Sensormodalitäts-Klassifikation (optisch / Radar / Höhenmodell) und Themenkürzel (flood, wildfire, ndvi, dem, ...).

• STAC -> GeoCroissant-Generierung – wandelt Live-Suchergebnisse in ein validiertes GeoCroissant-Dokument um: Schema.org-Abdeckung, CRS, Band-Konfiguration und spektrale Metadaten aus eo:bands (umgerechnet von Mikrometern in Nanometer), FileObjects für direkte Asset-URLs sowie ein RecordSet mit einer Zeile pro Szene.

• Offizieller Validator als Tool – strukturierte Erfolgs-/Fehlschlag-Berichte mit Fehlern und Warnungen von mlcroissant (dieselbe Engine wie mlcroissant validate).

• Tiefenprüfung – Kern-Metadaten plus jede GeoCroissant-Eigenschaft: CRS, räumliche/zeitliche Auflösung, Band-Konfiguration, spektrale Band-Metadaten, Record-Endpunkt, räumlicher Index/Bias/Sample-Strategie.

• Strukturgraphen-Extraktion – stellt den gerichteten Multigraphen bereit, den die Bibliothek intern aufbaut (Knoten: Metadata/FileObject/FileSet/RecordSet/Field; Kanten: Quelle, Verknüpfung, Enthaltensein).

• Record-Materialisierung – führt den echten Operationsgraphen aus (Downloads, Extrahierung, Transformationen), um tatsächliche Datensätze mal zu peken – genau wie Dataset.records(...) in Python.

• Validated Scaffolding – erzeugt standardkonformes GeoCroissant-JSON-LD aus strukturierten Parametern und prüft es mit dem realen Validator.

• Integrierte Spezifikationsreferenz – Namensräume, alle geocr:-Eigenschaften menschenbezogen auf Domänen/Kardinalität, kanonischer @context, Beispieldokument und Python-API.

Related MCP server: Copernicus Earth Observation MCP Server

Tools

Einen Katalog hinzufügen

Die Registry ist datengesteuert (src/geocr_mcp_server/config/catalogs.yaml): jeder Katalog ist ein Eintrag mit seiner STAC-URL, kuratierten Sammlungen pro Modalität, sowie gemeinsamen metadata und Stichwort-Hinweisen zur Modalität. Um einen weiteren Katalog ohne Codeänderung zu registrieren:

1. Kopieren Sie die YAML an irgendeinen Ort und fügen Sie Ihren Katalog unter catalogs (und alle Themen-Zuordnungen unter topics) ein.

2. Setzen Sie die Umgebungsvariable auf diese Datei: zu definieren.

"env": { "GEOCR_CATALOGS_CONFIG": "/path/to/catalogs.yaml" }

Der Ladeprozess validiert, dass Themen-Referenzen in den Sammlungskatalogen mindestens eines enthielten. Also schlagen Tippfehler bereits beim Start fehl.

Empfohlener Agent-Workflow

discovery:  list_eo_catalogs -> search_eo_datasets("burn scar", modality=optical)
            -> search_eo_scenes(bbox=[...], datetime_range=...)
metadata:   create_geocroissant_from_stac(...)  # validated output + optional file
consuming:  inspect_geocroissant -> get_records_preview -> extract_distribution_urls
authoring:  create_geocroissant_scaffold -> edit -> validate_croissant

Installation

Kein Clone nötig – pip/uvx holen geocr-mcpMittwochskasten sowie die mlcroissant-Abhängigkeit direkt von GitHub. Klonen ist nur für die Entwicklung nötig.

pip

pip install git+https://github.com/HarshShinde0/geocr_mcp.git@main

Alle Abhängigkeit mlcroissant wird automatisch aus dem GeoCroissant-Fork gezogen:

pip install git+https://github.com/HarshShinde0/croissant.git@main#subdirectory=python/mlcroissant

uv / uvx (für Clients empfohlen)

uvx --from "geocr-mcp @ git+https://github.com/HarshShinde0/geocr_mcp.git@main" geocr-mcp-server

Docker

docker build -t geocr-mcp-server .
# stdio (local clients):
docker run -i --rm geocr-mcp-server
# hosted (HTTP transports):
docker run -p 8000:8000 geocr-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

Client-Konfiguration

Kein Python-Code erforderlich – Clients installieren (und cachen) beide Pakete direkt über uvx von GitHub.

{
  "mcpServers": {
    "geocr": {
      "command": "uvx",
      "args": [
        "--from", "geocr-mcp @ git+https://github.com/HarshShinde0/geocr_mcp.git@main",
        "geocr-mcp-server"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

{
  "mcp": {
    "servers": {
      "geocr": {
        "command": "uvx",
        "args": [
          "--from", "geocr-mcp @ git+https://github.com/HarshShinde0/geocr_mcp.git@main",
          "geocr-mcp-server"
        ],
        "env": {
          "FASTMCP_LOG_LEVEL": "ERROR"
        }
      }
    }
  }
}

Nur erforderlich, wenn man den Server-Code selbst ausbauen will:

git clone https://github.com/HarshShinde0/geocr_mcp.git   # or this monorepo

{
  "mcpServers": {
    "geocr": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/geocr_mcp",
        "run", "geocr-mcp-server"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Starten Sie den Server mit HTTP-Transport für gemeinsame/entfernte Cloud-Nutzung:

geocr-mcp-server --transport streamable-http --host 0.0.0.0 --port $PORT

Bereitstellung auf Render (1-Click-Blueprint)

Dieses Repository enthält einen render.yaml-Blueprint:

1. Loggen Sie sich in das Render Dashboard ein.

2. Klicken Sie auf New + -> Blueprint und verbinden Sie das Repository HarshShinde0/geocr_mcp.

3. Klicken Sie auf Apply. Render erstellt den Container automatisch und stellt den Server bereit.

Live-Endpunkt: https://geocr-mcp-server/render.com/mcp

Anbindung von Clients an gehostetem MCP

In der Konfiguration Ihres KI-Clients, Ihrer IDE oder Ihres Agenten (mcpServers):

{
  "mcpServers": {
    "geocr-remote": {
      "url": "https://geocr-mcp-server.onrender.com/mcp"
    }
  }
}

Hinter einem eigenen Reverse-Proxy TLS am Proxy beenden und GEOCR_HOST=0.0.0.0 und GEOCR_TRANSPORT=streamable-http setzen.

Umgebungsvariablen

Sicherheitshinweise

• Der Server führt nur Netzwerkoperationen durch, wenn ein Tool-Input eine URL referenziert oder wenn Records aus externen Verteilungen materialisiert werden (get_records_preview). Sorge in nicht vertrauenswürdigen Umgebungen stets für einen kleinen limit.

• Generierte Dateien werden immer innerhalb von GEOCR_OUTPUT_DIR geschrieben; Pfad-Traversierung wird blockiert, indem Dateinamen auf ihren Basisnamen gekürzt werden.

• Lasse Container als Nicht-Root laufen (das beiliegende Dockerfile macht das bereits).

Entwicklung

cd geocr_mcp
uv venv && uv sync --all-groups     # or: python -m pip install -e ".[dev]"
uv run pytest --cov --cov-branch    # unit tests (no network required)
uv run ruff check src tests         # lint (same rules as awslabs/mcp)
npx @modelcontextprotocol/inspector geocr-mcp-server   # interactive debugging