backend-mcp/AI-TOOLS-GUIDE.md

Generador automático de backends con Node.js, Express, Prisma y módulos configurables. Servidor MCP compatible con npx para agentes IA. Soporta PostgreSQL, MySQL, MongoDB y SQLite.

# Guía Completa de Herramientas MCP para IA

## Introducción

Este documento proporciona una guía completa para que los agentes de IA utilicen las herramientas MCP del Backend Generator. Cada herramienta está diseñada para dar control granular sobre aspectos específicos del backend generado.

## Arquitectura del Sistema

```
IA Agent
    ↓
MCP Tools (25+ herramientas)
    ↓
Backend Generator (Orchestrator)
    ↓
Proyecto Backend Completo
```

## Flujo de Trabajo Recomendado

### 1. Configuración Inicial
```json
{
  "tool": "configure_project",
  "params": {
    "projectName": "mi-api",
    "description": "API para gestión de usuarios",
    "author": "Mi Empresa",
    "version": "1.0.0"
  }
}
```

### 2. Configuración de Base de Datos
```json
{
  "tool": "configure_database",
  "params": {
    "provider": "postgresql",
    "enableMigrations": true,
    "enableSeeding": true
  }
}
```

### 3. Definición de Tablas
```json
{
  "tool": "define_table",
  "params": {
    "tableName": "User",
    "fields": [
      {"name": "id", "type": "Int", "required": true, "unique": true},
      {"name": "email", "type": "String", "required": true, "unique": true},
      {"name": "password", "type": "String", "required": true},
      {"name": "role", "type": "String", "defaultValue": "user"},
      {"name": "createdAt", "type": "DateTime", "defaultValue": "now()"}
    ]
  }
}
```

### 4. Configuración de Autenticación
```json
{
  "tool": "setup_auth",
  "params": {
    "strategy": "jwt",
    "providers": ["local"],
    "jwtConfig": {
      "secret": "auto-generate",
      "expiresIn": "24h"
    },
    "roles": ["admin", "user"],
    "permissions": [
      {
        "resource": "users",
        "actions": ["create", "read", "update", "delete"],
        "roles": ["admin"]
      }
    ]
  }
}
```

### 5. Añadir Módulos
```json
{
  "tool": "add_module",
  "params": {
    "moduleName": "crud",
    "config": {
      "entities": ["User", "Product"],
      "enableSoftDelete": true,
      "enablePagination": true
    }
  }
}
```

### 6. Crear Endpoints Personalizados
```json
{
  "tool": "create_endpoint",
  "params": {
    "path": "/api/users/profile",
    "method": "GET",
    "controller": "getUserProfile",
    "middleware": ["auth", "validateUser"],
    "requiresAuth": true,
    "roles": ["user", "admin"]
  }
}
```

### 7. Validación y Generación
```json
{
  "tool": "validate_config",
  "params": {
    "strict": true,
    "checkDependencies": true
  }
}
```

```json
{
  "tool": "generate_project",
  "params": {
    "outputPath": "./mi-proyecto",
    "installDependencies": true,
    "runMigrations": true,
    "generateDocs": true
  }
}
```

## Catálogo Completo de Herramientas

### 🔧 Configuración de Proyecto

#### `configure_project`
**Propósito**: Establece la configuración base del proyecto

**Parámetros Requeridos**:
- `projectName`: Nombre del proyecto
- `description`: Descripción del proyecto

**Parámetros Opcionales**:
- `version`: Versión (default: "1.0.0")
- `author`: Autor del proyecto
- `license`: Licencia (default: "MIT")
- `nodeVersion`: Versión mínima de Node.js
- `packageManager`: npm, yarn, o pnpm

**Ejemplo de Uso**:
```json
{
  "projectName": "ecommerce-backend",
  "description": "Backend completo para e-commerce",
  "author": "Mi Empresa",
  "license": "MIT",
  "nodeVersion": ">=18.0.0"
}
```

### 📦 Gestión de Módulos

#### `add_module`
**Propósito**: Añade módulos específicos al proyecto

**Módulos Disponibles**:
- `auth`: Sistema de autenticación
- `database`: Configuración de base de datos
- `crud`: Operaciones CRUD automáticas
- `email`: Sistema de emails
- `logging`: Sistema de logs
- `websockets`: Comunicación en tiempo real
- `cache`: Sistema de caché
- `monitoring`: Monitoreo y métricas
- `validation`: Validación de datos
- `notifications`: Sistema de notificaciones
- `docker`: Contenedores Docker
- `ci`: Integración continua
- `testing`: Framework de testing

