chaos-core-mcp

AIがツールを公開するのではなく、AI自身が意思決定のカーネルとなるMCPサーバーです。呼び出し元クライアント（Claude、ChatGPT、Codexなど）は低レベルのエンドポイントを列挙するのではなく、Chaos Coreに目的を渡し、Cognitive Coreがその目的について推論し、ケイパビリティを発見し、計画し、決定論的ポリシーをチェックし、実行し、評価し、記憶する、という流れを任せます。

v0.2の時点で、cognitive coreはトランスポート非依存です。コア、ツール、ポリシー、メモリ、ケイパビリティレジストリはすべて、ローカルMCPクライアント向けのstdioと、ClaudeカスタムコネクタなどのリモートMCPクライアント向けのStreamable HTTP（/mcp）という2つの経路からアクセスできます。

                     CHAOS CORE
                         │
                  Cognitive Core
                         │
        ┌────────────────┴────────────────┐
        │                                 │
     stdio                         Streamable HTTP
        │                                 │
        ▼                                 ▼
 Local MCP clients                Remote MCP clients
                                     /mcp

認知処理のHTTP版は存在しません。src/transport/stdio.ts と src/transport/http.ts は、どちらも単一のサーバーファクトリ createChaosCoreServer() を呼び出します。トランスポートは認知レイヤーからは不可視であり、http_reason / remote_plan のような重複もありません。

Cognitive Core ループ

objective
   ↓
context
   ↓
AI planning
   ↓
policy
   ↓
capability execution
   ↓
evaluation
   ↓
result

V1では各段階が独自のMCPツールとして公開されるため、すべてのステップを検査可能に保ちながら、呼び出し元AIが段階間の制御を維持できます。

両方のトランスポートはこの同一のリストを提供します。これは、各トランスポート上で実際のMCPクライアントを介してツールを列挙し、定義を比較するテストによって保証されています。

core/brain.ts はまた、全体 ループを単一の合成可能な関数（runCognitiveCore）として実装しています。目的から結果までを一気に処理し、ステップ失敗時には自動で再計画し、REQUIRE_APPROVAL が発生すると即座に停止します。V1ではMCPツールとして登録されていません（V1境界 を参照）が、完全に配線済みであり、将来の chaoscore_achieve ツールを書き換えなしで支えられる状態にあります。

アーキテクチャ

src/
  index.ts                    transport dispatcher (stdio by default)
  config.ts                   the only file that reads process.env

  server/                     ← composition root; transport-independent
    create-server.ts          createRuntime() + createChaosCoreServer()
    register-tools.ts         the single definition of the V1 tool surface
    types.ts                  RuntimeServices / ChaosCoreDependencies
    schemas.ts                shared Zod schemas
    tools/                    reason plan execute inspect remember recall

  transport/                  ← the ONLY transport-aware code
    stdio.ts                  local subprocess transport (stdout reserved for JSON-RPC)
    http.ts                   Streamable HTTP at /mcp (stateful sessions)

  core/                       brain intent planner evaluator context types
  capabilities/               registry executor types + built-in/
  memory/                     store (factory) sqlite (impl) types (MemoryStore interface)
  policy/                     engine permissions approvals types
  providers/                  ai-provider (AIProvider interface) openai index
  state/                      session (Working Memory) execution (trace assembly)
  observability/              logger events audit
  util/                       to-structured

依存性注入と、それぞれのライフタイム

createRuntime() はプロセス全体のサービスを一度だけ構築します：config、ケイパビリティレジストリ、ポリシーエンジン、メモリストア、プロバイダーレジストリ、監査ログ、loggerです。createChaosCoreServer() はそのランタイムの上にMCPセッションごとに1つの McpServer を構築し、セッションごとの SessionState を追加して、注入された統合コンテナとともにツールを登録します。

コアモジュールは依存コンテナをインポートしません。core/intent.ts、core/planner.ts、capabilities/executor.ts はそれぞれ、コンテナがたまたま充足する狭い構造的インターフェース（IntentDeps、PlannerDeps、ExecutorDeps）を宣言しています。そのため、コアは単体でテスト可能で、サーバー層やトランスポート層について本当に知らない状態が保たれます。

ポリシーはAIの外側にある

AI proposes action
      ↓
deterministic policy engine
      ↓
ALLOW / DENY / REQUIRE_APPROVAL

モデルはどのような直接的なケイパビリティを広い歓迎されるものかもしれません。policy/engine.ts が、ケイパビリティ名とオペレーターが管理するポリシーファイルを純関数（pure function）として決定します。モデルは一切参照されません。次のように分けられます：

• policy/permissions.ts — 許可/拒否リスト（allowedCapabilities、deniedCapabilities）

• policy/approvals.ts — 許可されたケイパビリティのうち、どれが人間の承認を必要とするか（requireConfirmationFor）

