PortalV4 Context Server

Servidor local de Model Context Protocol (MCP) desarrollado en TypeScript para consultar el contexto técnico de PortalV4 desde clientes MCP. Permite localizar módulos, revisar controladores y modelos PHP, consultar esquemas SQL, generar plantillas de pruebas, exportar colecciones Postman y revisar el estado Git del backend y frontend.

La versión declarada en package.json y en el servidor es 0.1.0. Expone 8 tools y 2 resources, mediante transporte stdio. El cliente inicia un proceso local y se comunica por su entrada y salida estándar. Esta implementación no registra transporte HTTP, prompts ni plantillas de resources.

El servidor se mantiene en un repositorio independiente de PortalV4. La mayoría de las herramientas consultan archivos o metadatos; export_endpoint_docs escribe el JSON solicitado y generate_tests devuelve código PHP sin guardarlo ni ejecutarlo. Las herramientas que arrancan Laravel ejecutan también su proceso de bootstrap.

Contenido

• Prerrequisitos

• Instalación y compilación

• Configuración del entorno

• Integración con clientes MCP

• Herramientas disponibles

• Resources disponibles

• Desarrollo y validación

• Limitaciones y deuda técnica

• Resolución de problemas

Related MCP server: Engineering Intelligence MCP

Prerrequisitos

Para seleccionar la copia de Laravel que usarán las herramientas PHP, consulte Configuración del entorno.

Dependencias del proyecto

Las versiones siguientes son los rangos declarados en package.json; las versiones resueltas se conservan en pnpm-lock.yaml.

Las dependencias de desarrollo son typescript (^5.9.3), tsx (^4.20.6), @types/node (^24.10.1) y @types/mssql (^12.3.0). No se requiere un proveedor de IA ni una clave API para iniciar este servidor.

Instalación y compilación

Desde una copia de este repositorio, use la versión de pnpm indicada en package.json. Si necesita instalarla mediante npm:

npm install --global pnpm@11.17.0

Compruebe las versiones e instale las dependencias desde la raíz del repositorio:

node --version
pnpm --version
pnpm install --frozen-lockfile
pnpm check
pnpm build

pnpm-workspace.yaml incluye este paquete y autoriza el build de esbuild, usado por tsx. pnpm build compila src/**/*.ts en dist/ con configuración estricta de TypeScript, módulos NodeNext y destino ES2022. El punto de entrada resultante es dist/index.js.

Para ejecutar la versión compilada en Linux/WSL, sustituya la ruta por su copia de PortalV4:

PORTALV4_ROOT=/ruta/absoluta/portalv4 pnpm start

El proceso anuncia la raíz detectada en stderr y espera mensajes MCP por stdin. No abre un puerto ni muestra una interfaz web. El cliente MCP normalmente inicia y administra este proceso; la ejecución manual sirve para comprobar el arranque.

También existe ejecución directa del código TypeScript para desarrollo:

PORTALV4_ROOT=/ruta/absoluta/portalv4 pnpm dev

dev ejecuta tsx src/index.ts; no tiene modo watch. Tras cambiar el código, reinicie el proceso. Para clientes que ejecutan dist/index.js, compile de nuevo y reinicie la conexión MCP.

Configuración del entorno

El servidor lee variables del entorno del proceso. No carga automáticamente un archivo .env propio. Configure las variables en el cliente MCP o en el entorno que lanza Node; Laravel resuelve por separado su propia configuración durante el bootstrap.

Cuando se omite PORTALV4_ROOT, se prueban, en este orden: el directorio actual, portalv4/ bajo el directorio actual y portalv4/ junto al repositorio del servidor. Para los clientes de escritorio conviene establecer la raíz explícitamente y usar rutas absolutas.

Ejecución de las herramientas PHP

Ambas herramientas ejecutan el binario php del PATH mediante execFileSync, con argumentos separados y sin shell. La ruta del backend se normaliza para el sistema que ejecuta Node y se transmite al proceso PHP mediante PORTALV4_BACKEND_PATH. Laravel carga vendor/autoload.php y bootstrap/app.php desde esa misma ruta.

No hay una ruta fija al ejecutable PHP ni al backend. Con PORTALV4_ROOT configurado no es necesario añadir PORTALV4_BACKEND_PATH: el valor predeterminado es su subdirectorio backend/. Si usa el override para otra copia, las herramientas PHP consultarán esa copia, mientras que archivos, Git y LogTrait seguirán usando PORTALV4_ROOT.

Rutas y Windows/WSL