**Configuraciones por Módulo**:

##### Auth Module
```json
{
  "moduleName": "auth",
  "config": {
    "jwtSecret": "auto-generate",
    "tokenExpiry": "24h",
    "roles": ["admin", "user", "moderator"],
    "enableRefreshTokens": true,
    "enablePasswordReset": true,
    "enableEmailVerification": true
  }
}
```

##### CRUD Module
```json
{
  "moduleName": "crud",
  "config": {
    "entities": ["User", "Product", "Order"],
    "enableSoftDelete": true,
    "enablePagination": true,
    "enableFiltering": true,
    "enableSorting": true,
    "defaultPageSize": 20
  }
}
```

##### Email Module
```json
{
  "moduleName": "email",
  "config": {
    "provider": "smtp",
    "templates": ["welcome", "password-reset", "verification"],
    "enableQueue": true,
    "retryAttempts": 3
  }
}
```

### 🗄️ Base de Datos

#### `configure_database`
**Propósito**: Configura la conexión y configuración de base de datos con soporte completo para URLs de conexión

**Proveedores Soportados**:
- `postgresql`: PostgreSQL
- `mysql`: MySQL/MariaDB
- `sqlite`: SQLite
- `mongodb`: MongoDB

**Métodos de Configuración**:
1. **URL de Conexión** (Recomendado): Proporciona una URL completa de conexión
2. **Parámetros Individuales**: Especifica host, puerto, base de datos, usuario y contraseña por separado

**Parámetros Disponibles**:
- `provider`: Proveedor de base de datos (requerido)
- `url`: URL completa de conexión (alternativa a parámetros individuales)
- `host`: Host de la base de datos
- `port`: Puerto de la base de datos
- `database`: Nombre de la base de datos
- `username`: Usuario de la base de datos
- `password`: Contraseña de la base de datos
- `schema`: Esquema de la base de datos (para PostgreSQL, default: "public")
- `ssl`: Habilitar SSL (default: false)
- `enableMigrations`: Habilitar migraciones (default: true)
- `enableSeeding`: Habilitar datos de prueba (default: true)
- `poolSize`: Tamaño del pool de conexiones (default: 10)
- `connectionTimeout`: Timeout de conexión en ms (default: 30000)
- `queryTimeout`: Timeout de consulta en ms (default: 60000)

**Ejemplo con URL de PostgreSQL**:
```json
{
  "provider": "postgresql",
  "url": "postgresql://username:password@localhost:5432/database_name?schema=public",
  "enableMigrations": true,
  "enableSeeding": true,
  "poolSize": 15,
  "connectionTimeout": 30000,
  "queryTimeout": 60000,
  "ssl": false
}
```

**Ejemplo con Parámetros Individuales**:
```json
{
  "provider": "postgresql",
  "host": "localhost",
  "port": 5432,
  "database": "rental_management_db",
  "username": "postgres",
  "password": "mypassword",
  "schema": "public",
  "ssl": false,
  "enableMigrations": true,
  "poolSize": 10
}
```

**Ejemplos para Otros Proveedores**:

**MySQL**:
```json
{
  "provider": "mysql",
  "url": "mysql://user:password@localhost:3306/mydb",
  "poolSize": 15
}
```

**SQLite**:
```json
{
  "provider": "sqlite",
  "url": "file:./dev.db",
  "enableMigrations": true
}
```

**MongoDB**:
```json
{
  "provider": "mongodb",
  "url": "mongodb://username:password@localhost:27017/mydb",
  "poolSize": 20
}
```

#### `define_table`
**Propósito**: Define tablas/modelos en la base de datos

**Tipos de Campo Soportados**:
- `String`: Texto
- `Int`: Número entero
- `Float`: Número decimal
- `Boolean`: Verdadero/Falso
- `DateTime`: Fecha y hora
- `Json`: Datos JSON

**Tipos de Relación**:
- `oneToOne`: Uno a uno
- `oneToMany`: Uno a muchos
- `manyToMany`: Muchos a muchos

**Ejemplo Completo**:
```json
{
  "tableName": "Product",
  "fields": [
    {"name": "id", "type": "Int", "required": true, "unique": true},
    {"name": "name", "type": "String", "required": true},
    {"name": "price", "type": "Float", "required": true},
    {"name": "description", "type": "String"},
    {"name": "inStock", "type": "Boolean", "defaultValue": "true"},
    {"name": "metadata", "type": "Json"},
    {"name": "createdAt", "type": "DateTime", "defaultValue": "now()"}
  ],
  "relations": [
    {
      "type": "manyToMany",
      "relatedTable": "Category",
      "foreignKey": "categoryId"
    },
    {
      "type": "oneToMany",
      "relatedTable": "Review",
      "foreignKey": "productId"
    }
  ]
}
```

