# NestJS MCP Agent API

![NestJS](https://img.shields.io/badge/NestJS-12-E0234E?logo=nestjs&logoColor=white)
![TypeScript](https://img.shields.io/badge/TypeScript-6-3178C6?logo=typescript&logoColor=white)
![Node.js](https://img.shields.io/badge/Node.js-22-339933?logo=nodedotjs&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-6C47FF)
![Jest](https://img.shields.io/badge/Jest-Tests-C21325?logo=jest&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-yellow)

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

La idea principal es simple: reutilizar la misma lógica de negocio desde una API REST tradicional y desde herramientas MCP, sin duplicar los servicios del backend.

## Arquitectura

```text
                         ┌─────────────────┐
                         │   Agente / IA   │
                         └────────┬────────┘
                                  │ MCP
                         ┌────────▼────────┐
                         │   MCP Server    │
                         │     Tools       │
                         └────────┬────────┘
                                  │
                                  │
┌──────────────┐         ┌────────▼────────┐
│ Cliente REST │────────►│ Servicios NestJS│
└──────────────┘         └────────┬────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             ▼             ▼
                Clientes      Productos     Solicitudes
```

REST y MCP reutilizan los mismos servicios de NestJS.

## Herramientas MCP

El servidor expone tres tools:

- `consultar_cliente`: obtiene un cliente por ID.
- `listar_productos`: lista productos y permite filtrar los disponibles.
- `crear_solicitud`: registra una nueva solicitud.

Las tools no contienen una segunda implementación de la lógica de negocio. MCP actúa como una capa de entrada adicional sobre los servicios existentes.

## Stack

- NestJS 12
- TypeScript 6
- Model Context Protocol (MCP)
- Zod
- Jest
- ts-jest

## Requisitos

- Node.js 22 o superior.
- npm.

> Para utilizar la versión actual de MCP Inspector se recomienda mantener Node.js actualizado dentro de la línea 22 o utilizar una versión superior compatible.

## Instalación

```bash
npm install
```

## Ejecutar API REST

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

La API queda disponible por defecto en:

```text
http://localhost:3000
```

### Consultar cliente

```bash
curl http://localhost:3000/clientes/1
```

### Listar productos

```bash
curl http://localhost:3000/productos
```

También es posible solicitar solamente productos disponibles:

```bash
curl "http://localhost:3000/productos?disponibles=true"
```

### Crear solicitud

```bash
curl -X POST http://localhost:3000/solicitudes \
  -H "Content-Type: application/json" \
  -d '{"clienteId":1,"productoId":101,"detalle":"Solicitud de prueba desde la API REST"}'
```

Los DTO y `ValidationPipe` de NestJS validan los datos antes de ejecutar la lógica de negocio.

## Ejecutar servidor MCP

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

El servidor utiliza transporte **stdio**, por lo que queda esperando que un cliente MCP inicie la comunicación mediante entrada y salida estándar.

## Probar con MCP Inspector

Se puede utilizar el Inspector oficial de MCP:

```bash
npx @modelcontextprotocol/inspector@latest
```

Agregar el servidor manualmente con:

```text
Transport: stdio
Command: npm

Arguments:
run
start:mcp

Working directory:
/ruta/al/nestjs-mcp-agent-api
```

Al conectarse, el cliente descubre automáticamente:

```text
consultar_cliente
listar_productos
crear_solicitud
```

Desde Inspector es posible revisar el esquema de entrada de cada tool y ejecutarla sin llamar directamente a los endpoints REST.

## Tests

Ejecutar:

```bash
npm test
```

Actualmente se prueban los servicios utilizados por las tres operaciones principales:

```text
✓ consulta un cliente
✓ filtra productos disponibles
✓ crea una solicitud
```

## Build

```bash
npm run build
```

## ¿Qué demuestra este proyecto?

Normalmente un backend expone su lógica mediante HTTP para aplicaciones frontend u otros servicios.

MCP permite incorporar otro tipo de consumidor:

```text
Aplicación ──REST──┐
                   ├──► Servicios NestJS
Agente IA ──MCP────┘
```

El agente puede descubrir qué herramientas existen, conocer los parámetros que necesita cada una y ejecutarlas utilizando un contrato definido por MCP.

Para mí, lo interesante no es reemplazar REST, sino poder **reutilizar un backend existente y decidir qué capacidades queremos exponer a agentes de IA**.

## Próximos pasos

El proyecto utiliza datos mock intencionalmente para mantener el foco en la integración NestJS + MCP.

Una evolución natural sería incorporar:

- PostgreSQL.
- autenticación.
- autorización y permisos por tool.
- auditoría de operaciones ejecutadas por agentes.
- rate limiting.
- transporte HTTP para escenarios remotos.

## Licencia

MIT