Surface · Runtime

The shared foundation every KAOS package builds on.

When a diligence associate asks Claude Code to find every change-of-control trigger across a 1,200-document deal room, this is the layer that turns the request into typed tool calls, document handles, and cited answers. The Model Context Protocol (MCP) is the open standard that lets agents call outside tools; KAOS is built on it from the first commit. Three packages — kaos-core, kaos-content, kaos-mcp — supply the type system, the document data model, and the bridge that turns Python code into MCP servers an agent can actually call.

Terminal window
pip install 'kaos-core kaos-content kaos-mcp[mcp]'

Designed for agents from day one

Most legal-AI tooling was written before MCP existed and now wraps an adapter around an older shape. KAOS does the opposite. Tools, resources, prompts, content, sampling, elicitation, roots, and tasks are defined in kaos-core as protocol-native pydantic models — the wire format is the type. That choice pushes a small set of opinions (artifact-by-handle, disk-first virtual file system, explicit runtime injection, typed module settings) down to every package, which is why a dozen MCP servers behave consistently when an agent reaches across them.

The document data model lives in kaos-content. PDF, DOCX, HTML, EDGAR filings, XLSX — every extractor downstream produces the same typed Block/Inline tree, with page, bounding box, character offset, and confidence attached to every node. Pandoc-style grammar; Docling-style provenance; Pydantic v2 throughout.

The MCP bridge lives in kaos-mcp. One function call mounts a runtime into the official Python MCP SDK's FastMCP server, exposes 22 resource templates for documents and tables, registers five workflow prompts, and serves them over stdio or streamable HTTP. The unified kaos CLI (doctor, status, setup, serve) runs on top.

From a Python tool to an agent call

A tool is declared as a typed Python class, serialized into an MCP envelope by the runtime, registered alongside the file system and artifact store, and mounted on a FastMCP server. Claude Code, Cursor, or Codex can then call it like any other tool, with no extra adapter layer.

KaosTool typed pydantic ToolAnnotations to_mcp_dict() protocol-native envelope KaosRuntime registry + VFS + artifacts FastMCP stdio | HTTP agentic client

What you get

  • MCP-native type system. KaosTool, KaosResource, KaosPrompt, ToolResult, ToolMetadata, ParameterSchema, ToolAnnotations — all serialize to MCP envelopes via to_mcp_dict().
  • Runtime container. KaosRuntime bundles ToolRegistry, ResourceRegistry, PromptRegistry, NamespaceManager, VirtualFileSystem, ArtifactStore, and per-module settings — replacing process-global singletons.
  • Disk-first VFS + artifact store. Three-tier inline policy (16 KB / 256 KB / handles only), kaos://artifacts/<id>/... URIs, range and chunk reads, manifest persistence across restarts.
  • One document model for everything. 17 Block types + 17 Inline types in kaos-content, with 15 annotation types covering tracked changes, defined terms, redactions, citations, and cross-references. A redline in DOCX and an annotation on a PDF land in the same shape.
  • Agent-ready resource catalog. 22 resource templates in kaos-mcp let an agent retrieve documents, tables, pages, and slices by URI; five workflow prompts ship the recurring patterns (extraction, retrieval, citation check). Stdio and streamable HTTP transports.
  • Typed module settings. ModuleSettings base class with a 6-level resolution chain: explicit overrides → KaosContext._config → KAOS_<MODULE>_* env → legacy env → .env → defaults.

A taste

A bare runtime, plus the introspection tools every KAOS server inherits — the starting point for an in-house team building, say, a litigation-hold tool that flags any document containing custodian-attorney communication. 

from kaos_core import KaosRuntime, register_core_tools


runtime = KaosRuntime()
n = register_core_tools(runtime)            # registers 10 introspection tools
print(runtime.tools.list_namespaces())      # ['kaos-core']
print(runtime.settings.artifact_inline_read_max_bytes)  # 262144
Terminal window
kaos-core tools list --json
kaos-core artifacts list --session demo --json
kaos-core-serve --http --port 8000          # FastMCP server (requires [mcp] extra)

Packages in this group

All three install from PyPI; kaos-content and kaos-mcp both depend on kaos-core.

kaos-core

10 MCP tools. Runtime container, registries, VFS, artifact store, KaosTool ABC, ModuleSettings.

kaos-content

7 MCP tools. 34 typed AST node classes. 15 annotation types. Provenance on every node.

kaos-mcp

FastMCP bridge. 22 resource templates + 5 workflow prompts. The unified `kaos` CLI.

How it compares

vs. raw FastMCP + manual plumbing. The official Python MCP SDK gives you a server class and an HTTP transport. kaos-core adds the runtime container, the typed pydantic models, the artifact store, the virtual file system, and typed module settings. You can write a one-off MCP server in raw FastMCP in an afternoon — but you will rebuild every one of these pieces, badly, the second tool you ship.

vs. ad-hoc per-source schemas. The kaos-content AST is the contract every extractor produces. Pandoc-style Block/Inline grammar; Docling-style provenance on every node. Alternatives like raw markitdown or mammoth output strings or per-tool JSON; KAOS produces a single Pydantic v2 AST that round-trips losslessly to JSON, serializes to Markdown / HTML / text, and survives chunking, search, and LLM extraction with its source location intact.

See /compare for the full named-competitor table.

Get started

See the quickstart, browse all 18 packages, or read the docs.