incident-assistant — MCP „Hallo Welt“

Ein Test-MCP-Server (Model Context Protocol), der der Übung „Incident Response“ aus dem MCP-Buch/-Kurs folgt – mit dem Unterschied, dass er hier an Claude Code als Client angebunden ist, statt an Gemini CLI.

Der Server simuliert ein Alert-Dashboard für ein Produktionssystem und stellt Folgendes bereit:

• Eine Ressource (resource://incidents/active) mit der Liste aktiver Alerts (Mock-Daten).

• Ein Tool (resolve_incident), das einen Dienst „neu startet“, um einen Alert aufzulösen, mit einer simulierten Erfolgsrate von 80 % (damit man auch den Fehlerpfad sehen kann).

Quelle: src/index.ts

Stack

• @modelcontextprotocol/sdk – offizielles MCP-SDK für TypeScript/Node.

• stdio-Transport (der Client startet den Server als Unterprozess und sie kommunizieren über stdin/stdout).

• TypeScript kompiliert nach dist/ (siehe tsconfig.json).

1. Installieren und Builden

npm install
npx tsc

Dies kompiliert src/index.ts → dist/index.js (den Einstiegspunkt, der den Server startet).

Hinweis: console.error wird absichtlich für Logging im Server verwendet – stdout ist für das MCP-JSON-RPC-Protokoll reserviert, sodass jedes console.log dort die Kommunikation mit dem Client stören würde.

2. Server bei Claude Code registrieren

Anders als im Buch (das Gemini CLIs settings.json verwendet), wird ein lokaler MCP-Server in Claude Code mit dem Befehl claude mcp add registriert:

cd /absolute/path/to/incident-assistant
claude mcp add --scope project incident-assistant -- node /absolute/path/to/incident-assistant/dist/index.js

Wichtige Punkte:

• Das -- trennt die eigenen Flags von claude mcp add vom eigentlichen Befehl, der den Server startet.

• Ein absoluter Pfad zu dist/index.js wird verwendet (ein relativer Pfad würde relativ zum Verzeichnis aufgelöst, aus dem claude gestartet wurde, nicht relativ zum Speicherort von .mcp.json).

• --scope project speichert die Konfiguration in .mcp.json im Repository-Stamm (in git versionierbar). Alternativen: --scope local (privat für mich, nicht geteilt) oder --scope user (verfügbar in allen meinen Projekten, gespeichert in ~/.claude.json).

Dies erzeugt eine lokale .mcp.json mit dem absoluten Pfad deiner Maschine. Da dieser Pfad spezifisch für dein Setup ist, ist .mcp.json selbst gitignored – das Repository enthält stattdessen .mcp.json.example, das die erwartete Form mit einem Platzhalterpfad zeigt:

{
  "mcpServers": {
    "incident-assistant": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/incident-assistant/dist/index.js"]
    }
  }
}

3. Server genehmigen

Da .mcp.json eine Projektdatei ist (sie könnte aus einem geteilten Repository stammen), fragt Claude Code beim ersten Mal nach expliziter Genehmigung:

claude

Beim Start zeigt es einen Vertrauenshinweis für incident-assistant – akzeptiere ihn einmal pro Projekt (es sei denn, die Befehle/Argumente des Servers ändern sich später).

4. Überprüfen

claude mcp list
claude mcp get incident-assistant

Erwartete Ausgabe nach der Genehmigung:

incident-assistant: node /absolute/path/to/incident-assistant/dist/index.js - ✔ Connected

Innerhalb einer claude-Sitzung listet /mcp die verfügbaren Tools/Ressourcen des Servers auf.

5. Demo – echtes Ergebnis

Prompt an den Agenten: „Gibt es kritische Alerts? Wenn ja, versuche sie zu beheben und lass mich das Ergebnis wissen“

Der Agent:

1. Listete die verfügbaren MCP-Ressourcen auf (listMcpResources) und fand resource://incidents/active.

2. Las diese Ressource (readMcpResource) und erhielt die Mock-Alerts:

   ID	Service	Status	Message
   ALRT-001	auth-api	🔴 KRITISCH	Speicherleck erkannt
   ALRT-002	payment-gateway	🟡 WARNUNG (nicht kritisch)	Latenz > 500ms

3. Erkannte, dass nur ALRT-001 kritisch ist, und rief das Tool resolve_incident mit serviceName: "auth-api" auf.

4. Ergebnis:

   ✅ Behoben: auth-api wurde sauber neu gestartet, um das Speicherleck zu beseitigen (ALRT-001, KRITISCH). Neustart erfolgreich.

   ⚠️ Nicht angefasst: payment-gateway zeigt weiterhin eine WARNUNG (Latenz > 500ms), aber das ist nicht kritisch, also wurde es so gelassen.

   Hinweis des Agenten: Ein Neustart beseitigt das Symptom, nicht unbedingt die Ursache – es lohnt sich, den Speicher von auth-api im Auge zu behalten, um zu bestätigen, dass das Leck nicht wieder auftritt.

5. Wenn explizit „payment-gateway auch neu starten“ gefragt wird, ruft der Agent resolve_incident erneut mit serviceName: "payment-gateway" auf (das genaue Ergebnis wird hier nicht festgehalten, da es von der simulierten Erfolgsrate von 80 % abhängt – es kann ✅ oder ❌ FEHLER zurückkommen).

Dies bestätigt den vollständigen Kreislauf: MCP-Client (Claude Code) → Ressourcen-/Tool-Erkennung → Lesen einer Ressource → Entscheidung → Tool-Aufruf → Ergebnis.

Danksagungen

Diese Übung basiert auf / wurde gelernt von maliksahil/mcp-incident-assistant. Die ursprüngliche Anleitung verwendet Gemini CLI als MCP-Client; dieses Repository passt denselben Server an, um ihn stattdessen mit Claude Code zu verwenden.

Hinweise / Stolperfallen

• Der Server läuft unter WSL; da Claude Code in diesem Setup ebenfalls aus einem WSL-Terminal gestartet wird, sind Pfade in .mcp.json native Linux-Pfade (z. B. /home/<user>/...), keine Windows-UNC-Pfade (\\wsl.localhost\...).

• Wenn src/index.ts bearbeitet wird, muss es neu gebaut werden (npx tsc), bevor die Änderung wirksam wird – der Server startet von dist/index.js, nicht direkt von der .ts-Datei.

• resolve_incident hat absichtlich eine simulierte Erfolgsrate von 80 % (Math.random() > 0.2), sodass du beobachten kannst, wie der Agent sowohl den Erfolgs- als auch den Fehlerfall (isError: true) behandelt.