octave-mcp 1.2.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

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.0.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.

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.

• 3 MCP tools: octave_validate, octave_write, octave_eject
• 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
octave_eject	Format projection and template generation

octave_validate

Validates OCTAVE content against a schema and returns normalized canonical output.

# Parameters
content: str          # OCTAVE content to validate (or use file_path)
file_path: str        # Path to file (mutually exclusive with content)
schema: str           # Schema name (e.g., 'META', 'SESSION_LOG')
fix: bool = False     # Apply repairs (enum casefold, type coercion)
profile: str          # Validation strictness: STRICT, STANDARD, LENIENT, ULTRA
diff_only: bool       # Return diff instead of full canonical (saves tokens)
compact: bool         # Return counts instead of full error lists
debug_grammar: bool   # Include compiled regex/GBNF grammar in output

Returns: { status, canonical, repairs, warnings, errors, validation_status }

octave_write

Unified write operation for creating new files or modifying existing ones.

# Parameters
target_path: str      # File path to write
content: str          # Full content for new files (mutually exclusive with changes)
changes: dict         # Delta updates for existing files (tri-state: absent=no-op, DELETE=remove, value=set)
mutations: dict       # META field overrides
base_hash: str        # Expected SHA-256 for consistency check (CAS)
schema: str           # Schema name for validation
lenient: bool         # Enable lenient parsing with auto-repairs
corrections_only: bool # Dry run - return corrections without writing

Returns: { status, mode, canonical, repairs, warnings, errors, validation_status, file_hash }

octave_eject

Projects OCTAVE content to different formats and views.

# Parameters
content: str          # OCTAVE content to project (null for template generation)
schema: str           # Schema name for validation or template generation
mode: str             # Projection: canonical, authoring, executive, developer
format: str           # Output: octave, json, yaml, markdown, gbnf

Returns: { output, lossy, fields_omitted, validation_status }

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

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.