chaos-core-mcp

Ein MCP-Server, bei dem die KI der Entscheidungskern ist – nicht ein Tool, das bereitgestellt wird. Ein aufrufender Client (Claude, ChatGPT, Codex, was auch immer) zählt keine Low-Level-Endpunkte auf – er übergibt Chaos Core ein Ziel und überlässt es dem Cognitive Core, darüber nachzudenken, Fähigkeiten zu entdecken, zu planen, die deterministische Policy zu prüfen, auszuführen, auszuwerten und sich zu merken.

Ab v0.2 ist der Cognitive Core transportunabhängig. Derselbe Kern, dieselben Tools, Policies, Memory und die Capability-Registry sind auf zwei Wegen erreichbar: über stdio für lokale MCP-Clients und über Streamable HTTP unter /mcp für entfernte MCP-Clients wie Claude Custom Connectors.

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

Es gibt keine HTTP-Variante der Kognition. src/transport/stdio.ts und src/transport/http.ts rufen beide dieselbe Server-Factory createChaosCoreServer() auf – der Transport ist für die kognitive Schicht unsichtbar, und es gibt keine http_reason- oder remote_plan-Duplikate.

Die Cognitive-Core-Schleife

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

V1 legt jede Stufe als eigenes MCP-Tool offen, damit jeder Schritt inspizierbar bleibt und die aufrufende KI zwischen den Stufen die Kontrolle behält:

Beide Transporte bedienen diese identische Liste – durch einen Test abgesichert, der uber einen echten MCP-Client auf jedem Transport die Tools auflistet und die Definitionen vergleicht.

core/brain.ts implementiert die vollständige Schleife auch als eine einzige zusammensetzbare Funktion (runCognitiveCore) – vom Ziel direkt zum Ergebnis, mit automatischer Neuplanung bei Fehlern in einem Schritt und sofortigem Anhalten bei REQUIRE_APPROVAL. Diese ist nicht als MCP-Tool in V1 registriert (siehe V1-Boundary), aber vollständig verdrahtet und bereit, ohne Umschreiben ein zukünftiges 1kososcore_achieve-Tool zu untermauern.

Architektur

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

Dependency Injection und welche Lebensdauer was hat

createRuntime() baut die prozessweiten Dienste einmalig auf: Konfiguration, Capability-Registry, Policy-Engine, Memory-Store, Provider-Registry, Audit-Log, Logger. createChaosCoreServer() baut auf dieser Runtime einen McpServer pro MCP-Session auf, fügt einen Session-SessionState hinzu und registriert die Tools mit dem dynamischen Container injection.

Kein zentrales Modul importiert den Dependency-Container. core/intent.ts, core/planner.dart und capabilities/executor.ts deklarieren jeweils eine schmale strukturelle Schnittstelle (IntentDeps, PlannerDeps, ExecutorDeps), die der Container erfüllt von selbst erfüllt – darum ist der Kern isoliert testbar und wirklich ohne jede Kenntnis der Server- und Transportebenen.

Policy liegt außerhalb der KI

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

Das Modell kann jede Capability vorschlagen; policy/engine.ts entscheidet – eine reine Funktion aus Capability-Namens und der durch Operator festgelegten Policy-Datei. Kein Modell wird konsultiert. Aufgeteilt in:

• policy/permissions.ts – Allow-/Deny-Listen (allowedCapabilities, deniedCapabilities)

• policy/approvals.ts – welche erlaubten Capabilities weiterhin einen Menschen brauchen (requireConfirmationFor)

• policy/engine.ts – erstellt sie und die begrenzten Ressourcen zusammen (httpAllowedDomains)

data/policy.json wird bei erstem Lauf automatisch mit sicheren Standardwerten erzeugt:

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

Transport kann die Policy nicht umgehen. capabilities/executor.ts ist der einzige Pfad von einem Plan-Schritt zu einem Capability-Handler; es ruft zuerst policy.check() auf und enthält keinen Transport-verzweigten Zweig. Schritte, die auf REQUIRE_APPROVAL auflösen, werden übersprungen, es sei denn, der Aufrufer übergibt confirmed: true; Schritte, die auf DENY auflösen, werden stets nie ausgeführt. Jede Entscheidung wird mit ihrer Session-Id in den Audit-Trail geschrieben.

Das KI-Modell ist austauschbar – mit Absicht

Nichts außerhalb von src/providers/openai.ts importiert ein SDK eines KI-Anbieters. Alles läuft über einer einzigen Schnittstelle:

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

