Pokémon MCP Agent
Sandbox educativo para entender flujos agénticos de principio a fin.
Un agente de IA que responde preguntas sobre Pokémon conectándose al servidor MCP en vivo de mcp.mcpokedex.com/mcp (https://github.com/ShimaCoding/mcp-pokemon-server). Cada paso del flujo — qué herramienta se invocó, con qué argumentos, qué devolvió y cuánto tardó — se muestra al usuario en tiempo real. Nada es una caja negra.
El backend es FastAPI + Strands Agents SDK (Python). El frontend es una SPA en React con Zustand, CSS Modules y Vite, que consume el stream SSE del backend y actualiza la UI de forma reactiva.
Demo: http://vps22626.cubepath.net / https://mcpokedex.com Repos: https://github.com/ShimaCoding/pokemon-agent https://github.com/ShimaCoding/mcp-pokemon-server
Capturas de pantalla
| Herramientas MCP descubiertas dinámicamente | Respuesta con narración Dexter |
|---|---|
| MCP Tools panel | Dexter narration |
| Trazas del LLM Router con fallback | Admin dashboard |
|---|---|
| Router fallback traces | Admin dashboard |
Conceptos agénticos que ilustra el proyecto
| Concepto | Descripción |
|---|---|
| Tool use & selección dinámica | El modelo decide en cada turno qué herramienta(s) llamar según la intención del usuario, sin lógica hardcodeada. |
| Protocolo MCP | Integración con un servidor MCP real. El agente llama a list_tools_sync() en cada request para descubrir capacidades en tiempo de ejecución. |
| Streaming agéntico con SSE | El frontend consume un flujo start → tool_call → tool_result → text → done, mostrando el razonamiento antes de que la respuesta final esté lista. |
| Fallback multi-proveedor | LiteLLM Router con monkey-patch: Groq → Gemini → OpenAI de forma transparente, sin modificar el SDK de Strands. |
| Panel de trazas en vivo | Cada tool call aparece con spinner → resultado crudo + tiempo transcurrido. Didáctico para entender el ciclo de vida agéntico. |
| Dexter narration skill | Skill de narración que convierte las respuestas del agente en el estilo formal y sarcástico de la Pokédex del Dr. Dexter. |
| Admin dashboard | Panel en /admin que registra cada consulta en SQLite: modelos intentados, tokens, latencia, tools usadas y estado del fallback. |
Quick Start
Con Docker (recomendado)
# 1. Clonar el repositorio
git clone https://github.com/ShimaCoding/pokemon-agent && cd pokemon-agent
# 2. Copiar el fichero de variables de entorno
cp .env.example .env
# 3. Añadir al menos una API key en .env
$EDITOR .env
# 4. Construir e iniciar
docker-compose up --buildAbre http://localhost:8000 en el navegador.
Desarrollo local
# Backend
python -m uvicorn backend.main:app --reload
# Frontend (en otra terminal)
cd frontend && npm install && npm run devAPI Keys
Solo necesitas una para que el agente funcione. El Router hace fallback automático al siguiente proveedor disponible.
| Proveedor | Tier gratuito | Obtener key |
|---|---|---|
| OpenRouter | Sí — multiples modeles completamente gratis | https://platform.openai.com/api-keys |
| Groq | Sí — muy generoso | https://console.groq.com/keys |
| Gemini | Sí — cuota de Google AI Studio | https://aistudio.google.com/app/apikey |
| OpenAI | No — pay-as-you-go | https://platform.openai.com/api-keys |
Arquitectura
browser ──SSE──► FastAPI (backend/main.py)
│
├── Strands Agent (backend/agent.py)
│ ├── LiteLLMModel ← monkey-patched sobre LiteLLM Router
│ └── MCPClient → mcpokedex.com/mcp
│
└── SQLite (admin dashboard en /admin)Módulos del backend:
backend/providers.py— diccionarioPROVIDERScon IDs de modelo y vars de entorno; construye el LiteLLM Router con orden de fallback.backend/agent.py—build_agent()crea el modelo, el MCPClient y parchealitellm.completion/litellm.acompletionglobalmente para enrutar a través del Router.backend/main.py— app FastAPI con lifespan validation. El endpoint/api/agent/runhace streaming SSE:start,tool_call,tool_result,text,done,error.
Frontend React (SPA):
frontend/src/— componentes con CSS Modules, Zustand para estado global, Vite como bundler.IntroModal— modal de bienvenida con ejemplos de queries y descripción de herramientas disponibles.- Panel izquierdo: chat. Panel derecho: trazas de tool calls en tiempo real con vista Pretty/Raw y JSON viewer.
TitleBarcon selector de skill (Dexter narration toggle).
Cómo funciona el panel de trazas
Cuando haces una pregunta, el agente puede invocar una o más herramientas contra el servidor MCP. Cada invocación se reenvía al servidor MCP en mcpokedex.com/mcp; los resultados se devuelven y se alimentan al siguiente turno del modelo.
El panel derecho muestra cada invocación en tiempo real:
- La tarjeta aparece inmediatamente con un spinner.
- El spinner se reemplaza por el resultado en cuanto llega.
- Cada tarjeta muestra: nombre de la herramienta, argumentos, respuesta y tiempo transcurrido.
Todas las llamadas MCP son server-side — el navegador nunca habla directamente con mcpokedex.com.
Admin Dashboard
Disponible en /admin. Registra en SQLite cada consulta con:
- Modelo usado (y cuál fue el fallback)
- Tokens consumidos
- Latencia total
- Herramientas invocadas
- Estado de la respuesta
Útil para observar en tiempo real cómo el Router elige y hace fallback entre Groq, Gemini y OpenAI.
Limitaciones conocidas (MVP)
- Sin historial de sesión — la conversación se reinicia al refrescar la página.
- El monkey-patch de LiteLLM Router funciona para deployments de un solo worker; usar
--workers 1(por defecto en Docker) o refactorizar a instancias por request para concurrencia real. list_tools_sync()es sincrónico y añade ~100–300 ms de latencia por request en la conexión inicial al MCP.
Despliegue en CubePath
El proyecto está dockerizado con Dockerfile y docker-compose.yml listos para producción:
- Servidor: imagen Docker de FastAPI + Uvicorn desplegada en un servidor nano de CubePath, exponiendo el puerto 8000.
- Variables de entorno: las API keys se configuran como env vars en el panel de CubePath — sin subir el
.env. - Build automático: CubePath construye la imagen desde el
Dockerfiledel repositorio público en cada despliegue. - Dominio HTTPS: CubePath asigna un dominio con TLS automático, sin configurar proxy inverso manualmente.