El servidor normaliza rutas POSIX, unidades Windows y UNC de WSL (\\wsl.localhost\... o \\wsl$\...) según el sistema que ejecuta Node. Dentro de WSL convierte unidades Windows a /mnt/<unidad>/...; fuera de WSL, Linux rechaza esas unidades y las rutas UNC de WSL. Cuando WSL_DISTRO_NAME está disponible, se rechazan rutas UNC de otra distribución.

Para Windows nativo, instale PHP CLI y añádalo al PATH del proceso Node. Para un cliente Windows con PortalV4 dentro de WSL, ejecutar Node mediante wsl.exe permite usar PHP y Git de esa distribución; PHP debe estar disponible dentro de WSL.

Integración con clientes MCP

Compile primero y use node directamente con la ruta absoluta a dist/index.js. Reemplace todas las rutas de ejemplo por las de su equipo. Si Node no está en el PATH del cliente, use la ruta absoluta al ejecutable. stdout se reserva para el protocolo MCP; los diagnósticos deben escribirse en stderr.

Claude Desktop

Abra Settings → Developer → Edit Config, incorpore la entrada al objeto mcpServers existente y reinicie la aplicación. La ubicación documentada del archivo es:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json.

• Windows: %APPDATA%\Claude\claude_desktop_config.json.

Ejemplo para Node ejecutado en un entorno POSIX:

{
  "mcpServers": {
    "portalv4-context": {
      "command": "node",
      "args": ["/ruta/absoluta/portalv4-context-server/dist/index.js"],
      "env": {
        "PORTALV4_ROOT": "/ruta/absoluta/portalv4",
        "PORTALV4_BACKEND_PATH": "/ruta/absoluta/portalv4/backend"
      }
    }
  }
}

PORTALV4_BACKEND_PATH es opcional en este ejemplo porque coincide con el valor derivado de PORTALV4_ROOT. Referencia: guía oficial de conexión a servidores locales MCP.

Cursor

Añada la configuración a .cursor/mcp.json en el proyecto o a ~/.cursor/mcp.json para uso global. La entrada stdio incluye type: "stdio":

{
  "mcpServers": {
    "portalv4-context": {
      "type": "stdio",
      "command": "node",
      "args": ["/ruta/absoluta/portalv4-context-server/dist/index.js"],
      "env": {
        "PORTALV4_ROOT": "/ruta/absoluta/portalv4",
        "PORTALV4_BACKEND_PATH": "/ruta/absoluta/portalv4/backend"
      }
    }
  }
}

Recargue la conexión y compruebe las herramientas en la configuración MCP del cliente. Referencia: documentación oficial de MCP en Cursor. Estas configuraciones describen cómo lanzar el proceso; no constituyen una validación de ejecución en ambos clientes.

Cliente Windows que ejecuta el servidor dentro de WSL

Ejemplo con rutas de una instalación en WSL. Sustituya las rutas, la distribución y el ejecutable Node por los reales; en WSL puede obtener este último con command -v node:

{
  "mcpServers": {
    "portalv4-context": {
      "command": "wsl.exe",
      "args": [
        "--distribution", "Ubuntu-24.04",
        "--exec", "env",
        "PORTALV4_ROOT=/home/sjdarita/proyectos/portalv4",
        "PORTALV4_BACKEND_PATH=/home/sjdarita/proyectos/portalv4/backend",
        "/usr/bin/node",
        "/home/sjdarita/proyectos/portalv4-context-server/dist/index.js"
      ]
    }
  }
}

Para Cursor, añada "type": "stdio" a esta entrada. El servidor y sus dependencias deben estar instalados y compilados dentro de WSL. /usr/bin/node es un ejemplo: una instalación mediante un gestor de versiones puede usar otra ruta.

Herramientas disponibles

Las herramientas se registran en src/index.ts. Los nombres MCP son los indicados abajo; logtrait-context.ts y model-audit.ts son archivos de implementación, no nombres de tools.

Salvo generate_tests, las respuestas se entregan como JSON en content de tipo text y en structuredContent. Los errores capturados por los handlers incluyen error e isError: true; un hallazgo de lint se comunica mediante passed, sin ser necesariamente un error del protocolo.

get_module_structure

Argumento obligatorio: moduleName, un segmento PascalCase que cumpla ^[A-Z][A-Za-z0-9]*$.

{ "moduleName": "WebCoosajo" }

Busca directorios bajo Modules/ y app/Http/Controllers/ de ambas capas, respetando el nombre real del disco y comparando sin distinguir mayúsculas/minúsculas. Prioriza Modules si existe; conserva la arquitectura clásica si es la única encontrada y propone destinos en Modules para un módulo ausente.

