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.
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 |
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.
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.
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.
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 8080Tool | 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 |
octave validate document.oct.md
octave write output.oct.md --stdin
octave eject document.oct.md --mode executive --format markdownDocuments 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.
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
Two architectural ideas and one that sounds like it shouldn't work but does.
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.
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."
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
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===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.
Apache-2.0 — Built with MCP Python SDK.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Builtin schema name to compile grammar from (e.g., 'SKILL', 'META'). Mutually exclusive with content. | |
| content | No | Inline OCTAVE document content with META.CONTRACT or FIELDS block. Mutually exclusive with schema. | |
| format | No | Output format: gbnf (default) or json_schema. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions input and output format options but does not disclose behavioral traits like side effects, error handling, or performance implications. The information is adequate but not enhanced beyond schema details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, covering purpose, supported outputs, and input methods without any wasted words. It is well-structured and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a compile tool with three parameters and no output schema, the description covers essential usage. It lacks a description of the return value (the compiled grammar), which is a minor gap given the tool's output-oriented nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds context about the format parameter (associating GBNF with llama.cpp and JSON Schema with vLLM) but does not significantly enhance understanding beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compiles OCTAVE schemas/contracts into constraint grammars, distinguishing it from sibling tools (octave_eject, octave_validate, octave_write) which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies the supported output formats (GBNF, JSON Schema) and input options (builtin schema vs inline content), providing clear context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | OCTAVE content to eject (null for template generation) | |
| schema | Yes | Schema name for validation or template generation | |
| mode | No | Projection mode: canonical (full), authoring (lenient), executive (STATUS,RISKS,DECISIONS), developer (TESTS,CI,DEPS) | |
| format | No | Output format (gbnf exports llama.cpp GBNF grammar) | |
| sections | No | List of section identifiers to extract (Issue #341). When provided, only matching sections + META are included in output. Accepts flexible formats: '§3', '3', '§3::CAPABILITIES' all match section 3. Non-existent sections are silently omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, description discloses key behavioral traits: supports multiple projection modes, output formats, template generation, and sections parameter with flexible matching and silent omission. Does not cover permissions or side effects but provides substantial behavioral context beyond basic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two effective sentences: first defines primary action, second summarizes modes, template generation, and output formats. No wasted words, information is front-loaded and accessible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, description covers all parameters and their behavior (modes, formats, sections, template generation). It lacks details on return values or error cases, but is sufficient for a conversion tool. Missing only minor context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds significant value by explaining modes (e.g., 'executive: STATUS,RISKS,DECISIONS'), format implications (gbnf exports llama.cpp GBNF grammar), and sections parameter behavior (flexible matching, silent omission). This enriches the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool ejects OCTAVE content with projection modes, listing specific modes and output formats. It distinguishes from siblings (compile_grammar, validate, write) by focusing on projection and conversion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings. However, the description hints at template generation when content is null, providing some context. Lack of usage alternatives or exclusions reduces clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | OCTAVE content to validate (mutually exclusive with file_path) | |
| file_path | No | Path to OCTAVE file to validate (mutually exclusive with content) | |
| schema | Yes | Schema name to validate against (e.g., 'META', 'SESSION_LOG') | |
| fix | No | If True, apply repairs to canonical output. If False (default), suggest repairs only. | |
| debug_grammar | No | If True, include compiled regex/grammar in output for debugging constraint evaluation. | |
| grammar_hint | No | If True and validation returns INVALID, include compiled GBNF grammar in response to guide correction. | |
| diff_only | No | If True, return diff instead of canonical content. Saves tokens when validating. | |
| compact | No | If True, return warning/error counts instead of full lists. Saves tokens. | |
| profile | No | Validation strictness profile: STRICT (full compliance, reject unknown), STANDARD (default), LENIENT (warnings not errors, auto-repairs), ULTRA (minimal validation). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses validation and optional repairs, focus on specific constraints, but does not detail side effects, permissions, or whether modifications are persisted. Some behavioral context is present via parameters like fix and profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences concisely convey purpose, behavior, and focus areas without unnecessary detail. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no output schema, the description effectively summarizes tool behavior (validation, repair, canonical form) and key features (diff, grammar hints). It covers the main use cases but could elaborate on return value structure and error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by linking parameters to purpose (e.g., 'fix' for repairs, 'profile' for strictness) and highlighting focus on I3/I5 constraints, providing meaningful context beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs schema checking and repair suggestions for OCTAVE content, specifies it validates against schema and returns canonical form, and identifies focus on I3 and I5 constraints. This distinguishes it from siblings like compile_grammar and eject.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description does not mention prerequisites, scenarios, or when not to use it. Siblings are not referenced for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| target_path | Yes | File path to write to | |
| content | No | Full content for new files or overwrites. Accepts raw OCTAVE or a single markdown fenced code block. Mutually exclusive with changes. | |
| changes | No | Dictionary of field updates for existing files. Each value is either a bare value (full replacement, default) or a $op descriptor: {"$op":"DELETE"} removes the target; {"$op":"APPEND","value":x} pushes x (or each item of list x) onto the end of an array target; {"$op":"PREPEND","value":x} unshifts onto the front of an array; {"$op":"MERGE","value":{...}} deep-merges into a block target, preserving unmentioned children (use inner $op:DELETE to remove). Op/target-type mismatches return E_OP_TARGET_MISMATCH; missing paths return E_UNRESOLVABLE_PATH (no auto-create, I3); malformed descriptors return E_INVALID_OP_DESCRIPTOR. Paths support: top-level KEY, META.FIELD, PARENT.CHILD into a top-level Block, and §N.KEY / §N::NAME.KEY into Sections. (GH#373) | |
| mutations | No | META field overrides (applies to both modes). | |
| base_hash | No | Expected SHA-256 hash of existing file for consistency check (CAS). | |
| schema | No | Schema name for validation (I5). Common schemas: META, SKILL, CRS_REVIEW, COGNITION_DEFINITION, DEBATE_TRANSCRIPT. Use 'frozen@<hash>' or 'latest' for hermetic resolution. If an unknown schema is provided, the response includes available_schemas. | |
| debug_grammar | No | If True, include compiled regex/grammar in output for debugging constraint evaluation. | |
| grammar_hint | No | If True and validation returns INVALID, include compiled GBNF grammar in response to guide correction. | |
| lenient | No | If True, enable deterministic lenient parsing + optional schema repairs. Default: false (strict parsing). | |
| corrections_only | No | If True, return corrections/diff without writing to disk (dry run). | |
| dry_run | No | Alias for corrections_only. If True, return corrections/diff without writing to disk (default: false). | |
| parse_error_policy | No | Policy when tokenization/parsing fails in lenient mode: "error" (default) or "salvage". | |
| format_style | No | Output formatting style for canonical emission. 'preserve' (Strategy A, GH#377): span-aware preserve mode — clean nodes slice from baseline_bytes, dirty/repaired nodes re-emit canonically. Diff footprint ≤0.5% of file size on single-key edits against representative documents. Subsumes GH#248 mixed annotation form drift. 'expanded': lift inline-map shapes (KEY::[K::V,...]) into Block form before emit. 'compact': collapse atom-only Blocks (no comments, arity-bounded) into inline-list-of-InlineMap form. Comment-bearing subtrees vetoed with W_COMPACT_REFUSED (I3 Mirror Constraint, I4 Auditability). DEPRECATED v1.13.0: Passing format_style=null explicitly emits a DeprecationWarning; the default will change from full canonical re-emit to 'preserve' in v1.14.0. To keep canonical re-emit past the flip, pass 'expanded' explicitly. To opt in to the new default early, pass 'preserve'. Omitting the parameter accepts the future default silently. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses behavioral traits such as handling creation and modification, detailed op descriptors for changes, error codes, format_style options with deprecation, dry_run behavior, lenient parsing, and parse_error_policy. This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured, starting with a summary and then detailing modes, deprecation, and options. Every sentence adds value, though the op descriptor details could be slightly more concise. Still efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (13 params, nested objects, no output schema), the description is very complete. It covers use cases, op structure, error handling, formatting, and deprecation. It does not explain return values, but that is acceptable without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline is 3. The description adds significant extra context beyond schema descriptions, explaining the relationship between content and changes, op descriptors, format_style future changes, and the effect of lenient and parse_error_policy. This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is the unified entry point for writing OCTAVE files, handling both creation and modification. It explicitly distinguishes itself by noting it replaces octave_create and octave_amend, and describes different usage modes (content, changes, normalize).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use content vs changes vs omit both, and that it replaces older tools. However, it does not explicitly contrast with sibling tools like octave_validate or octave_compile_grammar, leaving some ambiguity about when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.13.0octave_compile_grammaroctave_ejectoctave_validateoctave_writeScored 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.
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.
DocBase MCP server for AI agents
MCP server for progressive tool usage at any scale (see https://klavis.ai)
