Kilkaya Server

Ein MCP-Server (Model Context Protocol) für die Kilkaya-Analytics-API. Er stellt Kilkayas Query-, Schema- und Metadata-Endpunkte als MCP-Tools bereit, läuft über Streamable HTTP (stateless) und ist für das Hosting auf Google Cloud Run ausgelegt.

Tools

Standardmäßig aktiv (read-only):

Tool	Kilkaya-Endpunkt	Beschreibung
kilkaya_query	POST /api/query	Analytics-Query (Haupt-API). Antwort im JSON:API-Format. 202-Antworten („Query queued/running") werden automatisch alle 2,5 s neu gesendet, bis das Ergebnis da ist (Timeout konfigurierbar).
kilkaya_list_schemas	GET /api/schemas	Verfügbare Schemas inkl. Felddefinitionen. allfields ist die verbindliche Liste gültiger Felder, timefields (_minute, _day, _month, …) können als Spalten für Zeitaggregation ergänzt werden.
kilkaya_get_metadata	GET /api/metadata	Metadaten für eine Artikel-URL (ohne Protokoll).
kilkaya_get_metadata_bulk	POST /api/metadata	Metadaten für viele URLs auf einmal.

Optional per Env-Flag:

Tool	Flag	Beschreibung
kilkaya_set_metadata	KILKAYA_ENABLE_WRITE_TOOLS=true	Schreibt/aktualisiert Artikel-Metadaten (POST /api/metadata/set).
kilkaya_list_users, kilkaya_get_user, kilkaya_list_roles, kilkaya_get_role	KILKAYA_ENABLE_ADMIN_TOOLS=true	Read-only User-/Rollen-Verwaltung. Standardmäßig aus, da Userdaten E-Mail-Adressen enthalten.

Destruktive Endpunkte (User/Rollen anlegen, ändern, löschen) sind bewusst nicht als Tools implementiert.

Konfiguration (Umgebungsvariablen)

Variable	Pflicht	Beschreibung
KILKAYA_API_TOKEN	✅	Kilkaya API Access Token. Wird als Authorization: Bearer <token> an die API gesendet. In Cloud Run über Secret Manager setzen, nicht als Klartext-Env.
MCP_AUTH_TOKEN	empfohlen	Shared Secret zum Schutz des /mcp-Endpunkts. Clients müssen Authorization: Bearer <token> mitschicken. Ohne diese Variable ist der Endpunkt ungeschützt — dann Cloud Run nicht mit --allow-unauthenticated deployen.
PORT	–	HTTP-Port (Default 8080; wird von Cloud Run automatisch gesetzt).
KILKAYA_BASE_URL	–	Default https://api.kilkaya.com.
KILKAYA_QUERY_TIMEOUT_MS	–	Wie lange auf ein 202-„Query delayed" gepollt wird (Default 90000). Läuft der Timeout ab, liefert das Tool den Queue-Status zurück; derselbe Query kann einfach erneut abgeschickt werden.
KILKAYA_ENABLE_WRITE_TOOLS	–	true aktiviert kilkaya_set_metadata.
KILKAYA_ENABLE_ADMIN_TOOLS	–	true aktiviert die read-only User-/Rollen-Tools.

Lokal starten

npm install
npm run build
KILKAYA_API_TOKEN=<token> npm start
# Healthcheck
curl http://localhost:8080/healthz

MCP-Endpunkt: POST http://localhost:8080/mcp (Streamable HTTP, stateless — keine Sessions, kein SSE-Stream vom Server; GET/DELETE /mcp antworten mit 405).

Deployment auf Google Cloud Run

PROJECT=<gcp-projekt>
REGION=europe-west3

# 1. Token als Secret hinterlegen
echo -n "<kilkaya-api-token>" | gcloud secrets create kilkaya-api-token \
  --project "$PROJECT" --data-file=-
echo -n "<selbst-generiertes-shared-secret>" | gcloud secrets create kilkaya-mcp-auth-token \
  --project "$PROJECT" --data-file=-

# 2. Bauen & deployen (Cloud Build baut das Dockerfile)
gcloud run deploy kilkaya-mcp \
  --project "$PROJECT" --region "$REGION" \
  --source . \
  --set-secrets "KILKAYA_API_TOKEN=kilkaya-api-token:latest,MCP_AUTH_TOKEN=kilkaya-mcp-auth-token:latest" \
  --allow-unauthenticated \
  --min-instances 0 --max-instances 3 --memory 256Mi

--allow-unauthenticated ist hier okay, weil MCP_AUTH_TOKEN den Endpunkt schützt. Alternativ das Flag weglassen und Cloud-Run-IAM nutzen (Clients senden dann ein Google-ID-Token) — dann kann MCP_AUTH_TOKEN entfallen.

Der Server ist stateless (ein frischer MCP-Server pro Request), daher sind beliebige Instanzzahlen inkl. Scale-to-zero unproblematisch.

Client-Konfiguration

Beispiel für Claude Code (.mcp.json) oder andere MCP-Clients mit Streamable HTTP:

{
  "mcpServers": {
    "kilkaya": {
      "type": "http",
      "url": "https://kilkaya-mcp-<hash>-<region>.a.run.app/mcp",
      "headers": {
        "Authorization": "Bearer <selbst-generiertes-shared-secret>"
      }
    }
  }
}

Beispiel-Query

Typischer Ablauf für ein LLM: erst kilkaya_list_schemas aufrufen, um Schema und gültige Felder zu ermitteln, dann kilkaya_query:

{
  "schemaname": "pageviews",
  "datefrom": "2026-07-01T00:00:00+00:00",
  "dateto": "2026-07-06T00:00:00+00:00",
  "columns": ["url", "pageviews", "section", "_day"],
  "filters": [
    { "column": "url", "operator": "like", "value": "*example.de*" }
  ],
  "sortby": ["pageviews"],
  "sortorder": ["desc"],
  "limit": 100
}

Filter-Operatoren: like, notlike, greater, less. Wildcards mit * (nicht %).

Projektstruktur

src/
  index.ts    – Express-App, Streamable-HTTP-Transport, Auth, /healthz
  server.ts   – MCP-Server- und Tool-Definitionen
  kilkaya.ts  – HTTP-Client für die Kilkaya-API inkl. 202-Polling
Dockerfile    – Multi-Stage-Build (Node 22 Alpine)