octave-mcp 1.5.0

OCTAVE MCP Server - Lenient-to-Canonical OCTAVE pipeline with schema validation and generative holographic contracts

OCTAVE MCP Server

Production-grade MCP server implementing the OCTAVE v6 document protocol: Generative Holographic Contracts.

Table of Contents

• For AI Agents
• What It Does
• Quick Start
• Installation
• MCP Tools
• When OCTAVE Helps
• Documentation
• Contributing

---

For AI Agents

Reading this section makes you OCTAVE-literate. The ~200-token primer below is all you need to write valid OCTAVE:

===OCTAVE_LITERACY_PRIMER===
META:
  TYPE::PRIMER
  VERSION::"6.0.0"
  TOKENS::~200

§1::ESSENCE
PURPOSE::"Write OCTAVE"
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===

Project Context (for working on this codebase):

===AGENT_BOOTSTRAP===
QUALITY_GATES::[mypy,ruff,black,pytest]
DEV_SETUP::docs/guides/development-setup.md
SPECS::src/octave_mcp/resources/specs/
PRIMERS::src/octave_mcp/resources/primers/

IMMUTABLES::[
  I1::SYNTACTIC_FIDELITY,     // Preserve semantic meaning exactly
  I2::DETERMINISTIC_ABSENCE,  // Distinguish absent vs null vs default
  I3::MIRROR_CONSTRAINT,      // Reflect only what exists, create nothing
  I4::TRANSFORM_AUDITABILITY, // Log every transformation with IDs
  I5::SCHEMA_SOVEREIGNTY      // Make validation status visible
]
===END===

---

What It Does

This repository ships the OCTAVE MCP Server (v1.5.0)—a Model Context Protocol implementation that transforms OCTAVE documents from passive text into Generative Holographic Contracts.

OCTAVE (Olympian Common Text And Vocabulary Engine) is a deterministic document format and control plane for LLM systems. It keeps meaning durable when text is compressed, routed between agents, or projected into different views.

Core Philosophy: Validation Precedes Generation OCTAVE v6 introduces the principle that schemas should constrain LLM output during generation, not just validate it afterward. The META block can compile to strict grammars (Regex/GBNF) for constrained generation.

Implementation Status (v0.6.0): Grammar compilation is implemented and available via debug_grammar=True. However, the MCP tools (octave_validate, octave_write) currently perform post-hoc validation rather than enforcing grammar constraints during generation. See the architecture spec for details.

• Generative Constraints: META.CONTRACT compiles to regex/GBNF grammar (use debug_grammar=True to inspect).
• Holographic Sovereignty: The document defines its own schema laws inline.
• Hermetic Anchoring: No network calls in the hot path. Standards are frozen or local.
• Auditable Loss: Compression tiers declared in META (LOSSLESS, AGGRESSIVE).

Language, operators, and readability

• Syntax: Unicode-first operators (→, ⊕, ⧺, ⇌, ∨, ∧, §) with ASCII aliases.
• Vocabulary: Mythological terms as semantic compression shorthands.
• Authoring: Humans write in the lenient view; tools normalize to canonical Unicode.

Mythological compression

OCTAVE's name -- Olympian Common Text And Vocabulary Engine -- reflects a foundational design insight: LLMs have deep training data saturation in classical mythology, making mythological terms function as pre-trained compression already in the weights. SISYPHEAN::BUILD_FAILURES encodes repetition, frustration, cyclicality, and futility in one word -- achieving 60-70% token reduction with 10x semantic density and 100% zero-shot comprehension across all tested models.

LLMs exhibit a documented paradigm blindness: when asked theoretically whether mythology helps, they hesitate; when given JOURNEY::ODYSSEAN practically, they understand instantly. If you just parsed that term without needing a definition, you've proven the thesis. Use mythology freely -- start with Greek, extend across world traditions as semantics demand.

See The Mythological Compression Principle for evidence and guidance. See research evidence for the full empirical basis.

See the protocol specs in src/octave_mcp/resources/specs/ for v6.0.0 rules.

What this server provides

octave-mcp bundles the OCTAVE tooling as MCP tools and a CLI.

• 4 MCP tools: octave_validate, octave_write, octave_eject, octave_compile_grammar
• Grammar Compiler: Compiles META.CONTRACT constraints to GBNF grammars (inspect via debug_grammar=True).
• Hermetic Hydrator: Resolves standards without network dependency.

When OCTAVE Helps

Use OCTAVE when documents must survive multiple agent/tool hops, repeated compression, or auditing:

• Self-Validating Agents: Agents that define their own output grammar.
• Coordination Briefs: Decision logs that circulate between agents.
• Compressed Context: Reusable prompts needing stable structure (54–68% token reduction).

Installation

PyPI:

pip install octave-mcp
# or
uv pip install octave-mcp

From source:

git clone https://github.com/elevanaltd/octave-mcp.git
cd octave-mcp
uv pip install -e ".[dev]"

Quick Start

CLI

# Validate and normalize (v6 auto-detection)
octave validate document.oct.md

# Write with validation (from content)
echo "===DOC===\nMETA:\n  TYPE::LOG\n  CONTRACT::GRAMMAR[...]\n..." | octave write output.oct.md --stdin

# Project to a view/format
octave eject document.oct.md --mode executive --format markdown

MCP Setup

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

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

MCP Tools

Tool	Purpose
octave_validate	Schema validation + repair suggestions + grammar compilation
octave_write	Unified file creation/modification with validation (includes normalize mode)
octave_eject	Format projection and template generation
octave_compile_grammar	Direct GBNF grammar compilation from META.CONTRACT constraints

See API Reference for full parameter documentation.

Generative Holographic Contracts (v6)

OCTAVE v6 introduces the Holographic Contract concept:

1. Read META: The parser reads the META block first.
2. Compile Grammar: Constraints (REQ, ENUM, REGEX) compile into GBNF grammar (available via debug_grammar=True).
3. Generate/Validate: The body can be validated against this bespoke grammar.

Note: In v0.6.0, grammar compilation is implemented but tools perform post-hoc validation. Grammar-constrained generation is a roadmap feature.

Documentation

Doc	Content
Usage Guide	CLI, MCP, and API examples
API Reference	Python API documentation
MCP Configuration	Client setup and integration
Protocol Specs	v6.0.0 Generative Holographic Specs
EBNF Grammar	Formal v1.0.0 grammar specification
Development Setup	Dev environment, testing, quality gates
Architecture Decisions	Architecture Decision Records (ADRs)
Research	Benchmarks and validation studies

Contributing

See CONTRIBUTING.md for development setup, testing, and guidelines.

# Quick dev setup
git clone https://github.com/elevanaltd/octave-mcp.git
cd octave-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest

# Quality checks
ruff check src tests && mypy src && black --check src tests

License

Apache-2.0 — Built with MCP Python SDK.