Devuelve requestedModule, canonicalModule, selectedArchitecture, indicadores detected, selectionReason, destinations, developmentStandards y notes. Cada destino incluye absolutePath, portablePath, exists y kind. La presencia de una ruta propuesta no implica que exista: compruebe exists.

lint_thin_controller

Argumento obligatorio: controllerPath, ruta a un .php existente, absoluta o relativa a backend/. Resuelve enlaces simbólicos y rechaza archivos fuera del backend; el tamaño máximo se configura con PORTALV4_MAX_CONTROLLER_BYTES.

{ "controllerPath": "Modules/WebCoosajo/Controllers/BeneficioController.php" }

Enmascara comentarios y cadenas y usa expresiones regulares para detectar:

• ELOQUENT_STATIC_CALL: llamadas estáticas a modelos reconocidos por importación o nombre calificado.

• ELOQUENT_MUTATION: llamadas como save, update, delete, restore, increment, decrement, touch o push.

• DB_FACADE_CALL: acceso mediante DB::.

Devuelve controllerPath, portablePath, passed, findingCount, findings y requiredAction. Los hallazgos incluyen regla, línea, columna, coincidencia y mensaje. No ejecuta PHP ni corrige el controlador; las expresiones regulares no sustituyen un parser ni resuelven todos los alias o tipos de objetos.

read_database_schema

Argumentos:

• table_name obligatorio: cadena de hasta 128 caracteres; "" lista las tablas base disponibles.

• connection_name opcional: conexión Laravel; al omitirla se usa database.default. Debe cumplir ^[A-Za-z][A-Za-z0-9_-]*$.

{ "table_name": "Agencia", "connection_name": "sqlsrv" }

{ "table_name": "" }

Arranca Laravel mediante php -r para resolver la configuración efectiva. Node conecta usando mssql para el driver sqlsrv o mysql2/promise para mysql; otros drivers se rechazan. Ejecuta consultas fijas de lectura sobre INFORMATION_SCHEMA y parametriza el nombre de tabla. No admite SQL arbitrario ni recibe credenciales como argumentos.

Devuelve connectionName, driver y mode; en modo tables, tableCount y tables; en modo columns, tableName, columnCount y columns. Las columnas incluyen esquema, nombre, posición, tipo, longitud, nulabilidad y una clasificación de llave (PRIMARY KEY, FOREIGN KEY o UNIQUE, cuando corresponde). No proporciona un inventario completo de índices ni destinos de claves foráneas. En SQL Server el filtro es por nombre de tabla y puede devolver varios esquemas con ese mismo nombre.

La conexión se cierra al terminar. La resolución de configuración PHP tiene timeout de 15 segundos; SQL Server usa 15 segundos para conectar y 30 para consultar; MySQL fija 15 segundos para conectar. Ambas herramientas PHP usan el backend seleccionado según Configuración del entorno.

export_endpoint_docs

{
  "output_path": "/ruta/absoluta/exportaciones/webcoosajo.postman.json",
  "prefix": "web-coosajo/",
  "module": "WebCoosajo",
  "route_file": "Modules/WebCoosajo/Routes/WebCoosajo.php",
  "overwrite": false
}

Obtiene las rutas registradas mediante bootstrap Laravel y reflexión PHP. Genera una Postman Collection v2.1.0, agrupada por el primer segmento de URI y con variables para parámetros de ruta. Omite HEAD y OPTIONS cuando quedan otros métodos; si son los únicos, conserva el valor de métodos original como alternativa.

La colección define base_url con valor inicial http://localhost; agregue o configure en Postman las variables referenciadas por las solicitudes, como token, _Colaborador, _Token y los parámetros de ruta. Incluye Accept, Content-Type para POST/PUT/PATCH y Authorization: Bearer {{token}} cuando reconoce middleware auth:api, auth:passport o que contiene passport.

El análisis de fuentes sólo busca menciones textuales de _Colaborador y _Token en el controlador y sus dependencias reflejadas; puede colocarlas en el cuerpo JSON de POST/PUT/PATCH. No extrae las reglas generales de FormRequest ni reconstruye todas las cabeceras, cuerpos, respuestas o requisitos de autenticación. Revise la colección contra cada endpoint antes de compartirla como contrato de API.

Rechaza un destino existente que sea enlace simbólico o no sea un archivo regular; no crea el directorio padre ni usa una ruta de salida predeterminada. El JSON completo queda en el archivo. La respuesta contiene exported, output_path, overwritten, prefix, route_count, request_count, byte_count y format.

