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.

Related MCP server: laravel-herd-mcp

Built-in Domains

Generic domain

Laravel domain

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

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