OCTAVE MCP Server

Deterministic document infrastructure for LLM pipelines. Canonicalization, schema validation, grammar compilation, and MCP tools for durable AI artifacts.

pip install octave-mcp

This README serves three audiences. We know that's unusual, and we're being upfront about it — because the project itself sits at the intersection of all three.

If you are...	Jump to
An engineer evaluating this for production	For Engineers
A researcher interested in what's novel here	For Researchers
An AI agent that needs to read/write OCTAVE	For AI Agents

For Engineers

OCTAVE is a structured document format with an MCP server and CLI. Documents normalise to a single canonical form, validate against their own schema, and log every transformation. It's infrastructure for AI documents that need to survive compression, multi-agent handoffs, and auditing.

Quick example: what changes

Ask an LLM to summarise a project status and you get prose:

The auth migration has been running for three sprints and keeps hitting
the same problems. There's a security audit in six weeks — the auditors
specifically flagged session management as a priority area. We've burned
through 60% of the quarterly budget on this migration alone.

Ask another LLM to restate that in English and it will paraphrase — silently dropping facts, merging details, escalating "priority area" to "vulnerability." That's not a bug in the LLM. It's what prose invites: retelling.

OCTAVE structures the same information as labelled fields:

migration::auth_service[3_sprints∧SISYPHEAN_FAILURES]
CHRONOS::audit_6wk
  ARTEMIS::session_mgmt_targeted
DEMETER::"60%_quarterly_burned[this_migration_alone]"

Pass that to any LLM — even one that has never seen OCTAVE — and it translates each field separately. ARTEMIS (monitoring/targeting domain) reconstructs as "specifically targeted," not "vulnerability." CHRONOS (time pressure) stays distinct from DEMETER (budget). Facts don't merge because the structure tells the agent "these are labelled data points," not "this is a narrative to retell."

The mythology terms (SISYPHEAN, ARTEMIS, CHRONOS, DEMETER) work like semantic zip files — compressed meaning that's already in the model weights. No training needed. Why that works.

If an LLM writes it slightly wrong (extra spaces, ASCII -> instead of →), the normaliser autocorrects and gives you a receipt:

normalization: '->' → '→' at line 3

Same input, same output, every time. That's what deterministic means.

What you get

Canonical normalisation — Same input, same output, always. Idempotent. Two agents independently producing the same document get a byte-for-byte match.
Schema validation with receipts — Documents carry their schema inline. Validation returns specific field errors. Every repair is logged with stable IDs — you know exactly what changed and why.
Controlled compression with loss accounting — Choose a tier (LOSSLESS, CONSERVATIVE, AGGRESSIVE) and the system declares what's preserved and what's dropped. Prose paraphrasing loses facts silently; OCTAVE makes every trade-off explicit. Evidence.
Grammar compilation — Schema constraints compile to GBNF grammars for llama.cpp-compatible backends. Constrain LLM generation at decode time.
Optional YAML frontmatter + OCTAVE body in one pass — Platform-deployed skill and agent files can include YAML headers for tool discovery alongside structured OCTAVE bodies. octave_write validates both in a single operation. YAML is optional for hub/system files consumed by the anchor ceremony.
Literal zones — Fenced code blocks pass through with zero processing. No normalisation, no escaping.
HTTP + stdio transport — Stdio by default, Streamable HTTP with DNS rebinding protection and health checks for web deployments.

Install

pip install octave-mcp

Claude Code (~/.claude.json) or Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "octave": {
      "command": "octave-mcp-server"
    }
  }
}

HTTP:

octave-mcp-server --transport http --port 8080

MCP Tools

Tool	What it does
`octave_validate`	Validate against schema. Field errors, repair suggestions, zone coverage
`octave_write`	Write files through the full validation pipeline. `mode: normalize` for dry-run
`octave_eject`	Project to different views — canonical, executive summary, developer, template
`octave_compile_grammar`	Compile schema constraints to GBNF grammar for constrained generation

CLI

octave validate document.oct.md
octave write output.oct.md --stdin
octave eject document.oct.md --mode executive --format markdown

When to use it

Documents passing through multiple agents, tools, or compression steps
Agent and skill files with optional YAML discovery headers + structured content
Decision logs, coordination briefs, audit trails
System prompts and reference docs where token cost matters

Not the right tool for single-step prompts, freeform prose, or code output.

