Cortex Agent Runtime — MCP-natives KI-Agenten-Framework

Vorher: KI versteht dein Projekt nicht. Nachher: KI kann Anwendungen analysieren, generieren und debuggen.

Ein Model Context Protocol (MCP)-Server, der jeden Coding-Agenten (Claude, Cursor, Codex, OpenCode und weitere) in ein autonomes Engineering-Gehirn für die Projekte verwandelt, an denen du arbeitest. Die Runtime ist projekttyp-agnostisch: sie lädt eine Reihe von Domänen basierend darauf, was dein Projekt ist, sodass dieselbe Runtime in Laravel-Apps, Node-Projekten und allem anderen funktioniert.

Runtime

• Projekttyp-Erkennung — core/detector.ts inspiziert das Projekt und aktiviert die passenden Domänen. Generische Tools werden immer geladen; die Laravel-Domäne aktiviert sich, wenn composer.json + artisan vorhanden sind.

• Domänenregistrierung — core/registry.ts stellt registerDomain(manifest) bereit; listTools() / callTool() bleiben stabil, sodass sich die MCP-Oberfläche zwischen Projekten nicht ändert.

• Standardmäßig sicher — nur lokal, offline, keine Telemetrie. Befehls-Whitelists, die Blockierung gefährlicher Befehle und die Schwärzung sensibler Daten sind integriert.

Related MCP server: Project Planner MCP

Integrierte Domänen

Generische Domäne

Laravel-Domäne

Warum Agenten ihren Antworten vertrauen

Zwei Designprinzipien, die aus realer System-Prompt-Architektur übernommen wurden:

• Rollen, keine Werkzeuglisten. listRoles sagt dem Agenten, wer er in diesem Projekt sein kann — ein explorer (nur lesende Untersuchung), ein engineer (bauen und reparieren) oder ein maintainer (Betrieb und Verifikation) — und welche Tools jede Rolle besitzt. Statt vor einer flachen Wand aus Tools zu stehen, wählt der Agent eine Rolle und bleibt innerhalb ihrer Grenzen. Weniger Fehltritte, klarere Absicht.

• Wisse, woher deine Fakten kommen. contextSource zeigt, ob jedes Modul des Projektkontexts aus dem Cache bedient oder in Echtzeit neu erstellt wurde, und der Kontext selbst wird über eine Prioritätskette (cache → live → safe default) zusammengesetzt, statt dass „der Agent es schon herausfindet“. Wenn der Agent antwortet, weiß er, wie frisch die Fakten sind — und du auch.

Vorher: Ein Agent starrt auf 29 Tools und veralteten Kontext, dessen Datum er nicht prüfen kann. Nachher: Er kennt seine Rolle, sein Toolset und die Frische von allem, was er liest.

Schnellstart

npm install
npm start

Lege den Projektpfad fest, an dem gearbeitet werden soll:

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

Führe den Server mit einer einzigen MCP-Anfrage aus, um zu sehen, welche Tools ein Projekt bereitstellt:

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

Mit OpenCode

Füge zu ~/.config/opencode/opencode.jsonc hinzu:

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

Mit Claude Desktop

Füge zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

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

Umgebungsvariablen

Architektur

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

Jede Domäne exportiert ein DomainManifest (id, name, detect, getTools, getHandlers, getProjectPath?, roles?). Rollen deklarieren, wer der Agent in diesem Projekt sein kann (explorer / engineer / maintainer) und welche Tools jede Rolle besitzt — der Agent kann listRoles aufrufen, statt zu raten. Die Laravel-Domäne behält ihre eigene Runtime (domains/laravel/mcp.ts), Tools, Workflows, Kontext, Sicherheit und ihren eigenen Planner — die bestehende Oberfläche mit 24 Tools bleibt unverändert.

Anforderungen

• Node.js 18+

• PHP 8.1+ (für die Laravel-Domäne)

Pi-Erweiterung (Port der MCP-Tools)

Dasselbe Toolset als Erweiterung für pi coding agent: 34 der 35 Tools wurden vom MCP-Server auf native pi-Custom-Tools migriert, minus intentPlanner (pi ist selbst ein LLM; natürliche Sprache → Plan ist dort redundant). Quelle: pi-extension/cortex-laravel/.

Installation

# 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

Starte dann pi neu (oder /reload). Die Erweiterung registriert 34 Tools:

Projektpfad-Auflösung: die Env-Variablen CORTEX_PROJECT_PATH / LARAVEL_PROJECT_PATH, mit Fallback auf das cwd der pi-Sitzung. Laravel-Tools schützen sich selbst mit einer klaren Fehlermeldung bei Nicht-Laravel-Projekten; Orchestrierungs-Tools lesen/schreiben dasselbe .htask/-Layout wie der MCP-Server (und die eigenständige htask-CLI).

Unterschiede zum MCP-Server

• Sicherheit — dieselbe Befehls-Whitelist + Validator für gefährliche Muster (zwei Ebenen), plus eine Bestätigungsabfrage bei taskAdvance / taskAccept / workflowStatus (resume·rollback): setze CORTEX_CONFIRM_OFF=1, um das in Skripten zu erlauben.

• Laravel-11+-Kompatibilität — das upstream entfernte config:get fällt auf tinker zurück; API-Routen werden automatisch über artisan install:api erstellt, wenn routes/api.php fehlt.

• nix-flake-Projekte — resolvePhpPath testet bekannte nix-Installationspfade (nicht nur nix im PATH).

• Fehler — geworfene Fehler erscheinen als Tool-Fehler; Tool-Ergebnisse sind reiner Text (kein MCP-JSON-RPC-Wrapper).

Entwicklung

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)

Lizenz

MIT