backend-mcp
Version:
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.
386 lines (323 loc) • 10.2 kB
Markdown
El generador de contratos es una herramienta que analiza automáticamente la configuración del backend MCP y genera un archivo JSON completo que contiene toda la información necesaria para que el frontend se auto-genere.
Un contrato es un archivo JSON que actúa como un puente de comunicación entre el backend y el frontend. Contiene:
- **Información del proyecto**: Nombre, descripción, versión, arquitectura
- **Configuración de API**: URLs, endpoints, documentación, CORS
- **Módulos habilitados**: Auth, database, email, websockets, etc.
- **Entidades CRUD**: Campos, validaciones, relaciones, endpoints
- **Configuración de autenticación**: Roles, permisos, middleware
- **Configuración de UI**: Temas, layouts, componentes
- **Información de deployment**: Ambiente, infraestructura
- **Checksums de integridad**: Para verificar cambios
```bash
node scripts/generate-contract.js
```
```bash
node scripts/generate-contract.js ./output/frontend-contract.json
```
```bash
npm run generate:contract
npm run contract
```
El generador está disponible como **herramienta MCP** para uso automático por IA:
```javascript
// La IA puede ejecutar esto automáticamente
const result = await executeTool('generate_contract', {
outputPath: './frontend-contract.json',
targetFramework: 'react',
includeUI: true,
verbose: true
});
```
```javascript
// Se ejecuta automáticamente al crear proyectos
const projectResult = await executeTool('generate_project', {
outputPath: './mi-proyecto',
generateContract: true // Por defecto es true
});
```
- `outputPath`: Ruta del archivo de contrato (default: `./frontend-contract.json`)
- `includeEntities`: Incluir entidades CRUD (default: `true`)
- `includeAuth`: Incluir configuración de autenticación (default: `true`)
- `includeAPI`: Incluir endpoints de API (default: `true`)
- `includeUI`: Incluir configuración de UI (default: `true`)
- `includeValidations`: Incluir reglas de validación (default: `true`)
- `targetFramework`: Framework objetivo (`react`, `vue`, `angular`, `all`) (default: `all`)
- `generateTypes`: Generar definiciones TypeScript (default: `true`)
- `verbose`: Información detallada (default: `false`)
### Opción 3: Integración Automática
La herramienta MCP permite que la IA:
- ✅ **Detecte automáticamente** cuándo es necesario generar un contrato
- ✅ **Ejecute la generación** sin intervención manual
- ✅ **Mantenga sincronizado** el contrato con los cambios del backend
- ✅ **Optimice para el framework** específico del frontend
Esto generará el archivo `frontend-contract.json` en la raíz del proyecto.
### Especificar Ruta de Salida
```bash
node scripts/generate-contract.js ./output/my-contract.json
```
### Desde Código
```javascript
const ContractGenerator = require('./scripts/generate-contract');
const generator = new ContractGenerator();
const contract = await generator.generateContract();
// Guardar en archivo
await generator.saveContract('./frontend-contract.json');
// O usar el objeto directamente
console.log(contract.entities);
```
```json
{
"contract": {
"version": "1.0.0",
"type": "backend-frontend-bridge",
"generatedAt": "2024-01-15T10:30:00.000Z",
"generatedBy": "backend-mcp-v2.0.17",
"compatibility": {
"minFrontendMcpVersion": "1.0.0",
"backendMcpVersion": "2.0.17",
"contractHash": "sha256:a1b2c3d4...",
"checksums": {
"entities": "sha256:e5f6g7h8...",
"auth": "sha256:i9j0k1l2...",
"modules": "sha256:m3n4o5p6..."
}
}
}
}
```
```json
{
"project": {
"name": "mi-proyecto",
"domain": "Sistema de Gestión",
"description": "API backend para gestión empresarial",
"mode": "development",
"architecture": "monolithic",
"database": "postgresql",
"environment": "development"
}
}
```
```json
{
"api": {
"baseUrl": "http://localhost:3000",
"version": "v1",
"prefix": "/api/v1",
"documentation": {
"openapi": "/api/v1/docs/openapi.json",
"swagger": "/api/v1/docs",
"postman": "/api/v1/docs/postman.json"
},
"rateLimit": {
"enabled": true,
"requests": 1000,
"window": "15m"
},
"cors": {
"enabled": true,
"origins": ["http://localhost:3000"],
"credentials": true
}
}
}
```
```json
{
"entities": [
{
"name": "User",
"table": "users",
"primaryKey": "id",
"timestamps": true,
"softDeletes": true,
"apiPath": "/users",
"fields": [
{
"name": "id",
"type": "uuid",
"primaryKey": true,
"generated": "uuid"
},
{
"name": "name",
"type": "string",
"required": true,
"validation": "min:2,max:100"
},
{
"name": "email",
"type": "string",
"required": true,
"unique": true,
"validation": "email"
}
],
"endpoints": {
"list": {
"method": "GET",
"path": "/users",
"permissions": ["admin", "manager"],
"pagination": true,
"filters": ["status"],
"search": ["name", "email"]
},
"create": {
"method": "POST",
"path": "/users",
"permissions": ["admin"],
"validation": "CreateUserRequest"
}
},
"ui": {
"listView": {
"columns": ["name", "email", "status"],
"searchable": ["name", "email"],
"filterable": ["status"],
"sortable": ["name", "createdAt"]
},
"formView": {
"layout": "sections",
"sections": [
{
"title": "Información Personal",
"fields": ["name", "email"]
}
]
}
}
}
]
}
```
```json
{
"auth": {
"roles": [
{
"name": "admin",
"description": "Administrador del sistema",
"permissions": ["*"]
},
{
"name": "user",
"description": "Usuario estándar",
"permissions": ["read"]
}
],
"middleware": {
"authenticate": "verifyJwtToken",
"authorize": "checkPermissions"
}
}
}
```
El generador analiza automáticamente:
- `package.json` para información básica
- `.env.example` para configuración de ambiente
- Dependencias instaladas
- Lee `modules/*/manifest.yaml`
- Analiza `modules/*/init.js` para configuraciones específicas
- Detecta características habilitadas
- Busca directorios en `src/` con estructura CRUD
- Analiza `dto.ts` para extraer campos
- Analiza `routes.ts` para extraer endpoints
- Analiza `validator.ts` para extraer validaciones
- Detecta tipo de base de datos desde `DATABASE_URL`
- Identifica características como migraciones, seeders
Puedes extender el generador para incluir información específica de tu proyecto:
```javascript
class CustomContractGenerator extends ContractGenerator {
analyzeCustomModule() {
// Tu lógica personalizada
return {
customField: 'customValue'
};
}
async generateContract() {
const contract = await super.generateContract();
contract.custom = this.analyzeCustomModule();
return contract;
}
}
```
El contrato generado puede ser usado por herramientas de frontend para:
1. **Auto-generar páginas**: Crear automáticamente páginas CRUD
2. **Generar formularios**: Crear formularios con validaciones
3. **Configurar routing**: Establecer rutas automáticamente
4. **Generar tipos TypeScript**: Crear interfaces y tipos
5. **Configurar permisos**: Implementar control de acceso
6. **Generar documentación**: Crear documentación automática
El contrato incluye checksums para detectar cambios:
- **contractHash**: Hash del contrato completo
- **checksums.entities**: Hash de todas las entidades
- **checksums.auth**: Hash de configuración de auth
- **checksums.modules**: Hash de módulos habilitados
Esto permite al frontend detectar cuándo necesita regenerarse.
```yaml
name: Generate Frontend Contract
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
generate-contract:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm install
- run: npm run generate:contract
- name: Upload contract
uses: actions/upload-artifact@v3
with:
name: frontend-contract
path: frontend-contract.json
```
- Verifica que estés ejecutando el comando desde la raíz del proyecto
- Asegúrate de que existe el archivo `package.json`
- Verifica que existan directorios en `src/` con estructura CRUD
- Asegúrate de que los archivos `controller.ts` y `service.ts` existan
- Verifica que los módulos tengan archivos `manifest.yaml`
- Asegúrate de que `.env.example` esté configurado correctamente
Para agregar nuevas características al generador:
1. Extiende la clase `ContractGenerator`
2. Agrega nuevos métodos de análisis
3. Actualiza la estructura del contrato
4. Agrega tests correspondientes
5. Actualiza esta documentación