swapi_mcp

Ein kleines End-to-End-Referenzprojekt zum Aufbau eines beobachtbaren KI-Agenten: ein MCP-Server, der die Star Wars API kapselt, ein Claude-Agent, der ihn steuert, und eine Web-Chat-UI – alles instrumentiert mit OpenTelemetry und Grafana Cloud (verteilte Traces, RED-Metriken, Frontend-RUM und KI-/Agenten-Beobachtbarkeit).

Es soll in einer einzigen lauffähigen Codebasis zeigen, wie die Teile zusammenspielen – die MCP-Tool-Grenze, die Schleife zur Tool-Nutzung des Agenten und das Full-Stack-Tracing von einem Browserklick bis hinunter zu einem HTTP-Aufruf an einen vorgelagerten Dienst und zurück.

Was ist enthalten

Zwei Hälften, die über MCP (stdio) miteinander kommunizieren:

Der MCP-Server (src/index.ts, src/tools/) – kapselt die Star Wars API als 18 Tools über 6 Ressourcen (Personen, Planeten, Filme, Spezies, Fahrzeuge, Raumschiffe): ein search_, ein get-all und ein get-by-id pro Ressource. Er ist ein reiner Tool-Anbieter; er trifft keine Entscheidungen.

Der Agent (src/agent/) – der Entscheidungsträger:

• mcpClient.ts – startet den gebauten Server über stdio und verbindet sich als MCP-Client.

• agent.ts – eine manuelle Schleife zur Tool-Nutzung: die Frage plus die Tools des Servers an Claude senden, jedes angeforderte Tool über MCP ausführen, Ergebnisse zurückspielen und wiederholen, bis alles erledigt ist.

• main.ts – ein CLI-Einstiegspunkt.

• server.ts + public/index.html – ein HTTP-Server und eine Single-Page-Chat-UI.

Related MCP server: SWAPI MCP Server

Beobachtbarkeit

Alles unten ist optional und über Umgebungsvariablen gesteuert – der Agent läuft auch ganz ohne all das einwandfrei.

• Verteiltes Tracing (OpenTelemetry → Tempo): ein Trace erstreckt sich über browser → POST /ask → agent.turn → llm.request / tool.call → tool.execute → swapi.fetch über drei Dienste (swapi-web, swapi-agent, swapi-mcp-server). Der Trace-Kontext wird über das _meta-Feld der Anfrage über die MCP-Grenze hinweg propagiert.

• RED-Metriken (→ Mimir): Histogramme für Rate, Fehler und Dauer pro Tool und pro LLM-Aufruf sowie ein Token-Verbrauchszähler für Kosten, getaggt mit model, error und error.type.

• Frontend-RUM ([Gra fana Faro](https://gra fana.com/oss/faro/)): Web-Vitals, JS-Fehler und Browser→Backend-Trace-Weitergabe.

• KI-/Agenten-Beobachtbarkeit (@gra fana/agent-o11y): normalisierte LLM-Generierungen und Tool-Ausführungen.

• Demo-Fehlerinjektion (src/chaos.ts): lässt optional eine Ressource einen simulierten 503 zurückgeben und eine andere 50 % langsamer laufen, sodass die Dashboards echte Fehler- und Latenzsignale zeigen.

Voraussetzungen

• Node.js 22+ (verwendet --env-file)

• Yarn 4 (über Corepack)

• Ein Anthropic-API-Schlüssel (für den Agenten)

• Ein Grafana-Cloud-Konto (optional – nur für die Beobachtbarkeitsfunktionen)

Einrichtung

yarn install
yarn build

Den MCP-Server direkt verwenden (z. B. Claude Desktop)

Richten Sie Ihren MCP-Client auf den gebauten Server aus:

{
  "mcpServers": {
    "swapi": { "command": "node", "args": ["/absolute/path/to/swapi_mcp/build/index.js"] }
  }
}

Den Agenten ausführen

Erstellen Sie eine .env (von Git ignoriert) mit mindestens Ihrem Anthropic-API-Schlüssel:

ANTHROPIC_API_KEY=sk-ant-...

Dann:

yarn dev                              # build + serve the web UI at http://localhost:8787
yarn ask "Who is Luke's homeworld?"   # one-shot CLI

Umgebungsvariablen

Hinweise

Dies ist ein Lern-/Demoprojekt. Die Daten stammen aus einem statischen Spiegel von SWAPI, der Assoziationen modelliert (ein Charakter „erscheint in“ einem Film), keine Aktionen – daher sind die Antworten entsprechend formuliert.

Lizenz

MIT