swapi_mcp

Un pequeño proyecto de referencia de extremo a extremo para construir un agente de IA observable: un servidor MCP que envuelve la Star Wars API, un agente Claude que lo maneja y una interfaz de chat web — todo instrumentado con OpenTelemetry y Grafana Cloud (trazas distribuidas, métricas RED, RUM de frontend y observabilidad de IA/agentes).

Existe para mostrar, en una única base de código ejecutable, cómo encajan las piezas — el límite de herramientas de MCP, el bucle de uso de herramientas del agente y el trazado de pila completa desde un clic en el navegador hasta una llamada HTTP upstream y de vuelta.

Qué hay aquí

Dos mitades que se comunican entre sí mediante MCP (stdio):

El servidor MCP (src/index.ts, src/tools/) — envuelve la Star Wars API como 18 herramientas en 6 recursos (people, planets, films, species, vehicles, starships): una search_, una get-all y una get-by-id por recurso. Es un mero proveedor de herramientas; no toma decisiones.

El agente (src/agent/) — el que toma las decisiones:

• mcpClient.ts — lanza el servidor compilado a través de stdio y se conecta como cliente MCP.

• agent.ts — un bucle manual de uso de herramientas: envía la pregunta + las herramientas del servidor a Claude, ejecuta cada herramienta solicitada mediante MCP, devuelve los resultados y repite hasta terminar.

• main.ts — un punto de entrada de CLI.

• server.ts + public/index.html — un servidor HTTP y una interfaz de chat de una sola página.

Related MCP server: SWAPI MCP Server

Observabilidad

Todo lo siguiente es opcional y está controlado por variables de entorno — el agente funciona perfectamente sin nada de eso.

• Trazado distribuido (OpenTelemetry → Tempo): una única traza abarca browser → POST /ask → agent.turn → llm.request / tool.call → tool.execute → swapi.fetch, a través de tres servicios (swapi-web, swapi-agent, swapi-mcp-server). El contexto de la traza se propaga a través del límite de MCP mediante el _meta de la petición.

• Métricas RED (→ Mimir): histogramas de tasa / errores / duración por herramienta y por llamada al LLM, además de un contador de uso de tokens para el coste, etiquetados con model, error y error.type.

• RUM de frontend (Grafana Faro): Web Vitals, errores de JS y propagación de trazas del navegador al backend.

• Observabilidad de IA / agentes (@grafana/agent-o11y): generaciones de LLM normalizadas y ejecuciones de herramientas.

• Inyección de fallos de demostración (src/chaos.ts): opcionalmente hace que un recurso devuelva un 503 simulado y que otro responda un 50% más lento, para que los paneles muestren señales reales de error y latencia.

Requisitos previos

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

• Yarn 4 (mediante Corepack)

• Una clave de API de Anthropic (para el agente)

• Una cuenta de Grafana Cloud (opcional — solo para las funciones de observabilidad)

Configuración

yarn install
yarn build

Usar el servidor MCP directamente (p. ej., Claude Desktop)

Apunta tu cliente MCP al servidor compilado:

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

Ejecutar el agente

Crea un .env (ignorado por Git) con al menos tu clave de Anthropic:

ANTHROPIC_API_KEY=sk-ant-...

Después:

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

Variables de entorno

Notas

Este es un proyecto de aprendizaje / demostración. Los datos provienen de un espejo estático de SWAPI, que modela asociaciones (un personaje "aparece en" una película), no acciones — por lo que las respuestas se formulan en consecuencia.

Licencia

MIT