Cortex Agent Runtime — Marco de agentes de IA nativo de MCP

Antes: la IA no entiende tu proyecto. Después: la IA puede analizar, generar y depurar aplicaciones.

Un servidor de Model Context Protocol (MCP) que convierte a cualquier agente de codificación (Claude, Cursor, Codex, OpenCode y más) en un cerebro de ingeniería autónomo para los proyectos en los que trabajas. El runtime es agnóstico respecto al tipo de proyecto: carga un conjunto de dominios según lo que sea tu proyecto, de modo que el mismo runtime funciona en aplicaciones Laravel, proyectos Node y cualquier otra cosa.

Runtime

• Detección de tipo de proyecto — core/detector.ts inspecciona el proyecto y activa los dominios correspondientes. Las herramientas genéricas siempre se cargan; el dominio Laravel se activa cuando están presentes composer.json y artisan.

• Registro de dominios — core/registry.ts expone registerDomain(manifest); listTools() / callTool() permanecen estables para que la superficie MCP no cambie entre proyectos.

• Seguro por defecto — solo local, sin conexión, sin telemetría. Se incorporan en capas listas blancas de comandos, bloqueo de comandos peligrosos y redacción de datos sensibles.

Related MCP server: Project Planner MCP

Dominios integrados

Dominio genérico

Dominio Laravel

Por qué los agentes confían en sus respuestas

Dos principios de diseño tomados de la arquitectura de system prompts del mundo real:

• Roles, no listas de herramientas. listRoles le dice al agente quién puede ser en este proyecto — un explorador (investigación de solo lectura), un ingeniero (construir y corregir) o un mantenedor (operaciones y verificación) — y qué herramientas posee cada rol. En lugar de enfrentarse a un muro plano de herramientas, el agente elige un rol y se mantiene dentro de sus límites. Menos errores, intención más clara.

• Saber de dónde provienen tus datos. contextSource muestra si cada módulo del contexto del proyecto se sirvió desde la caché o se reconstruyó en tiempo real, y el propio contexto se ensambla mediante una cadena de prioridad (cache → live → safe default) en lugar de "que el agente lo averigüe". Cuando el agente responde, sabe lo frescos que están los datos — y tú también.

Antes: un agente se enfrenta a 29 herramientas y a un contexto obsoleto cuya fecha no puede comprobar. Después: conoce su rol, su conjunto de herramientas y la frescura de todo lo que lee.

Inicio rápido

npm install
npm start

Establece la ruta del proyecto sobre la que trabajar:

# Any project (Node, Laravel, ...)
CORTEX_PROJECT_PATH=/path/to/project npm start

# Laravel-specific path resolution (backward compatible)
LARAVEL_PROJECT_PATH=/path/to/laravel-app npm start

# Nothing set → process.cwd()

Ejecuta el servidor con una única solicitud MCP para ver qué herramientas expone un proyecto:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  CORTEX_PROJECT_PATH=/path/to/node-project npx tsx src/index.ts
# → only generic tools

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  CORTEX_PROJECT_PATH=/path/to/laravel-app npx tsx src/index.ts
# → generic + laravel tools

Con OpenCode

Añade a ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "cortex": {
      "type": "local",
      "command": ["node", "/path/to/cortex-agent-runtime/dist/index.js"],
      "environment": { "CORTEX_PROJECT_PATH": "/path/to/project" }
    }
  }
}

Con Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["/path/to/cortex-agent-runtime/dist/index.js"]
    }
  }
}

Variables de entorno

Arquitectura

src/
├── index.ts                 # entry: detect → load domains → register → start MCP
├── core/                    # framework layer — project-type agnostic
│   ├── registry.ts          # ToolRegistry: registerDomain / listTools / callTool / roles
│   ├── source-chain.ts      # resolveChain: priority fallback chain (cache → live → default)
│   ├── mcp.ts               # getConfig / getLogger / runCommand
│   ├── logger.ts            # leveled logger
│   ├── detector.ts          # detectDomains(projectPath) → DomainManifest[]
│   ├── glob.ts              # minimal `*` / `**` glob
│   ├── context/             # generic context interface
│   └── tools/               # shared tools (listRoles)
└── domains/
    ├── generic/             # always loaded: gitStatus / fileSearch / projectTree / listRoles
    └── laravel/             # tools / workflows / context / security / planner / manifest

Cada dominio exporta un DomainManifest (id, name, detect, getTools, getHandlers, getProjectPath?, roles?). Los roles declaran quién puede ser el agente en este proyecto (explorer / engineer / maintainer) y qué herramientas posee cada rol — el agente puede llamar a listRoles en lugar de adivinar. El dominio Laravel mantiene su propio runtime (domains/laravel/mcp.ts), herramientas, flujos de trabajo, contexto, seguridad y planificador — la superficie preexistente de 24 herramientas no cambia.

Requisitos

• Node.js 18+

• PHP 8.1+ (para el dominio Laravel)

Extensión Pi (port de las herramientas MCP)

El mismo conjunto de herramientas, como extensión de pi coding agent: 34 de las 35 herramientas migradas del servidor MCP a herramientas personalizadas nativas de pi, menos intentPlanner (pi es en sí mismo un LLM; lenguaje natural → plan es redundante allí). Fuente: pi-extension/cortex-laravel/.

Instalación

# either copy …
cp -R pi-extension/cortex-laravel ~/.pi/agent/extensions/
# … or symlink (always in sync with this repo)
ln -s "$(pwd)/pi-extension/cortex-laravel" ~/.pi/agent/extensions/cortex-laravel

Luego reinicia pi (o /reload). La extensión registra 34 herramientas:

Resolución de la ruta del proyecto: variables de entorno CORTEX_PROJECT_PATH / LARAVEL_PROJECT_PATH, con respaldo en el cwd de la sesión de pi. Las herramientas Laravel se autoprotegen con un error claro en proyectos que no son Laravel; las herramientas de orquestación leen/escriben la misma estructura .htask/ que el servidor MCP (y la CLI independiente htask).

Diferencias con el servidor MCP

• Seguridad — la misma lista blanca de comandos + validador de patrones peligrosos (dos capas), más una puerta de confirmación en taskAdvance / taskAccept / workflowStatus (reanudar·revertir): establece CORTEX_CONFIRM_OFF=1 para permitirlo en scripts.

• Compatibilidad con Laravel 11+ — config:get, eliminado en versiones recientes, recurre a tinker; las rutas de API se crean automáticamente mediante artisan install:api cuando routes/api.php no existe.

• Proyectos con nix flake — resolvePhpPath sondea rutas de instalación de nix conocidas (no solo nix en PATH).

• Errores — los errores lanzados se muestran como errores de herramienta; los resultados de las herramientas son texto plano (sin envoltorio JSON-RPC de MCP).

Desarrollo

npm install
npm run typecheck   # tsc --noEmit (type-check only)
npm test            # run all tests
npm run build       # compile to dist/
npm start           # node dist/index.js
npm run dev         # npx tsx src/index.ts (hot reload)

Licencia

MIT