# OCTAVE MCP Server

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-2258%20passing-brightgreen.svg)]()
[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)]()

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

## Table of Contents

- [For AI Agents](#for-ai-agents)
- [What It Does](#what-it-does)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [MCP Tools](#mcp-tools)
- [When OCTAVE Helps](#when-octave-helps)
- [Documentation](#documentation)
- [Contributing](#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
===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):

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

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

---

## What It Does

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

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

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

> **Implementation Status (v0.6.0):** Grammar compilation is implemented and available via `debug_grammar=True`. However, the MCP tools (`octave_validate`, `octave_write`) currently perform post-hoc validation rather than enforcing grammar constraints during generation. See the [architecture spec](src/octave_mcp/resources/specs/octave-mcp-architecture.oct.md) for details.

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

### Language, operators, and readability

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

### Mythological compression

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

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

See [The Mythological Compression Principle](docs/guides/mythological-compression.md) for evidence and guidance. See [research evidence](docs/research/mythology-evidence-synthesis.oct.md) for the full empirical basis.

See the [protocol specs in `src/octave_mcp/resources/specs/`](src/octave_mcp/resources/specs/) for v6.0.0 rules.

## What this server provides

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

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

## When OCTAVE Helps

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

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

## Installation

**PyPI:**
```bash
pip install octave-mcp
# or
uv pip install octave-mcp
```

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

## Quick Start

### CLI

```bash
# 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`):

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

## MCP Tools

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

See [API Reference](docs/api.md) for full parameter documentation.

### Generative Holographic Contracts (v6)

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

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

## Documentation

| Doc | Content |
|-----|---------|
| [Usage Guide](docs/usage.md) | CLI, MCP, and API examples |
| [API Reference](docs/api.md) | Python API documentation |
| [MCP Configuration](docs/mcp-configuration.md) | Client setup and integration |
| [Protocol Specs](src/octave_mcp/resources/specs/) | v6.0.0 Generative Holographic Specs |
| [EBNF Grammar](docs/grammar/octave-v1.0-grammar.ebnf) | Formal v1.0.0 grammar specification |
| [Development Setup](docs/guides/development-setup.md) | Dev environment, testing, quality gates |
| [Architecture Decisions](docs/adr/) | Architecture Decision Records (ADRs) |
| [Research](docs/research/) | Benchmarks and validation studies |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and guidelines.

```bash
# 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](https://github.com/modelcontextprotocol/python-sdk).
