Related Pages

Related topics: System Architecture, Canonical Normalization

Project Introduction

Overview

Octave-MCP (Olympian Common Text And Vocabulary Engine - Model Context Protocol) is a semantic DSL (Domain Specific Language) framework designed for structured document creation, validation, and transformation in LLM workflows. It provides a unified text format with rich semantic annotations that enables precise machine-readable documentation while remaining human-readable.

Sources: README.md

Core Concepts

What is OCTAVE?

OCTAVE stands for Olympian Common Text And Vocabulary Engine. It is a semantic DSL specifically designed for Large Language Models (LLMs) that bridges the gap between human-readable documentation and machine-processable structured data.

The framework operates on a patterns → archetypes → holographic methodology, where semantic patterns are mapped to recognizable archetypes which then create holographic constraints for validation and processing.

Sources: src/octave_mcp/resources/primers/octave-mastery-primer.oct.md

Key Features

Architecture

System Components

graph TD
    A[OCTAVE Documents] --> B[Parser Layer]
    B --> C[Grammar Compiler]
    B --> D[Validator]
    C --> E[GBNF Grammar Output]
    D --> F[Validation Results]
    B --> G[Writer/Reader]
    G --> H[Normalized Output]
    
    I[MCP Tools] --> J[octave_validate]
    I --> K[octave_write]
    I --> L[octave_eject]
    I --> M[octave_compile_grammar]
    
    N[CLI] --> O[octave validate]
    N --> P[octave write]
    N --> Q[octave eject]

Package Structure

The main package resides in src/octave_mcp/ with the following core modules:

Sources: src/octave_mcp/__init__.py

OCTAVE Syntax

Document Structure

An OCTAVE document follows a specific envelope format:

===DOCUMENT_NAME===
META:
  TYPE::"DOCUMENT_TYPE"
  VERSION::"1.0.0"
  PURPOSE::"Document purpose description"

Related Pages

Related topics: Project Introduction, System Architecture

Project File Structure

Overview

The octave-mcp project is organized as a Python package implementing the Olympian Common Text And Vocabulary Engine (OCTAVE) — a semantic DSL designed for LLM document processing. The repository follows a modular structure that separates core parsing logic, MCP (Model Context Protocol) server implementation, resource definitions, utilities, and documentation.

Directory Architecture

graph TD
    A[octave-mcp Root] --> B[src/octave_mcp/]
    A --> C[tools/]
    A --> D[examples/]
    A --> E[standards/]
    A --> F[docs/]
    
    B --> B1[core/]
    B --> B2[mcp/]
    B --> B3[resources/]
    
    B1 --> B1a[grammar_compiler/]
    B1 --> B1b[parser/]
    B1 --> B1c[validator/]
    
    B2 --> B2a[write.py]
    B2 --> B2b[grammar_resources.py]
    
    B3 --> B3a[primers/]
    B3 --> B3b[specs/]
    B3 --> B3c[skills/]
    B3 --> B3d[vocabularies/]

Root Directory Structure

Source Code (`src/octave_mcp/`)

The main package contains three primary submodules:

Core Module (`src/octave_mcp/core/`)

Contains the fundamental parsing and validation logic.

The grammar_compiler package was renamed from octave_mcp.core.grammar to resolve a naming collision, as documented in ADR-0006. It provides the public API:

from octave_mcp.core.grammar_compiler import compile_document_grammar, emit_grammar_for_schema

Sources: src/octave_mcp/core/grammar_compiler/__init__.py:1-18

MCP Module (`src/octave_mcp/mcp/`)

Implements the Model Context Protocol server and tools.

The grammar_resources.py module provides:

• Resource templates for accessing pre-compiled GBNF grammars
• Dynamic schema compilation with caching
• URI template access via octave://grammars/{schema_name}

Sources: src/octave_mcp/mcp/grammar_resources.py:1-80

Resources Module (`src/octave_mcp/resources/`)

Contains distributable OCTAVE resources used by implementers and agents.

graph LR
    A[resources/] --> B[primers/]
    A --> C[specs/]
    A --> D[skills/]
    A --> E[vocabularies/]
    
    B --> B1[octave-literacy-primer]
    B --> B2[octave-compression-primer]
    B --> B3[octave-mastery-primer]
    B --> B4[octave-ultra-mythic-primer]
    
    C --> C1[octave-core-spec.oct.md]
    C --> C2[octave-agents-spec.oct.md]
    C --> C3[octave-skills-spec.oct.md]
    C --> C4[schemas/]
    
    D --> D1[octave-compression/SKILL.md]
    
    E --> E1[registry.oct.md]
    E --> E2[core/]

#### Primers (primers/)

Self-referential training documents that teach OCTAVE syntax:

#### Specs (specs/)

Official OCTAVE v6.0.0 specifications:

#### Schemas (specs/schemas/)

Schema definitions including:

• debate_transcript.oct.md - Debate transcript schema
• json/ - JSON Schema for OCTAVE

#### Vocabularies (specs/vocabularies/)

OCTAVE vocabulary definitions:

#### Skills (skills/)

Workflow definitions for OCTAVE operations:

• octave-compression/SKILL.md - Workflow for prose-to-OCTAVE transformation

Sources: src/octave_mcp/resources/README.md:1-80

Package Exports

The octave_mcp/__init__.py exports 51 public APIs organized into categories:

Sources: src/octave_mcp/__init__.py:1-50

Tools Directory (`tools/`)

Standalone utilities for OCTAVE validation and conversion.

Lint Tool (`lint-octave.py`)

Validates OCTAVE documents with checks for:

• Document markers (===NAME=== and ===END===)
• META section presence
• Indentation (2-space multiples)
• Assignment syntax (KEY::VALUE)
• Balanced brackets
• No trailing commas in lists

Usage:

python3 lint-octave.py < document.oct.md
# Returns: OCTAVE_VALID or OCTAVE_INVALID: <reason>

Validator Tool (`octave-validator.py`)

Supports validation profiles:

• protocol
• hestai-agent
• hestai-skill
• hestai-pattern

Usage:

octave validate document.oct.md
octave-validator.py --path /directory --profile hestai-agent

Sources: tools/README.md:1-50

Examples Directory (`examples/`)

Demonstrates OCTAVE compression across different scales.

Integrations (`examples/integrations/`)

Integration examples including:

Compression Tier Examples

Demonstrates OCTAVE 5.1.0 compression on research documents:

Sources: examples/README.md:1-60

Standards Directory (`standards/`)

Official OCTAVE format standards defining document schemas.

L3 Agent Format (`L3-AGENT-FORMAT.oct.md`)

Defines the exact L3 file format for HestAI Agents with:

graph LR
    A[YAML_HEADER] --> B[+ OCTAVE_BODY]
    B --> C[===AGENT_DEFINITION===]
    
    C --> D[§0::META]
    C --> E[§1::CONSTITUTIONAL_CORE]
    C --> F[§2::COGNITIVE_FRAMEWORK]
    C --> G[§3::SHANK_OVERLAY]
    C --> H[§4::OPERATIONAL_IDENTITY]
    C --> I[§5::DOMAIN_CAPABILITIES]
    C --> J[§6::OUTPUT_CONFIGURATION]
    
    J --> K[===END===]

Required YAML header fields:

• name: Agent identifier
• description: One-line summary
• allowed-tools: Tool permissions list

Sources: standards/L3-AGENT-FORMAT.oct.md:1-50

Documentation Structure (`docs/`)

MCP Server Setup

Claude Code Configuration (~/.claude.json):

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

HTTP Transport:

octave-mcp-server --transport http --port 8080

Sources: README.md:1-60

MCP Tools Reference

CLI Commands

octave validate document.oct.md
octave write output.oct.md --stdin
octave eject document.oct.md --mode executive --format markdown

Resource Loading Pattern

For programmatic access to bundled resources:

from importlib.resources import files, as_file

# Read a primer
primer_file = files('octave_mcp.resources.primers').joinpath('octave-compression-primer.oct.md')
with as_file(primer_file) as path:
    primer_content = path.read_text()

# Read a spec
spec_file = files('octave_mcp.resources.specs').joinpath('octave-core-spec.oct.md')

All resources are versioned at v6.0.0 as part of the Universal Anchor release.

