Servidor GeoCroissant MCP

Servidor Model Context Protocol (MCP) para GeoCroissant y su extensión geoespacial.

Funcionalidades

• Descubrimiento de conjuntos de datos EO — búsqueda por palabra clave/tema en colecciones STAC y búsqueda espacial de escenas (bbox + datetime + cobertura de nubes) contra la Element84 Earth Search API en vivo (https://earth-search.aws.element84.com/v1, AWS Open Data), con clasificación por modalidad de sensor (óptica / radar / elevación) y atajos de tema (flood, wildfire, ndvi, dem, ...).

• Generación STAC -> GeoCroissant — convierte los resultados de búsqueda en vivo en un documento GeoCroissant validado: cobertura de schema.org, CRS, configuración de bandas y metadatos espectrales derivados de eo:bands (convertidos de micrómetros a nanómetros), FileObjects de distribución para URLs directas de activos, y un RecordSet que incrusta una fila por escena.

• Validador oficial como herramienta — informes estructurados de apto/no apto con errores y advertencias de mlcroissant (el mismo motor que mlcroissant validate).

• Inspección profunda — metadatos principales y todas las propiedades de GeoCroissant: CRS, resolución espacial/temporal, configuración de bandas, metadatos de bandas espectrales, endpoint de registros, índice espacial / sesgo / estrategia de muestreo.

• Extracción del grafo de estructura — expone el multigrafo dirigido que la librería construye internamente (nodos Metadata / FileObject / FileSet / RecordSet / Field; aristas de origen, unión y contención).

• Materialización de registros — ejecuta el grafo de operaciones real (descargas, extracciones, transformaciones) para previsualizar los registros, exactamente como Dataset.records(...) en Python.

• Scaffolding validado — genera GeoCroisant JSON-LD conforme a estándares a partir de parámetros estructurados y lo verifica a través del validador real.

• Referencia de especificación integrada — namespaces, todas las propiedades geocr: con dominios/cardinalidad, @context canónico, documento de ejemplo y API de Python.

Related MCP server: Copernicus Earth Observation MCP Server

Herramientas

Añadir un catálogo

El registro está basado en datos (src/geocr_mcp_server/config/catalogs.yaml): cada catálogo es una entrada con su URL STAC, colecciones curadas por modalidad, además de topics compartidos y pistas de palabras clave por modalidad. Para registrar otro catálogo sin tocar código:

1. Copie el YAML a alguna ubicación y añade tu catálogo bajo catalogs (así como las asignaciones de temas bajo topics).

2. Apunta la variable de entorno a ese archivo:

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

El cargador valida que las referencias de temas existan en las listas de colecciones de algún catálogo, para que los erros tipográficos provoquen un fallo rápido al inicio.

Flujo de trabajo recomendado para el agente

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

Instalación

No hace falta clonar el repositorio: pip/uvx descargan tanto geocr-mcp como su dependencia mlcroissant directamente desde GitHub. Clonar solo es necesario para el desarrollo.

pip

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

La única dependencia, mlcroissant, se extrae automáticamente del fork GeoCroissant:

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

uv / uvx (recomendado para clientes)

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

Configuración del cliente

No hace falta clonar el repositorio: los clientes instalan (y guardan en caché) ambos paquetes directamente desde GitHub mediante uvx.

{
  "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"
        }
      }
    }
  }
}

Solo es necesario cuando se itera sobre el código del propio servidor:

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": []
    }
  }
}

Ejecuta el mismo servidor con transporte HTTP para uso compartido/remoto en la nube:

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

Despliegue en Render (Blueprint de un clic)

Este repositorio incluye un blueprint render.yaml:

1. Inicia sesión en Panel de control de Render.

2. Clique en New + -> Blueprint y conecta el repositorio HarshShinde0/gecr_mcp.

3. Clique en Apply. Render creará el contenedor automáticamente y hará el despliegue del servidor.

Endpoint en vivo: https://geocr-mcp-server.onrender.com/mcp

Conexión de clientes a MCP alojado

En la configuración de tu cliente, IDE o agente (mcpServers):

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

Detrás de un proxy inverso personalizado, termina el TLS en el proxy y establece GEOCR_HOST=0.0.0.0 y GEOCR_TRANSPORT=streamable-http.

Variables de entorno

Consideraciones de seguridad

• El servidor realiza solicitudes de red solo cuando una entrada de herramienta hace referencia a una URL o cuando materializa registros de distribuciones remotas (get_records_preview). Mantenga el valor de limit elevado/pequeño en no contextos confiables.

• Los archivos generados se escriben siempre dentro de GEOCR_OUTPUT_DIR; el de recorrido de rutas se bloquea reduciendo los nombres de archivo a su nombre base.

• Ejecute los contenedores como usuario no root (el Dockerfile proporcionado ya lo hace).

Desarrollo

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