Sin filtros se procesan todas las rutas. route_file identifica el archivo que declara cada ruta durante su registro, antes de realizar reflexión y análisis de fuentes de los endpoints seleccionados. La coincidencia es por archivo exacto, no por subcadena ni por el archivo del controlador. Los demás filtros se aplican conjuntamente al conjunto seleccionado. Un nombre ambiguo, un archivo inválido o un filtro vacío producen un error; una ruta válida sin endpoints registrados produce una colección vacía.

Para identificar las fuentes, el proceso PHP temporal registra las rutas sin usar la caché de rutas de Laravel. No elimina ni modifica archivos de caché del backend. Se ejecuta el bootstrap completo para conservar prefijos y middleware de los grupos, pero sólo los endpoints del archivo seleccionado pasan a reflexión y exportación. Si una implementación de router no permite identificar las fuentes, la herramienta devuelve un error en lugar de exportar rutas sin atribución. El timeout de extracción PHP sigue siendo de 30 segundos.

generate_tests

Argumentos obligatorios: test_name (PascalCase, ^[A-Z][A-Za-z0-9]*$) y type (Feature o Unit). module_name es opcional y usa el mismo patrón de nombre.

{
  "test_name": "BeneficioControllerTest",
  "type": "Feature",
  "module_name": "WebCoosajo"
}

Devuelve texto PHP con namespace Tests\<type> o Modules\<module_name>\Tests\<type>, herencia de Tests\TestCase, importación y uso de DatabaseTransactions y un método test_example() vacío. No usa RefreshDatabase. No añade aserciones, no guarda archivos y no ejecuta pruebas; el equipo debe completar y revisar la plantilla antes de utilizarla.

review_quality_and_git

No requiere argumentos. Los campos adicionales heredados se aceptan y se ignoran.

{}

Inspecciona backend/ y frontend/ bajo la raíz resuelta ejecutando exclusivamente:

git status --porcelain
git rev-parse --abbrev-ref HEAD
git diff --stat

Usa GIT_OPTIONAL_LOCKS=0, GIT_PAGER=cat y timeout de 10 segundos por comando. Devuelve audit_mode: "passive_read_only", audit_completed, git_writes_executed: false e informes por repositorio con rama, archivos staged/unstaged/untracked, resumen del diff, observaciones y sugerencias.

Valida ramas con prefijos feature/, bugfix/, hotfix/, release/ o chore/ y segmentos en kebab-case. Puede sugerir una rama y un mensaje Conventional Commits a partir de los archivos y la rama actuales; no ejecuta operaciones de escritura en Git. git diff --stat resume cambios rastreados sin preparar; staged y untracked se identifican por status --porcelain. La revisión de calidad se basa en metadatos y nombres de archivos potencialmente sensibles, no en el contenido del diff.

get_logtrait_context

Argumento obligatorio: layer, exactamente backend o frontend; rechaza campos adicionales.

{ "layer": "backend" }

Lee en cada llamada la sección aprobada de .github/copilot-instructions.md de la capa y backend/app/Traits/LogTrait.php, sin caché ni copia de respaldo del estándar. Devuelve layer, resourceUri, policyMarkdown, traitSource y sources; cada fuente incluye path, startLine, endLine y SHA-256 del texto devuelto.

Resuelve enlaces simbólicos, limita las lecturas a la capa correspondiente y admite archivos de hasta 1 MiB. Normaliza a LF la sección Markdown. Si falta una fuente o no hay exactamente una sección con el título requerido, devuelve un error explícito. No ejecuta PHP ni consulta la base de datos.

lint_model_audit

Argumentos obligatorios: modelPath (archivo .php existente, absoluto o relativo a backend/) y mode (new o legacy). Rechaza campos adicionales.

{
  "modelPath": "Modules/AdministracionCarteras/Models/Perfil.php",
  "mode": "new"
}

Lee el modelo dentro del backend, hasta 1 MiB, y consulta el estándar backend de LogTrait. Inspecciona clases, importaciones, traits y métodos mediante un analizador léxico limitado. No ejecuta PHP, no arranca Laravel ni modifica archivos.

Devuelve modelPath, mode, verification: "static", status, passed, hasLogTrait, findings, manualReview, standard y sources. hasLogTrait indica uso directo reconocido; no prueba su ausencia en una herencia o composición no resuelta. Los hallazgos incluyen regla, severidad, línea, columna y mensaje, sin copiar los valores del modelo.

Reconoce herencia directa de Illuminate\Database\Eloquent\Model, importaciones simples y múltiples con alias y uso directo o plenamente calificado de App\Traits\LogTrait. Ignora comentarios y literales. Importaciones agrupadas, atributos PHP, heredoc/nowdoc, padres personalizados, otros traits y adaptaciones requieren revisión.

