# NestJS MCP Agent API

Prueba de concepto para entender cómo exponer lógica de un backend NestJS a agentes de IA mediante **Model Context Protocol (MCP)**.

La intención fue mantener el proyecto pequeño: la misma lógica de negocio puede ser consumida desde una API REST tradicional o desde un cliente/agente compatible con MCP.

## Arquitectura

```text
                 ┌─────────────────┐
                 │   Agente / IA   │
                 └────────┬────────┘
                          │ MCP
                 ┌────────▼────────┐
                 │   MCP Server    │
                 │ 3 herramientas │
                 └────────┬────────┘
                          │
        ┌─────────────────▼─────────────────┐
        │          Servicios NestJS         │
        ├────────────┬────────────┬─────────┤
        │ Clientes   │ Productos  │Solicitudes│
        └─────┬──────┴─────┬──────┴────┬────┘
              │            │           │
          REST API       datos mock  lógica demo
```

## Herramientas MCP

- `consultar_cliente`: busca un cliente por ID.
- `listar_productos`: lista productos y puede filtrar los disponibles.
- `crear_solicitud`: registra una solicitud simple.

El punto importante es que las tools **no duplican la lógica de negocio**. MCP llama a los mismos servicios que utilizan los controllers REST.

## Requisitos

- Node.js 20 o superior.
- npm.

## Instalación

```bash
npm install
```

## Ejecutar API REST

```bash
npm run start:dev
```

Ejemplos:

```bash
curl http://localhost:3000/clientes/1
curl "http://localhost:3000/productos?disponibles=true"
curl -X POST http://localhost:3000/solicitudes \
  -H "Content-Type: application/json" \
  -d '{"clienteId":1,"productoId":101,"detalle":"Quiero información del plan"}'
```

## Ejecutar servidor MCP

```bash
npm run start:mcp
```

El servidor usa transporte **stdio**, pensado para que un host MCP lo levante como proceso local.

Ejemplo conceptual de configuración de un cliente MCP:

```json
{
  "mcpServers": {
    "nestjs-demo": {
      "command": "npm",
      "args": ["run", "start:mcp"],
      "cwd": "/ruta/al/nestjs-mcp-agent-api"
    }
  }
}
```

> La ubicación exacta de esta configuración depende del cliente MCP utilizado.

## Probar

```bash
npm test
npm run build
```

## ¿Por qué este proyecto?

Normalmente una API se diseña pensando en un frontend u otros servicios. MCP permite agregar otro consumidor: un agente de IA capaz de descubrir y ejecutar herramientas con contratos definidos.

Para mí, lo interesante no es reemplazar REST, sino reutilizar un backend existente y controlar qué operaciones se exponen a un agente.

## Próximos pasos

Este repositorio es intencionalmente simple. Una evolución natural sería agregar autenticación, permisos por tool, PostgreSQL, auditoría y un transporte HTTP para escenarios remotos.

## Tecnologías

NestJS · TypeScript · MCP · Zod · Jest

## Licencia

MIT