feat: enhance globalapi with new features and configurable base URL

Author: piotrnowakowski

.dockerignore

@@ -0,0 +1,13 @@
+.git
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.env
+.venv/
+venv/
+.mypy_cache/
+.pytest_cache/
+Dockerfile
+build/
+dist/

.github/workflows/backend.yml

@@ -0,0 +1,88 @@
+name: MCP Global API Deployment
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - '**'
+      - '.github/workflows/backend.yml'
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ghcr.io/open-earth-foundation/mcp-global-api
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      image_tag: ${{ steps.vars.outputs.commit_hash }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get Git commit hash
+        id: vars
+        run: echo "commit_hash=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Build and push image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          platforms: linux/amd64
+          tags: |
+            ${{ env.IMAGE_NAME }}:${{ steps.vars.outputs.commit_hash }}
+            ${{ env.IMAGE_NAME }}:latest
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    env:
+      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID_EKS_DEV_USER }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY_EKS_DEV_USER }}
+      EKS_DEV_NAME: ${{ secrets.EKS_DEV_NAME }}
+      IMAGE_TAG: ${{ needs.build.outputs.image_tag }}
+      IMAGE_NAME: ${{ env.IMAGE_NAME }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID_EKS_DEV_USER }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY_EKS_DEV_USER }}
+          aws-region: us-east-1
+
+      - name: Creating kubeconfig file
+        run: aws eks update-kubeconfig --name "$EKS_DEV_NAME" --region us-east-1
+
+      - name: Testing connection to EKS
+        run: kubectl get pods -n default
+
+      - name: Apply Kubernetes manifests
+        run: |
+          kubectl apply -f k8s/mcp-deployment.yml
+          kubectl apply -f k8s/mcp-service.yml
+
+      - name: Update deployment image
+        run: |
+          kubectl set image deployment/mcp-global-api mcp-global-api=${IMAGE_NAME}:${IMAGE_TAG} -n default
+          kubectl rollout status deployment/mcp-global-api -n default

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    GLOBALAPI_BASE_URL=https://ccglobal.openearth.dev \
+    MCP_HOST=0.0.0.0 \
+    MCP_PORT=8000 \
+    MCP_PATH=/mcp \
+    MCP_TRANSPORT=http
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["python", "globalapi_mcp_server.py", "--transport", "http"]

config.yml

@@ -0,0 +1,3 @@
+openai_model: "gpt-5.1"
+mcp_server_url: "https://mcp-global-api.openearth.dev/mcp"
+mcp_server_path: "./globalapi_mcp_server.py"

globalapi_api_client.py

@@ -1,10 +1,12 @@
 """
 API client for CityCatalyst Global API
-Base URL: https://ccglobal.openearth.dev
+Base URL is configurable via the GLOBALAPI_BASE_URL environment variable.
 """
+import os
+
 import httpx
 
-BASE_URL = "https://ccglobal.openearth.dev"
+BASE_URL = os.getenv("GLOBALAPI_BASE_URL", "https://ccglobal.openearth.dev").rstrip("/")
 
 
 def get_health() -> dict:
@@ -72,17 +74,60 @@ def get_catalogue(format: str = None) -> dict:
     Get the data catalogue from CityCatalyst Global API.
     
     Args:
-        format: Optional format parameter (e.g., "csv")
+        format: Optional format parameter (e.g., "csv"). When "csv", returns raw text.
     
     Returns:
