🛡️ PortalV4 Context Server (MCP) - Manual Oficial

Versión: 1.0.0 Entorno: Híbrido (Windows / WSL2) Gestor de paquetes: pnpm Transporte: stdio

📖 Introducción

El portalv4-context-server es un microservicio basado en el estándar Model Context Protocol (MCP). Actúa como el "gobierno técnico" del proyecto PortalV4. Su propósito principal es dotar a los agentes de Inteligencia Artificial (Cursor, Codex, Claude Code) de herramientas seguras para leer el contexto real del proyecto, validar reglas de arquitectura y prevenir código destructivo o fuera de estándar.

Related MCP server: git-context-mcp

🤖 Sección para Agentes de IA (Instrucciones)

ATENCIÓN IA: Este servidor te proporciona capacidades de lectura y validación sobre el entorno real del usuario.

• PROHIBIDO adivinar rutas, esquemas de base de datos o inventar plantillas de tests.

• OBLIGATORIO invocar las herramientas documentadas en este manual antes de generar o proponer código al desarrollador.

• Tienes permiso implícito para usar estas herramientas de forma autónoma durante tu proceso de razonamiento.

🛠️ Catálogo de Herramientas (Skills)

El servidor expone 6 herramientas especializadas divididas por responsabilidades:

1. get_module_structure (Backend & Frontend)

Propósito: Garantizar el cumplimiento de la arquitectura modular desacoplada.

• Qué hace: Verifica si un módulo existe en la arquitectura clásica o en la nueva arquitectura Modules. Busca el nombre sin depender de mayúsculas/minúsculas y devuelve el nombre real del disco.

• Payload exacto: { "moduleName": "WebCoosajo" }

• Salida: Destinos que incluyen ruta nativa absoluta, ruta portable con /, tipo y existencia actual.

2. lint_thin_controller (Solo Backend)

Propósito: Forzar el patrón Thin Controller.

• Qué hace: Analiza estáticamente archivos PHP dentro de portalv4/backend. Es un guardrail regex que detecta llamadas estáticas a modelos, mutaciones como ->save() y ->update(), y acceso directo mediante DB::.

• Payload exacto: { "controllerPath": "/ruta/absoluta/Controller.php" }

• Salida: Devuelve passed: false, ubicación y acción requerida cuando hay hallazgos.

3. read_database_schema (Solo Backend)

Propósito: Eliminar alucinaciones de SQL y proteger el esquema de la base de datos.

• Qué hace: Levanta un proceso PHP en segundo plano, lee la conexión real desde config/database.php de Laravel y ejecuta una consulta de solo lectura (INFORMATION_SCHEMA) al motor (SQL Server o MySQL).

• Payload exacto: { "table_name": "Agencia", "connection_name": "sqlsrv" } (Nota: connection_name es opcional. Si table_name se deja vacía "", lista todas las tablas disponibles).

4. export_endpoint_docs (Solo Backend)

Propósito: Automatizar la documentación de la API.

• Qué hace: Lee las rutas registradas en memoria en Laravel, realiza un análisis estático de los FormRequests y métodos para extraer parámetros obligatorios (_Colaborador, _Token), y escribe una colección Postman Collection v2.1.0 exclusivamente en el archivo .json indicado por el usuario. También inyecta automáticamente variables de URL y encabezados como Authorization: Bearer {{token}}. No existe una ruta de salida predeterminada; el directorio padre debe existir y los enlaces simbólicos existentes se rechazan. Tampoco sobrescribe un archivo salvo autorización expresa.

• Filtros Granulares: Permite filtrar las rutas a documentar a través de los siguientes parámetros opcionales:

  • prefix: Filtra por prefijo de URL (ej. api/).

  • module: Filtra por el nombre del módulo de la arquitectura (ej. WebCoosajo).

  • route_file: Filtra por archivo de registro de ruta (ej. api.php).

  • search_pattern: Regex para filtrar por URI, nombre de ruta o controlador.

