chaos-core-mcp

MCP-сервер, где ИИ — это ядро принятия решений, а не инструмент, который он предоставляет наружу. Вызывающий клиент (Claude, ChatGPT, Codex — неважно) не перебирает низкоуровневые конечные точки: он передаёт Chaos Core цель и позволяет когнитивному ядру проанализировать её, обнаружить доступные возможности, спланировать, проверить детерминированную политику, выполнить план, оценить результат и запомнить.

Начиная с v0.2 когнитивное ядро не зависит от транспортного протокола. Одно и то же ядро, те же инструменты, политики, память и реестр возможностей доступны двумя способами: через stdio для локальных MCP-клиентов и через Streamable HTTP на /mcp для удалённых MCP-клиентов, таких как пользовательские коннекторы Claude.

                     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 нет.

Цикл когнитивного ядра

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

В V1 каждый этап представлен собственным MCP-инструментом, поэтому каждый шаг остаётся контролируемым, а управляющий клиент сохраняет контроль между этапами:

Оба транспорта предоставляют именно этот список — это обеспечивается тестом, который получает список инструментов через реальный MCP-клиент на каждом транспорте и сравнивает определения.

core/brain.ts также реализует полный цикл как единую композируемую функцию (runCognitiveCore) — от цели сразу к результату, с автоматическим перепланированием при сбое шага и немедленной остановкой на REQUIRE_APPROVAL. Эта функция не зарегистрирована как MCP-инструмент в V1 (см. границы 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() создаёт сервисы уровня процесса один раз: конфигурацию, реестр возможностей, движок политики, хранилище памяти, реестр провайдеров, журнал аудита, логгер. createChaosCoreServer() создаёт поверх этого runtime один McpServer на каждую MCP-сессию, добавляет индивидуальный для сессии SessionState и регистрирует инструменты с внедрённым контейнером.

Ни один модуль ядра не импортирует контейнер зависимостей. core/intent.ts, core/planner.ts и capabilities/executor.ts объявляют по узкому структурному интерфейсу (IntentDeps, PlannerDeps, ExecutorDeps), которому контейнер соответствует — поэтому ядро тестируется изолированно и действительно ничего не знает о серверном и транспортном слоях.

Политика находится за пределами ИИ

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

Модель может предложить любую возможность; policy/engine.ts принимает решение как чистая функция от имени возможности и управляемого оператором файла политики. Модель не привлекается. Это разбито на:

• policy/permissions.ts — списки разрешения и запрета (allowedCapabilities, deniedCapabilities)

• policy/approvals.ts — какие из разрешённых возможностей ещё нужно подтверждать человеку (requireConfirmationFor)

• policy/engine.ts — объединяет их, плюс ресурсные ограничения (httpAllowedDomains)

Файл data/policy.json автоматически создаётся с безопасными defaults при первом запуске:

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

Транспорт не может обойти политику. capabilities/executor.ts — единственный путь от шага плана к обработчику возможности; он первым делом вызывает policy.check() и не содержит ветвей, зависящих от транспорта. Шаги, которые завершаются значением REQUIRE_APPROVAL, пропускаются, если вызывающий не передал confirmed: true; шаги, которые завершаются значением DENY, не выполняются вообще. Каждое решение пишется в журнал аудита вместе с идентификатором сессии.

Модель заменяема — намеренно

// 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;
}

Ничто за пределами src/providers/openai.ts не импортирует SDK вендора ИИ. Всё проходит через один интерфейс:

Когнитивные этапы соотносятся с ним так: рассуждение → generateJson, планирование → generateJson, а оценка → детерминированный код в core/evaluator.ts. Оценка специально не является вызовом провайдера, поэтому модель не может засчитать собственное неудачное выполнение как успешный результат.

Чтобы добавить модель/вендора: напишите файл src/providers/<name>.ts, реализующий AIProvider, зарегистрируйте его в providers/index.ts, задайте CHAOS_CORE_PROVIDER=<name>. Само имя модели настраивается один раз через OPENAI_MODEL — оно не встречается ни в одном другом файле.

Реестр возможностей — точка расширения

Объекты Capability имеют вид { name, description, risk, inputSchema (Zod), annotations, handler }. В V1 входят два:

• cognition.generate_text — универсальная генерация текста через активного провайдера

• http.request — только GET, ограничен policy.httpAllowedDomains

Чтобы добавить новую — внешний API, базу данных, другой MCP-сервер или одно из ваших приложений: создайте файл в src/capabilities/built-in/, экспортирующий Capability, и зарегистрируйте его в src/capabilities/index.ts. Ничего в core/, policy/, server/ или transport/ менять не нужно, и возможность становится видимой одновременно для локальных и удалённых клиентов. ИИ рассуждает по описаниям реестра, чтобы понять, какая возможность решает шаг плана — вы никогда не хардкодите 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 на Postgres или векчитый storplace означает добавление одного файла рядом с sqlite.ts и изменение фабрики. MCP-инструменты, планировщик, когнативное ядро и движок политики не меняются, потому что ни один из них не ссылается на SQLite.

