mcp-agent-toolkit

Demo en vivo: aún no desplegada — prevista en agent.build-with-deepak.com. Este repositorio está completo y verificado localmente (build, lint, 25 pruebas unitarias — incluyendo un round-trip real del protocolo MCP — y 5 pruebas e2e); aún no se ha desplegado ni probado contra un Ollama/Postgres en vivo. Ver Estado.

El problema

La mayoría de las demos de "agentes de IA" son una única llamada a herramienta oculta disfrazada de autonomía. Esta muestra su trabajo: un agente del Model Context Protocol con tres herramientas reales — una base de datos PostgreSQL de comercio de solo lectura, una API meteorológica en vivo y una calculadora — respondiendo preguntas que genuinamente necesitan más de una de ellas ("ingresos totales de clientes de Dubái, y ¿qué tiempo hace allí?"). Cada invocación de herramienta, sus argumentos, su resultado, su latencia y — lo importante — sus fallos y la recuperación del modelo de ellos se transmiten a la pantalla a medida que ocurren.

Related MCP server: MCP Tool Server

Pruébalo

Continuar con cuenta de demo emite una sesión real de 2 horas contra la API real — mismo agente, mismas herramientas, mismos datos. La base de datos de muestra es compartida y de solo lectura, por lo que las sesiones de demo no necesitan limpieza por usuario: nada de lo que haga un visitante puede escribir nada. El registro (datos persistentes por usuario) está en progreso; el botón Register y POST /api/auth/register (501) ambos lo dicen honestamente.

Arquitectura