Docs

Doc	Content
Usage Guide	CLI, MCP, and API examples
API Reference	Python API
MCP Configuration	Client setup and integration
Development Setup	Testing, quality gates, contributing
EBNF Grammar	Formal grammar spec
Architecture Decisions	ADRs

For Researchers

Two architectural ideas and one that sounds like it shouldn't work but does.

Self-describing artifacts

Most structured output validates at a single point and then becomes a plain object. OCTAVE documents are different — the schema, compression tier, and transformation log travel with the document. A downstream agent doesn't infer integrity; it reads it.

This creates a property that JSON Schema or Pydantic don't give you: the validation receipt is part of the artifact, not external to it.

Grammar compilation from inline constraints

A document's META.CONTRACT block compiles to a GBNF grammar that can constrain LLM generation at decode time. The schema doesn't just validate output after the fact — it can shape generation while it happens. This bridges the gap between "check if it's valid" and "make it valid by construction."

Mythological compression

This is the part where we lose some of you. We know how it sounds. Just look at it from an inquisitive perspective and consider it for a moment.

OCTAVE is named Olympian Common Text And Vocabulary Engine. That's not branding — it's the hypothesis. Classical mythology seems to be so deeply represented in LLM training data that mythological terms function as a pre-compressed semantic vocabulary that's already in the weights.

Term	What it encodes
`JOURNEY::ODYSSEAN`	Long, difficult, full of unforeseen obstacles
`CHALLENGE::SISYPHEAN`	Repetitive, frustrating, cyclical, futile
`CHOICE::SOLOMONIC`	Requires wisdom to divide fairly between competing claims
`STRATEGY::ATHENA`	Find a clever solution balancing competing constraints

SISYPHEAN_FAILURES — a single term that carries repetition, frustration, cyclicality, and futility. In prose, that's 10–15 tokens. Here, it's one.

But mythology isn't just compression. In round-trip testing, mythology terms used as domain labels (ARTEMIS::session_mgmt_targeted instead of bare session_mgmt_flagged) consistently prevented downstream agents from misinterpreting facts. ARTEMIS (precision targeting) reconstructed as "specifically targeted" — never "vulnerability." The domain label anchored the agent to the right semantic register. Evidence.

In informal cross-model testing (GPT-4, Claude, Gemini, Llama, Mistral), these terms were consistently interpreted as expected without few-shot priming. No fine-tuning, no examples, no definitions provided. Personally, we've seen zero-shot comprehension in every model we've tried, but that's bias. Like every good hypothesis, we want to prove it wrong until we can't.

There's a paradox worth noting: when asked theoretically whether mythology works as compression, models hesitate and cite cultural concerns. When given JOURNEY::ODYSSEAN practically, they understand it instantly. We don't fully understand why that gap exists — but the practical result is consistent. So OCTAVE primers explicitly encourage operational use rather than meta-discussion.

This is exploratory. We're not claiming a universal law. We are claiming it works reliably in practice, across every model we've tested, and that it's worth investigating why.

If you're sceptical, fair enough. If you want to falsify this quickly, the guide includes a short replication protocol.

Evidence and methodology: The Mythological Compression Principle | Compression Fidelity Study

For AI Agents

The ~200-token block below makes you OCTAVE-literate:

===OCTAVE_LITERACY_PRIMER===
META:
  TYPE::PRIMER
  VERSION::"6.0.0"

§1::ESSENCE
OCTAVE::"Semantic DSL for LLMs"
STRUCTURE::KEY::value,[list],indent_2

§2::SYNTAX
::::"assign"
→::"flow"
⊕::"synthesis"
⇌::"tension"

§3::ONE_SHOT
IN::"flow from A to B"
OUT::A→B

§4::VALIDATE
MUST::[valid_OCTAVE,preserve_§_names,"===END==="]
===END===

Working on this codebase:

===AGENT_BOOTSTRAP===
QUALITY_GATES::[mypy,ruff,black,pytest]
SPECS::src/octave_mcp/resources/specs/
PRIMERS::src/octave_mcp/resources/primers/
===END===

Contributing

git clone https://github.com/elevanaltd/octave-mcp.git
cd octave-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
ruff check src tests && mypy src && black --check src tests

See CONTRIBUTING.md for guidelines.

License

Apache-2.0 — Built with MCP Python SDK.