chaos-core-mcp

一个 MCP 服务器，AI 是决策内核，而不是它暴露的工具。调用方（Claude、ChatGPT、Codex 等）不需要枚举底层接口——它把一个目标交给 Chaos Core，让 Cognitive Core 对其推理、发现能力、制定计划、检查确定性策略、执行、评估，然后记忆。

自 v0.2 起，认知核心是与传输无关的（transport-agnostic）。同一套核心、工具、策略、记忆和能力注册表可以通过两种方式访问：本地 MCP 客户端走 stdio，远程 MCP 客户端（例如 Claude 自定义连接器）走位于 /mcp 的 Streamable HTTP。

                     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 工具暴露出来，因此每一步都可被检查，且调用方 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() 构建进程级服务一次：配置、能力注册表、策略引擎、内存存储、提供者注册表、审计日志、日志记录器。运行时之上，createChaosCoreServer() 为每个 MCP 会话构建一个 McpServer，增加一个 per-session 的 SessionState，并注册这些工具（注入的是组合后的依赖容器）。

没有任何核心 module 导入依赖容器。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 以纯函数的方式，以能力名称和 operator 控制的策略文件为输入来决定是否允许。整个过程对模型是不可咨询的。拆分为：

• policy/permissions.ts — allow/deny 列表（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 的步骤根本不会执行。每一步决策都会连同其 session id 记录到一个审计式的事件流中。

AI 模型可以被替换，这是刻意设计

在 src/providers/openai.ts 之外，没有任何地方导入 AI 提供商的 SDK。一切都要通过一个接口：

// 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 中的确定性代码。eval` 特意不是提供商调用，因此模型永远无法将自己一次失败的执行“判为”成功。

要添加一个模型/提供商： 编写实现 AIProvider 的 src/providers/<name>.ts，在 providers/index.ts 注册它，设置 CHAOS_CORE_PROVIDER=<name>。模型名本身只通过 OPENAI_MODEL 配置一次——它在其他文件中都不出现。

能力注册表——扩展缝

Capability 对象是 { name, description, risk, inputSchema, annotations, handler }。V1 包含：

• cognition.generate_text — 通过默认 provider 进行通用文本生成

• http.request — 只支持 GET，受策略 policy.httpAllowedDomains 限制

要再加一个——外部 API、数据库、另一个 MCP 服务器，或你自己的应用：在 src/capabilities/built-in/ 中创建一个文件，导出 Capability，然后在 src/capabilities/index.ts 注册它即可。core/、policy/、server/ 或 transport/ 都不用改，而且本地和远程客户端会同时对它可见。AI 根据注册表中的 item 描述推理出哪个能力能完成计划步骤——你永远不会在代码里写死 if (task === "email") ... 这样的逻辑。

未来方向： 注册表就是扩展的路径——能力 包（一组注册的能力）、基于 risk 而不是逐个名称的按能力策略、一个包装远端 MCP 客户端使 Chaos Core 能 federation 其他 MCP 服务器的 adapter 能力，以及持久化的过程性记忆，用于学习哪些能力序列能成功完成重复出现的目标。

记忆

V1 实现了可持久化的语义记忆层，通过 MemoryStore 接口（src/memory/types.ts）和由工厂（src/memory/store.ts）选择的 SQLite 实现（src/memory/sqlite.ts）来支持。底层是 node:sqlite —— 内置在 Node 22.5+ 中，零额外的原生依赖：键值存储，带标签、TTL、子串搜索和分页。

把 SQLite 换成 Postgres 或矢量存储，只需要在 sqlite.ts 旁边增加一个文件并修改工厂调用。MCP 工具、planner、认知核心和策略引擎都不需要动，因为它们都不引用 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）并露出：

本地端点：http://localhost:3000/mcp

HTTP 传输是带上会话状态的：每一个 initialize 都会签发一个 Mcp-Session-Id，后续请求必须携带它。正是因为这样，chaoscore_plan 才能把 plan_id 交给 chaoscore_execute，而不会计划泄漏给另一个远程会话。带 unknown session id 的请求会得到 404；不带 session id 的非 initialize 请求会得到 400。

环境变量

会从工作目录自动加载 .env 文件（Node 内置 loader，无额外依赖）。.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 自定义连接器，将其作为远程 MCP 服务器添加，使用该 URL（公开部署需要公开的 HTTPS URL —— 请参阅下方的安全警告）。若要手动测试：

npm run inspector:http

然后选择“Streamable HTTP”并输入 URL。

⚠️ 远程部署的安全警告

V1 不附带任何认证。 这是有意为之，只因为 HTTP 传输默认绑定到 127.0.0.1 才是安全的。该层的结构设计让认证中间件能够干净地接入（AuthMiddleware 在 src/transport/http.ts 中，在任何 MCP 处理之前应用到 MCP 路由）——但没有提供任何虚假的东西：没有 OAuth 存根，没有硬编码的秘密，没有只是看起来像安全的 bearer token。

在将服务暴露到 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

• 纯化和 HTTP 双传输：stdio + /mcp 上的 Streamable HTTP，共享同一认知核心

• 由六个工具组成的认知界面，两种传输上完全一致

• 能力注册表 + authorize cells + metadata policy engine + structured audit events : 能力注册表 + 确定的策略引擎 + 结构化审计事件

• SQLite Semantic Memory，后端是可替换的 MemoryStore 接口

• 对每个工具输入和每个能力输入进行 Zod 验证

刻意排除的内容：

• 无 UI

• 无 agent 集群 / 多 agent 架构

• 无序自动后台执行 —— chaoscore_execute 只运行给定的步骤；core/brain.ts 中完整循环的重新规划存在，但没有暴露为工具

• 无 OAuth 实现，无 multi-tenancy，无 marketplace

• 无 MCP 服务器联邦（注册表可以托管一个适配器能力，但没有附带的适配器）

构建与测试

npm run build

npm test

该测试套件针对构建产物运行，并涵盖：策略的确定性与不可绕过性、模拟重启后的记忆持久性，以及一个通过两种传输连接的实时 MCP 客户端，以验证工具界面一致、共享记忆有效，并且被拒绝的能力在每种传输上都被阻止。