Cortex Agent Runtime — MCP-네이티브 AI 에이전트 프레임워크

이전: AI는 당신의 프로젝트를 이해하지 못합니다. 이후: AI가 애플리케이션을 분석·생성·디버깅할 수 있습니다.

Model Context Protocol (MCP) 서버로, 모든 코딩 에이전트(Claude, Cursor, Codex, OpenCode 등)를 당신이 작업하는 프로젝트를 위한 자율 엔지니어링 두뇌로 바꿔줍니다. 이 런타임은 프로젝트 유형에 구애받지 않습니다: 프로젝트가 무엇이냐에 따라 도메인 세트를 로드하므로, Laravel 앱, Node 프로젝트 등 어디에서나 동일한 런타임이 작동합니다.

런타임

• 프로젝트 유형 감지 — core/detector.ts가 프로젝트를 검사하여 일치하는 도메인을 활성화합니다. 일반 도구는 항상 로드되고, composer.json + artisan이 있으면 Laravel 도메인이 활성화됩니다.

• 도메인 등록 — core/registry.ts가 registerDomain(manifest)를 노출하고, listTools() / callTool()은 안정적으로 유지되므로 MCP 표면이 프로젝트 간에 변경되지 않습니다.

• 기본적으로 안전 — 로컬 전용, 오프라인, 텔레메트리 없음. 명령어 화이트리스트, 위험 명령 차단, 민감 데이터 마스킹이 계층적으로 적용됩니다.

Related MCP server: Project Planner MCP

기본 제공 도메인

Generic 도메인

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 코딩 에이전트 확장으로 제공: MCP 서버에서 35개 도구 중 34개를 네이티브 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 환경 변수를 사용하고, 없으면 pi의 세션 cwd로 폴백합니다. Laravel 도구는 Laravel이 아닌 프로젝트에서 명확한 오류와 함께 자체 보호되며, 오케스트레이션 도구는 MCP 서버(및 독립 실행형 htask CLI)와 동일한 .htask/ 레이아웃을 읽고 씁니다.

MCP 서버와의 차이점

• 안전성 — 동일한 명령어 화이트리스트 + 위험 패턴 검증기(2계층)에 더해 taskAdvance / taskAccept / workflowStatus(재개·롤백)에 확인 게이트가 있습니다: 스크립트에서 허용하려면 CORTEX_CONFIRM_OFF=1을 설정하세요.

• Laravel 11+ 호환성 — 상위 버전에서 제거된 config:get은 tinker로 폴백되고, routes/api.php가 없으면 artisan install:api로 API 라우트가 자동 생성됩니다.

• nix flake 프로젝트 — resolvePhpPath가 알려진 nix 설치 경로를 검색합니다(PATH의 nix뿐만 아니라).

• 오류 — 발생한 오류는 도구 오류로 표시되고, 도구 결과는 일반 텍스트입니다(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