### 🔐 Autenticación

#### `setup_auth`
**Propósito**: Configura el sistema de autenticación completo

**Estrategias Disponibles**:
- `jwt`: JSON Web Tokens
- `session`: Sesiones del servidor
- `oauth`: OAuth 2.0

**Proveedores OAuth**:
- `local`: Autenticación local
- `google`: Google OAuth
- `github`: GitHub OAuth
- `facebook`: Facebook OAuth

**Ejemplo Completo**:
```json
{
  "strategy": "jwt",
  "providers": ["local", "google"],
  "jwtConfig": {
    "secret": "mi-secreto-super-seguro",
    "expiresIn": "24h",
    "algorithm": "HS256"
  },
  "roles": ["admin", "user", "moderator"],
  "permissions": [
    {
      "resource": "users",
      "actions": ["create", "read", "update", "delete"],
      "roles": ["admin"]
    },
    {
      "resource": "products",
      "actions": ["read"],
      "roles": ["user", "admin", "moderator"]
    },
    {
      "resource": "products",
      "actions": ["create", "update", "delete"],
      "roles": ["admin", "moderator"]
    }
  ]
}
```

### 🌐 API Endpoints

#### `create_endpoint`
**Propósito**: Crea endpoints personalizados de API

**Métodos HTTP Soportados**:
- `GET`: Obtener datos
- `POST`: Crear datos
- `PUT`: Actualizar datos completos
- `PATCH`: Actualizar datos parciales
- `DELETE`: Eliminar datos

**Middleware Disponible**:
- `auth`: Verificación de autenticación
- `cors`: Configuración CORS
- `rateLimit`: Limitación de velocidad
- `validation`: Validación de datos
- `logging`: Registro de solicitudes

**Ejemplo Completo**:
```json
{
  "path": "/api/products/search",
  "method": "POST",
  "controller": "searchProducts",
  "middleware": ["auth", "validation", "rateLimit"],
  "validation": {
    "body": {
      "query": {"type": "string", "required": true},
      "filters": {"type": "object"},
      "page": {"type": "number", "default": 1},
      "limit": {"type": "number", "default": 20}
    }
  },
  "response": {
    "success": {
      "products": "array",
      "total": "number",
      "page": "number",
      "totalPages": "number"
    },
    "error": {
      "message": "string",
      "code": "string"
    }
  },
  "requiresAuth": true,
  "roles": ["user", "admin"]
}
```

### 📧 Email y Notificaciones

#### `setup_email`
**Propósito**: Configura el sistema de emails

**Proveedores Soportados**:
- `smtp`: Servidor SMTP personalizado
- `sendgrid`: SendGrid
- `mailgun`: Mailgun
- `ses`: Amazon SES

**Ejemplo SMTP**:
```json
{
  "provider": "smtp",
  "config": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "auth": {
      "user": "mi-email@gmail.com",
      "pass": "mi-password"
    }
  },
  "templates": [
    {
      "name": "welcome",
      "subject": "¡Bienvenido a nuestra plataforma!",
      "htmlTemplate": "<h1>Bienvenido {{name}}</h1>",
      "textTemplate": "Bienvenido {{name}}"
    },
    {
      "name": "password-reset",
      "subject": "Restablecer contraseña",
      "htmlTemplate": "<p>Haz clic <a href='{{resetLink}}'>aquí</a> para restablecer tu contraseña</p>",
      "textTemplate": "Visita este enlace para restablecer tu contraseña: {{resetLink}}"
    }
  ]
}
```

### 🔌 WebSockets

#### `setup_websockets`
**Propósito**: Configura comunicación en tiempo real

**Ejemplo Completo**:
```json
{
  "enabled": true,
  "port": 3001,
  "cors": {
    "origin": "http://localhost:3000",
    "credentials": true
  },
  "events": [
    {
      "name": "join-room",
      "handler": "handleJoinRoom",
      "requiresAuth": true
    },
    {
      "name": "send-message",
      "handler": "handleSendMessage",
      "requiresAuth": true
    },
    {
      "name": "typing",
      "handler": "handleTyping",
      "requiresAuth": false
    }
  ],
  "rooms": ["general", "support", "announcements"]
}
```

### 💾 Cache

#### `setup_cache`
**Propósito**: Configura el sistema de caché