• policy/engine.ts — それらを組み合わせ、さらに制限付きリソースを扱う（httpAllowedDomains）

data/policy.json は初回起動時に安全なデフォルトで自動生成されます。

{
  "allowedCapabilities": [],
  "deniedCapabilities": [],
  "requireConfirmationFor": ["http.request"],
  "httpAllowedDomains": []
}

トランスポートがポリシーを迂回することはできません。 capabilities/executor.ts は、プランステップからケイパビリティハンドラへの唯一の経路であり、最初に policy.check() を呼び出し、トランスポート依存の分岐を持ちません。REQUIRE_APPROVAL に解決されるステップは、呼び出し側が confirmed: true を渡さない限りスキップされます。DENY に解決されるステップは一切実行されません。すべての決定はセッションIDとともに監査証跡に書き込まれます。

AIモデルは意図的に置き換え可能

src/providers/openai.ts 以外のどこもAIベンダーSDKをインポートしません。すべては1つのインターフェースを経由します：

// src/providers/ai-provider.ts
interface AIProvider {
  id: string;
  displayName: string;
  generateText(instructions, input, options?): Promise<{ text, model, providerId }>;
  generateJson(instructions, input, jsonShapeDescription, options?): Promise<{ raw, model, providerId }>;
  isConfigured(): boolean;
}

認知ステージは、reason → generateJson、plan → generateJson、evaluate → core/evaluator.ts 内の決定論的コード という形でこのインターフェースに対応します。評価は意図的に プロバイダ呼び出し ではなく、検証が失敗した実行をモデルが成功として評価することは絶対にできません。

モデル／ベンダーを追加するには： AIProvider を実装する src/providers/<name>.ts を作成し、providers/index.ts に登録して、CHAOS_CORE_PROVIDER=<name> を設定します。モデル名自体は OPENAI_MODEL で一度だけ設定され、他のファイルには現れません。

Capability registry — 拡張の接ぎ目

Capability オブジェクトは { name, description, risk, inputSchema (Zod), annotations, handler } です。V1には次の2つが実装されています：

• cognition.generate_text — アクティブなプロバイダで提供する汎用テキスト生成

• http.request — GETのみ、policy.httpAllowedDomains で制御

追加するには、外部API、データベース、別のMCPサーバー、または自作アプリなどを問わず、src/capabilities/built-in/ に Capability をエクスポートするファイルを置き、src/capabilities/index.ts に登録します。core/、policy/、server/、transport/ は何も変更されず、ローカルとリモートの両方のクライアントから同時に参照できるようになります。AIはレジストリの説明をもとに、どのケイパビリティがプランのステップを解決できるかを発見します。if (task === "email") ... とハードコードすることはありません。

将来の方向性： このレジストリが成長の道です。ケイパビリティパック（登録グループ）、risk をキーにした過パビリティ単位のポリシー（名前の列挙ではなく）、リモートMCPクライアントをラップしてChaos Coreが他のMCPサーバーを連携できるようにするアダプタケーパビリティ、そして、反復目的のために成功するケイパビリティの並びを学習する永続的な手続きメモリなどが考えられます。

メモリ

V1は永続的なセマンティックメモリ層を実装しています。背後にあるのは MemoryStore インターフェース（src/memory/types.ts）で、SQLite実装（src/memory/sqlite.ts）がファクトリ（src/memory/store.ts）によって選択されます。バックエンドは node:sqlite（Node 22.5+ 組み込み、ネイティブ依存ゼロ）で、タグ、TTL、部分一致検索、改ページを備えたキーバリュー型です。

SQLiteをPostgreSQLやベクターストアに置き換えるには、sqlite.ts の隣に1ファイル追加してファクトリを変えるだけで十分です。MCPツール、プランナー、Cognitive Core、ポリシーエンジンはSQLiteを参照していないため、変更は不要です。

同じデータベースがリクエストの到着方法によらず使用されます。stdioで書き込まれた事実はHTTPでも potential参照でき、再起動後も残ります。

ワーキングメモリ（現在のセッションコンテキスト）は src/state/session.ts です。エピソードメモリ（過去のタスクで発生したこと）と手続きメモリ（学習された成功したステップ列）はアーキテクチャ上では言及されていますが、V1では実装されていません。

セットアップ

npm install
cp .env.example .env    # then fill in OPENAI_API_KEY
npm run build

stdioで実行する（ローカルクライアント、開発）

npm start

npm run start:stdio がその明示的な並存です。npm start はstdioのままなので、既存のローカルセットアップには影響しません。

stdioでは、standard output は MCPプロトコル専用です。コードベース内のすべての診断は observability/logger.ts を経由。stdioトランスポート害は、CHAOS_CORE_LOG_STREAM=stdout が設定されている場合でも、ロガーを強制的にstderrにします。

Streamable HTTPで実行（リモートクライアント）

npm run start:http

