GCP Stateless MCP Server

Tilaton Model Context Protocol (MCP) -palvelin Google Cloud Run -alustalle. Toimii dynaamisena välityspalvelimena GCP:n kaikkiin REST API -rajapintoihin Discovery Servicen kautta.

Arkkitehtuuri

Palvelin käyttää tilatonta Streamable HTTP -transporttia (StreamableHTTPServerTransport). Tilattomuus tarkoittaa, ettei pyyntöjen välillä säily tilaa — jokainen HTTP-pyyntö on itsenäinen. Tämä mahdollistaa Cloud Runin scale-to-zero -käytön ilman session affinity -vaatimusta.

JSON-RPC-viestit reititetään manuaalisesti ilman SDK:n McpServer-luokkaa, mikä antaa täyden kontrollin protokollan käsittelystä.

Tarjotut työkalut

Tyypillinen käyttöketju

1. list_gcp_apis { filter: "run" }
   → [{ name: "run", version: "v2", ... }]

2. describe_gcp_api { api: "run", version: "v2" }
   → [{ id: "projects.locations.services.list", httpMethod: "GET", ... }]

3. call_gcp_api {
     api: "run", version: "v2",
     method_id: "projects.locations.services.list",
     path_params: { projectsId: "my-project", locationsId: "europe-north1" }
   }
   → { services: [...] }

Tiedostorakenne

gcp-stateless-mcp/
├── mcp-gcp-server.ts   — palvelimen pääkoodi (TypeScript)
├── Dockerfile          — monivaiheinen konttikuva
├── service.yaml        — Cloud Run -palvelun Knative-määritys
├── deploy-mcp.sh       — automaattinen deploy-skripti
├── package.json        — riippuvuudet
├── tsconfig.json       — TypeScript-konfiguraatio
├── README.md           — tämä tiedosto
└── INTEGRATION.md      — asiakasintegraation ohjeet

Käyttöönotto

Aja deploy suorittamalla:

./deploy-mcp.sh

Skripti suorittaa seuraavat vaiheet:

1. Varmistaa pääsyn GCP-projektiin uutisseuranta-activitystreams.

2. Kääntää TypeScript-lähdekoodin ja rakentaa Docker-konttikuvan.

3. Lataa konttikuvan Artifact Registryn mcp-servers-repositorioon.

4. Päivittää Cloud Run -palvelun service.yaml-määrityksen mukaisesti.

IAM-oikeudet

Palvelu on yksityinen (--no-allow-unauthenticated). Kutsujilla täytyy olla roles/run.invoker -rooli.

Oikeuden lisääminen kehittäjälle:

gcloud run services add-iam-policy-binding mcp-gcp-server \
  --region europe-north1 \
  --member="user:jaakko.korhonen@gmail.com" \
  --role="roles/run.invoker" \
  --project=uutisseuranta-activitystreams

Palvelun service accountille tarvitaan oikeudet niihin GCP-resursseihin joita call_gcp_api kutsuu. Esimerkiksi Cloud Run -palveluiden listaukseen:

gcloud projects add-iam-policy-binding uutisseuranta-activitystreams \
  --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" \
  --role="roles/run.viewer"

Lokaalikehitys ja testaus

Ks. INTEGRATION.md asiakasintegraation ohjeista ja lokaalitestauksesta.