Summary

The octave-mcp project follows a clear separation of concerns:

1. Core parsing/validation in src/octave_mcp/core/ — language-agnostic processing
2. MCP protocol in src/octave_mcp/mcp/ — server implementation and tools
3. Resources in src/octave_mcp/resources/ — distributable specs, primers, and vocabularies
4. Utilities in tools/ — standalone CLI tools for CI/CD integration
5. Examples in examples/ — integration demonstrations
6. Standards in standards/ — official format definitions

Related Pages

Related topics: MCP Tools Reference, CLI Interface

System Architecture

Overview

OCTAVE-MCP (Olympian Common Text And Vocabulary Engine - Model Context Protocol) is a semantic DSL implementation designed for structured document processing, validation, and LLM integration. The architecture follows a layered approach combining MCP protocol support, grammar-based validation, and integration adapters for various inference backends.

High-Level Architecture

graph TD
    subgraph "Client Layer"
        CLI[CLI Tools]
        MCP[Claude Desktop / HTTP]
    end

    subgraph "MCP Protocol Layer"
        Server[MCP Server]
        GrammarResources[Grammar Resources]
        WriteTool[Write Tool]
        ValidateTool[Validate Tool]
        EjectTool[Eject Tool]
    end

    subgraph "Core Processing Layer"
        Parser[Parser]
        GrammarCompiler[Grammar Compiler]
        Validator[Validator]
    end

    subgraph "Integration Layer"
        LLM[LLM Integrations]
    end

    subgraph "Resource Layer"
        Specs[Specifications]
        Primers[Primers]
        Skills[Skills]
    end

    CLI --> Server
    MCP --> Server
    Server --> GrammarResources
    Server --> WriteTool
    Server --> ValidateTool
    Server --> EjectTool
    GrammarResources --> GrammarCompiler
    WriteTool --> Parser
    WriteTool --> Validator
    EjectTool --> Parser
    GrammarCompiler --> Specs
    Parser --> Validator
    Specs --> LLM

MCP Server Architecture

Server Initialization

The MCP server (octave-mcp-server) provides the primary interface for OCTAVE document operations. It initializes with configuration options supporting both Claude Desktop and HTTP transport modes.

Configuration Methods:

Sources: README.md

Transport Architecture

The server supports multiple transport mechanisms for flexibility in deployment scenarios:

1. Standard I/O: Default mode for CLI and Claude Desktop integration
2. HTTP Transport: Scalable deployment option with port configuration

graph LR
    A[Claude Desktop] -->|stdio| B[octave-mcp-server]
    C[HTTP Client] -->|HTTP| D[--transport http]
    B --> E[Core Parser]
    D --> E

Core Processing Components

Parser Module

The parser (src/octave_mcp/core/parser.py) handles OCTAVE document parsing with support for:

• Document Envelope Detection: Identifies ===NAME=== markers for document boundaries
• META Block Parsing: Extracts metadata including TYPE, VERSION, and custom fields
• Grammar Sentinel Support: Recognizes OCTAVE::VERSION patterns for grammar versioning
• Byte Offset Tracking: Records start_byte and end_byte positions for each document region

Parser Features:

Sources: src/octave_mcp/core/parser.py:50-80

Grammar Compiler

The grammar compiler (src/octave_mcp/core/grammar_compiler/__init__.py) generates GBNF (Greibach Normal Form) grammars for constrained generation and validation.

Public API:

from octave_mcp.core.grammar_compiler import (
    compile_document_grammar,
    emit_grammar_for_schema,
)

Compilation Features:

Sources: src/octave_mcp/core/grammar_compiler/__init__.py

Grammar Resources

The grammar resources module (src/octave_mcp/mcp/grammar_resources.py) provides MCP resources for dynamic grammar access:

• Resource Templates: Dynamic grammar retrieval via octave://grammars/{schema_name}
• Caching: In-memory cache for compiled grammars
• Schema Resolution: Loads schemas from builtin registry or search paths

Resource URI Pattern:

octave://grammars/{schema_name}

Sources: src/octave_mcp/mcp/grammar_resources.py

MCP Tools

Validate Tool

Performs schema-based validation with detailed error reporting:

Write Tool

The write tool (src/octave_mcp/mcp/write.py) provides file writing with full validation pipeline:

Format Style Modes:

Sources: src/octave_mcp/mcp/write.py

Eject Tool

Projects documents to different views for various audiences:

• canonical: Full document structure
• executive: Summary view for decision-makers
• developer: Implementation-focused perspective
• template: Blank template for new documents

Resource Organization

graph TD
    subgraph "Resources"
        subgraph "Specs"
            Core[octave-core-spec.oct.md]
            Agents[octave-agents-spec.oct.md]
            Skills[octave-skills-spec.oct.md]
            Data[octave-data-spec.oct.md]
            Schema[octave-schema-spec.oct.md]
        end

        subgraph "Primers"
            Mastery[octave-mastery-primer]
            Compression[octave-compression-primer]
            Ultra[octave-ultra-mythic-primer]
        end

        subgraph "Skills"
            CompressionSkill[octave-compression]
        end
    end

Specifications Structure

Sources: src/octave_mcp/resources/README.md

Validation Profiles

The system supports multiple validation profiles for different use cases:

Profile Configuration:

octave validate document.oct.md --profile hestai-agent --require-frontmatter

Sources: tools/octave-validator.py

Document Flow

sequenceDiagram
    participant Client
    participant Server
    participant Validator
    participant Parser
    participant GrammarCompiler

    Client->>Server: octave_write(document)
    Server->>Parser: parse_document(content)
    Parser->>Validator: validate(parsed_doc, schema)
    Validator->>GrammarCompiler: compile_grammar(schema)
    GrammarCompiler-->>Validator: GBNF grammar
    Validator-->>Server: validation_result
    Server-->>Client: write_response

    Note over Client,GrammarCompiler: Round-trip: OCTAVE → JSON → OCTAVE

Integration Points

CLI Integration

# Validate a document
octave validate document.oct.md

# Write with validation
octave write output.oct.md --stdin

# Eject to different view
octave eject document.oct.md --mode executive --format markdown

MCP Tool Integration

Sources: README.md

Architectural Principles

1. Separation of Concerns: MCP protocol layer is isolated from core processing
2. Profile-Based Validation: Different profiles support various document types
3. Grammar-Driven Validation: GBNF grammars ensure structured output
4. Round-Trip Fidelity: OCTAVE ↔ JSON conversion preserves document semantics
5. Extensible Resources: Primers and skills provide domain-specific guidance

File Organization

src/octave_mcp/
├── core/
│   ├── parser.py           # Document parsing
│   └── grammar_compiler/   # GBNF generation
├── mcp/
│   ├── server.py           # MCP server
│   ├── http_transport.py   # HTTP transport
│   ├── grammar_resources.py # Dynamic grammars
│   └── write.py            # Write tool
├── integrations/           # LLM backend adapters
└── resources/
    ├── specs/             # OCTAVE specifications
    ├── primers/           # Learning primers
    └── skills/            # Skill definitions

Related Pages

Related topics: Schema Validation, Compression System

Canonical Normalization

Canonical Normalization is the process by which OCTAVE documents are validated, transformed, and written in a standardized format. It ensures consistency across documents by enforcing syntax rules, resolving dialect variations, and producing output that conforms to the OCTAVE specification. The normalization pipeline is a core component of the write workflow, operating between parsing and emission.

Overview

OCTAVE (Olympian Common Text And Vocabulary Engine) is a semantic DSL designed for LLMs. When documents pass through the system—either during editing, compression, or cross-agent transfer—syntax variations can accumulate. Canonical Normalization addresses this by providing a deterministic transformation that produces a consistent "canonical" form.

The normalization system is governed by ADR-0006 (Writer/Reader Symmetry Programme), which defines a phased rollout of behavior changes across multiple milestones.

Architecture

graph TD
    A[Input OCTAVE] --> B[Lexer]
    B --> C[Parser]
    C --> D[Concrete Syntax Tree CST]
    D --> E[Tier Normalization]
    E --> F[Semantic Validation]
    F --> G[Emitter]
    G --> H[Canonical Output]
    
    E --> E1[warnings list]
    F --> F1[Field Errors]
    F --> F2[Repair Suggestions]
    
    style E fill:#f9f,stroke:#333
    style H fill:#9f9,stroke:#333