passed: true no certifica auditoría en ejecución. La revisión manual debe verificar identidad y cabeceras, atributos sensibles, manejo de transacciones y fallos, escrituras sin eventos y registros manuales duplicados. Reconocer parent::boot() tampoco demuestra su ejecución en todas las ramas.

Resources disponibles

Ambos usan MIME text/markdown, leen las fuentes en cada consulta y comparten implementación con get_logtrait_context. Su registro no comprueba que las fuentes existan; la comprobación ocurre al leerlos. Se requieren estos archivos:

portalv4/
├── backend/
│   ├── .github/copilot-instructions.md
│   └── app/Traits/LogTrait.php
└── frontend/
    └── .github/copilot-instructions.md

En cada documento de instrucciones debe existir exactamente una cabecera de tercer nivel con el título literal correspondiente:

### Auditoría de modelos mediante LogTrait

### Contexto de auditoría en llamadas al backend

La sección termina ante la siguiente cabecera de nivel 1, 2 o 3. Los hashes describen el texto devuelto, no necesariamente el archivo completo de instrucciones. El estándar normativo se mantiene en PortalV4; este README documenta cómo consultarlo.

Desarrollo y validación

Scripts disponibles

No hay scripts test, lint ni watch definidos en package.json. check comprueba tipos; no demuestra conectividad SQL, bootstrap Laravel ni funcionamiento en un cliente de escritorio.

Organización del código

Comprobación desde un cliente MCP

Después de pnpm check y pnpm build, conecte el cliente y compruebe:

1. tools/list devuelve las 8 herramientas de este catálogo.

2. resources/list devuelve los 2 resources LogTrait.

3. Una llamada a get_module_structure refleja las rutas de su copia de PortalV4.

4. La lectura de un resource o get_logtrait_context devuelve fuentes de esa copia, si los archivos requeridos están disponibles.

Use esta comprobación para distinguir el arranque del servidor de la disponibilidad real de cada herramienta. Las herramientas PHP y SQL requieren sus prerrequisitos particulares.

El flujo indicado por las instrucciones del servidor es consultar primero get_module_structure, leer el estándar LogTrait de la capa, ejecutar los lints que correspondan y revisar Git pasivamente. Para modelos backend nuevos auditables, passed debe ser true antes de concluir la verificación estática, además de atender manualReview.

Limitaciones y deuda técnica

• Selección explícita de otro backend: PORTALV4_BACKEND_PATH prevalece para ambas herramientas PHP. Si apunta a otra copia, archivos/Git/LogTrait y PHP consultarán copias diferentes; omítalo cuando baste PORTALV4_ROOT/backend.

• Atribución de rutas: el filtro depende del registro mediante el router Laravel en el proceso temporal. No atribuye rutas sin una fuente PHP identificable dentro del backend ni usa archivos de controladores como sustituto. Los nombres de archivo ambiguos requieren una ruta completa.

• Exportación de contratos parcial: no se extraen las reglas generales de FormRequest ni se analizan las fuentes de middleware para completar contratos. La búsqueda textual de _Colaborador/_Token puede confundir cabeceras con cuerpo. Las variables referenciadas, salvo base_url, no se declaran en la colección; deben configurarse al usarla.

• Código contextual sin integración completa: RouteRegistration no se utiliza; requiredHeaders, signedUrlRequired y notes no alimentan la colección. La reflexión produce dependencias con la clave class, mientras el tipo TypeScript espera className y se convierte con un cast. Las lecturas de fuentes fallidas se ignoran, por lo que una exportación exitosa puede estar incompleta.

• Bootstrap Laravel: las consultas SQL emitidas por el MCP son de lectura, pero resolver configuración y rutas ejecuta Laravel y sus proveedores de servicio. El servidor no limita el comportamiento interno de ese bootstrap.

• Docker incompleto para el catálogo: el Dockerfile instala Git y dependencias Node, compila y fija PORTALV4_ROOT=/app/portalv4, pero no instala PHP ni Composer ni provisiona una copia de PortalV4. Instala pnpm global sin fijar versión explícita y usa --no-frozen-lockfile. No constituye por sí solo un entorno listo para todas las herramientas.

• Alcance de la validación: los lints PHP son estáticos y la revisión Git sólo inspecciona metadatos. No hay una suite de pruebas ni un script de tests en el repositorio; la compilación no sustituye verificación funcional en Laravel, SQL Server/MySQL o los clientes MCP.

Resolución de problemas

Para diagnosticar una conexión, consulte los logs MCP del cliente y la salida stderr del servidor. Evite imprimir diagnósticos en stdout, porque puede interrumpir el protocolo.