incident-assistant — MCP "Hola Mundo"

Un servidor MCP (Model Context Protocol) de prueba, construido siguiendo el ejercicio de "respuesta a incidentes" del libro/curso de MCP — con la diferencia de que aquí está conectado a Claude Code como cliente en lugar de Gemini CLI.

El servidor simula un panel de alertas para un sistema de producción y expone:

• Un recurso (resource://incidents/active) con la lista de alertas activas (datos simulados).

• Una herramienta (resolve_incident) que "reinicia" un servicio para resolver una alerta, con una tasa de éxito simulada del 80% (para que también puedas ver la ruta de fallo).

Fuente: src/index.ts

Stack

• @modelcontextprotocol/sdk — SDK oficial de MCP para TypeScript/Node.

• Transporte stdio (el cliente lanza el servidor como subproceso y se comunican por stdin/stdout).

• TypeScript compilado a dist/ (ver tsconfig.json).

1. Instalar y compilar

npm install
npx tsc

Esto compila src/index.ts → dist/index.js (el punto de entrada que inicia el servidor).

Nota: console.error se usa para el registro dentro del servidor a propósito — stdout está reservado para el protocolo MCP JSON-RPC, por lo que cualquier console.log ahí rompería la comunicación con el cliente.

2. Registrar el servidor con Claude Code

A diferencia del libro (que usa settings.json de Gemini CLI), en Claude Code un servidor MCP local se registra con el comando claude mcp add:

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

Puntos clave:

• El -- separa las banderas propias de claude mcp add del comando real que inicia el servidor.

• Se usa una ruta absoluta a dist/index.js (una ruta relativa se resolvería contra el directorio desde el que se lanzó claude, no contra la ubicación de .mcp.json).

• --scope project guarda la configuración en .mcp.json en la raíz del repositorio (versionable en git). Alternativas: --scope local (privado para mí, no compartido) o --scope user (disponible en todos mis proyectos, guardado en ~/.claude.json).

Esto genera un .mcp.json local con la ruta absoluta de tu máquina incrustada. Dado que esa ruta es específica de tu configuración, .mcp.json en sí está en gitignore — el repositorio incluye .mcp.json.example en su lugar, mostrando la forma esperada con una ruta de marcador de posición:

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

3. Aprobar el servidor

Como .mcp.json es un archivo de proyecto (podría venir de un repositorio compartido), Claude Code pide aprobación explícita la primera vez:

claude

Al iniciar, muestra una solicitud de confianza para incident-assistant — acéptala una vez por proyecto (a menos que el comando/argumentos del servidor cambien después).

4. Verificar

claude mcp list
claude mcp get incident-assistant

Salida esperada una vez aprobado:

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

Dentro de una sesión de claude, /mcp lista las herramientas/recursos disponibles del servidor.

5. Demo — resultado real

Prompt al agente: "¿hay alguna alerta crítica? Si es así, intenta arreglarlas y dime el resultado"

El agente:

1. Listó los recursos MCP disponibles (listMcpResources) y encontró resource://incidents/active.

2. Leyó ese recurso (readMcpResource) y obtuvo las alertas simuladas:

   ID	Servicio	Estado	Mensaje
   ALRT-001	auth-api	🔴 CRÍTICO	Fuga de memoria detectada
   ALRT-002	payment-gateway	🟡 ADVERTENCIA (no crítica)	Latencia > 500ms

3. Identificó que solo ALRT-001 es crítica y llamó a la herramienta resolve_incident con serviceName: "auth-api".

4. Resultado:

   ✅ Arreglado: auth-api se reinició correctamente para eliminar la fuga de memoria (ALRT-001, CRÍTICO). El reinicio se realizó con éxito.

   ⚠️ No tocado: payment-gateway sigue mostrando una ADVERTENCIA (latencia > 500ms), pero eso no es crítico, así que se dejó como estaba.

   Nota del agente: un reinicio elimina el síntoma, no necesariamente la causa raíz — vale la pena vigilar la memoria de auth-api para confirmar que la fuga no reaparece.

5. Cuando se le pide explícitamente "reinicia también payment-gateway", el agente llama a resolve_incident de nuevo con serviceName: "payment-gateway" (el resultado exacto no se registra aquí, ya que depende de la tasa de éxito simulada del 80% — puede devolver ✅ o ❌ FALLO).

Esto confirma el bucle completo: cliente MCP (Claude Code) → descubrimiento de recursos/herramientas → lectura de un recurso → decisión → invocación de herramienta → resultado.

Créditos

Este ejercicio está basado en / aprendido de maliksahil/mcp-incident-assistant. El tutorial original usa Gemini CLI como cliente MCP; este repositorio adapta el mismo servidor para usarse con Claude Code en su lugar.

Notas / advertencias

• El servidor se ejecuta bajo WSL; dado que Claude Code también se lanza desde una terminal WSL en esta configuración, las rutas en .mcp.json son rutas nativas de Linux (p. ej. /home/<user>/...), no rutas UNC de Windows (\\wsl.localhost\...).

• Si se edita src/index.ts, hay que recompilarlo (npx tsc) antes de que el cambio surta efecto — el servidor arranca desde dist/index.js, no directamente desde el archivo .ts.

• resolve_incident tiene una tasa de éxito simulada deliberadamente del 80% (Math.random() > 0.2), para que puedas observar cómo el agente maneja tanto el caso de éxito como el de fallo (isError: true).