GeoCroissant MCP Server

GeoCroissant 및 그 geospatial 확장을 위한 Model Context Protocol (MCP) 서버입니다.

기능

• EO 데이터셋 탐색 - STAC 컬렉션에 대한 키워드/주제 검색과 bbox + datetime + cloud cover 기반 공간 장면 검색을 라이브 Element84 Earth Search API(https://earth-search.aws.element84.com/v1, AWS Open Data)를 대상으로 수행하며, 센서 모달리티 분류(optical / radar / elevation) 및 테마 단축키(flood, wildfire, ndvi, dem, ...)를 제공합니다.

• STAC -> GeoCroissant 생성 - 라이브 검색 결과를 검증된 GeoCroissant 문서로 변환합니다. schema.org coverage, CRS, eo:bands에서 파생된 밴드 구성 및 분광 메타데이터(µm 단위에서 nm 단위로 변환), 직접 에셋 URL을 위한 distribution FileObject, 그리고 장면당 하나의 행을 포함하는 RecordSet까지 포함됩니다.

• 검증 도구로서의 공식 검증기 - mlcroissant(즉, mlcroissant validate와 동일한 엔진)에서 제공하는 오류 및 경고를 포함한 구조화된 합격/불합격 보고서를 생성합니다.

• 심층 검사 - 핵심 메타데이터에 더해 GeoCroissant의 모든 속성까지: CRS, 공간/시간 해상도, 밴드 구성, 분광 밴드 메타데이터, 레코드 엔드포인트, 스키마/바이어스/샘플링 전략.

• 구조 그래프 추출 - 라이브러리가 내부적으로 구축하는 방향성 다중 그래프를 노출합니다(Metadata / FileObject / FileSet / RecordSet / Field 노드, source/join/containment 에지).

• 레코드 구체화 - 굉장이 실제 레코드 그래프(다운로드, 추출, 변환)를 실행하여 실제 레코드를 직접 미리 봅니다. Python의 Dataset.records(...)와 완전히 동일합니다.

• 검증된 스캐폴딩 - 구조화된 파라미터로 표준에 부합하는 GeoCroissant JSON-LD를 생성하고, 실제 검증기로 검증합니다.

• 내장된 스펙 참조 - 네임스페이스, 도메인/카디널리티를 포함한 모든 geoc: 속성, canonical @context, 샘플 문서, Python API를 제공합니다.

Related MCP server: Copernicus Earth Observation MCP Server

기능

카탈로그 추가

레지스트리는 데이터 기반(src/geocr_mcp_server/config/catalogs.yaml)입니다. 각 카탈로그는 STAC URL, 모달리티별로 관리되는 컬렉션, 그리고 공유 topics와 모달리티 키워드 힌트를 포함하는 항목입니다. 코드를 수정하지 않고 다른 카탈로그를 등록하려면:

1. YAML을 복사하고 catalogs 아래에 카탈로그를 추가하세요(테마 매핑은 topics 아래에).

2. 환경 변수로 해당 파일을 가리키도록 하세요:

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

로더는 주제 참조가 어떤 카탈로그의 컬렉션 목록에 존재하는지 검증하므로, 시작 시 오타가 즉시 실패합니다.

권장 에이전트 워크플로우

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

설치

클론이 필요 없습니다 - pip 또는 uvx가 GitHub에서 geocr-mcp와 그 mlcroissant 의존성을 바로 가져옵니다. 클론은 개발용으로만 필요합니다.

pip

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

단일 의존성인 mlcroissant은 GeoCroissant 포크에서 자동으로 설치됩니다:

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

uv / uvx (클라이언트에 권장)

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

클라이언트 설정

클론이 필요 없습니다. 클라이언트는 uvx을 통해 이 두 패키지를 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"
        }
      }
    }
  }
}

서버 코드 자체를 개발 중일 때만 필요합니다:

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

공유/원격 클라우드 사용을 위해 동일한 서버를 HTTP 전송으로 실행합니다:

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

Render에 배포(원클릭 Blueprint)

이 저장소에는 render.yaml blueprint가 포함되어 있습니다:

1. Render Dashboard에 로그인합니다.

2. New + -> Blueprint를 클릭하고 HarshShinde0/geocr_mcp 저장소를 연결합니다.

3. Apply를 클릭합니다. Render가 자동으로 컨테이너를 빌드해 서버를 배포합니다.

라이브 엔드포인트: https://geocr-mcp-server.onrender.com/mcp

호스팅된 MCP에 클라이언트 연결하기

AI 클라이언트, IDE 또는 에이전트 설정(mcpServers)에서:

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

사용자 지정 리버스 프록시 뒤에서 TLS를 프록시에서 종료하고 GEOCR_HOST=0.0.0.0과 GEOCR_TRANSPORT=streamable-http로 설정하세요.

환경 변수

보안 고려 사항

• 서버는 도구 입력이 URL을 참조하거나 원격으로부터 레코드를 구체화할 때(get_records_preview)에만 네트워크 요청을 수행합니다. 신뢰할 수 없는 환경에서는 limit을 작게 유지하세요.

• 생성된 파일은 항상 GEOCR_OUTPUT_DIR 안에 저장되며, 파일 이름을 basename으로 축소하여 이려움 경로 추적을 차단합니다.

• 컨테이너는 비-루트(non-root) 사용자로 실행하세요(제공된 Dockerfile이 이미 그렇게 합니다).

개발

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