Phases of Normalization

Phase 1: Lexical Analysis

The lexer (src/octave_mcp/core/lexer.py) performs initial tokenization, handling:

• Standard identifiers and operators
• Angle bracket annotations (NAME<qualifier>)
• Comma-separated qualifier lists

Qualifier List Support (GH#320)

The lexer supports comma-separated qualifier lists in angle bracket annotations:

NEVER[PEDANTIC,DISMISSIVE,VAGUE]

This is parsed by consuming valid identifier characters, then checking for commas followed by subsequent segments. Sources: src/octave_mcp/core/lexer.py:lexer-impl()

Phase 2: Parsing

The parser (src/octave_mcp/core/parser.py) builds a Concrete Syntax Tree (CST) from token streams. Key features include:

Sources: src/octave_mcp/core/parser.py:parse_document-90-115(ADR-0006 SR2-T2)

Phase 3: Tier Normalization

The tier normalization module (src/octave_mcp/core/grammar/tier_normalize.py) applies compression-tier-specific transformations:

Sources: src/octave_mcp/core/grammar/tier_normalize.py()

Phase 4: CST Representation

The CST module (src/octave_mcp/core/grammar/cst.py) provides the intermediate representation:

classDiagram
    class Document {
        +str name
        +int start_byte
        +int end_byte
        +str grammar_version
        +MetaBlock? meta
        +list~Section~ sections
    }
    class MetaBlock {
        +int meta_start_byte
        +int meta_end_byte
        +dict fields
    }
    class Section {
        +str identifier
        +str content
        +list annotations
    }
    
    Document *-- MetaBlock
    Document *-- Section

Sources: src/octave_mcp/core/grammar/cst.py()

Phase 5: Emission

The emitter (src/octave_mcp/core/emitter.py) writes the canonical form:

warnings = []
canonical = emitter.emit(cst, normalize=True)
# warnings contains list of normalization changes applied

Sources: src/octave_mcp/core/emitter.py()

Behavior Timeline

Per ADR-0006, normalization behavior evolves across milestones:

graph LR
    T1[TODAY<br/>SR1] --> T2[AFTER_SR1_T4<br/>SR1 Milestone] --> T3[AFTER_SR3_T2<br/>SR3 Milestone]
    
    T1:::today
    T2:::milestone1
    T3:::milestone3
    
    classDef today fill:#ff6b6b,color:#fff
    classDef milestone1 fill:#feca57,color:#000
    classDef milestone3 fill:#48dbfb,color:#000
    
    T1 -->|"normalize on write"| T1a["warnings: []<br/>source was already canonical"]
    T2 -->|"NO-OP normalization<br/>warnings enumerate what<br/>WOULD have changed"| T2a["warnings: []<br/>no normalization attempted<br/>≠ canonicality guarantee"]
    T3 -->|"octave_fmt for canonicalization<br/>octave_write for persistence"| T3a["Separate concerns<br/>Two distinct calls"]

Timeline Details

Sources: src/octave_mcp/resources/skills/octave-literacy/SKILL.md:§6a::TIMELINE(ADR-0006)

Normalization Rules

Syntax Normalization

Semantic Normalization

• Operator resolution: Alias operators mapped to canonical forms (⇌ vs <->)
• Quoted strings: Preserved verbatim with original quotes
• Blank lines: Tracked for round-trip fidelity

META Sanity Checks

Minimal validation of META section:

MCP Tool Integration

The normalization system integrates with MCP tools:

Sources: README.md:MCP Tools()

CLI Usage

# Validate document (implicit normalization check)
octave validate document.oct.md

# Write with dry-run normalization
octave write output.oct.md --mode normalize

# Canonical format ejection
octave eject document.oct.md --mode canonical --format markdown

Round-Trip Fidelity

The normalization system guarantees round-trip fidelity:

graph LR
    A[OCTAVE] -->|octave-to-json| B[JSON]
    B -->|json-to-octave| C[OCTAVE']
    A -->|diff| C
    
    C -->|identical| A

When a document passes through JSON serialization and back:

python3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md
diff input.oct.md output.oct.md  # Should produce no differences

Preserved elements during round-trip:

• Blank lines
• Quoted strings
• Semantic operators (⊕, ⇌, §)
• Section identifiers

Sources: tools/README.md:Round-Trip Example()

Error Handling

Normalization produces structured warnings:

{
  "warnings": [
    "Indentation normalized: 4 spaces → 2 spaces",
    "Trailing comma removed in list [a, b, c,]",
    "Operator alias <-> → ⇌"
  ]
}

Empty warnings array indicates no normalization changes were needed.

See Also

• ADR-0006: Writer/Reader Symmetry Programme
• OCTAVE Data Specification
• Usage Guide
• API Reference

Related Pages

Related topics: Canonical Normalization, MCP Tools Reference

Schema Validation

Overview

Schema Validation in OCTAVE-MCP is the core mechanism that ensures OCTAVE documents conform to defined structural rules, type constraints, and semantic policies. The validation system operates on parsed AST (Abstract Syntax Tree) representations of documents, providing comprehensive error reporting with field-level precision.

The validation framework is designed to:

• Validate documents against predefined schema definitions
• Enforce required fields and type constraints
• Support enum validation with prefix matching and ambiguity detection
• Detect unknown fields based on policy settings
• Evaluate constraint chains for complex validation logic
• Support target routing with audit trails for policy enforcement

Sources: src/octave_mcp/core/validator.py:1-30

Architecture

The validation system follows a layered architecture with clear separation of concerns:

graph TD
    A[OCTAVE Document] --> B[Parser]
    B --> C[Document AST]
    C --> D[Validator]
    D --> E{Schema Definition}
    E -->|Built-in| F[META, SKILL, AGENT]
    E -->|Custom| G[User Schemas]
    D --> H[Validation Errors]
    H --> I[Repair Suggestions]
    
    J[Schema Loader] --> E
    K[Schema Extractor] --> E

Core Components

Sources: src/octave_mcp/core/validator.py:50-100

The Validator Class

The Validator class is the primary entry point for schema validation, implementing the visitor pattern for AST traversal:

from octave_mcp import Validator

validator = Validator(schema=schema_def)
errors = validator.validate(doc, strict=False)

Validation Flow

graph LR
    A[validate doc] --> B[_prepare_document_validation]
    B --> C[_validate_sections_recursive]
    C --> D{nested blocks?}
    D -->|yes| C
    D -->|no| E[section_schemas defined?]
    E -->|yes| F[validate_frontmatter]
    E -->|no| G[return errors]
    F --> G

Key Validation Features

1. Required Field Checking - Ensures mandatory fields are present
2. Type Validation - Validates field values against defined types
3. Enum Validation - Supports prefix matching and ambiguity detection
4. Regex Pattern Validation - Validates string formats against regex
5. Unknown Field Detection - Policy-driven detection of unexpected fields
6. Constraint Chain Evaluation - Processes complex validation rules
7. Target Routing - Validates routing targets with audit trail

Sources: src/octave_mcp/core/validator.py:100-150

Schema Definition

Schemas define the structure and constraints for OCTAVE documents. They consist of:

Schema Structure

Policy Settings

The POLICY block controls validation behavior:

POLICY:
  VERSION::"1.0"
  UNKNOWN_FIELDS::REJECT  # REJECT, WARN, or ALLOW

UNKNOWN_FIELDS Policy Options:

• REJECT - Validation fails on unknown fields
• WARN - Unknown fields are reported but don't fail validation
• ALLOW - Unknown fields are ignored

Sources: src/octave_mcp/core/schema_extractor.py:50-80

Schema Extraction

The extract_schema_from_document() function parses OCTAVE documents and builds SchemaDefinition objects:

from octave_mcp.core.schema_extractor import extract_schema_from_document

schema = extract_schema_from_document(doc)
# Returns SchemaDefinition with:
#   - name from document envelope
#   - version from META block
#   - policy settings
#   - field definitions
#   - frontmatter definitions

Extraction Process

graph TD
    A[parse OCTAVE document] --> B[extract name from envelope]
    B --> C[extract VERSION from META]
    C --> D[_extract_policy]
    D --> E[extract FIELDS block]
    E --> F[extract FRONTMATTER block]
    F --> G[build SchemaDefinition]
    G --> H[return with warnings]

Sources: src/octave_mcp/core/schema_extractor.py:80-150

Validation Profiles

The CLI tool supports multiple validation profiles for different document types:

CLI Usage

# Validate single file
python tools/octave-validator.py document.oct.md

# Validate with specific schema
python tools/octave-validator.py document.oct.md --schema META

# Directory scan
python tools/octave-validator.py --path .hestai-sys/library/ --profile hestai-agent

# Require frontmatter (fail on missing)
python tools/octave-validator.py document.oct.md --require-frontmatter

Sources: tools/octave-validator.py:1-50

MCP Tool Integration

The octave_validate MCP tool provides programmatic validation access:

Tool Interface

Return Structure

{
  "valid": true,
  "validation_status": "VALIDATED",
  "validation_errors": []
}

On validation failure:

{
  "valid": false,
  "validation_status": "INVALID",
  "validation_errors": [
    {"code": "E_REQUIRED_FIELD", "message": "...", "field": "META.VERSION"}
  ],
  "grammar_hint": {"format": "gbnf", "grammar": "..."}
}

Sources: src/octave_mcp/mcp/validate.py:1-50

Error Codes

Validation Workflow

graph TD
    A[Input OCTAVE] --> B[Parse Document]
    B --> C{Parse Success?}
    C -->|No| D[Parser Error]
    C -->|Yes| E[Load Schema]
    E --> F{Schema Found?}
    F -->|No| G[UNVALIDATED]
    F -->|Yes| H[Create Validator]
    H --> I[Run Validation]
    I --> J{Validation Errors?}
    J -->|Yes| K[Report INVALID]
    J -->|No| L[Report VALIDATED]
    
    K --> M[Generate Error Details]
    M --> N[Optional: Grammar Hint]
    L --> O[Optional: Validation Success]

Best Practices

1. Always specify schema - Provides precise error messages and repair suggestions
2. Use strict mode for CI/CD - Catches all violations early
3. Leverage profile validation - Ensures documents match their intended type
4. Handle validation errors gracefully - Provide meaningful feedback to users
5. Use grammar hints for generation - Guide LLM output toward valid structures

Sources: src/octave_mcp/core/validator.py:150-200

Related Documentation

• Usage Guide - CLI, MCP, and API examples
• API Reference - Python API documentation
• Schema Specification - Schema format specification

Related Pages

Related topics: Canonical Normalization

Compression System

The OCTAVE Compression System is a semantic compression framework that transforms prose into structured OCTAVE (Olympian Common Text And Vocabulary Engine) documents. Unlike traditional text compression that destroys structural relationships, OCTAVE compression preserves semantic invariants while achieving significant token reduction, making documents both machine-executable and LLM-legible.

Overview

OCTAVE compression serves as the bridge between natural language prose and semantic DSL (Domain-Specific Language) representations. The system operates on a tiered fidelity model where operators specify exactly what is preserved and what is lost at each compression level.

The core principle is mythological semantic compression — leveraging pre-trained mythological vocabulary as functional semantic binding for LLM audiences. This approach achieves 60-70% token reduction while maintaining 88-96% cross-model zero-shot comprehension.

Sources: src/octave_mcp/resources/skills/octave-mythology/SKILL.md:1-15

Compression Tiers

OCTAVE defines four standardized compression tiers, each with explicit loss profiles:

Sources: src/octave_mcp/resources/skills/octave-compression/SKILL.md:15-30

Tier Selection Flow

graph TD
    A[Start: Source Document] --> B{Document Type?}
    B -->|Critical/Legal| C[LOSSLESS]
    B -->|Research/Design| D{Critical Details?}
    B -->|Overview/Summary| E[AGGRESSIVE]
    B -->|Token-Constrained| F[ULTRA]
    D -->|Yes| G[CONSERVATIVE]
    D -->|No| E
    C --> H[0% Loss]
    G --> I[10-15% Loss]
    E --> J[~30% Loss]
    F --> K[40-50% Loss]

Core Architecture

Holographic Patterns

The foundational unit of OCTAVE compression is the HolographicPattern, which encodes constraints and validation rules alongside semantic content. Each field in a compressed document carries its own holographic metadata.

class HolographicPattern:
    example: Optional[str]      # Concrete example value
    constraints: List[str]     # Validation constraints
    target: Optional[str]      # Routing/execution target

Sources: src/octave_mcp/core/holographic.py

Literal Zone Audit

The LiteralZoneAudit system tracks zones that should be preserved verbatim during compression. These zones represent semantic invariants that must survive any transformation:

• Schema definitions
• Contract specifications
• Routing declarations
• Required structural elements

graph LR
    A[Input Document] --> B[Zone Scanner]
    B --> C{Literal Zone?}
    C -->|Yes| D[Seal for Preservation]
    C -->|No| E[Compressible Zone]
    D --> F[Output: SEALED content]
    E --> G[Compression Engine]
    G --> H[Output: Compressed content]

Sources: src/octave_mcp/core/sealer.py

Semantic Operators

OCTAVE compression uses specialized operators that maintain semantic relationships during transformation:

Sources: src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:15-25

Mythological Compression

The Mythological Compression Principle treats mythology as OCTAVE's native compression dialect. Mythological domains provide pre-trained semantic binding that activates rich probability distributions in LLMs.

Domain Categories

Sources: src/octave_mcp/resources/skills/octave-mythology/SKILL.md:30-50

How Mythological Compression Works

Mythology terms function as semantic zip files — compressed meaning already present in model weights. No training required:

1. LLM recognizes domain term (e.g., ODYSSEAN)
2. Automatically loads psychological/operational context (grueling long-term journey)
3. Maintains distinct categorical boundaries (CHRONOS vs DEMETER)
4. Preserves causal graph (the "Why") rather than just the "What"

Sources: examples/compression-comparisons/octave-vs-llmlingua-compression-comparison-2026.md:50-70

Repair and Validation

The repair subsystem (repair.py) provides schema validation with specific field errors and repair suggestions. Every transformation passes through the validation pipeline:

graph TD
    A[Compressed OCTAVE] --> B[Schema Validator]
    B --> C{Valid?}
    C -->|Yes| D[Schema Valid]
    C -->|No| E[Repair Engine]
    E --> F[Field Errors]
    E --> G[Repair Suggestions]
    F --> H[Repair Receipt]
    G --> H
    H --> I[Normalized Output]

Sources: src/octave_mcp/core/repair.py

Validation Checks

Documents compressed with OCTAVE must pass these checks:

Sources: src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:30-35

Workflow: Prose to OCTAVE

graph TD
    A[Prose Document] --> B[Tier Selection]
    B --> C[Phase 1: Field Extraction]
    C --> D[Identify semantic atoms]
    D --> E[Phase 2: Mythology Mapping]
    E --> F[Map to mythological domains]
    F --> G[Phase 3: Operator Application]
    G --> H[Apply synthesis/tension/flow]
    H --> I[Phase 4: Loss Accounting]
    I --> J[Document LOSS_PROFILE]
    J --> K[OCTAVE Document]
    K --> L[Validation]
    L --> M{Valid?}
    M -->|No| N[Repair & Retry]
    N --> C
    M -->|Yes| O[Output with receipt]

Compression Example

Original Prose (5600 tokens)

"The quarterly budget analysis shows significant resource constraints. Downtime from the migration creates tension with the need for parallel work on the new system. Specifically targeted optimization efforts have burned through 60% of the quarterly allocation for this migration alone."

CONSERVATIVE Compression (4800 tokens)

CONFLICT::downtime ⇌ parallel_work
→ MIGRATION[Q4_window]
SISYPHEAN::eternal_repetition[this_migration_alone]
ARTEMIS::specifically_targeted_optimization
DEMETER::60%_quarterly_burned[this_migration_alone]

AGGRESSIVE Compression (1800 tokens)

MIGRATION::SISYPHEAN[Q4] ⊕ CHRONOS[deadline]
→ DEMETER::60%_quarterly_burned

Loss Profiles

Every compressed document declares its LOSS_PROFILE, enabling auditable transformation:

META:
  COMPRESSION_TIER::CONSERVATIVE
  LOSS_PROFILE::redundancy ⊕ verbose_transitions
  NARRATIVE_DEPTH::maintained[tradeoff_reasoning_inline,execution_strategies_explained]

Sources: examples/survey-octave-5-conservative.oct.md:1-15

Integration Points

With Claude Code

repomix --style xml --output context.xml
python octave_enhance_targeted.py context.xml enhanced.xml
# Paste enhanced.xml into Claude Code session

With MCP Tools

Best Practices

1. Select tier before reading source — Tier drives all transformation decisions
2. Preserve literal zones — Seal schema/contract zones before compression
3. Apply mythology selectively — Use domain terms for repeated concepts
4. Document loss explicitly — Always declare LOSS_PROFILE in metadata
5. Validate after compression — Run repair pipeline to ensure schema compliance

Related Pages

Related topics: Schema Validation, System Architecture

Grammar Compilation

Grammar Compilation is the process of transforming OCTAVE schema definitions into GBNF (Gendered Backus-Naur Form) grammar rules that enable constrained text generation. The octave-mcp project uses this system to provide grammar-level validation and AI-assisted document generation with predictable structure.

Overview

OCTAVE documents follow a strict hierarchical structure defined by schemas. The grammar compilation subsystem allows:

• Schema validation: Compile schemas to verify structural correctness
• Constrained generation: Generate GBNF grammars that LLMs can use to produce valid OCTAVE output
• Dynamic compilation: Compile grammars on-demand for any registered schema

Sources: src/octave_mcp/core/grammar_compiler/__init__.py:1-17

Architecture

graph TD
    A[OCTAVE Schema Definition] --> B[SchemaDefinition]
    B --> C[GBNFCompiler]
    C --> D[GBNF Grammar Rules]
    D --> E[Constrained LLM Generation]
    
    F[load_schema_by_name] --> B
    G[Contract Field Specs] --> H[parse_contract_field]
    H --> I[HolographicPattern]
    I --> C
    
    J[GBNFCompiler.compile_schema] --> C
    K[compile_document_grammar] --> C

Core Components

GBNFCompiler

The GBNFCompiler class is the central component that transforms schema definitions into GBNF grammar strings.

Sources: src/octave_mcp/core/grammar_compiler/gbnf.py Sources: src/octave_mcp/mcp/grammar_resources.py:48-76

SchemaDefinition

Schemas define the structure of OCTAVE documents:

schema = SchemaDefinition(
    name=schema_type,
    version=str(meta.get("VERSION", "1.0")),
)

Sources: src/octave_mcp/core/gbnf_compiler.py:42-47

FieldDefinition

Individual fields within schemas include holographic patterns for constraint representation:

schema.fields[field_name] = FieldDefinition(
    name=field_name,
    pattern=pattern,
    raw_value=field_spec,
)

Sources: src/octave_mcp/core/gbnf_compiler.py:59-63

Compilation Pipeline

Step 1: Schema Loading

graph LR
    A[Schema Name] --> B[load_schema_by_name]
    B --> C{Found?}
    C -->|Yes| D[Return SchemaDefinition]
    C -->|No| E[Search Paths]
    E --> C

The load_schema_by_name function searches builtin registry and configured search paths:

Sources: src/octave_mcp/mcp/grammar_resources.py:48-52

schema_def = load_schema_by_name(schema_name)
if schema_def is None:
    raise ValueError(f"Schema '{schema_name}' not found in builtin registry or search paths")

Step 2: CONTRACT Parsing

The CONTRACT field in OCTAVE META sections defines field constraints using holographic notation:

Sources: src/octave_mcp/core/gbnf_compiler.py:30-40

The parse_contract_field function extracts field names and constraints from CONTRACT specifications:

field_name, constraints = parse_contract_field(field_spec)
pattern = HolographicPattern(
    example=None,
    constraints=constraints,
    target=None,
)

Sources: src/octave_mcp/core/gbnf_compiler.py:53-58

Step 3: Grammar Emission

The compiler generates GBNF rules from the schema structure:

compiler = GBNFCompiler()
grammar = compiler.compile_schema(schema_def, include_envelope=True)

Sources: src/octave_mcp/mcp/grammar_resources.py:53-55

MCP Integration

Grammar Resource Provider

The MCP server exposes grammars through a resource provider:

graph TD
    A[MCP Client] --> B[GrammarResources]
    B --> C{Cached?}
    C -->|Yes| D[Return cached GBNF]
    C -->|No| E[_compile_grammar]
    E --> F[GBNFCompiler]
    F --> G[Cache Result]
    G --> D

Sources: src/octave_mcp/mcp/grammar_resources.py:43-56

Resource Templates

Grammars are accessible via URI templates:

Sources: src/octave_mcp/mcp/grammar_resources.py:23-32

Caching

The grammar compiler uses an in-memory cache to avoid recompilation:

if schema_name in self._cache:
    return self._cache[schema_name]

Sources: src/octave_mcp/mcp/grammar_resources.py:43-44

Public API

compile_document_grammar

Main entry point for document grammar compilation:

from octave_mcp.core.grammar_compiler import compile_document_grammar

emit_grammar_for_schema

Emit grammar for a specific schema by name:

from octave_mcp.core.grammar_compiler import emit_grammar_for_schema

Sources: src/octave_mcp/core/grammar_compiler/__init__.py:10-11

MCP Tool: octave_compile_grammar

The MCP server exposes a tool for grammar compilation:

Sources: README.md - MCP Tools section

Example Usage

Compile from META definition

from octave_mcp.core.gbnf_compiler import compile_gbnf_from_meta

meta = {
    "TYPE": "SESSION_LOG",
    "VERSION": "1.0",
    "CONTRACT": [
        "FIELD[STATUS]::REQ∧ENUM[ACTIVE,PAUSED,COMPLETE]",
        "FIELD[PRIORITY]::OPT∧ENUM[LOW,MEDIUM,HIGH]",
    ],
}
gbnf = compile_gbnf_from_meta(meta)

Sources: src/octave_mcp/core/gbnf_compiler.py:20-35

Access via MCP Resource

# Using MCP resource URI
octave://grammars/META
octave://grammars/SKILL

EBNF Grammar Reference

The base grammar definition for OCTAVE v1.0 is documented in:

• docs/grammar/octave-v1.0-grammar.ebnf

This EBNF defines the fundamental syntax that GBNF grammars must conform to, including:

• Document envelope markers (===NAME=== ... ===END===)
• Section references (§N::NAME)
• Assignment syntax (KEY::VALUE)
• List and inline map structures

Architecture Notes

ADR-0006 Design

The grammar compilation system was restructured under ADR-0006 to resolve naming conflicts:

• Original: octave_mcp.core.grammar
• Current: octave_mcp.core.grammar_compiler.gbnf

The octave_mcp.core.grammar package now serves as a unified front-door for parsing, while grammar compilation lives in the grammar_compiler submodule.

Sources: src/octave_mcp/core/grammar/__init__.py:1-30

Backward Compatibility

Legacy GBNF exports are available through lazy module loading:

_DEPRECATED_GBNF_EXPORTS: frozenset[str] = frozenset({
    "compile_document_grammar",
    "emit_grammar_for_schema",
})

Accessing deprecated symbols emits a DeprecationWarning but returns the correct objects.

Sources: src/octave_mcp/core/grammar/__init__.py:48-52

Workflow Summary

graph TD
    A[Define OCTAVE Schema] --> B[Register Schema]
    B --> C[MCP Request: compile_grammar]
    C --> D[Load Schema Definition]
    D --> E[Parse CONTRACT Fields]
    E --> F[Generate HolographicPatterns]
    F --> G[GBNFCompiler.compile_schema]
    G --> H[Return GBNF String]
    H --> I[LLM Constrained Generation]
    I --> J[Validate Output]

See Also

• OCTAVE Core Specification
• Schema Validation Framework
• Holographic Patterns

Related Pages

Related topics: CLI Interface, Python API Reference

MCP Tools Reference

The Model Context Protocol (MCP) tools in Octave-MCP provide a standardized interface for LLM agents to interact with OCTAVE documents. These tools enable validation, writing, transformation, and grammar compilation operations through the MCP protocol, serving as the primary programmatic interface for document-centric workflows.

Overview

Octave-MCP exposes four core MCP tools that wrap the underlying Python API functions. These tools are designed for documents that pass through multiple agents, tools, or compression steps—including agent/skill files, decision logs, coordination briefs, audit trails, system prompts, and reference documentation where token cost optimization matters.

Sources: README.md

Architecture

The MCP tools layer sits atop the core parsing and validation engine, providing an asynchronous interface compatible with the MCP protocol. Each tool inherits from a base class that enforces consistent error handling, logging, and result formatting.

graph TD
    A[MCP Client] --> B[Octave-MCP Server]
    B --> C[octave_validate]
    B --> D[octave_write]
    B --> E[octave_eject]
    B --> F[octave_compile_grammar]
    C --> G[Core Validator]
    D --> H[Core Parser + Emitter]
    E --> I[Projection Engine]
    F --> J[GBNF Grammar Compiler]
    G --> K[Schema Registry]
    H --> K
    I --> K
    J --> K

Sources: src/octave_mcp/mcp/base_tool.py

MCP Tool Configuration

Before using the tools, the MCP server must be configured in your client application. Octave-MCP supports two transport mechanisms.

Claude Code / Claude Desktop

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

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

Sources: README.md

HTTP Transport

For HTTP-based deployments, start the server with explicit transport configuration:

octave-mcp-server --transport http --port 8080

Tool Reference

1. `octave_validate`

Validates OCTAVE documents against schemas, returning field errors, repair suggestions, and zone coverage analysis.

#### Parameters

#### Returns

#### Validation Process

The validator performs four sequential steps:

1. Block-target extraction — Extracts block-level targets from the document AST, enabling feudal inheritance where children inherit parent block targets
2. Schema-aware META validation — Validates META section against schema definitions when a schema is provided
3. Schema-independent loss-accounting — Fires warnings regardless of schema presence
4. Duplicate-target detection — Structural safety net for GH#369 duplicate-target issues

Sources: src/octave_mcp/mcp/validate.py Sources: src/octave_mcp/core/validator.py

2. `octave_write`

Writes files through the full validation pipeline, supporting both creation and modification of OCTAVE documents.

#### Parameters

#### Format Style Options

#### Response

{
  "status": "success",
  "path": "/path/to/document.oct.md",
  "canonical_hash": "sha256:abc123...",
  "corrections": ["Fixed trailing whitespace", "Balanced brackets"],
  "diff": "--- a/doc.oct.md\n+++ b/doc.oct.md\n@@ ...",
  "validation_status": "VALIDATED"
}

#### Deprecation Note

In v1.14.0, the default format style will change from canonical re-emit to span-aware "preserve" mode. To opt in now, explicitly pass format_style="preserve". Omitting the parameter accepts the future default silently without warning.

Sources: src/octave_mcp/mcp/write.py

3. `octave_eject`

Projects OCTAVE documents to different views—canonical, executive summary, developer, or template format.

#### Parameters

#### Projection Modes

Sources: src/octave_mcp/mcp/eject.py

4. `octave_compile_grammar`

Compiles schema constraints to GBNF (Greibach Normal Form) grammar for constrained generation.

#### Parameters

#### Returns

Returns compiled GBNF grammar string suitable for use with constrained decoding libraries.

#### Grammar Access via MCP Resources

The MCP server also exposes grammar resources at octave://grammars/{schema_name}, enabling dynamic grammar access without compilation:

graph LR
    A[MCP Client] -->|octave://grammars/META| B[Grammar Resources]
    B --> C{Grammar Cache}
    C -->|cache hit| D[Return Cached]
    C -->|cache miss| E[Compile Schema]
    E --> F[Cache Result]
    F --> D

Sources: src/octave_mcp/mcp/compile_grammar.py Sources: src/octave_mcp/mcp/grammar_resources.py

Base Tool Infrastructure

All MCP tools inherit from BaseTool which provides:

• Async execution — All tools support async invocation
• Logging integration — Structured logging with tool context
• Error handling — Consistent error formatting with error codes
• Result schema — Standardized response structure

Sources: src/octave_mcp/mcp/base_tool.py

CLI Equivalents

For command-line usage, the tools are also available as CLI commands:

octave validate document.oct.md
octave write output.oct.md --stdin
octave eject document.oct.md --mode executive --format markdown

Sources: README.md

Tool Selection Guide

Error Codes

When to Use MCP Tools

Use MCP tools for:

• Documents passing through multiple agents or tools
• Agent and skill files with YAML discovery headers
• Decision logs, coordination briefs, and audit trails
• System prompts where token cost matters

Do not use for:

• Single-step prompts
• Freeform prose
• Direct code output without document structure

Sources: README.md

Related Pages

Related topics: MCP Tools Reference, Python API Reference

CLI Interface

The CLI (Command Line Interface) for octave-mcp provides a suite of standalone tools for validating, converting, and processing OCTAVE documents outside of the MCP protocol. These tools enable direct file-based workflows, batch processing, and integration with external systems that require OCTAVE content in alternative formats.

Overview

The CLI interface consists of two categories of tools:

The standalone tools are particularly valuable for build pipelines, CI/CD workflows, and scenarios where spawning an MCP server is impractical.

Architecture

graph TD
    subgraph "CLI Tools"
        A[octave CLI] --> B[octave validate]
        A --> C[octave write]
        A --> D[octave eject]
    end
    
    subgraph "Standalone Tools"
        E[lint-octave.py] --> F[Fast Syntax Check]
        G[octave-to-json.py] --> H[JSON Conversion]
        I[json-to-octave.py] --> J[OCTAVE Conversion]
        K[octave-validator.py] --> L[Repo Validation]
    end
    
    subgraph "Core Library"
        M[octave_mcp.core] --> N[Parser]
        M --> O[Validator]
        M --> P[Emitter]
    end
    
    B --> M
    C --> M
    D --> M
    E --> M
    G --> M
    I --> M
    K --> M

Installation & Configuration

Server Installation

Install the octave-mcp-server executable for MCP-based CLI access:

pip install octave-mcp

MCP Configuration

#### Claude Code (~/.claude.json)

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

#### Claude Desktop (claude_desktop_config.json)

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

#### HTTP Transport

For remote or containerized deployments:

octave-mcp-server --transport http --port 8080

Core CLI Commands

`octave validate`

Validates OCTAVE documents against the specification and optional schema.

octave validate document.oct.md

Exit Codes:

• 0 - Validation successful
• 1 - Validation failed (outputs OCTAVE_INVALID: <reason>)

`octave write`

Writes files through the full validation pipeline.

octave write output.oct.md --stdin

The --stdin flag reads content from standard input, enabling piping from other tools.

`octave eject`

Projects documents to different views for specialized audiences.

octave eject document.oct.md --mode executive --format markdown

Available Modes:

Standalone Validation Tools

`lint-octave.py`

Fast syntax validation script optimized for rapid feedback.

Usage:

python3 lint-octave.py < document.oct.md

Output:

• OCTAVE_VALID - Document passes all checks
• OCTAVE_INVALID: <reason> - Document fails with specific reason

Validation Checks:

Sources: tools/README.md

`octave-validator.py`

Repository-level validator that wraps the OCTAVE-MCP core parser/validator. This tool prevents drift between runtime validation and document validation.

Usage:

# Single file validation
python3 octave-validator.py document.oct.md

# Directory scanning
python3 octave-validator.py --path /path/to/documents

Command-Line Arguments:

Validation Profiles:

# Strict validation with required frontmatter
python3 octave-validator.py agent.oct.md --profile hestai-agent --require-frontmatter

# Schema validation
python3 octave-validator.py document.oct.md --schema SKILL

Sources: tools/octave-validator.py

Format Conversion Tools

`octave-to-json.py`

Converts OCTAVE documents to JSON for system integration.

Usage:

python3 octave-to-json.py document.oct.md > output.json

Features:

• Preserves semantic operators (synthesis, tension, progression)
• Tracks blank lines for round-trip fidelity
• Maintains quoted strings
• Handles nested structures

Sources: tools/README.md

`json-to-octave.py`

Converts JSON back to OCTAVE format, restoring original formatting.

Usage:

python3 json-to-octave.py input.json > document.oct.md

Features:

• Restores original formatting including blank lines
• Reconstructs semantic operators
• Preserves document structure

Round-Trip Conversion

The conversion tools support bidirectional transformation with fidelity preservation:

graph LR
    A[OCTAVE] -->|octave-to-json.py| B[JSON]
    B -->|json-to-octave.py| A
    B -->|round-trip| C{Same Content?}
    C -->|Yes| D[Perfect Round-Trip]
    C -->|No| E[Check for Data Loss]

Verification Example:

# Convert OCTAVE to JSON and back
python3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md

# Verify perfect round-trip
diff input.oct.md output.oct.md

MCP Tool Interface

The CLI tools mirror MCP tools available for programmatic access:

Tool Comparison

Sources: README.md

`octave_write` Parameters

The octave_write MCP tool provides comprehensive file writing capabilities:

Return Value Structure:

Sources: src/octave_mcp/mcp/write.py

Format Style Options

The format_style parameter controls output formatting:

Deprecation Notice:

Passing format_style=None explicitly is deprecated. In v1.14.0 the default will change from full canonical re-emit to span-aware preserve mode.

Sources: src/octave_mcp/mcp/write.py

Workflow Examples

CI/CD Integration

#!/bin/bash
# Validate all OCTAVE documents in a directory
for file in $(find . -name "*.oct.md"); do
    python3 octave-validator.py "$file" --profile hestai-agent --require-frontmatter
    if [ $? -ne 0 ]; then
        echo "Validation failed for $file"
        exit 1
    fi
done
echo "All documents validated successfully"

Build Pipeline

# 1. Convert source documents to JSON
python3 octave-to-json.py docs/*.oct.md > build/documents.json

# 2. Process with external tool
external-processor build/documents.json > build/processed.json

# 3. Convert back to OCTAVE
python3 json-to-octave.py build/processed.json > docs/updated/

# 4. Validate results
python3 octave-validator.py --path docs/updated/

Quick Validation Loop

# Watch file and validate on change (requires inotifywait)
while inotifywait -e close_write document.oct.md; do
    python3 lint-octave.py < document.oct.md
done

Tool Selection Guide

graph TD
    A[Need to process OCTAVE?] --> B{Environment}
    B -->|MCP Server| C[Use octave CLI commands]
    B -->|No MCP| D{Operation Type}
    D -->|Fast Check| E[lint-octave.py]
    D -->|Full Validation| F[octave-validator.py]
    D -->|Format Conversion| G{Which Direction?}
    G -->|OCTAVE to JSON| H[octave-to-json.py]
    G -->|JSON to OCTAVE| I[json-to-octave.py]
    D -->|Batch Processing| J[octave-validator.py --path]

Decision Matrix:

Error Handling

Exit Codes

Validation Error Output Format

OCTAVE_INVALID: <reason>

Common reasons include:

• Missing envelope markers (===NAME===)
• Invalid META section structure
• Syntax errors in assignments
• Schema validation failures

Verbose Mode

For debugging validation issues, enable debug grammar output:

octave write document.oct.md --debug-grammar

This includes the compiled GBNF grammar in the output, useful for identifying grammar-level failures.

Related Pages

Related topics: CLI Interface, MCP Tools Reference

Python API Reference

The Python API Reference documents the public programmatic interface of the octave_mcp library. This API enables developers to integrate OCTAVE document parsing, validation, emission, and transformation directly into Python applications without relying on CLI commands or MCP tools.

Overview

The octave_mcp package provides a complete toolkit for working with OCTAVE (Olympian Common Text And Vocabulary Engine) documents. OCTAVE is a semantic DSL designed for structured document representation in LLM workflows.

The public API exports 51 functions and classes, organized into the following categories:

*Sources: src/octave_mcp/__init__.py:12-45

Core Functions

parse()

def parse(content: str) -> Document

The primary parsing function that converts OCTAVE-formatted text into an Abstract Syntax Tree (AST).

Parameters:

Returns: Document - The parsed AST representation

Behavior:

• Returns a Document object with sections, blocks, and assignments
• Does not emit warnings; use parse_with_warnings() for detailed diagnostics
• Supports OCTAVE 6.x grammar including grammar sentinel OCTAVE::VERSION headers

*Sources: src/octave_mcp/__init__.py:27

parse_with_warnings()

def parse_with_warnings(content: str) -> tuple[Document, list[WarningEntry]]

Extended parsing that returns both the document and any warnings encountered during parsing.

Returns: tuple[Document, list[WarningEntry]] - Document and warnings list

Warning Types:

• Missing META section
• Non-protocol dialect tokens detected
• Lenient preprocessing applied for HestAI dialect

*Sources: src/octave_mcp/core/parser.py:340-350

emit()

def emit(doc: Document) -> str

Converts a Document AST back into a canonical OCTAVE-formatted string.

Parameters:

Returns: str - Canonical OCTAVE-formatted output

Note: This function is the inverse of parse(). Round-trip conversion preserves document structure including blank lines and semantic operators.

*Sources: src/octave_mcp/__init__.py:27, src/octave_mcp/core/emitter.py

tokenize()

def tokenize(content: str) -> list[Token]

Breaks OCTAVE content into a stream of tokens for lexical analysis.

Parameters:

Returns: list[Token] - Ordered list of tokens with type and value

Token Types:

• ENVELOPE_START / ENVELOPE_END
• SECTION_KEY
• ASSIGNMENT
• LIST_START / LIST_END
• GRAMMAR_SENTINEL
• IDENTIFIER
• STRING

*Sources: src/octave_mcp/__init__.py:27

repair()

def repair(content: str) -> tuple[str, RepairLog]

Attempts to automatically fix malformed OCTAVE content.

Parameters:

Returns: tuple[str, RepairLog] - Repaired content and log of changes

Repair Strategies:

• Localized salvaging preserves document structure where possible
• Wraps plain text into BODY: RAW carrier for non-parseable content
• Marks failing lines with _PARSE_ERROR_LINE_N markers

*Sources: src/octave_mcp/__init__.py:27, src/octave_mcp/core/repair.py

project()

def project(doc: Document, mode: str) -> ProjectionResult

Transforms a document into different output views.

Parameters:

Returns: ProjectionResult - Transformed document with routing log

*Sources: src/octave_mcp/__init__.py:27

hydrate()

def hydrate(doc: Document, policy: HydrationPolicy) -> Document

Applies a hydration policy to a document for variable substitution and template expansion.

Parameters:

Returns: Document - Hydrated document with substitutions applied

*Sources: src/octave_mcp/__init__.py:27

extract_schema_from_document()

def extract_schema_from_document(doc: Document) -> SchemaDefinition

Infers the schema definition from an existing document's structure.

Parameters:

Returns: SchemaDefinition - Inferred schema with field definitions

*Sources: src/octave_mcp/__init__.py:27

seal_document() / verify_seal()

def seal_document(doc: Document) -> Document
def verify_seal(doc: Document) -> SealVerificationResult

Integrity management functions for document sealing.

*Sources: src/octave_mcp/__init__.py:27

Core Classes

Parser

The Parser class provides detailed control over the parsing process.

class Parser:
    def __init__(self, content: str)
    def parse(self) -> Document
    def parse_document(self) -> Document
    def current() -> Token
    def advance() -> Token

Key Methods:

Grammar Sentinel Support:

• Recognizes OCTAVE::VERSION pattern
• Populates doc.grammar_version from lexer

*Sources: src/octave_mcp/core/parser.py:150-180

Document

The AST representation of an OCTAVE document.

@dataclass
class Document:
    name: str
    grammar_version: str | None
    start_byte: int
    end_byte: int
    meta_start_byte: int | None
    meta_end_byte: int | None
    sections: list[Block]

Attributes:

*Sources: src/octave_mcp/core/parser.py:150-160

Block

Represents a structural block within a document.

@dataclass
class Block:
    key: str
    children: list[Section | Assignment]

Assignment

Represents a key-value assignment.

@dataclass
class Assignment:
    key: str
    value: str | ListValue | InlineMap

HydrationPolicy

Configuration for document hydration.

@dataclass
class HydrationPolicy:
    registry: VocabularyRegistry
    strict: bool
    mode: str  # "substitute", "expand", "validate"

SchemaDefinition

Schema definition for validation.

@dataclass
class SchemaDefinition:
    name: str
    fields: list[FieldDefinition]

*Sources: src/octave_mcp/__init__.py:30-45

Exception Classes

*Sources: src/octave_mcp/__init__.py:43-45

Repair System

RepairLog

@dataclass
class RepairLog:
    entries: list[RepairEntry]
    corrections: list[dict[str, Any]]

RepairTier

RepairEntry

@dataclass
class RepairEntry:
    code: str
    tier: RepairTier
    message: str
    safe: bool
    semantics_changed: bool

Common Repair Codes:

*Sources: src/octave_mcp/core/repair.py

Schema Loading

load_schema_by_name()

def load_schema_by_name(schema_name: str) -> SchemaDefinition | None

Loads a schema definition by name from the builtin registry or search paths.

Parameters:

Returns: SchemaDefinition or None if not found

Builtin Schemas:

• META - Document metadata schema
• SKILL - Skill definition schema
• SESSION_LOG - Session logging schema

*Sources: src/octave_mcp/schemas/loader.py

Usage Examples

Basic Parsing

from octave_mcp import parse, emit

# Parse OCTAVE content
content = '''===MY_DOC===
META:
  TYPE::SKILL
  VERSION::"1.0.0"
§1::CONTENT
KEY::VALUE
===END===
'''

doc = parse(content)
print(f"Document name: {doc.name}")
print(f"Grammar version: {doc.grammar_version}")

Round-Trip Conversion

from octave_mcp import parse, emit

content = '''===EXAMPLE===
META:
  TYPE::TEST
§1::SECTION
FIELD::VALUE
===END===
'''

doc = parse(content)
output = emit(doc)
# output is canonical OCTAVE

Validation with Repair

from octave_mcp import repair, parse

malformed = '''===DOC===
META:
  TYPE::TEST
INVALID§SYNTAX
===END===
'''

repaired, log = repair(malformed)
print(f"Repaired content: {repaired}")
print(f"Corrections made: {len(log.corrections)}")

Schema Validation

from octave_mcp import parse, Validator
from octave_mcp.schemas import load_schema_by_name

doc = parse(octave_content)
schema = load_schema_by_name("META")
validator = Validator(schema)
result = validator.validate(doc)

*Sources: docs/api.md

Architecture Diagram

graph TD
    A[OCTAVE String Input] --> B[Parser]
    B --> C[Document AST]
    C --> D[Validator]
    C --> E[Emitter]
    C --> F[Repair]
    F --> G{Parse Success?}
    G -->|No| H[Localized Salvage]
    G -->|Yes| C
    H --> I[Repaired Content]
    I --> B
    D --> J[ValidationResult]
    E --> K[Canonical OCTAVE Output]
    F --> L[RepairLog]
    C --> M[Projector]
    M --> N[ProjectionResult]
    C --> O[Hydrator]
    O --> P[HydratedDocument]
    
    style A fill:#e1f5fe
    style K fill:#c8e6c9
    style J fill:#fff3e0
    style L fill:#fce4ec

CLI vs Python API

Advanced: Grammar Compilation

from octave_mcp.core.grammar_compiler import compile_document_grammar

grammar = compile_document_grammar("META")
# Returns GBNF grammar string for schema

The grammar compiler supports:

• Schema-based grammar generation
• Cached compilation for performance
• Include/exclude envelope markers

*Sources: src/octave_mcp/core/grammar_compiler/__init__.py

Best Practices

1. Use parse_with_warnings() during development to catch non-protocol dialect tokens
2. Call repair() before parse() when processing untrusted input
3. Cache schema definitions if loading repeatedly
4. Use emit() for round-trip verification in tests
5. Leverage HydrationPolicy for template-based workflows

See Also

• Usage Guide - CLI and integration examples
• Specs - OCTAVE specification documents
• Primers - Quick-start primers for specific use cases

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Security or permission risk: Developers should check this security_permissions risk before relying on the project: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md
• User impact: Developers may expose sensitive permissions or credentials: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | fmev_22c0329bf698546f57cbd9edd620083f | https://github.com/elevanaltd/octave-mcp/issues/424 | octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md

2. Security or permission risk: Developers should check this security_permissions risk before relying on the project: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)
• User impact: Developers may expose sensitive permissions or credentials: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38). Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | fmev_e63e5f9a96f8ad23bef9d32f6c4c13e7 | https://github.com/elevanaltd/octave-mcp/issues/420 | octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)

3. Security or permission risk: bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)

• Severity: high
• Finding: Security or permission risk is backed by a source signal: bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes). Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/elevanaltd/octave-mcp/issues/411

4. Security or permission risk: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks

• Severity: high
• Finding: Security or permission risk is backed by a source signal: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/elevanaltd/octave-mcp/issues/426

5. Installation risk: Developers should check this installation risk before relying on the project: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks
• User impact: Developers may fail before the first successful local run: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | fmev_8ff9088f7d6c1752dffdf17a7dd320db | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks

6. Installation risk: Developers should check this installation risk before relying on the project: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents
• User impact: Developers may fail before the first successful local run: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | fmev_9d395f7455d912516430481376e952e2 | https://github.com/elevanaltd/octave-mcp/issues/425 | octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type documents

7. Installation risk: bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)

• Severity: medium
• Finding: Installation risk is backed by a source signal: bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431). Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/elevanaltd/octave-mcp/issues/432

8. Configuration risk: Developers should check this configuration risk before relying on the project: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)
• User impact: Developers may misconfigure credentials, environment, or host setup: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty). Context: Observed when using python
• Evidence: failure_mode_cluster:github_issue | fmev_c368f015439226dbb8b9c45fddf3158d | https://github.com/elevanaltd/octave-mcp/issues/430 | RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describing operator sovereignty)

9. Configuration risk: Developers should check this configuration risk before relying on the project: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)
• User impact: Developers may misconfigure credentials, environment, or host setup: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: bug: emitter normalises backslash counts in string literals (round-trip byte-loss). Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | fmev_bbc57f3d1a93f9e5fb48332874044f35 | https://github.com/elevanaltd/octave-mcp/issues/434 | bug: emitter normalises backslash counts in string literals (round-trip byte-loss)

10. Configuration risk: Developers should check this configuration risk before relying on the project: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)
• User impact: Developers may misconfigure credentials, environment, or host setup: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue). Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | fmev_cf23dec47765d23b75fcd69bef5c1332 | https://github.com/elevanaltd/octave-mcp/issues/433 | bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only patterns parse as ListValue)

11. Configuration risk: Developers should check this configuration risk before relying on the project: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...
• User impact: Developers may misconfigure credentials, environment, or host setup: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O.... Context: Observed when using python
• Evidence: failure_mode_cluster:github_issue | fmev_6420a6baab4269626b43aeca56c0d6c8 | https://github.com/elevanaltd/octave-mcp/issues/443 | bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-overwrite of nested BLOCK produces duplicate key (invalid O...

12. Configuration risk: Developers should check this configuration risk before relying on the project: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate
• User impact: Developers may misconfigure credentials, environment, or host setup: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | fmev_67bfde22b66b3bde199f59556c21e82d | https://github.com/elevanaltd/octave-mcp/issues/441 | governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using octave-mcp with real data or production workflows.

• DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports - github / github_issue
• bug: octave_write surgical edit primitives unsafe on inline-array top-le - github / github_issue
• bug: octave_write changes_mode adds nested block instead of mutating exi - github / github_issue
• octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negative - github / github_issue
• octave_validate: SKILL schema only validates frontmatter; §-section body - github / github_issue
• enhancement: validator section-bucket merging may mask path-isolated req - github / github_issue
• octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed - github / github_issue
• bug: octave_write changes-mode bare-dict on top-level KEY silently acts - github / github_issue
• governance: amend pre-merge CI gate to use octave_write --dry-run, not j - github / github_issue
• bug/governance: octave_validate vs octave_write asymmetric handling of E - github / github_issue
• Developers should check this security_permissions risk before relying on the project: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md - GitHub / issue
• Developers should check this security_permissions risk before relying on the project: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38) - GitHub / issue