• Payload exacto: { "output_path": "/ruta/elegida/portalv4-api.json", "prefix": "api/", "module": "WebCoosajo", "overwrite": false } (Nota: output_path es obligatorio, absoluto y debe terminar en .json; los filtros y overwrite son opcionales. Para reemplazar un archivo existente, el usuario debe indicar overwrite: true expresamente).

• Salida: Metadatos de la exportación: ruta efectiva, prefijo, cantidad de rutas y requests, bytes escritos y formato. La colección completa queda únicamente en output_path.

5. generate_tests (Solo Backend)

Propósito: Proteger la base de datos de desarrollo frente a ejecuciones de tests destructivos.

• Qué hace: Genera la plantilla base PHP para pruebas automatizadas garantizando la importación y uso estricto del trait DatabaseTransactions (prohibiendo RefreshDatabase).

• Payload exacto: { "test_name": "BeneficioControllerTest", "type": "Feature", "module_name": "WebCoosajo" } (Nota: module_name es opcional).

6. review_quality_and_git (Backend & Frontend)

Propósito: Auditar de forma analítica y segura el control de versiones sin alterar Git.

• Qué hace: Inspecciona automática y pasivamente los repositorios reales backend/ y frontend/ bajo PORTALV4_ROOT. Ejecuta exclusivamente git status --porcelain, git rev-parse --abbrev-ref HEAD y git diff --stat con bloqueos opcionales desactivados. A partir de esa evidencia propone, cuando corresponde, un nombre de rama válido y un mensaje bajo Conventional Commits acorde con los archivos modificados.

• Payload: {}. No recibe nombres de rama ni mensajes redactados por el usuario; los campos heredados que un cliente antiguo envíe son ignorados.

• Salida: Reporte JSON por repositorio con rama actual, cumplimiento del estándar, estado porcelain, archivos cambiados, resumen del diff, observaciones y sugerencias. La herramienta nunca ejecuta git add, git commit, git push, git merge ni ninguna otra operación de escritura o alteración.

👨‍💻 Sección para Desarrolladores Humanos

Requisitos Previos

• Node.js: v20 o superior.

• Gestor de paquetes: pnpm v11+ (Requerido por pnpm-workspace.yaml).

• Una copia accesible de PortalV4 con los directorios backend/ y frontend/.

Variables de Entorno

Instalación y Desarrollo

El servidor MCP no se ejecuta en tiempo de ejecución de TypeScript, debe compilarse previamente. El transporte stdio reserva stdout para MCP; cualquier diagnóstico debe escribirse a stderr.

# Instalación y validación
pnpm install
pnpm check

# Compilar TypeScript a JavaScript (Genera dist/index.js)
pnpm build

La opción más estable es ejecutar el servidor en el mismo entorno donde vive el código:
Bash

PORTALV4_ROOT=/home/sjdarita/proyectos/portalv4 pnpm start

Ejemplos de Configuración de Clientes MCP
Use rutas y variables nativas del proceso que lanza Node.
Cliente ejecutado en WSL (Codex / Claude Code)
JSON

{
  "mcpServers": {
    "portalv4-context": {
      "command": "node",
      "args": [
        "/home/sjdarita/proyectos/portalv4-context-server/dist/index.js"
      ],
      "env": {
        "PORTALV4_ROOT": "/home/sjdarita/proyectos/portalv4"
      }
    }
  }
}

Cliente ejecutado en Windows, código dentro de WSL (Cursor / VS Code)
JSON

{
  "mcpServers": {
    "portalv4-context": {
      "command": "node",
      "args": [
        "\\\\wsl.localhost\\Ubuntu-24.04\\home\\sjdarita\\proyectos\\portalv4-context-server\\dist\\index.js"
      ],
      "env": {
        "PORTALV4_ROOT": "\\\\wsl.localhost\\Ubuntu-24.04\\home\\sjdarita\\proyectos\\portalv4"
      }
    }
  }
}

	Nota para Windows: Algunos clientes no permiten usar una ruta UNC (\\wsl.localhost\...) como directorio de trabajo. En ese caso, mantenga command como un ejecutable local de Windows y pase la ruta UNC sólo en args y PORTALV4_ROOT, o ejecute wsl.exe como wrapper.