flowchart TB
    subgraph Browser
        UI[Angular SPA<br/>login → live tool-call timeline]
    end

    subgraph VPS -- host nginx, TLS
        Nginx[nginx :443]
    end

    subgraph "Docker Compose stack"
        Web[web container]
        subgraph API [api container — NestJS]
            Loop[Agent loop]
            Client[MCP Client]
            Server[MCP Server]
        end
        PG[(PostgreSQL<br/>sample dataset<br/>mcp_readonly role)]
    end

    Ollama[Ollama llama3.1 — on the VPS]
    Meteo[Open-Meteo API]

    UI -->|HTTPS| Nginx --> Web -->|/api/*| Loop
    Loop -->|chat + tools| Ollama
    Loop -->|listTools / callTool| Client
    Client <-->|MCP protocol, in-memory transport| Server
    Server -->|query_database| PG
    Server -->|get_weather| Meteo
    Server -->|calculate| Server

El bucle: el modelo recibe la pregunta más los esquemas de herramientas descubiertos por MCP → emite llamadas a herramientas → cada llamada se ejecuta a través del cliente MCP → los resultados (incluidos los errores) vuelven al modelo → repite hasta que responde en prosa o alcanza el límite de pasos (por defecto 6). Cada salto es un evento SSE.

Decisiones clave y compensaciones

Un servidor y cliente MCP reales, en un solo proceso. Las herramientas podrían haber sido funciones simples — el límite del protocolo es el punto. El bucle del agente habla solo con el cliente MCP: descubre herramientas mediante listTools() y las invoca mediante callTool(), exactamente como lo haría contra un servidor externo a través de stdio o HTTP. Mover una herramienta fuera de este proceso cambia una línea de transporte, no al agente. El transporte en memoria mantiene una demo de un solo VPS libre de puertos extra y supervisión de subprocesos, mientras que el SDK aún valida esquemas en ambas direcciones — y la suite de pruebas unitarias ejercita ese apretón de manos real, no un mock.

La inyección SQL se trata como el estado POR DEFECTO, no como un caso límite. El agente escribe SQL a partir de la pregunta en lenguaje natural de un desconocido — eso es entrada no confiable por construcción. Dos capas: un guardia del lado de la aplicación (sql-guard.ts: eliminación de comentarios, una sola sentencia, solo SELECT/WITH, una lista negra de palabras clave que sabe que set_config no es set, y un envoltorio de subconsulta que limita los resultados a 100 filas) falla rápidamente con mensajes que el modelo puede usar; debajo, la consulta se ejecuta como un rol de Postgres dedicado mcp_readonly — permisos solo de SELECT, default_transaction_read_only=on, tiempo de espera de sentencia de 5s — que se mantiene incluso si el guardia tiene un error. Las propias pruebas del guardia documentan su limitación léxica aceptada.

Los errores de herramienta se devuelven al modelo, no se muestran como fallos. Una llamada a herramienta fallida devuelve un resultado isError y entra en la conversación como salida de herramienta. El modelo lee el error, corrige su SQL o elige otra ciudad, y reintenta — y la interfaz anota exactamente eso ("el error vuelve al modelo — observa el siguiente paso"). Ver la recuperación vale más, como evidencia de ingeniería, que nunca fallar.

La calculadora es un parser de 60 líneas, no eval. Una expresión escrita por un LLM entregada a cualquier evaluador de JavaScript convierte una calculadora en una herramienta de ejecución de código. El descenso recursivo con una gramática explícita es la alternativa aburrida y correcta; sus pruebas incluyen 1 + 1; process.exit().

Los pasos del bucle no son streaming; la línea de tiempo es el stream. Si una respuesta del modelo es una llamada a herramienta o la respuesta final solo se sabe cuando está completa, y las respuestas de llamadas a herramienta son cortas. Lo que se transmite en vivo es lo que realmente interesa — las llamadas a herramientas y sus resultados a medida que ocurren. La respuesta final en prosa llega como un solo evento. (Misma decisión de transporte SSE-sobre-POST que la demo del router hermano, mismas razones.)

Open-Meteo para el clima. Gratis y sin clave: una demo pública desatendida con una clave de API de terceros es una fuga esperando a suceder y una factura esperando a acumularse. La compensación — sin SLA — es aceptable porque una caída de la herramienta meteorológica es en sí misma una demostración en vivo de la ruta de manejo de errores.

Conjunto de datos de muestra fijo con IDs fijos. El sembrado usa ON CONFLICT DO NOTHING, por lo que cada arranque converge a los mismos 15 clientes / 12 productos / 32 pedidos en lugar de acumular duplicados. Las ciudades se eligieron para que las preguntas de BD + clima se compongan naturalmente (Dubái, Nueva Delhi, Londres…).

Configuración y reinicio de la base de datos

El esquema, los datos de muestra y los permisos del rol mcp_readonly viven en apps/api/db/schema.sql, aplicados idempotentemente en cada arranque de la API; el rol en sí (contraseña de MCP_READONLY_PASSWORD) se crea en db.service.ts porque CREATE ROLE no puede tomar una contraseña parametrizada. pnpm db:reset elimina las tablas de muestra; el siguiente arranque recrea todo. No hay limpieza rutinaria de datos de demo aquí por diseño — los visitantes no pueden escribir.

Qué cambiaría a escala 100x

El transporte MCP en memoria es lo primero que se mueve: los servidores de herramientas multi-tenant reales se ejecutan como servicios separados (subprocesos stdio o HTTP), con autorización por herramienta y registro de auditoría en el límite del protocolo — este código ya está formado para ese intercambio. El bucle del agente ganaría conversaciones persistentes (una tabla conversations claveada por sesión — la primera característica natural de las cuentas registradas), ejecución paralela de herramientas cuando las llamadas son independientes, y un límite de presupuesto de tokens junto al límite de pasos. Y la herramienta SQL dejaría de exponer SELECT crudo por completo: a escala publicas plantillas de consulta nombradas y parametrizadas y dejas que el modelo llene los parámetros — el patrón de guardia más rol de solo lectura aquí es la versión de tamaño demo de esa idea, no un sustituto.

Configuración local

Node 22+, pnpm; para la experiencia completa, Postgres y un Ollama con un modelo capaz de usar herramientas (ollama pull llama3.1:8b — el llama3 simple no emite llamadas a herramientas de manera confiable).

corepack enable && pnpm install
pnpm dev:api   # :3000
pnpm dev:web   # :4200, proxies /api → :3000

Comprobaciones de puerta:

pnpm --filter api build && pnpm --filter api lint && pnpm --filter api test && pnpm --filter api test:e2e
pnpm --filter web build && pnpm --filter web test

Despliegue en el VPS

1. cp .env.example .env — establece POSTGRES_PASSWORD, MCP_READONLY_PASSWORD y JWT_SECRET (compose se niega a arrancar sin ellos). Confirma que ollama list en el VPS muestra llama3.1:8b.

2. docker compose up -d --build — web se enlaza solo a 127.0.0.1:8092.

3. Instala nginx/agent.build-with-deepak.com.conf en el nginx del host, luego certbot --nginx -d agent.build-with-deepak.com.

4. GET /api/health es la sonda de vivacidad sin autenticación.

Estado

• Servidor y cliente MCP reales sobre el transporte en memoria del SDK, tres herramientas, round-trip del protocolo cubierto por pruebas

• Bucle del agente con línea de tiempo de llamadas a herramientas SSE en vivo, retroalimentación de recuperación de errores, límite de pasos

• Protección SQL de dos capas (guardia + rol de Postgres de solo lectura dedicado)

• Autenticación de cuenta demo de extremo a extremo; registro = 501 honesto próximamente

• Compila, lint, pasa todas las pruebas (API: 25 unitarias + 5 e2e; web: 6)

• Aún no probado contra Ollama/Postgres en vivo — este entorno no tenía ninguno; la ruta de llamada a herramientas de Ollama del bucle del agente en particular necesita una ejecución real con llama3.1 antes de poner esto frente a alguien

• Aún no desplegado

• Registro/cuentas persistentes — en progreso (demo-primero por diseño)