-        dict: Catalogue data with list of datasources
+        dict or str: Catalogue data with list of datasources, or CSV text if format="csv"
     """
     params = {"format": format} if format else {}
     response = httpx.get(f"{BASE_URL}/api/v0/catalogue", params=params, timeout=10.0)
     response.raise_for_status()
+    if format and str(format).lower() == "csv":
+        # Endpoint returns CSV when format=csv; surface the raw text instead of JSON parsing.
+        return response.text
+    return response.json()
+
+
+def get_cities_by_country(country_code: str) -> dict:
+    """
+    Get a list of cities (locodes) for a given country.
+
+    Args:
+        country_code: ISO alpha-2 country code (e.g., "BR", "AR")
+
+    Returns:
+        dict: Response from the /api/v0/ccra/city/{country_code} endpoint.
+    """
+    response = httpx.get(f"{BASE_URL}/api/v0/ccra/city/{country_code}", timeout=10.0)
+    response.raise_for_status()
     return response.json()
 
 
+def list_available_country_codes(prefer_iso2: bool = True) -> list[str]:
+    """
+    Derive available country codes from the catalogue.
+
+    Args:
+        prefer_iso2: When True, return only 2-letter codes; otherwise include any codes seen.
+
+    Returns:
+        Sorted list of unique country codes present in catalogue datasources.
+    """
+    catalogue = get_catalogue()
+    datasources = catalogue.get("datasources", []) if isinstance(catalogue, dict) else []
+    codes = set()
+    for ds in datasources:
+        loc = str(ds.get("geographical_location", "")).strip()
+        if not loc:
+            continue
+        # Some entries might have mixed or longer strings; optionally filter to ISO2 length
+        if prefer_iso2 and len(loc) == 2:
+            codes.add(loc.upper())
+        elif not prefer_iso2:
+            codes.add(loc.upper())
+    return sorted(codes)
+
+
 def get_gpc_reference_numbers_by_source(source: str) -> list:
     """
     Get all GPC reference numbers covered by a particular source.
@@ -120,3 +165,84 @@ def get_gpc_reference_numbers_by_source(source: str) -> list:
 
     return sorted(list(gpc_refs))
 
+
+def list_datasources(filter_text: str | None = None) -> list[dict]:
+    """
+    List datasources from the catalogue with key metadata for discovery.
+
+    Args:
+        filter_text: Optional case-insensitive filter applied to publisher_id,
+            datasource_name, or api_endpoint.
+
+    Returns:
+        list of dicts: Each entry contains publisher_id (source), gpc_reference_number,
+        start/end/latest years, spatial_resolution, geographical_location,
+        and api_endpoint.
+    """
+    catalogue = get_catalogue()
+    datasources = catalogue.get("datasources", []) if isinstance(catalogue, dict) else []
+    results: list[dict] = []
+    needle = filter_text.lower() if filter_text else None
+
+    for ds in datasources:
+        publisher_id = ds.get("publisher_id", "")
+        datasource_name = ds.get("datasource_name", "")
+        api_endpoint = ds.get("api_endpoint", "")
+        if needle:
+            blob = f"{publisher_id} {datasource_name} {api_endpoint}".lower()
+            if needle not in blob:
+                continue
+
+        results.append(
+            {
+                "publisher_id": publisher_id,
+                "datasource_name": datasource_name,
+                "gpc_reference_number": ds.get("gpc_reference_number"),
+                "start_year": ds.get("start_year"),
+                "end_year": ds.get("end_year"),
+                "latest_accounting_year": ds.get("latest_accounting_year"),
+                "spatial_resolution": ds.get("spatial_resolution"),
+                "geographical_location": ds.get("geographical_location"),
+                "api_endpoint": api_endpoint,
+            }
+        )
+
+    return results
+
+
+def get_source_years(source: str) -> dict | None:
+    """
+    Get year coverage for a datasource by matching catalogue entries.
+
+    Args:
+        source: Source identifier (matches publisher_id, datasource_name, or api_endpoint).
+
+    Returns:
+        dict with start_year, end_year, latest_accounting_year, and gpc_reference_number,
+        or None if no match is found.
+    """
+    catalogue = get_catalogue()
+    datasources = catalogue.get("datasources", []) if isinstance(catalogue, dict) else []
+    source_upper = source.upper()
+
+    for ds in datasources:
+        publisher_id = str(ds.get("publisher_id", ""))
+        datasource_name = str(ds.get("datasource_name", ""))
+        api_endpoint = str(ds.get("api_endpoint", ""))
+        if (
+            source_upper in publisher_id.upper()
+            or source_upper in datasource_name.upper()
+            or source_upper in api_endpoint.upper()
+        ):
+            return {
+                "publisher_id": publisher_id,
+                "datasource_name": datasource_name,
+                "gpc_reference_number": ds.get("gpc_reference_number"),
+                "start_year": ds.get("start_year"),
+                "end_year": ds.get("end_year"),
+                "latest_accounting_year": ds.get("latest_accounting_year"),
+                "geographical_location": ds.get("geographical_location"),
+            }
+
+    return None
+