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

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

Architecture Immutables

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.