HOST:PORT（デフォルト: 127.0.0.1:3000）でリッスンし、以下を公開します：

ローカルエンドポイント: http://localhost:3000/mcp

HTTPトランスポートはステートフルです。各 initialize は Mcp-Session-Id を作成し、後続のリクエストはそれを保持している必要があります。これにより chaoscore_plan が plan_id を chaoscore_execute に渡せる一方、リモートクライアント間でプランを泄漏しません。未知のセッションIDの要求は 404、セッションIDを持たない非initialize要求は 400 になります。

環境変数

作業ディレクトリの .env は自動的にロードされます（Node組み込みのローダー — 依存不要）。.env.example はプレースホルダーだけを含みます。実際の資格情報をコミットしてはなりません。

0.2以前のCOGNITION_*変数名は、フォールバックとして引き続き機能します。

ローカルMCPクライアントの接続

Claude Desktop / Claude Code / 任意のstdioクライアント:

{
  "mcpServers": {
    "chaos-core": {
      "command": "node",
      "args": ["F:/Chaos-Origins/chaos-core-mcp/dist/index.js", "--stdio"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

またはMCP Inspectorを使う場合:

npm run inspector:stdio

リモートMCPクライアントの接続

HTTPトランスポートを起動し、クライアントをエンドポイントURLに向けます:

http://localhost:3000/mcp

Claudeのカスタムコネクタの場合は、そのURLをリモートMCPサーバーとして追加します（公開デプロイには公開HTTPS URLが必要です。下記のセキュリティ警告を参照してください）。手動で試してみるには:

npm run inspector:http

次に「Streamable HTTP」を選択して、URLを入力します。

⚠️ リモートデプロイのセキュリティ警告

V1には認証が一切搭載されていません。 これは意図的なものであり、HTTPトランスポートがデフォルトで127.0.0.1にバインドされるためにのみ安全です。このレイヤーは、認証ミドルウェアをきれいに組み込めるように構造化されています（src/transport/http.ts内のAuthMiddlewareは、MCP処理の前にMCPルートに適用されます）— ただし、偽物は一切提供されません。スタブのOAuth、ハードコードされたシークレット、セキュリティらしく見えるだけのベアラートークンはありません。

localhost以外に公開する前に、必ず追加する必要があります:

• /mcpルートへの認証（MCP認証仕様に沿ったOAuth 2.1リソースサーバー、またはアイデンティティを終端するゲートウェイ）

• TLS — サーバーはプレーンなHTTPで通信します。リバースプロキシでTLSを終端してください

• レート制限とリクエストサイズ制限 — reason/plan呼び出しのたびにOpenAIのクォータを消費します

• DNSリバインディング保護 — MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINSを設定します

• レビュー済みのpolicy.json — デフォルトでは、確認が必要なものを除くすべての登録済みケーパビリティを許可します

• 永続的な監査ストレージ — V1の監査トレイルはインメモリリングバッファです

ミドルウェアなしで非ループバックアドレスにバインドすると、サーバーは起動時にこの内容のまま警告をログに記録します。完全なチェックリストはdocs/remote-deployment.mdを参照してください。

OpenAI APIキーはproviders/openai.ts内でサーバーの環境から読み取られ、ツール出力、インスペクションペイロード、監査エントリ、HTTPレスポンスのいずれにも返されません。

V1のケービリティと境界

含まれているもの:

• TypeScript/Node、MCP SDK、デフォルトで利用可能な（交換可能な）プロバイダーとしてのOpenAI Responses API

• デュアルトランスポート: stdio + /mcpでのStreamable HTTP、および共有された単一の認知コア

• 6ツールで構成される認知的サーフェス。両方のトランスポートで同一

• ケービリティレジストリ + 決定論的ポリシーエンジン + 構造化された監査イベント

• 交換可能なMemoryStoreインターフェースの背後にあるSQLite Semantic Memory

• すべてのツール入力とすべてのケービリティ入力に対するZodでの検証

意図的に含めていないもの:

• UIなし

• エージェントスウォーム / マルチエージェントアーキテクチャなし

• 自律的なバックグラウンド実行なし — chaoscore_executeは与えられた手順をそのまま実行するだけです。core/brain.tsの完全ループの再プランニングは存在しますが、ツールとしては公開されていません

• OAuth実装なし、マルチテナンシーなし、マーケットプレイスなし

• MCPサーバーのフェデレーションなし（レジストリはアダプタ・ケービリティをホストできますが、同梱されているものはありません）

ビルドとテスト

npm run build

npm test

このスイートはビルドの生成物に対して実行され、以下をカバーしています: ポリシーの決定性と非バイパス性、シミュレートした再起動をまたいだメモリの永続性、そしてライブMCPクライアントが両方のトランスポートに接続して、同一のツールサーフェスと共有メモリを検証し、拒否されたケービリティが各トランスポートでブロックされることを確認します。