Cortex Agent Runtime — MCP-native AI Agent Framework

Before: AI doesn't understand your project. After: AI can analyze, generate and debug applications.

A Model Context Protocol (MCP) server that turns any coding agent (Claude, Cursor, Codex, OpenCode, and more) into an autonomous engineering brain for the projects you work on. The runtime is project-type agnostic: it loads a set of domains based on what your project is, so the same runtime works across Laravel apps, Node projects, and anything else.

Runtime

• Project-type detection — core/detector.ts inspects the project and activates the matching domains. Generic tools are always loaded; the Laravel domain activates when composer.json + artisan are present.
• Domain registration — core/registry.ts exposes registerDomain(manifest); listTools() / callTool() stay stable so the MCP surface doesn't change between projects.
• Safe by default — local-only, offline, no telemetry. Command whitelists, dangerous-command blocking, and sensitive-data redaction are layered in.

Built-in Domains

Domain	When it loads	Tools
Generic	Always	gitStatus, fileSearch, projectTree
Laravel	composer.json + artisan exist	artisan, schema, model, routes, migrations, CRUD/feature/API generators, debug workflow, intentPlanner, workflowStatus, context, and more

Generic domain

Tool	Description
gitStatus	Git status summary (branch, staged/unstaged changes)
fileSearch	Search files by glob, excluding .git / node_modules / vendor
projectTree	Two-level directory tree of the project
listRoles	List the roles available in this project and the tools each role owns

Laravel domain

Tool	Description
artisan	Run whitelisted php artisan commands
migrateStatus	Migration status
envInfo / envInfoSafe	Environment info (safe variant redacts secrets)
cache	Clear/cache config, routes, views
configGet	Inspect config values
schema	List tables / columns
model	Scan Eloquent models
log	Recent log entries
routeList	Routes with name/URI/method filters
runTest	Run PHPUnit tests
frontendScanner	Scan views/js/css structure
makeModel / makeController / makeMigration	Scaffold classes
migrationAnalyzer	Parse migrations into schema
composerAnalyzer	Project dependencies
projectContext	Full project context (cached by file mtime)
crudGenerator	Full CRUD generator
createFeature	CRUD + Blade views
apiGenerator	REST API generator (optional Sanctum auth)
debugWorkflow	Error location, diagnosis, fix suggestions
intentPlanner	Natural-language request → executable plan
workflowStatus	List/inspect/resume/rollback runs
contextSource	Show whether each piece of project context came from cache or was rebuilt live
listRoles	List the roles available in this project and the tools each role owns

Why agents trust their answers

Two design principles borrowed from real-world system-prompt architecture:

• Roles, not tool lists. listRoles tells the agent who it can be in this project — an explorer (read-only investigation), an engineer (build and fix), or a maintainer (ops and verification) — and which tools each role owns. Instead of facing a flat wall of tools, the agent picks a role and stays inside its boundary. Fewer missteps, clearer intent.
• Know where your facts come from. contextSource shows whether each module of project context was served from cache or rebuilt in real time, and context itself is assembled through a priority chain (cache → live → safe default) instead of "the agent figures it out". When the agent answers, it knows how fresh the facts are — and so do you.

Before: an agent stares at 29 tools and stale context it can't date-check. After: it knows its role, its toolset, and the freshness of everything it reads.

Quick Start

npm install
npm start

Set the project path to work against:

# 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()

Run the server with a single MCP request to see which tools a project exposes:

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

With OpenCode

Add to ~/.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" }
    }
  }
}

With Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Environment Variables

Variable	Default	Description
CORTEX_PROJECT_PATH	—	Project path (takes priority)
LARAVEL_PROJECT_PATH	process.cwd()	Backward-compatible Laravel project path
PHP_PATH	php	PHP executable path (Laravel domain)
LLM_API_KEY	(empty)	Enables the LLM semantic layer for intentPlanner
LLM_BASE_URL	https://api.deepseek.com/v1	OpenAI-compatible API base URL
LLM_MODEL	deepseek-chat	LLM model used for intent analysis

Architecture

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

Each domain exports a DomainManifest (id, name, detect, getTools, getHandlers, getProjectPath?, roles?). Roles declare who the agent can be in this project (explorer / engineer / maintainer) and which tools each role owns — the agent can call listRoles instead of guessing. The Laravel domain keeps its own runtime (domains/laravel/mcp.ts), tools, workflows, context, security, and planner — the pre-existing 24-tool surface is unchanged.

Requirements

• Node.js 18+
• PHP 8.1+ (for the Laravel domain)

Development

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)

License

MIT