Cortex Agent Runtime — MCPネイティブAIエージェントフレームワーク

Before: AIはあなたのプロジェクトを理解していません。After: AIはアプリケーションの分析、生成、デバッグができます。

任意のコーディングエージェント（Claude、Cursor、Codex、OpenCodeなど）を、作業中のプロジェクトの自律的なエンジニアリング脳に変えるModel Context Protocol (MCP)サーバーです。ランタイムはプロジェクトタイプ非依存です。プロジェクトの内容に基づいて一連のドメインを読み込むため、同じランタイムがLaravelアプリ、Nodeプロジェクト、その他あらゆるものに対応します。

ランタイム

• プロジェクトタイプ検出 — core/detector.tsがプロジェクトを検査し、一致するドメインをアクティブにします。汎用ツールは常に読み込まれます。Laravelドメインはcomposer.jsonとartisanが存在する場合にアクティブになります。

• ドメイン登録 — core/registry.tsはregisterDomain(manifest)を公開します。listTools() / callTool()は安定しているため、MCPサーフェスはプロジェクト間で変わりません。

• デフォルトで安全 — ローカルのみ、オフライン、テレメトリなし。コマンドのホワイトリスト、危険なコマンドのブロック、機密データの編集が組み込まれています。

Related MCP server: Project Planner MCP

組み込みドメイン

汎用ドメイン

Laravelドメイン

エージェントが回答を信頼する理由

実世界のシステムプロンプトアーキテクチャから借用した2つの設計原則：

• ツールリストではなくロール。 listRolesは、このプロジェクトでエージェントが誰になれるか（エクスプローラー（読み取り専用の調査）、エンジニア（構築と修正）、メンテナー（運用と検証））と、各ロールが所有するツールを伝えます。エージェントはツールのフラットな壁に直面する代わりに、ロールを選択し、その境界内に留まります。ミスが減り、意図が明確になります。

• 事実の出所を知る。 contextSourceは、プロジェクトコンテキストの各モジュールがキャッシュから提供されたか、リアルタイムで再構築されたかを示します。また、コンテキスト自体は「エージェントが推測する」のではなく、優先チェーン（cache → live → safe default）を通じて組み立てられます。エージェントが回答するとき、事実がどれだけ新しいかを知っています。そしてあなたも同様です。

Before: エージェントは29のツールと、日付を確認できない古いコンテキストを見つめています。 After: 自分のロール、ツールセット、そして読むすべてのものの鮮度を知っています。

クイックスタート

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?）をエクスポートします。ロールは、このプロジェクトでエージェントが誰になれるか（explorer / engineer / maintainer）と、各ロールが所有するツールを宣言します。エージェントは推測する代わりにlistRolesを呼び出すことができます。Laravelドメインは独自のランタイム（domains/laravel/mcp.ts）、ツール、ワークフロー、コンテキスト、セキュリティ、プランナーを保持しており、既存の24ツールのサーフェスは変更されません。

要件

• Node.js 18+

• PHP 8.1+（Laravelドメイン用）

Pi拡張（MCPツールの移植）

同じツールセットをpiコーディングエージェント拡張として提供します。35ツールのうち34が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環境変数を使用し、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