mcpaisuite-kernelmcp 1.0.3

The sovereign orchestrator — connects all MCP AI suite libraries into an autonomous agent

kernelmcp

The sovereign orchestrator -- connects all MCP AI suite libraries into an autonomous agent

Part of the MCP AI Suite.

Features

• ReAct engine with autonomous Thought-Action-Observation loop driven by LLM
• LTP (Lean Task Protocol) compiler turns goals into deterministic execution plans in one LLM call
• Suite orchestration -- wires websearchmcp, sandboxmcp, workspacemcp, planningmcp, schedulermcp, memorymcp, and ragmcp in-process
• Smart routing -- TaskSupervisor selects cloud, local, or fast model per task complexity
• Sub-agent system -- spawn specialized agents (code, research, file, memory) for subtasks
• Budget enforcement with per-task and per-namespace token/cost caps
• DLP secret guard -- redacts secrets (AWS keys, tokens, private keys, connection strings) in tool results before they reach the model, and blocks outbound tool calls whose arguments carry a secret. Enforced at the tool chokepoint -- deterministic, not asked of the model. Opt-in via enable_dlp; emits secret.redacted / secret.blocked events
• Agent-JIT cache (experimental, situational) -- amortizes repeated task families: the first instance reasons normally and its execute_code solution is cached by a semantic signature; a later instance is validated once by shadow execution (cached pattern vs cold engine, outputs compared deterministically) and then reused. When it engages, a reuse measured ~34× cheaper (~330 vs ~11k tokens) and never ships an unvalidated answer (falls back to the full engine on mismatch). Honest caveat: the gain is only net-positive on repetitive workloads that reliably route through execute_code — engagement hinges on that, which is non-deterministic for simple tasks, so on low-repetition or non-code-routed traffic it can be net-neutral to ~+15% (an un-amortized shadow pass). Hence off by default. Opt-in via jit=True / KERNELMCP_JIT; inspect with kernel.jit_stats()
• Circuit breaker and fallback chain for resilient LLM calls with automatic retry and backoff
• Full audit trail via SQLite -- every tool call, cost, and token count logged
• Event bus for real-time streaming and progress callbacks
• Elicitation -- agent can pause execution to ask user questions
• Self-hosted Hub connector -- connect_hub() reports an embedded kernel's traces to your own Hub for monitoring, with opt-in remote control (ping/stats/set_config/run/cancel) over an outbound-only connection

Installation

pip install mcpaisuite-kernelmcp
# Optional extras:
pip install mcpaisuite-kernelmcp[dev]          # Development tools
pip install mcpaisuite-kernelmcp[all]          # All suite libraries + webhooks + REST API
pip install mcpaisuite-kernelmcp[memorymcp]    # Memory integration
pip install mcpaisuite-kernelmcp[sandboxmcp]   # Sandbox integration
pip install mcpaisuite-kernelmcp[planningmcp]  # Planning integration

Quick Start

from kernelmcp import KernelFactory

kernel = KernelFactory.from_env()
task = await kernel.run("Research the latest Python 3.13 features and summarize them")
print(task.summary)
print(f"Cost: ${task.total_cost:.4f}, Tokens: {task.total_tokens}")

MCP Server

# Agent mode (kernel LLM drives the ReAct/LTP loop):
kernelmcp start --transport stdio --mode agent

# Router mode (client LLM drives tool selection, kernel routes):
kernelmcp start --transport stdio --mode router

# SSE transport:
kernelmcp start --transport sse --port 8080

Configuration

Variable	Default	Description
KERNELMCP_MODEL	claude-sonnet-4-6	Primary LLM model
KERNELMCP_FAST_MODEL	claude-haiku-4-5-20251001	Fast model for simple tasks
KERNELMCP_LOCAL_MODEL	ollama/mistral	Local model fallback
KERNELMCP_ROUTING	true	Enable smart model routing
KERNELMCP_MAX_TURNS	20	Max ReAct turns per task
KERNELMCP_MAX_TOKENS	50000	Token budget per task
KERNELMCP_DLP	false	Redact secrets in tool I/O + block secret exfiltration (DLP)
KERNELMCP_JIT	false	Reuse shadow-validated solution patterns across repeated task families (Agent-JIT)
KERNELMCP_NANO	false	Fast path for trivial single-shot tasks (skips constitution/full tools)
KERNELMCP_NAMESPACE	default	Default tenant namespace
ANTHROPIC_API_KEY	--	API key for Claude models

Or configure via YAML:

llm_model: claude-sonnet-4-6
enable_routing: true
max_turns: 20
memory:
  episodic_store: sqlite
workspace:
  root_path: /data/workspace
sandbox:
  enable_host_access: true

kernel = KernelFactory.from_yaml("config.yaml")

Self-Hosted Hub (Monitoring & Control)

Embed kernelmcp in your own app and point it at a self-hosted Hub to monitor your kernels from one place -- and optionally control them. Monitoring is telemetry push over an outbound-only connection (no inbound port on your app); control is opt-in.

from kernelmcp import KernelFactory, connect_hub

kernel = KernelFactory.from_env()

# Monitoring only (always on once connected):
await connect_hub(kernel, hub_url="http://my-hub:8007", project="prod", api_key="kmh_...")

# ...or also let the Hub send commands to this kernel (opt-in):
await connect_hub(kernel, hub_url="http://my-hub:8007", project="prod",
                  api_key="kmh_...", allow_control=True)

# Use the kernel normally -- finished tasks show up in your Hub.

connect_hub(...) is fail-safe and a no-op if unconfigured (it also reads KERNELMCP_HUB_URL / KERNELMCP_HUB_KEY / KERNELMCP_HUB_PROJECT from the environment), so it is always safe to call unconditionally. With allow_control=True the Hub can send ping / stats / set_config / run / cancel commands; pass run_handler(goal) to customize how run executes. Returns a HubConnector (or None if unconfigured); call await connector.stop() to disconnect.

API Reference

KernelPipeline

The main orchestrator managing tasks, budgets, and all suite libraries.

await kernel.run(goal, namespace="default", mode="", budget_usd=None, constitution=None)
await kernel.call_tool(tool_name, arguments, namespace="default")
await kernel.spawn_agent(agent_type, task, namespace="default", max_turns=None)
await kernel.get_stats()
await kernel.health()

KernelFactory

KernelFactory.default()             # Minimal kernel, no integrations
KernelFactory.from_env()            # Build from environment variables
KernelFactory.from_yaml("cfg.yaml") # Build from YAML config
KernelFactory.full_suite()           # All libraries wired in-process
KernelFactory.create(llm_model=..., memory_pipeline=..., ...)  # Full control

Architecture

KernelPipeline wraps a ReActEngine that drives the Thought-Action-Observation loop. A SuiteOrchestrator holds references to all sub-library pipelines (memory, workspace, sandbox, planning, scheduler, RAG) and exposes their tools to the engine. TaskSupervisor routes each task to the appropriate LLM model (cloud, fast, or local) based on complexity, while BudgetEnforcer and CircuitBreaker provide cost control and resilience.

Testing

pip install -e ".[dev]"
pytest tests/ -v

License

AGPL-3.0 — see LICENSE.

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact [e-mail].