octave-mcp 0.4.1

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

===AGENT_BOOTSTRAP===
META:
  TYPE::BOOTSTRAP
  VERSION::"6.0"
  CONTRACT::HOLOGRAPHIC[
    VALIDATION::JIT_GRAMMAR
    ANCHOR::HERMETIC
  ]

GUIDANCE::AGENTS.oct.md
QUALITY_GATES::[mypy,ruff,black,pytest]
DEV_SETUP::docs/guides/development-setup.md
SPECS::specs/README.oct.md
IMMUTABLES::[I1,I2,I3,I4,I5]
===END===

---

What It Does

This repository ships the OCTAVE MCP Server (v0.4.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 Instead of checking if an LLM wrote a valid document after the fact, OCTAVE v6 compiles the document's META block into a strict grammar (Regex/GBNF) that constrains the LLM's output generation. It is structurally impossible to generate invalid syntax.

• Generative Constraints: META.CONTRACT compiles to regex/grammar for LLM guidance.
• 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.

See the protocol specs in specs/ for v6.0.0 rules.

What this server provides

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

• 3 MCP tools: octave_validate, octave_write, octave_eject
• Generative Engine: Compiles constraints to grammars (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 + Grammar Compilation (debug_grammar=True)
octave_write	Unified file creation/modification (content OR delta changes)
octave_eject	Format projection (octave, json, yaml, markdown)

Generative Holographic Contracts (v6)

OCTAVE v6 introduces the Holographic Contract:

1. Read META: The parser reads the META block first.
2. Compile Grammar: It compiles the constraints (REQ, ENUM, REGEX) into a generative grammar.
3. Generate/Validate: The body is generated/validated against this bespoke grammar.

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
Development Setup	Dev environment, testing, quality gates
Architecture	Decision records and design docs
Research	Benchmarks and validation studies

Architecture Immutables

ID	Principle
I1	Syntactic Fidelity — normalization alters syntax, never semantics
I2	Deterministic Absence — distinguish absent vs null vs default
I3	Mirror Constraint — reflect only what's present, create nothing
I4	Transform Auditability — log every transformation with stable IDs
I5	Schema Sovereignty — validation status visible in output

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.