Die kognitiven Stufen bilden sich darauf ab als Reasoning → generateJson, Planung → generateJson und **Auswertung → deterministischer Code in `core/evaluatcher``. Die Auswertung ist absichtlich kein Provider-Aufruf, damit ein Modell seine eigene fehlgeschlagene Ausführung nie als Erfolg einstufen kann.

Um ein Modell/einen Anbieter hinzuzufügen: Schreibe eine src/providers/<name>.ts-Datei, die AIProvider implementiert, registriere sie in providers/index.ts und setze CHAOS_CORE_PROVIDER=<name>. Der Modellname selbst wird nur einmal konfiguriert, über OPENAI_MODEL – er taucht in keiner anderen Datei auf.

Capability-Registry – der Erweiterungsansatz

Capability-Objekte sind { name, description, risk, inputSchema (Zod), annotations, handler }. Zwei liefert V1 mit:

• cognition.generate_text – allgemeine Textgenerierung über den aktiven Provider

• http.request – nur GET, gesteuert durch policy.httpAllowedDomains

Um eine weitere hinzuzufügen – eine externe API, eine Datenbank, einen anderen MCP-Server oder eine deiner eigenen Applikationen: Erzeuge eine Datei in src/capabilities/built-in/, die eine Capability exportiert, und registriere sie in src/capabilities/index.ts. Nichts in core/, policy/, server/ oder transport/ ändert sich, und sie ist zugleich für lokale und entfernte Clients verfügbar. Die KI schließt anhand der Beschreibungen der Registry daraus, was einen Plan-Schritt löst – du codierst nie if (task === "email") ... hart ein.

Zukünftige Ausrichtung: Die Registry ist der Weg zu erweiterter – Capability-Packs (registrierte Gruppen), eine Policy pro Capability auf Basis von risk statt Namen einzeln, eine Adapter-Capability, die einen remote MCP-Client umgeht, sodass Chaos Core andere MCP-Server föderieren kann, und ein dauerhaftes prozedurales Memory, das aussucht, welche Capability-Sequenzen für wiederkehrende Ziele erfolgreich sind.

Memory

V1 implementiert die durable Semantic-Memory-Schicht hinter einem Umsetzungsinterface (interface src/memory/types.ts) mit einer SQLite-Implementierung (src/memory/sqlite.ts), ausgewählt durch eine Factory (src/memory/store.ts). node:sqlite liegt zugrunde – eingebaut in Node.js 22.5+, ohne native Abhängigkeiten: Key/Value mit Tags, TTL, Teilstring-Suche, Pagination.

SQLite für Postgres oder einen Vektor-Speicher auszutauschen, bedeutet nur eine Datei neben sqlite.ts zu ergänzen die Factory zu ändern. Die MCP-Tools, Planner, Cognitive Core und Policy-Engine bleiben unverändert, denn keine von ihnen referenziert SQLite.

Die Core-Datenbank wird immer verwendet, wie eine Anfrage auch kam – eine Tatsache, die über stdio geschrieben wurde, ist über HTTP abrufbar- und übersteht einen Restart.

Working Memory ist der src/state/session.ts (Kontext der aktuellen Session). Episodic Memory (was passierte in abgelaufenen Tasks) und Procedural Memory (gelernte erfolgreiche Schrittfolgen) sind in der Architektur benannt, aber in V1 noch nicht implementiert.

Einrichtung

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

Bas deposit "Run overlay over stdio (local clients, development)"

npm start

npm run start:stdio ist das explizite Pendant; npm start bleibt stdio, damit bestehende lokale Setups unberührt bleiben.

Unter stdio gehört stdout MCP[^]-> dem MCP-protocol. Jede Diagnose im Codebase läuft über observability/logger.ts, und der stdio-Transport zwingt den Logger folglich auf stderr, auch wenn CHAOS_CORE_LOG_STREAM=stdout gesetzt ist.

Basis über Streamable HTTP (entfernte Clients)

npm run start:http

Lauscht auf HOST:PORT (Standard 127.0.0.1:3000) und bietet:

Lokaler Endpunkt: http://localhost:3000/mcp

Der HTTP-Transport ist statusbehaftet: Jedes initialize erzeugt eine neue Mcp-Session-Id, und nachfolgende Anfragen müssen sie mitführen. Genau das ermöglicht, dass chaoscore_plan eine plan_id an chaoscore_execute weitergibt, ohne Pläne zwischen entfernten Clients auslaufen zu lassen. Eine Anfrage mit unbekannter Session-ID bekommt 404; eine Nicht-initialize-Anfrage ohne Session-ID bekommt 400.

Umgebungsvariablen

Eine .env im Arbeitsverzeichnis wird automatisch geladen (interner Loader von Node.js – keine Abhängigkeit). .env.example enthält nur Platzhalter; Committe niemals echte Zugangsdaten.

Die COGNITION_*-Variablennamen aus der Zeit vor 0.2 funktionieren weiterhin als Fallback.

Einen lokalen MCP-Client verbinden

Claude Desktop / Claude Code / jeder stdio-Client:

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

Oder mit dem MCP Inspector:

npm run inspector:stdio

Einen Remote-MCP-Client verbinden

Starten Sie den HTTP-Transport und richten Sie den Client auf die Endpunkt-URL aus:

http://localhost:3000/mcp

Fügen Sie für einen benutzerdefinierten Claude-Connector den Server als Remote-MCP-Server mit dieser URL hinzu (eine öffentliche Bereitstellung benötigt eine öffentliche HTTPS-URL – siehe den Sicherheitshinweis weiter unten). Zum manuellen Ausprobieren:

npm run inspector:http

Wählen Sie dann „Streamable HTTP“ und geben Sie die URL ein.

⚠️ Sicherheitswarnung für Remote-Bereitstellung

V1 enthält keine Authentifizierung. Das ist beabsichtigt und nur deshalb sicher, weil der HTTP-Transport standardmäßig an 127.0.0.1 bindet. Die Schicht ist so aufgebaut, dass Authentifizierungs-Middleware sauber integriert werden kann (AuthMiddleware in src/transport/http.ts, angewendet auf die MCP-Route vor jeder MCP-Verarbeitung) – aber es wird nichts Vorgetäuschtes bereitgestellt: kein OAuth-Stub, keine hartcodierten Geheimnisse, kein Bearer-Token, das nur wie Sicherheit aussieht.

Bevor Sie dies über localhost hinaus bereitstellen, müssen Sie Folgendes hinzufügen:

• Authentifizierung auf der /mcp-Route (OAuth-2.1-Ressourcenserver gemäß der MCP-Auth-Spezifikation oder ein Gateway, das die Identitätsprüfung übernimmt)

• TLS – der Server spricht unverschlüsseltes HTTP; terminieren Sie TLS an einem Reverse-Proxy

• Rate-Limiting und Begrenzung der Anfragegröße – jeder reason/plan-Aufruf verbraucht Ihr OpenAI-Kontingent

• DNS-Rebinding-Schutz – setzen Sie MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS

• Eine geprüfte policy.json – der Standard gewährt allen registrierten Capabilities Zugriff außer denjenigen, die eine Bestätigung erfordern

• Dauerhafte Audit-Speicherung – der V1-Audit-Trail ist ein In-Memory-Ringpuffer

Wenn Sie ohne Middleware an eine Nicht-Loopback-Adresse binden, protokolliert der Server beim Start eine Warnung, die genau das aussagt. Siehe docs/remote-deployment.md für die vollständige Checkliste.

Der OpenAI-API-Schlüssel wird in providers/openai.ts aus der Umgebung des Servers ausgelesen und niemals in Tool-Ausgaben, inspect-Payloads, Audit-Einträgen oder HTTP-Antworten zurückgegeben.

V1-Fähigkeiten und -Grenzen

Enthalten sind:

• TypeScript/Node, MCP SDK, OpenAI Responses API als Standard-Provider (austauschbar)

• Zwei Transporte: stdio + Streamable HTTP unter /mcp, ein gemeinsamer kognitiver Kern

• Kognitive Oberfläche mit sechs Tools, identisch auf beiden Transportarten

• Capability-Registry + deterministische Policy-Engine + strukturierte Audit-Ereignisse

• SQLite Semantic Memory hinter einer austauschbaren MemoryStore-Schnittstelle

• Zod-Validierung bei jeder Tool-Z Controls quasi jedem Capability-Eingang

Bewusst nicht enthalten:

• Keine UI

• Keine Agentenschwärme / Multi-Agent-Architektur

• Keine autonome Hintergr-legitim – chaoscore_execute führt genau die übergebenen Schritte aus; die Replanung des vollständigen Zyklus von core/brain.ts existiert, wird aber nicht als Tool freigegeben

• Keine OAuth-Implementierung, kein Multi-Tenancy, kein Marktplatz

• Keine MCP-Server-Föderation (die Registry könnte eine Adapter-Capability hosten; es wird keine ausgeliefert)

Build und Tests

npm run build

npm test

Die Suite läuft gegen das gebaute Ergebnis und deckt ab: Policy-Determinismus und Nichtumgehbarkeit, Speicherpersistenz über einen simulierten Neustart hinweg sowie einen Live-MCP-Server, der über beide Transport verbindet, um identische Tool-Oberflächen, gemeinsamen Speicher und die Blockierung einer verweigerten Capability auf jedem zu überprüfen.