chaos-core-mcp

AI가 노출하는 도구가 아니라 의사결정 커널 그 자체인 MCP 서버입니다. 호출하는 클라이언트(Claude, ChatGPT, Codex, 무엇이든)는 저수준 엔드포인트를 열거하지 않습니다 — Chaos Core에 목표를 넘기면 Cognitive Core가 그 목표에 대해 추론하고, 캐퍼빌리티를 발견하고, 계획을 세우고, 결정론적 정책을 확인하고, 실행하고, 평가하며, 기억합니다.

v0.2부터 인지 코어는 전송 방식에 구애받지 않습니다(transport-agnostic). 동일한 코어, 도구, 정책, 메모리, 캐퍼빌리티 레지스트리에는 두 가지 방식으로 접근할 수 있습니다. 로컬 MCP 클라이언트는 stdio를 통해, Claude custom connectors 같은 원격 MCP 클라이언트는 /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 같은 중복은 없습니다.

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, 캐퍼빌리티 레지스트리, 정책 엔진, 메모리 저장소, 프로바이더 레지스트리, 감사 로그, 로거. createChaosCoreServer()는 해당 런타임 위에 MCP 세션당 하나의 McpServer를 생성하고, 세션별 SessionState를 추가하며, 결합된 컨테이너를 주입한 상태로 도구를 등록합니다.

어떤 코어 모듈도 의존성 컨테이너를 import 하지 않습니다. 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는 캐퍼빌리티 이름과 운영자가 제어하는 정책 파일의 순수 함수로 실행 여부를 결정합니다. 어떠한 모델도 개입하지 않습니다. 다음과 같이 나뉩니다:

• 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를 import 하지 않습니다. 모든 것은 하나의 인터페이스를 거칩니다:

// 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 객체는 { name, description, risk, inputSchema (Zod), annotations, handler } 형태입니다. V1에는 두 개가 포함됩니다:

• cognition.generate_text — 활성 프로바이더를 통한 범용 텍스트 생성

• http.request — GET 전용이며, policy.httpAllowedDomains로 제한됩니다

하나를 추가하려면 — 외부 API, 데이터베이스, 다른 MCP 서버 또는 자체 애플리케이션: Capability를 내보내는 파일을 src/capabilities/built-in/에 만들고 src/capabilities/index.ts에 등록합니다. core/, policy/, server/, transport/에는 아무것도 변경되지 않으며, 로컬 및 원격 클라이언트에 동시에 노출됩니다. AI는 레지스트리의 설명을 통해 무엇이 계획 단계를 해결할지 발견하며, if (task === "email") ...처럼 하드코딩하지 않습니다.

향후 방향: 레지스트리는 확장의 성장 경로입니다 — 캐퍼빌리티 팩(등록된 그룹), 이름이 아니라 risk를 키로 하는 캐퍼빌리티별 정책, 원격 MCP 클라이언트를 감싸 Chaos Core가 다른 MCP 서버를 통합할 수 있게 하는 어댑터 캐퍼빌리티, 반복 목표에 어떤 캐퍼빌리티 시퀀스가 성공하는지 학습하는 지속형 절차적 메모리.

메모리

V1은 지속형 Semantic Memory 계층을 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 도구, 플래너, 인지 코어, 정책 엔진은 SQLite를 참조하지 않으므로 변경할 필요가 없습니다.

요청이 어디서 왔든 동일한 데이터베이스가 사용됩니다 — stdio로 작성된 사실은 HTTP로도 조회 가능하며 재시작 후에도 유지됩니다.

Working Memory(현재 세션 컨텍스트)는 src/state/session.ts입니다. Episodic Memory(과거 작업에서 일어난 일)와 Procedural Memory(학습된 성공 단계 시퀀스)는 아키텍처에서 명명되지만 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 트랜스포트는 CHAOS_CORE_LOG_STREAM=stdout으로 설정되어 있더라도 로거가 stderr로 출력되도록 강제합니다.

Streamable HTTP로 실행 (원격 클라이언트)

npm run start:http

HOST:PORT(기본값 127.0.0.1:3000)에서 리슨하고 다음을 노출합니다:

로컬 엔드포인트: http://localhost:3000/mcp

HTTP 전송은 stateful입니다: 각 initialize는 Mcp-Session-Id를 발급하고 이후 요청은 그 id를 포함해야 합니다. 그래서 chaoscore_plan이 원격 클라이언트 사이에 plan_id가 유출되지 않으면서 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도, 하드코딩된 비밀 값도, 보안처럼 보이기만 하는 베어러 토큰도 제공되지 않습니다.

이를 로컬호스트 밖으로 노출하기 전에 반드시 다음을 추가하세요:

• 인증 — /mcp 라우트에 적용(MCP 인증 사양에 따른 OAuth 2.1 리소스 서버 또는 identity 인증을 처리하는 게이트웨이)

• TLS — 서버는 평문 HTTP를 사용하므로 리버스 프록시에서 TLS를 종료하세요.

• Rate limiting 및 요청 크기 제한 — 모든 reason/plan 호출은 OpenAI 할당량을 소모합니다.

• DNS 리바인딩 방지 — MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS 설정

• 검토된 policy.json — 기본값은 확인이 필요한 기능을 제외한 모든 등록된 기능을 허용합니다.

• 영구적인 감사 저장소 — V1 감사 추적은 인메모리 링 버퍼입니다.

미들웨어 없이 루프백이 아닌 주소에 바인딩하면, 서버는 시작 시 정확히 이 사실을 알리는 경고를 로그에 남깁니다. 전체 체크리스트는 docs/remote-deployment.md를 참조하세요.

OpenAI API 키는 providers/openai.ts 내부에서 서버의 환경 변수로 읽히며, 도구 출력, 검사(inspect) 페이로드, 감사 항목, HTTP 응답에는 절대 반환되지 않습니다.

V1 기능과 경계

포함된 것:

• TypeScript/Node, MCP SDK, OpenAI Responses API를 기본(교체 가능) 프로바이더로 사용

• 이중 전송: /mcp에서의 stdio + Streamable HTTP, 하나의 공유 인지 코어

• 여섯 가지 도구로 구성된 인지 레이어, 두 전송에서 동일

• 기능 레지스트리 + 결정론적 정책 엔진 + 구조화된 감사 이벤트

• 교체 가능한 MemoryStore 인터페이스 뒤에 위치한 SQLite Semantic Memory

• 모든 도구 입력과 모든 기능 입력에 대한 Zod 검증

의도적으로 제외된 것:

• UI 없음

• 에이전트 스웜 / 멀티 에이전트 아키텍처 없음

• 자율적인 백그라운드 실행 없음 — chaoscore_execute는 전달된 단계만 정확히 실행하며, core/brain.ts의 전체 루프 재계획은 존재하지만 도구로 노출되지는 않습니다.

• OAuth 구현 없음, 멀티 테넌시 없음, 마켓플레이스 없음

• MCP 서버 페더레이션 없음(레지스트리는 어댑터 기능을 호스팅할 수는 있지만 어떤 것도 포함되어 제공되지는 않습니다)

빌드 및 테스트

npm run build

npm test

테스트 스위트는 빌드된 결과물을 대상으로 실행되며 다음을 검증합니다: 정책의 결정론성과 비우회 가능성, 시뮬레이션된 재시작 후에도 메모리가 유지되는지, 그리고 두 전송 모두에 연결한 라이브 MCP 클라이언트가 동일한 도구 표면과 공유 메모리를 확인하고, 거부된 기능이 각 전송에서 차단되는지 확인합니다.