Cortex Agent Runtime — MCP-нативный фреймворк для AI-агентов

До: ИИ не понимает ваш проект. После: ИИ может анализировать, генерировать и отлаживать приложения.

Сервер Model Context Protocol (MCP), который превращает любого агента кодирования (Claude, Cursor, Codex, OpenCode и другие) в автономный инженерный мозг для ваших проектов. Среда выполнения не зависит от типа проекта: она загружает набор доменов в зависимости от того, что представляет собой ваш проект, поэтому одна и та же среда работает с приложениями Laravel, проектами Node и всем остальным.

Среда выполнения

• Определение типа проекта — core/detector.ts проверяет проект и активирует соответствующие домены. Общие инструменты загружаются всегда; домен Laravel активируется при наличии composer.json + artisan.

• Регистрация доменов — core/registry.ts предоставляет registerDomain(manifest); listTools() / callTool() остаются стабильными, поэтому поверхность MCP не меняется между проектами.

• Безопасно по умолчанию — только локально, офлайн, без телеметрии. Встроены белые списки команд, блокировка опасных команд и редактирование конфиденциальных данных.

Related MCP server: Project Planner MCP

Встроенные домены

Общий домен

Домен Laravel

Почему агенты доверяют своим ответам

Два принципа проектирования, заимствованные из реальной архитектуры системных подсказок:

• Роли, а не списки инструментов. listRoles сообщает агенту, кем он может быть в этом проекте — исследователем (только чтение), инженером (создание и исправление) или сопровождающим (операции и проверка) — и какими инструментами владеет каждая роль. Вместо плоского списка инструментов агент выбирает роль и остается в ее границах. Меньше ошибок, яснее намерения.

• Знайте, откуда берутся ваши факты. contextSource показывает, была ли каждая часть контекста проекта получена из кэша или пересобрана в реальном времени, а сам контекст собирается через цепочку приоритетов (cache → live → safe default) вместо того, чтобы «агент сам разбирался». Когда агент отвечает, он знает, насколько свежи факты — и вы тоже.

До: агент смотрит на 29 инструментов и устаревший контекст, который не может проверить по дате. После: он знает свою роль, свой набор инструментов и свежесть всего, что читает.

Быстрый старт

npm install
npm start

Укажите путь к проекту, с которым нужно работать:

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

Запустите сервер с одним MCP-запросом, чтобы увидеть, какие инструменты доступны для проекта:

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

С OpenCode

Добавьте в ~/.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" }
    }
  }
}

С Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Переменные окружения

Архитектура

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

Каждый домен экспортирует DomainManifest (id, name, detect, getTools, getHandlers, getProjectPath?, roles?). Роли объявляют, кем агент может быть в этом проекте (исследователь / инженер / сопровождающий) и какими инструментами владеет каждая роль — агент может вызвать listRoles вместо того, чтобы угадывать. Домен Laravel сохраняет собственную среду выполнения (domains/laravel/mcp.ts), инструменты, рабочие процессы, контекст, безопасность и планировщик — существующая поверхность из 24 инструментов не изменена.

Требования

• Node.js 18+

• PHP 8.1+ (для домена Laravel)

Расширение Pi (порт инструментов MCP)

Тот же набор инструментов, как расширение pi coding agent: 34 из 35 инструментов перенесены с MCP-сервера на нативные пользовательские инструменты pi, за исключением intentPlanner (pi сам является LLM; преобразование естественного языка в план там избыточно). Исходный код: pi-extension/cortex-laravel/.

Установка

# 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

Затем перезапустите pi (или /reload). Расширение регистрирует 34 инструмента:

Определение пути к проекту: переменные окружения CORTEX_PROJECT_PATH / LARAVEL_PROJECT_PATH, с возвратом к cwd сессии pi. Инструменты Laravel самозащищаются с понятной ошибкой на не-Laravel проектах; инструменты оркестрации читают/записывают ту же структуру .htask/, что и MCP-сервер (и автономный CLI htask).

Отличия от MCP-сервера

• Безопасность — тот же белый список команд + валидатор опасных шаблонов (два уровня), плюс подтверждение на taskAdvance / taskAccept / workflowStatus (возобновление·откат): установите CORTEX_CONFIRM_OFF=1, чтобы разрешить в скриптах.

• Совместимость с Laravel 11+ — удаленный вышестоящий config:get возвращается к tinker; API-маршруты автоматически создаются через artisan install:api, если routes/api.php отсутствует.

• Проекты nix flake — resolvePhpPath проверяет известные пути установки nix (не только nix в PATH).

• Ошибки — выброшенные ошибки отображаются как ошибки инструментов; результаты инструментов — обычный текст (без обертки MCP JSON-RPC).

Разработка

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)

Лицензия

MIT