octave-mcp
The OCTAVE MCP server lets you validate, write, project, and compile grammars for deterministic OCTAVE structured documents.
Validate OCTAVE content or files against schemas with repair suggestions, canonical form, strictness profiles, compact/diff outputs, and optional grammar hints/debug grammar.
Write or modify OCTAVE files via full content or delta operations (DELETE/APPEND/PREPEND/MERGE), with schema validation, dry-run/corrections, CAS hashing, lenient parsing, mutations, formatting styles, and parse-error policies.
Eject/project OCTAVE content into canonical, authoring, executive, or developer views and export as OCTAVE, JSON, YAML, Markdown, or GBNF; extract sections or generate templates.
Compile built-in schemas or inline OCTAVE contracts into constrained-generation grammars as GBNF (llama.cpp) or JSON Schema (vLLM).
Run as an MCP server over stdio or Streamable HTTP for web deployments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@octave-mcp Normalize and validate my status.octave file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OCTAVE MCP Server
Deterministic document infrastructure for LLM pipelines. Canonicalization, schema validation, grammar compilation, and MCP tools for durable AI artifacts.
pip install octave-mcpThis 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 | |
A researcher interested in what's novel here | |
An AI agent that needs to read/write OCTAVE |
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 3Same 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_writevalidates 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-mcpClaude Code (~/.claude.json) or Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"octave": {
"command": "octave-mcp-server"
}
}
}HTTP:
octave-mcp-server --transport http --port 8080MCP Tools
Tool | What it does |
| Validate against schema. Field errors, repair suggestions, zone coverage |
| Write files through the full validation pipeline. |
| Project to different views — canonical, executive summary, developer, template |
| 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 markdownWhen 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 |
CLI, MCP, and API examples | |
Python API | |
Client setup and integration | |
Testing, quality gates, contributing | |
Formal grammar spec | |
ADRs |
Related MCP server: Contentrain MCP
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 |
| Long, difficult, full of unforeseen obstacles |
| Repetitive, frustrating, cyclical, futile |
| Requires wisdom to divide fairly between competing claims |
| 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 compact ~140-token block below (cl100k_base) 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 testsSee CONTRIBUTING.md for guidelines.
License
Apache-2.0 — Built with MCP Python SDK.
Available Tools
4 toolsoctave_compile_grammarA
Compile OCTAVE schema or contract to constraint grammar. Supports GBNF (llama.cpp) and JSON Schema (vLLM) output formats. Provide either a builtin schema name or inline OCTAVE content.
Inputs: format, schema, content.
octave_ejectA
Eject OCTAVE content with projection modes. Supports canonical, authoring, executive, and developer views. Can generate templates when content is null. Output formats: octave, json, yaml, markdown, gbnf.
Inputs: schema (required), mode, format, content, +1 more.
octave_validateA
Schema check + repair suggestions for OCTAVE content. Validates content against schema, returns canonical form with optional repairs. Focus on I3 (Mirror Constraint) and I5 (Schema Sovereignty).
Inputs: schema (required), fix, compact, content, +5 more.
octave_writeA
Unified entry point for writing OCTAVE files. Handles creation (new files) and modification (existing files). Use content for full payload, changes for delta updates. Omit both content and changes to normalize an existing file in-place. Replaces octave_create and octave_amend.
Inputs: target_path (required), schema, changes, content, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: compiling grammars, ejecting content in various formats, validating and repairing content, and writing files. There is no overlap or ambiguity.
All tools use the 'octave_' prefix and snake_case, but the verb pattern is not fully uniform: 'compile_grammar' is verb_noun while 'eject', 'validate', and 'write' are single verbs. This minor deviation reduces consistency slightly.
Four tools is well-scoped for a specialized server dealing with OCTAVE content management. Each tool serves a necessary function without redundancy or unnecessary excess.
The tools cover core operations (compile, eject, validate, write), but there is no explicit read/list or delete tool, which may be a minor gap depending on the expected workflow. The focus on writing and validation is evident, but a complete lifecycle is not fully covered.
Maintenance
Related MCP Connectors
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
AlicenseNot gradedqualityFmaintenanceIntentText MCP server lets AI agents parse, validate, query, diff, and render IntentText (.it) documents. It exposes 9 tools for safe parsing, workflow validation, HTML/print rendering, template merging, and round-trip source generation.72 npmMIT
Contentrain MCPofficial
AlicenseAqualityBmaintenanceLocal-first MCP server for AI content governance. 13 tools for model/content management, validation, normalization, and i18n across any framework.237MIT- AlicenseAqualityBmaintenanceMCP server for MDMA (Markdown Document with Mounted Applications) — interactive Markdown with forms, approval gates, tables, and more. Exposes the MDMA spec, authoring prompts, package metadata, and live docs to AI assistants so agents can author and integrate MDMA correctly.886 npm75MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for structured document management of markdown and YAML files, with RBAC, git-based approval workflows, and semantic search, enabling agents to read, edit, and maintain documents under governance.MIT