**Proveedores Soportados**:
- `redis`: Redis
- `memory`: Caché en memoria
- `memcached`: Memcached

**Ejemplo Redis**:
```json
{
  "provider": "redis",
  "config": {
    "host": "localhost",
    "port": 6379,
    "password": "mi-password",
    "db": 0
  },
  "defaultTTL": 3600,
  "strategies": [
    {
      "key": "user-profile-*",
      "ttl": 1800,
      "invalidateOn": ["user-update", "user-delete"]
    },
    {
      "key": "product-list",
      "ttl": 600,
      "invalidateOn": ["product-create", "product-update", "product-delete"]
    }
  ]
}
```

### 📊 Monitoreo

#### `setup_monitoring`
**Propósito**: Configura monitoreo y métricas

**Métricas Disponibles**:
- `requests`: Solicitudes HTTP
- `errors`: Errores de aplicación
- `performance`: Rendimiento
- `database`: Métricas de base de datos
- `memory`: Uso de memoria
- `cpu`: Uso de CPU

**Ejemplo Completo**:
```json
{
  "enabled": true,
  "metrics": ["requests", "errors", "performance", "database"],
  "alerts": [
    {
      "metric": "error-rate",
      "threshold": 5,
      "action": "send-email"
    },
    {
      "metric": "response-time",
      "threshold": 1000,
      "action": "log-warning"
    }
  ],
  "dashboards": true
}
```

### 🐳 Docker

#### `setup_docker`
**Propósito**: Configura contenedores Docker

**Ejemplo Completo**:
```json
{
  "enabled": true,
  "baseImage": "node:18-alpine",
  "services": [
    {
      "name": "postgres",
      "image": "postgres:15",
      "ports": ["5432:5432"],
      "environment": {
        "POSTGRES_DB": "myapp",
        "POSTGRES_USER": "user",
        "POSTGRES_PASSWORD": "password"
      }
    },
    {
      "name": "redis",
      "image": "redis:7-alpine",
      "ports": ["6379:6379"]
    }
  ],
  "volumes": ["./data:/var/lib/postgresql/data"],
  "networks": ["app-network"]
}
```

### 🧪 Testing

#### `setup_testing`
**Propósito**: Configura el framework de testing

**Frameworks Soportados**:
- `jest`: Jest
- `mocha`: Mocha
- `vitest`: Vitest

**Tipos de Test**:
- `unit`: Tests unitarios
- `integration`: Tests de integración
- `e2e`: Tests end-to-end

**Ejemplo Completo**:
```json
{
  "framework": "jest",
  "coverage": true,
  "testTypes": ["unit", "integration", "e2e"],
  "mocking": true,
  "fixtures": true
}
```

## Patrones de Uso Comunes

### 🛒 E-commerce Completo

```json
[
  {
    "tool": "configure_project",
    "params": {
      "projectName": "ecommerce-api",
      "description": "API completa para e-commerce"
    }
  },
  {
    "tool": "configure_database",
    "params": {"provider": "postgresql"}
  },
  {
    "tool": "define_table",
    "params": {
      "tableName": "User",
      "fields": [
        {"name": "id", "type": "Int", "required": true, "unique": true},
        {"name": "email", "type": "String", "required": true, "unique": true},
        {"name": "password", "type": "String", "required": true},
        {"name": "role", "type": "String", "defaultValue": "customer"}
      ]
    }
  },
  {
    "tool": "define_table",
    "params": {
      "tableName": "Product",
      "fields": [
        {"name": "id", "type": "Int", "required": true, "unique": true},
        {"name": "name", "type": "String", "required": true},
        {"name": "price", "type": "Float", "required": true},
        {"name": "stock", "type": "Int", "defaultValue": "0"}
      ]
    }
  },
  {
    "tool": "define_table",
    "params": {
      "tableName": "Order",
      "fields": [
        {"name": "id", "type": "Int", "required": true, "unique": true},
        {"name": "userId", "type": "Int", "required": true},
        {"name": "total", "type": "Float", "required": true},
        {"name": "status", "type": "String", "defaultValue": "pending"}
      ],
      "relations": [
        {"type": "oneToMany", "relatedTable": "User", "foreignKey": "userId"}
      ]
    }
  },
  {
    "tool": "setup_auth",
    "params": {
      "strategy": "jwt",
      "roles": ["admin", "customer"],
      "providers": ["local"]
    }
  },
  {
    "tool": "add_module",
    "params": {"moduleName": "crud"}
  },
  {
    "tool": "add_module",
    "params": {"moduleName": "email"}
  },
  {
    "tool": "setup_cache",
    "params": {"provider": "redis"}
  },
  {
    "tool": "generate_project",
    "params": {"installDependencies": true}
  }
]
```