База данных используется независимо от способа доставления запроса: факт, записанный через stdio, можно извлечь через HTTP, и он переживает перезапуск.

Рабочая память (контекст текущей сессии) — это 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 stdout принадлежит протоколу MCP. Все диагностические сообщения в коде проходят через observability/logger.ts, и stdio-транспорт принудительно отправляет этот логгер в stderr, даже если установлено значение CHAOS_CORE_LOG_STREAM=stdout.

Запуск через Streamable HTTP (удалённые клиенты)

npm run start:http

Сервер слушает HOST:PORT (по умолчанию 127.0.0.1:3000) и предоставляет:

Локальный endpoint: http://localhost:3000/mcp

HTTP-транспорт с сохраняемым состоянием: каждый вызов initialize создаёт Mcp-Session-Id, и дальнейшиезапросы должны его передавать. Именно поэтому chaoscore_plan может отдавать plan_id в chaoscore_execute без утечки планов между удалёнными клиентами. Запрос с неизвестным идентификатором сессии получает 404; запрос, не являющийся initialize, но без идентификатора сессии, получает 400.

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

Файл .env в рабочем каталоге будет вызван автоматически (встроенный загрузчик Node.js — без сторонних зависимостей). Файл .env.example содержит только заглушки; никогда не коммитьте реальные учётные данные.

Имена переменных COGNITION_* из версии до 0.2 по-прежнему работают как запасные варианты.

Подключение локального 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 добавьте его как удалённый MCP-сервер с этим URL (публичное развёртывание требует публичного HTTPS-URL — см. предупреждение о безопасности ниже). Чтобы опробовать его вручную:

npm run inspector:http

затем выберите «Streamable HTTP» и введите URL.

⚠️ Предупреждение о безопасности при удалённом развёртывании

В V1 нет аутентификации. Это сделано намеренно, и это безопасно только потому, что HTTP-транспорт по умолчанию привязывается к 127.0.0.1. Слой устроен так, что middleware аутентификации подключается без лишних усилий (AuthMiddleware в src/transport/http.ts, применяется к маршруту MCP до любой обработки MCP) — но никакой имитации не предусмотрено: ни заглушки OAuth, ни захардкоженных секретов, ни bearer-токена, который лишь выглядит как защита.

Прежде чем открывать доступ за пределы localhost, вы обязаны добавить:

• Аутентификацию на маршруте /mcp (ресурсный сервер OAuth 2.1 в соответствии со спецой MCP auth, или шлюз, на котором завершается идентификация)

• TLS — сервер говорит по обычному HTTP; завершайте TLS на обратном прокси

• Ограничение скорости и лимиты размера запросов — каждый вызов reason/plan тратит вашу квоту OpenAI

• Защиту от DNS-ребдинга — установите MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS

• Проверенный policy.json — по умолчанию разрешены все зарегистрированные возможности, кроме тех, что требуют подтверждения

• Долговечное хранилище аудита — журнал аудита V1 представляет собой кольцевой буфер в памяти

Если вы привяжетесь к не-loopback адресу без middleware, сервер при запуске выведет в журнал предупреждение, в котором сказано именно это. Полный контрольный список — в docs/remote-deployment.md.

Ключ OpenAI API считывается из окружения сервера внутри providers/openai.ts и никогда не возвращается в выводе инструментов, в данных инспектора, в записях аудита или в HTTP-ответах.

Возможности и границы V1

Что включено:

• TypeScript/Node, на MCP SDK, OpenAI Responses API как провайдер по умолчанию (с возможностью замены)

• Двойной транспорт: stdio + Streamable HTTP на /mcp, одно общее когнитивное ядро

• Когнитивная поверхность из шести инструментов, идентичная на обоих транспортах

• Реестр возможностей + детерминированный механизм политик + структурированные события аудита

• SQLite Semantic Memory за сменяемым интерфейсом MemoryStore

• Zod-валидация каждого входа инструмента и всех данных capability

Что сознательно не включено:

• Нет UI

• Нет роёв агентов / мультиагентной архитектуры

• Нет автономного фонового выполнения — вкладка chaoscore_execute — идеально заданные шаги; полный цикл перепланирования в core/brain.ts существует, но не выставляется как инструмент

• Нет реализации OAuth, нет мультиарендности, нет маркетплейса

• Нет MCP-федерации (реестр мог бы разместить capability-адаптер, но его не поставляется)

Сборка и тестирование

npm run build

npm test

Тестовый набор выполняется против собранного вывода и покрывает: детерминированность политик и невозможность их обхода, сохранение памяти во время симуляционного перезапуска и живой MCP-клиент, подключающийся по обоим транспортам для проверки идентичных поверхностей инструментов, общей памяти и того, что отклонённая capability блокируется на каждом.