### 📝 Blog API

```json
[
  {
    "tool": "configure_project",
    "params": {
      "projectName": "blog-api",
      "description": "API para blog con comentarios"
    }
  },
  {
    "tool": "configure_database",
    "params": {"provider": "postgresql"}
  },
  {
    "tool": "define_table",
    "params": {
      "tableName": "Post",
      "fields": [
        {"name": "id", "type": "Int", "required": true, "unique": true},
        {"name": "title", "type": "String", "required": true},
        {"name": "content", "type": "String", "required": true},
        {"name": "published", "type": "Boolean", "defaultValue": "false"},
        {"name": "authorId", "type": "Int", "required": true}
      ]
    }
  },
  {
    "tool": "define_table",
    "params": {
      "tableName": "Comment",
      "fields": [
        {"name": "id", "type": "Int", "required": true, "unique": true},
        {"name": "content", "type": "String", "required": true},
        {"name": "postId", "type": "Int", "required": true},
        {"name": "authorId", "type": "Int", "required": true}
      ]
    }
  },
  {
    "tool": "setup_auth",
    "params": {
      "strategy": "jwt",
      "roles": ["admin", "author", "reader"]
    }
  },
  {
    "tool": "add_module",
    "params": {"moduleName": "crud"}
  },
  {
    "tool": "generate_project",
    "params": {"installDependencies": true}
  }
]
```

## Validación y Errores

### Validación Automática
Cada herramienta valida automáticamente:
- Parámetros requeridos
- Tipos de datos
- Valores permitidos (enums)
- Dependencias entre configuraciones

### Errores Comunes

1. **Parámetros faltantes**:
```json
{
  "error": "Parámetros requeridos faltantes: projectName, description",
  "tool": "configure_project"
}
```

2. **Tipo de dato incorrecto**:
```json
{
  "error": "El campo 'port' debe ser un número",
  "tool": "setup_websockets"
}
```

3. **Dependencias no satisfechas**:
```json
{
  "error": "Debe configurar la base de datos antes de definir tablas",
  "tool": "define_table"
}
```

## Mejores Prácticas para IA

### 1. Orden de Ejecución
1. `configure_project` (siempre primero)
2. `configure_database` (antes de definir tablas)
3. `define_table` (definir todas las tablas)
4. `setup_auth` (configurar autenticación)
5. `add_module` (añadir módulos necesarios)
6. `create_endpoint` (endpoints personalizados)
7. Configuraciones adicionales (email, cache, etc.)
8. `validate_config` (validar antes de generar)
9. `generate_project` (generar proyecto final)

### 2. Manejo de Errores
- Siempre validar configuración antes de generar
- Usar `validate_config` para detectar problemas
- Manejar dependencias entre herramientas

### 3. Optimización
- Agrupar configuraciones relacionadas
- Usar configuraciones por defecto cuando sea posible
- Validar entrada del usuario antes de procesar

### 4. Documentación
- Cada proyecto generado incluye documentación automática
- Los esquemas de API se generan automáticamente
- Los ejemplos de uso se incluyen en la documentación

## Integración con Agentes IA

### Configuración MCP
```json
{
  "mcpServers": {
    "backend-generator": {
      "command": "npx",
      "args": ["-y", "mcp-server-backend-mcp"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

### Ejemplo de Conversación con IA

**Usuario**: "Crea una API para un sistema de gestión de tareas con autenticación JWT y base de datos PostgreSQL"

**IA**: 
1. Configura proyecto base
2. Configura PostgreSQL
3. Define tabla Task con campos: id, title, description, completed, userId
4. Define tabla User para autenticación
5. Configura JWT auth
6. Añade módulo CRUD
7. Genera proyecto completo

## Soporte y Troubleshooting

### Logs y Debugging
- Todos los comandos generan logs detallados
- Usar `validate_config` para debugging
- Revisar archivos `.mcp-report.json` para detalles

### Problemas Comunes

1. **Puerto en uso**: Cambiar puerto en configuración
2. **Base de datos no conecta**: Verificar URL de conexión
3. **Módulos incompatibles**: Revisar dependencias

### Contacto
- Documentación: `MCP-SETUP.md`
- Ejemplos: `agent-config-example.json`
- Issues: Crear issue en repositorio

---

*Esta guía está diseñada específicamente para agentes de IA. Todas las herramientas están optimizadas para uso programático y generación automática de backends.*