# https://github.com/elevanaltd/octave-mcp 项目说明书

生成时间：2026-05-16 03:50:43 UTC

## 目录

- [Project Introduction](#page-project-introduction)
- [Project File Structure](#page-file-structure)
- [System Architecture](#page-system-architecture)
- [Canonical Normalization](#page-canonical-normalization)
- [Schema Validation](#page-schema-validation)
- [Compression System](#page-compression-system)
- [Grammar Compilation](#page-grammar-compilation)
- [MCP Tools Reference](#page-mcp-tools)
- [CLI Interface](#page-cli-interface)
- [Python API Reference](#page-python-api)

<a id='page-project-introduction'></a>

## Project Introduction

### 相关页面

相关主题：[System Architecture](#page-system-architecture), [Canonical Normalization](#page-canonical-normalization)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)
- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)
- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)
- [src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)
- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)
</details>

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

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/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.

资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-mastery-primer.oct.md)

### Key Features

| Feature | Description |
|---------|-------------|
| **Semantic DSL** | Domain-specific language with typed syntax for structured documents |
| **MCP Integration** | Model Context Protocol server for tool-based access |
| **CLI Tools** | Command-line utilities for validation and transformation |
| **Grammar Compilation** | GBNF grammar generation for constrained text generation |
| **Validation Pipeline** | Multi-stage validation with repair suggestions |
| **Holographic Patterns** | Constraint-based field validation with logical operators |

## Architecture

### System Components

```mermaid
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:

| Module | Purpose |
|--------|---------|
| `core/parser.py` | Parses OCTAVE documents into AST |
| `core/validator.py` | Validates documents against schemas |
| `core/grammar_compiler/` | Compiles schemas to GBNF grammar |
| `core/holographic.py` | Handles holographic constraint patterns |
| `mcp/write.py` | MCP tool implementation for writing files |

资料来源：[src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)

## OCTAVE Syntax

### Document Structure

An OCTAVE document follows a specific envelope format:

```octave
===DOCUMENT_NAME===
META:
  TYPE::"DOCUMENT_TYPE"
  VERSION::"1.0.0"
  PURPOSE::"Document purpose description"
---
// Section content
FIELD::"value"
FIELD::[list_value]
===END===
```

### Core Operators

| Operator | Meaning | Example |
|----------|---------|---------|
| `::` | Assignment/definition | `KEY::VALUE` |
| `→` | Flow/sequence | `AUTH::login→validate→dashboard` |
| `⊕` | Synthesis/combine | `A⊕B` |
| `⇌` | Tension/opposition | `security⇌usability` |
| `[]` | List definition | `FIELD::["item1","item2"]` |
| `∧` | Logical AND constraint | `["value"∧ENUM[A,B]]` |
| `§` | Section reference | `§TARGET` |

资料来源：[src/octave_mcp/resources/primers/octave-compression-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-compression-primer.oct.md)

### Holographic Constraints

Holographic patterns provide powerful constraint validation:

```octave
FIELD::["value"∧REQ∧ENUM[OPTION_A,OPTION_B]]
```

This pattern specifies that `FIELD` is required (`REQ`) and must be one of the enumerated options.

资料来源：[src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)

## MCP Tools

Octave-MCP provides Model Context Protocol tools for integration with AI assistants:

| Tool | Function |
|------|----------|
| `octave_validate` | Validate documents against schema; provides field errors and repair suggestions |
| `octave_write` | Write files through full validation pipeline |
| `octave_eject` | Project documents to different views (canonical, executive, developer, template) |
| `octave_compile_grammar` | Compile schema constraints to GBNF grammar |

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)

### MCP Configuration

**Claude Desktop Configuration:**

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

**HTTP Transport:**

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

## CLI Tools

### Installation

```bash
# Install the package
pip install octave-mcp

# Verify installation
octave --version
```

### Available Commands

| Command | Description |
|---------|-------------|
| `octave validate <file>` | Validate an OCTAVE document |
| `octave write <output>` | Write output through validation pipeline |
| `octave eject <file>` | Export document in alternate format |

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)

### Standalone Validation Tools

Located in the `tools/` directory:

| Tool | Purpose |
|------|---------|
| `lint-octave.py` | Fast syntax validation |
| `octave-to-json.py` | Convert OCTAVE to JSON |
| `json-to-octave.py` | Convert JSON back to OCTAVE |
| `octave-validator.py` | Full document validation |

资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)

## Validation System

### Validation Process

```mermaid
graph LR
    A[Document Input] --> B[Lexer]
    B --> C[Parser]
    C --> D[AST]
    D --> E[Schema Validator]
    E --> F{Valid?}
    F -->|Yes| G[Validation Passed]
    F -->|No| H[Error Report]
    H --> I[Repair Suggestions]
```

### Validator Features

The validation system provides:

- **Field-level error reporting** with line numbers
- **Repair suggestions** for common issues
- **Zone coverage analysis** for document completeness
- **Semantic validation** against holographic constraints

资料来源：[src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)

### Audit Patterns

The validator recognizes specific audit-related field prefixes:

| Pattern Prefix | Purpose |
|----------------|---------|
| `NON_CANONICAL_` | Non-canonical normalization fields |
| `DEGRADED_` | Degraded state indicators |
| `NORMALIZED_` | Normalization metadata |
| `ROUNDTRIP_` | Roundtrip conversion fields |

These patterns allow controlled admission of non-standard fields during validation.

资料来源：[src/octave_mcp/core/validator.py:line-range](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)

## Grammar Compilation

### GBNF Generation

The grammar compiler transforms OCTAVE schemas into GBNF (Greibach Normal Form) grammar for constrained text generation:

```python
from octave_mcp.core.grammar_compiler import compile_document_grammar

schema = SchemaDefinition(name="DOCUMENT_TYPE", version="1.0")
gbnf = compile_document_grammar(schema)
```

This enables LLMs to generate valid OCTAVE documents through constrained decoding.

资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)

### CONTRACT Extraction

The grammar compiler can extract field specifications from META `CONTRACT` definitions:

```octave
META:
  CONTRACT::[
    "FIELD[NAME]::REQ∧ENUM[A,B]",
    "FIELD[STATUS]::OPT"
  ]
```

Each contract entry is parsed into structured field definitions with holographic constraints.

资料来源：[src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)

## Use Cases

### When to Use Octave-MCP

| Scenario | Recommended |
|----------|-------------|
| Multi-agent document workflows | ✅ Yes |
| Agent and skill file definitions | ✅ Yes |
| Decision logs and audit trails | ✅ Yes |
| System prompts with token optimization | ✅ Yes |
| Single-step freeform prompts | ❌ No |
| Code output generation | ❌ No |

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)

### Document Types

Octave-MCP supports structured document types including:

- **SESSION_LOG** - Conversation session records
- **DECISION** - Decision documentation
- **AGENT** - Agent definitions
- **SKILL** - Skill specifications
- **PATTERN** - Pattern definitions

## Integration Examples

### With Claude Code

```bash
# Generate enhanced context
repomix --style xml --output context.xml
python octave_enhance_targeted.py context.xml enhanced.xml

# Paste enhanced.xml content into Claude Code session
```

### With Repomix Enhancement

The `examples/integrations/repomix/` directory provides scripts for:

- **Targeted enhancement** - Focus on key files
- **Comprehensive enhancement** - Full codebase analysis

Enhanced contexts add semantic annotations like:

```octave
===FILE_PROCESSOR===
META:
  PURPOSE::"Process files"
  PATTERN::PIPELINE
===END===
```

资料来源：[examples/integrations/repomix/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/examples/integrations/repomix/README.md)

## Additional Resources

| Resource | Location |
|----------|----------|
| Usage Guide | [docs/usage.md](docs/usage.md) |
| API Reference | [docs/api.md](docs/api.md) |
| MCP Configuration | [docs/mcp-config.md](docs/mcp-config.md) |
| Primers | [src/octave_mcp/resources/primers/](src/octave_mcp/resources/primers/) |
| Skills | [src/octave_mcp/resources/skills/](src/octave_mcp/resources/skills/) |

---

<a id='page-file-structure'></a>

## Project File Structure

### 相关页面

相关主题：[Project Introduction](#page-project-introduction), [System Architecture](#page-system-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)
- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)
- [tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)
- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)
- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)
- [standards/L3-AGENT-FORMAT.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/standards/L3-AGENT-FORMAT.oct.md)
</details>

# 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

```mermaid
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

| File/Directory | Purpose |
|----------------|---------|
| `README.md` | Main project documentation, MCP server setup, and usage guide |
| `CONTRIBUTING.md` | Guidelines for contributors |
| `pyproject.toml` | Python package configuration |
| `src/octave_mcp/` | Main package source code |
| `tools/` | Standalone CLI utilities for OCTAVE validation |
| `examples/` | Integration examples and compression tier demonstrations |
| `standards/` | OCTAVE format standards and schemas |
| `docs/` | Additional documentation files |

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

| Submodule | Purpose |
|-----------|---------|
| `parser/` | Lexer and parser implementations |
| `validator/` | Schema validation engine |
| `grammar_compiler/` | GBNF grammar compilation for constrained generation |

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:

```python
from octave_mcp.core.grammar_compiler import compile_document_grammar, emit_grammar_for_schema
```

资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-18]()

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

Implements the Model Context Protocol server and tools.

| File | Purpose |
|------|---------|
| `write.py` | MCP tool for writing OCTAVE files with full validation pipeline |
| `grammar_resources.py` | Dynamic grammar resource templates for MCP |

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}`

资料来源：[src/octave_mcp/mcp/grammar_resources.py:1-80]()

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

Contains distributable OCTAVE resources used by implementers and agents.

```mermaid
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:

| Primer | Version | Purpose |
|--------|---------|---------|
| `octave-literacy-primer.oct.md` | 6.0.0 | Basic OCTAVE literacy |
| `octave-compression-primer.oct.md` | 6.0.0 | Prose-to-OCTAVE transformation |
| `octave-mastery-primer.oct.md` | 6.1.0 | Advanced pattern mastery |
| `octave-ultra-mythic-primer.oct.md` | 6.2.0 | Ultra-compression techniques |

#### Specs (`specs/`)

Official OCTAVE v6.0.0 specifications:

| Specification | Description |
|---------------|-------------|
| `octave-core-spec.oct.md` | Core syntax, operators, and type system |
| `octave-agents-spec.oct.md` | Agent architecture patterns |
| `octave-skills-spec.oct.md` | Skill document format |
| `octave-data-spec.oct.md` | Data compression tiers |
| `octave-execution-spec.oct.md` | Execution flow and protocols |
| `octave-schema-spec.oct.md` | Schema validation framework |
| `octave-rationale-spec.oct.md` | Design rationale |
| `octave-primers-spec.oct.md` | Primer specification |
| `octave-mcp-architecture.oct.md` | MCP implementation architecture |

#### Schemas (`specs/schemas/`)

Schema definitions including:

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

#### Vocabularies (`specs/vocabularies/`)

OCTAVE vocabulary definitions:

| Path | Content |
|------|---------|
| `registry.oct.md` | Vocabulary registry index |
| `core/META.oct.md` | META vocabulary specification |
| `core/SNAPSHOT.oct.md` | SNAPSHOT vocabulary specification |

#### Skills (`skills/`)

Workflow definitions for OCTAVE operations:

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

资料来源：[src/octave_mcp/resources/README.md:1-80]()

### Package Exports

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

| Category | Key Exports |
|----------|-------------|
| Functions | `parse`, `parse_with_warnings`, `emit`, `tokenize`, `repair`, `project`, `hydrate` |
| Classes | `Parser`, `Validator`, `TokenType`, `Token`, `HydrationPolicy`, `VocabularyRegistry` |
| AST Nodes | `Document`, `Block`, `Assignment`, `Section`, `ListValue`, `InlineMap`, `Absent` |
| Schema | `SchemaDefinition`, `FieldDefinition`, `extract_schema_from_document` |
| Repair | `RepairLog`, `RepairEntry`, `RepairTier`, `RoutingLog` |
| Exceptions | `VocabularyError`, `CollisionError`, `VersionMismatchError`, `ParserError`, `LexerError` |

资料来源：[src/octave_mcp/__init__.py:1-50]()

## Tools Directory (`tools/`)

Standalone utilities for OCTAVE validation and conversion.

| Tool | Purpose |
|------|---------|
| `lint-octave.py` | Fast syntax validation for OCTAVE documents |
| `octave-to-json.py` | Convert OCTAVE to JSON for system integration |
| `json-to-octave.py` | Convert JSON back to OCTAVE format |
| `octave-validator.py` | Repo validator wrapping the MCP core parser |

### 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:**
```bash
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:**
```bash
octave validate document.oct.md
octave-validator.py --path /directory --profile hestai-agent
```

资料来源：[tools/README.md:1-50]()

## Examples Directory (`examples/`)

Demonstrates OCTAVE compression across different scales.

### Integrations (`examples/integrations/`)

Integration examples including:

| File | Purpose |
|------|---------|
| `repomix/octave_enhance_targeted.py` | Targeted OCTAVE annotation for specific files |
| `repomix/octave_enhance_comprehensive.py` | Comprehensive codebase semantic coverage |

### Compression Tier Examples

Demonstrates OCTAVE 5.1.0 compression on research documents:

| Tier | Fidelity | Tokens | Use Case |
|------|----------|--------|----------|
| LOSSLESS | 100% | ~14,900 | Critical decisions, legal/safety analysis |
| CONSERVATIVE | 85-90% | ~4,800 | Research summaries, design decisions |
| AGGRESSIVE | 70% | ~1,800 | Quick overviews |
| ULTRA | ~60% | ~900 | High token efficiency |

资料来源：[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:

```mermaid
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

资料来源：[standards/L3-AGENT-FORMAT.oct.md:1-50]()

## Documentation Structure (`docs/`)

| Document | Content |
|----------|---------|
| `usage.md` | CLI, MCP, and API usage examples |
| `api.md` | Python API reference |
| Configuration | MCP server setup for Claude Code and Claude Desktop |

### MCP Server Setup

**Claude Code Configuration** (`~/.claude.json`):
```json
{
  "mcpServers": {
    "octave": {
      "command": "octave-mcp-server"
    }
  }
}
```

**HTTP Transport:**
```bash
octave-mcp-server --transport http --port 8080
```

资料来源：[README.md:1-60]()

## MCP Tools Reference

| Tool | Function |
|------|----------|
| `octave_validate` | Validate against schema, field errors, repair suggestions |
| `octave_write` | Write files through full validation pipeline |
| `octave_eject` | Project to different views (canonical, executive, developer, template) |
| `octave_compile_grammar` | Compile schema constraints to GBNF grammar |

### CLI Commands

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

```python
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

---

<a id='page-system-architecture'></a>

## System Architecture

### 相关页面

相关主题：[MCP Tools Reference](#page-mcp-tools), [CLI Interface](#page-cli-interface)

<details>
<summary>Relevant Source Files</summary>

以下源码文件用于生成本页说明：

- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)
- [src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/__init__.py)
- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)
- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)
- [src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)
</details>

# 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

```mermaid
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:**

| Method | Configuration Location | Example |
|--------|----------------------|---------|
| Claude Desktop | `~/.claude.json` | `mcpServers.octave.command` |
| Claude Code | `.claude.json` | Same structure |
| HTTP | CLI flags | `--transport http --port 8080` |

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/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

```mermaid
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:**

| Feature | Description | Implementation |
|---------|-------------|----------------|
| Envelope Detection | Required document markers | `ENVELOPE_START` token type |
| META Region | Structured metadata section | `meta_start_byte` / `meta_end_byte` tracking |
| Grammar Sentinel | Version identification | `GRAMMAR_SENTINEL` token |
| Inferred Envelope | Single-document support | Default name: "INFERRED" |

资料来源：[src/octave_mcp/core/parser.py:50-80](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)

### 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:**

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

**Compilation Features:**

| Function | Purpose |
|----------|---------|
| `compile_document_grammar` | Main entry point for grammar generation |
| `emit_grammar_for_schema` | Schema-specific grammar emission |

资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/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}
```

资料来源：[src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)

## MCP Tools

### Validate Tool

Performs schema-based validation with detailed error reporting:

| Parameter | Type | Description |
|-----------|------|-------------|
| document | string | OCTAVE content to validate |
| schema | string | Schema name for validation |
| profile | string | Validation profile (protocol, hestai-agent, etc.) |

### Write Tool

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

| Parameter | Type | Description |
|-----------|------|-------------|
| target_path | string | File path to write |
| content | string | Full content for new files |
| changes | dict | Field updates for existing files |
| schema | string | Optional schema name |
| format_style | string | Output mode: preserve, expanded, compact |

**Format Style Modes:**

| Mode | Behavior | Deprecation Note |
|------|----------|-------------------|
| `preserve` | Span-aware preserve mode | Recommended for future |
| `expanded` | Full canonical re-emit | Explicit opt-in for legacy behavior |
| `compact` | Minimal output | Default in v1.14.0+ |

资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/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

```mermaid
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

| Category | Purpose | Version |
|----------|---------|---------|
| Core Spec | Syntax, operators, type system | v6.0.0 |
| Agents Spec | Agent architecture patterns | v6.0.0 |
| Skills Spec | Skill document format | v6.0.0 |
| Data Spec | Compression tiers and patterns | v6.0.0 |
| Schema Spec | Validation framework | v6.0.0 |

资料来源：[src/octave_mcp/resources/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/README.md)

## Validation Profiles

The system supports multiple validation profiles for different use cases:

| Profile | YAML Frontmatter | Default Behavior |
|---------|------------------|------------------|
| `protocol` | Optional | Warning on missing |
| `hestai-agent` | Required | Hard fail if missing |
| `hestai-skill` | Required | Hard fail if missing |
| `hestai-pattern` | Optional | Warning on missing |

**Profile Configuration:**
```bash
octave validate document.oct.md --profile hestai-agent --require-frontmatter
```

资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)

## Document Flow

```mermaid
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

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

| Tool | Function |
|------|----------|
| `octave_validate` | Validate against schema with repair suggestions |
| `octave_write` | Write files through full validation pipeline |
| `octave_eject` | Project to different views |
| `octave_compile_grammar` | Compile schema to GBNF |

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/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

---

<a id='page-canonical-normalization'></a>

## Canonical Normalization

### 相关页面

相关主题：[Schema Validation](#page-schema-validation), [Compression System](#page-compression-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/octave_mcp/core/lexer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/lexer.py)
- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)
- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)
- [src/octave_mcp/core/grammar/tier_normalize.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar/tier_normalize.py)
- [src/octave_mcp/core/grammar/cst.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar/cst.py)
</details>

# 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

```mermaid
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. 资料来源：[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:

| Feature | Description |
|---------|-------------|
| `start_byte` / `end_byte` | Byte offsets for document and META region (ADR-0006 SR2-T2) |
| Grammar Sentinel | Parses `OCTAVE::VERSION` pattern |
| Envelope Detection | Handles explicit `===NAME===` and inferred envelopes |

资料来源：[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:

| Tier | Target Fidelity | Preserved | Dropped |
|------|------------------|-----------|---------|
| LOSSLESS | 100% | Everything | Nothing |
| CONSERVATIVE | 85-90% | Explanatory depth | Redundancy |
| AGGRESSIVE | 70% | Core thesis | Edge cases |
| ULTRA | Minimal | Key semantics | Most detail |

资料来源：[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:

```mermaid
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
```

资料来源：[src/octave_mcp/core/grammar/cst.py]()()

### Phase 5: Emission

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

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

资料来源：[src/octave_mcp/core/emitter.py]()()

## Behavior Timeline

Per ADR-0006, normalization behavior evolves across milestones:

```mermaid
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

| Phase | Behavior | `warnings: []` Meaning |
|-------|----------|------------------------|
| **TODAY** | `octave_write` normalizes on every write | Source was already canonical |
| **AFTER_SR1_T4** | Default becomes NO-OP normalization | No normalization attempted (not a canonicality guarantee) |
| **AFTER_SR3_T2** | Canonicalization moves to `octave_fmt` tool | Separate persist vs canonicalize calls |

资料来源：[src/octave_mcp/resources/skills/octave-literacy/SKILL.md:§6a::TIMELINE]()(ADR-0006)

## Normalization Rules

### Syntax Normalization

| Rule | Before | After |
|------|--------|-------|
| Indentation | Mixed (1, 3, 4 spaces) | 2-space multiples |
| Assignment spacing | `KEY:: VALUE` | `KEY::VALUE` |
| List formatting | Trailing commas allowed | Trailing commas forbidden |
| Bracket balance | All brackets must balance | Enforced at parse time |

### 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:

| Field | Required | Validation |
|-------|----------|------------|
| TYPE | Yes | Must be valid document type |
| VERSION | Yes | Semantic version format |

## MCP Tool Integration

The normalization system integrates with MCP tools:

| Tool | Mode | Behavior |
|------|------|----------|
| `octave_write` | normalize | Dry-run, returns warnings |
| `octave_write` | persist | Apply normalization, return warnings |
| `octave_validate` | — | Validate against schema, provide repair suggestions |
| `octave_eject` | — | Project to different views (canonical, executive, developer) |

资料来源：[README.md:MCP Tools]()()

## CLI Usage

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

```mermaid
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:

```bash
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

资料来源：[tools/README.md:Round-Trip Example]()()

## Error Handling

Normalization produces structured warnings:

```json
{
  "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](docs/adr/ADR-0006-writer-reader-symmetry.md)
- [OCTAVE Data Specification](src/octave_mcp/resources/specs/octave-data-spec.oct.md)
- [Usage Guide](docs/usage.md)
- [API Reference](docs/api.md)

---

<a id='page-schema-validation'></a>

## Schema Validation

### 相关页面

相关主题：[Canonical Normalization](#page-canonical-normalization), [MCP Tools Reference](#page-mcp-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/validator.py)
- [src/octave_mcp/core/schema_extractor.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/schema_extractor.py)
- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)
- [src/octave_mcp/resources/primers/octave-mastery-primer.oct.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/primers/octave-mastery-primer.oct.md)
- [src/octave_mcp/mcp/validate.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/validate.py)
- [src/octave_mcp/resources/skills/octave-compression/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-compression/SKILL.md)
</details>

# 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

资料来源：[src/octave_mcp/core/validator.py:1-30]()

## Architecture

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

```mermaid
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

| Component | Location | Purpose |
|-----------|----------|---------|
| `Validator` | `core/validator.py` | Main validation surface - structural visitor pattern |
| `SchemaDefinition` | `core/schema.py` | Schema data model |
| `FieldDefinition` | `core/schema.py` | Field constraint definitions |
| `SchemaExtractor` | `core/schema_extractor.py` | Extract schemas from OCTAVE documents |
| `SchemaLoader` | `schemas/loader.py` | Load built-in and custom schemas |

资料来源：[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:

```python
from octave_mcp import Validator

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

### Validation Flow

```mermaid
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

资料来源：[src/octave_mcp/core/validator.py:100-150]()

## Schema Definition

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

### Schema Structure

| Section | Purpose |
|---------|---------|
| `POLICY` | Version, UNKNOWN_FIELDS handling, default targets |
| `FIELDS` | Field definitions with constraints |
| `FRONTMATTER` | YAML frontmatter field definitions |

### Policy Settings

The `POLICY` block controls validation behavior:

```octave
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

资料来源：[src/octave_mcp/core/schema_extractor.py:50-80]()

## Schema Extraction

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

```python
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

```mermaid
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]
```

资料来源：[src/octave_mcp/core/schema_extractor.py:80-150]()

## Validation Profiles

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

| Profile | YAML Frontmatter | META.TYPE Requirement |
|---------|------------------|----------------------|
| `protocol` | Forbidden | Any |
| `hestai-agent` | Recommended (warning) | `AGENT_DEFINITION` |
| `hestai-skill` | Recommended (warning) | `SKILL` |
| `hestai-pattern` | Forbidden | `PATTERN` |

### CLI Usage

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

资料来源：[tools/octave-validator.py:1-50]()

## MCP Tool Integration

The `octave_validate` MCP tool provides programmatic validation access:

### Tool Interface

| Parameter | Type | Description |
|-----------|------|-------------|
| `content` | string | OCTAVE document content |
| `schema` | string | Schema name to validate against (optional) |
| `strict` | boolean | Enable strict validation mode |

### Return Structure

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

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

资料来源：[src/octave_mcp/mcp/validate.py:1-50]()

## Error Codes

| Code | Description |
|------|-------------|
| `E_REQUIRED_FIELD` | Mandatory field is missing |
| `E_TYPE_MISMATCH` | Field value type doesn't match schema |
| `E_ENUM_INVALID` | Value not in allowed enum values |
| `E_REGEX_MISMATCH` | String doesn't match pattern |
| `E_UNKNOWN_FIELD` | Field not defined in schema (when UNKNOWN_FIELDS=REJECT) |
| `E_CONSTRAINT_VIOLATION` | Constraint chain evaluation failed |
| `E_FRONTEMATTER_INVALID` | YAML frontmatter validation failed |
| `E_AST_CYCLE` | Cyclic structure detected |

## Validation Workflow

```mermaid
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

资料来源：[src/octave_mcp/core/validator.py:150-200]()

## Related Documentation

- [Usage Guide](docs/usage.md) - CLI, MCP, and API examples
- [API Reference](docs/api.md) - Python API documentation
- [Schema Specification](../resources/specs/octave-schema-spec.oct.md) - Schema format specification

---

<a id='page-compression-system'></a>

## Compression System

### 相关页面

相关主题：[Canonical Normalization](#page-canonical-normalization)

<details>
<summary>Relevant Source Files</summary>

以下源码文件用于生成本页说明：

- [src/octave_mcp/core/holographic.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/holographic.py)
- [src/octave_mcp/core/sealer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/sealer.py)
- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)
- [src/octave_mcp/resources/skills/octave-compression/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-compression/SKILL.md)
- [src/octave_mcp/resources/skills/octave-mythology/SKILL.md](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/resources/skills/octave-mythology/SKILL.md)
- [examples/compression-comparisons/octave-vs-llmlingua-compression-comparison-2026.md](https://github.com/elevanaltd/octave-mcp/blob/main/examples/compression-comparisons/octave-vs-llmlingua-compression-comparison-2026.md)
</details>

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

资料来源：[src/octave_mcp/resources/skills/octave-mythology/SKILL.md:1-15]()

## Compression Tiers

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

| Tier | Target Fidelity | Preserved | Dropped | Use Cases |
|------|-----------------|-----------|---------|-----------|
| **LOSSLESS** | 100% | Everything | Nothing | Critical reasoning, legal documents, safety analysis, audit trails |
| **CONSERVATIVE** | 85-90% | Explanatory depth, tradeoff reasoning | Redundancy, verbose transitions | Research summaries, design decisions, technical analysis |
| **AGGRESSIVE** | 70% | Core thesis, landscape | Explanatory depth, execution narratives | Overview documents, quick references |
| **ULTRA** | 50-60% | Semantic invariants | All narrative prose | High-density summaries, token-constrained contexts |

资料来源：[src/octave_mcp/resources/skills/octave-compression/SKILL.md:15-30]()

### Tier Selection Flow

```mermaid
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.

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

资料来源：[src/octave_mcp/core/holographic.py](https://github.com/elevanaltd/octave-mcp/blob/main/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

```mermaid
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]
```

资料来源：[src/octave_mcp/core/sealer.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/sealer.py)

## Semantic Operators

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

| Operator | Symbol | Meaning | Example |
|----------|--------|---------|---------|
| Synthesis | `⊕` | Combining elements | `teaches_format ⊕ validates_rules ⊕ routes_data` |
| Tension | `⇌` | Tradeoff/balance | `downtime ⇌ parallel_work` |
| Flow | `→` | Routing/execution | `REQ → INDEXER` |
| Constraint | `∧` | Required conjunction | `valid ∧ processed` |
| Disjunction | `∨` | Optional alternatives | `CREATE ∨ UPDATE ∨ DELETE` |
| Definition | `::` | Maps to/assignment | `PURPOSE::"Master OCTAVE"` |

资料来源：[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

| Domain | Mythological Name | Semantic Load | Example |
|--------|------------------|---------------|---------|
| Eternal Tasks | SISYPHEAN | Futile repetition | `SISYPHEAN::loop_detected` |
| Precision Targeting | ARTEMIS | Focused accuracy | `ARTEMIS::targeted_optimization` |
| Time Pressure | CHRONOS | Temporal constraints | `CHRONOS::q4_deadline` |
| Resource Limits | DEMETER | Budget/budget exhaustion | `DEMETER::60%_burned` |
| Forbidden Knowledge | PROMETHEAN | Risk of revelation | `PROMETHEAN::sensitive_exposure` |

资料来源：[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"

资料来源：[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:

```mermaid
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]
```

资料来源：[src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)

### Validation Checks

Documents compressed with OCTAVE must pass these checks:

| Check | Requirement | Purpose |
|-------|-------------|---------|
| `valid_OCTAVE` | Valid syntax | Grammar compliance |
| `preserve_§_names_verbatim` | Section names unchanged | Structural integrity |
| `patterns_applied` | Semantic operators used correctly | Semantic preservation |
| `archetypes_used` | Valid archetype selection | Compression fidelity |
| `holographic_valid` | Field-level holograms intact | Constraint preservation |

资料来源：[src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:30-35]()

## Workflow: Prose to OCTAVE

```mermaid
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)
```octave
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)
```octave
MIGRATION::SISYPHEAN[Q4] ⊕ CHRONOS[deadline]
→ DEMETER::60%_quarterly_burned
```

## Loss Profiles

Every compressed document declares its `LOSS_PROFILE`, enabling auditable transformation:

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

| Tier | Loss Profile | Narrative Impact |
|------|--------------|------------------|
| LOSSLESS | `none` | Fully preserved |
| CONSERVATIVE | `redundancy ⊕ verbose_transitions` | Tradeoffs explained inline |
| AGGRESSIVE | `explanatory_depth ⊕ execution_narratives` | Core thesis preserved |
| ULTRA | `all_narrative` | Semantic invariants only |

资料来源：[examples/survey-octave-5-conservative.oct.md:1-15]()

## Integration Points

### With Claude Code
```bash
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

| Tool | Compression Use |
|------|-----------------|
| `octave_validate` | Validates compressed documents against schema |
| `octave_write` | Writes with normalization and repair receipts |
| `octave_compile_grammar` | Compiles constraints to GBNF for generation |

## 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

---

<a id='page-grammar-compilation'></a>

## Grammar Compilation

### 相关页面

相关主题：[Schema Validation](#page-schema-validation), [System Architecture](#page-system-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/octave_mcp/core/gbnf_compiler.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/gbnf_compiler.py)
- [src/octave_mcp/core/grammar_compiler/gbnf.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/grammar_compiler/gbnf.py)
- [src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/grammar_resources.py)
- [docs/grammar/octave-v1.0-grammar.ebnf](https://github.com/elevanaltd/octave-mcp/blob/main/docs/grammar/octave-v1.0-grammar.ebnf)
</details>

# 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

资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:1-17]()

## Architecture

```mermaid
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.

| Method | Purpose |
|--------|---------|
| `compile_schema(schema_def, include_envelope=True)` | Compile full schema to GBNF |
| `emit_grammar_for_schema(schema_name)` | Emit grammar for named schema |

资料来源：[src/octave_mcp/core/grammar_compiler/gbnf.py]()
资料来源：[src/octave_mcp/mcp/grammar_resources.py:48-76]()

### SchemaDefinition

Schemas define the structure of OCTAVE documents:

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

资料来源：[src/octave_mcp/core/gbnf_compiler.py:42-47]()

### FieldDefinition

Individual fields within schemas include holographic patterns for constraint representation:

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

资料来源：[src/octave_mcp/core/gbnf_compiler.py:59-63]()

## Compilation Pipeline

### Step 1: Schema Loading

```mermaid
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:

资料来源：[src/octave_mcp/mcp/grammar_resources.py:48-52]()

```python
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:

| Constraint Syntax | Meaning |
|-------------------|---------|
| `REQ` | Required field |
| `OPT` | Optional field |
| `ENUM[values]` | Enumerated values |
| `FIELD[NAME]::REQ∧ENUM[...]` | Combined constraints |

资料来源：[src/octave_mcp/core/gbnf_compiler.py:30-40]()

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

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

资料来源：[src/octave_mcp/core/gbnf_compiler.py:53-58]()

### Step 3: Grammar Emission

The compiler generates GBNF rules from the schema structure:

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

资料来源：[src/octave_mcp/mcp/grammar_resources.py:53-55]()

## MCP Integration

### Grammar Resource Provider

The MCP server exposes grammars through a resource provider:

```mermaid
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
```

资料来源：[src/octave_mcp/mcp/grammar_resources.py:43-56]()

### Resource Templates

Grammars are accessible via URI templates:

| Template | Schema |
|----------|--------|
| `octave://grammars/{schema_name}` | Any registered schema |

资料来源：[src/octave_mcp/mcp/grammar_resources.py:23-32]()

### Caching

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

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

资料来源：[src/octave_mcp/mcp/grammar_resources.py:43-44]()

## Public API

### compile_document_grammar

Main entry point for document grammar compilation:

```python
from octave_mcp.core.grammar_compiler import compile_document_grammar
```

### emit_grammar_for_schema

Emit grammar for a specific schema by name:

```python
from octave_mcp.core.grammar_compiler import emit_grammar_for_schema
```

资料来源：[src/octave_mcp/core/grammar_compiler/__init__.py:10-11]()

## MCP Tool: octave_compile_grammar

The MCP server exposes a tool for grammar compilation:

| Parameter | Type | Description |
|-----------|------|-------------|
| `schema_name` | string | Name of schema to compile |
| `include_envelope` | boolean | Include document envelope rules (default: true) |

资料来源：[README.md - MCP Tools section]()

## Example Usage

### Compile from META definition

```python
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)
```

资料来源：[src/octave_mcp/core/gbnf_compiler.py:20-35]()

### Access via MCP Resource

```bash
# 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.

资料来源：[src/octave_mcp/core/grammar/__init__.py:1-30]()

### Backward Compatibility

Legacy GBNF exports are available through lazy module loading:

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

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

资料来源：[src/octave_mcp/core/grammar/__init__.py:48-52]()

## Workflow Summary

```mermaid
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](../specs/octave-core-spec.oct.md)
- [Schema Validation Framework](../specs/octave-schema-spec.oct.md)
- [Holographic Patterns](holographic-patterns.md)

---

<a id='page-mcp-tools'></a>

## MCP Tools Reference

### 相关页面

相关主题：[CLI Interface](#page-cli-interface), [Python API Reference](#page-python-api)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this documentation:

- [src/octave_mcp/mcp/validate.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/validate.py)
- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)
- [src/octave_mcp/mcp/eject.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/eject.py)
- [src/octave_mcp/mcp/compile_grammar.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/compile_grammar.py)
- [src/octave_mcp/mcp/base_tool.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/base_tool.py)
- [docs/mcp-configuration.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/mcp-configuration.md)
</details>

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

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/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.

```mermaid
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
```

资料来源：[src/octave_mcp/mcp/base_tool.py](https://github.com/elevanaltd/octave-mcp/blob/main/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):

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

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)

### HTTP Transport

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

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `document` | string | Yes | The OCTAVE document content to validate |
| `schema` | string | No | Schema name to validate against (e.g., META, SKILL, AGENT) |
| `strict` | boolean | No | If true, reject unknown META fields (default: false) |

#### Returns

| Field | Type | Description |
|-------|------|-------------|
| `status` | string | "VALID" or "INVALID" |
| `errors` | array | List of validation errors with line numbers |
| `warnings` | array | List of warnings (e.g., W_META_001, W_META_002) |
| `suggestions` | array | Auto-correction suggestions for repairable issues |

#### 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

资料来源：[src/octave_mcp/mcp/validate.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/validate.py)
资料来源：[src/octave_mcp/core/validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `target_path` | string | Yes | File path to write to |
| `content` | string | No | Full content for new files or overwrites |
| `changes` | object | No | Field updates for existing files (mutually exclusive with content) |
| `mutations` | object | No | Optional META field overrides |
| `base_hash` | string | No | SHA-256 hash for CAS consistency check |
| `schema` | string | No | Schema name for validation |
| `debug_grammar` | boolean | No | Include compiled grammar in output (default: false) |
| `format_style` | string | No | Output mode: "preserve", "expanded", or "compact" |

#### Format Style Options

| Mode | Description |
|------|-------------|
| `preserve` | Span-aware mode that preserves original formatting (recommended for edits) |
| `expanded` | Canonical re-emit with full canonical form |
| `compact` | Minimal whitespace, reduced token count |

#### Response

```json
{
  "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.

资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)

### 3. `octave_eject`

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

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `document` | string | Yes | The OCTAVE document to transform |
| `mode` | string | No | Projection mode (default: canonical) |
| `format` | string | No | Output format: "markdown" or "json" (default: markdown) |

#### Projection Modes

| Mode | Description | Use Case |
|------|-------------|----------|
| `canonical` | Full document with all sections | Preservation, validation |
| `executive` | High-level summary with key decisions | Stakeholder review |
| `developer` | Implementation-focused view | Code generation, testing |
| `template` | Structure without content | New document scaffolding |

资料来源：[src/octave_mcp/mcp/eject.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/eject.py)

### 4. `octave_compile_grammar`

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

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `schema` | string | Yes | Schema name to compile (e.g., META, SKILL) |
| `include_envelope` | boolean | No | Include document envelope markers (default: true) |
| `debug` | boolean | No | Include debug comments in output (default: false) |

#### 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:

```mermaid
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
```

资料来源：[src/octave_mcp/mcp/compile_grammar.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/compile_grammar.py)
资料来源：[src/octave_mcp/mcp/grammar_resources.py](https://github.com/elevanaltd/octave-mcp/blob/main/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

资料来源：[src/octave_mcp/mcp/base_tool.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/base_tool.py)

## CLI Equivalents

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

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

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)

## Tool Selection Guide

| Scenario | Recommended Tool |
|----------|-----------------|
| Verify document correctness | `octave_validate` |
| Create new document | `octave_write` with `content` |
| Modify existing document | `octave_write` with `changes` |
| Generate summary view | `octave_eject` with `mode: executive` |
| Prepare for constrained generation | `octave_compile_grammar` |
| Reformat document | `octave_eject` with `mode: canonical` |

## Error Codes

| Code | Meaning |
|------|---------|
| `E_NESTED_INLINE_MAP` | Inner value is an inline map (strict mode error) |
| `W_NESTED_INLINE_MAP` | Inner value is an inline map (lenient mode warning) |
| `W_META_001` | Missing recommended META field |
| `W_META_002` | Unknown META field present |
| `GH#369` | Duplicate target detected |

## 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

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)

---

<a id='page-cli-interface'></a>

## CLI Interface

### 相关页面

相关主题：[MCP Tools Reference](#page-mcp-tools), [Python API Reference](#page-python-api)

<details>
<summary>Relevant Source Files</summary>

The following source files were used to generate this documentation:

- [src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)
- [tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)
- [tools/octave-to-json.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-to-json.py)
- [tools/json-to-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/json-to-octave.py)
- [tools/lint-octave.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/lint-octave.py)
- [README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)
</details>

# 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:

| Category | Tools | Purpose |
|----------|-------|---------|
| **Core CLI** | `octave validate`, `octave write`, `octave eject` | Primary operations via MCP server executable |
| **Standalone Scripts** | `lint-octave.py`, `octave-to-json.py`, `json-to-octave.py`, `octave-validator.py` | Fast validation and format conversion without server overhead |

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

## Architecture

```mermaid
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:

```bash
pip install octave-mcp
```

### MCP Configuration

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

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

#### Claude Desktop (`claude_desktop_config.json`)

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

#### HTTP Transport

For remote or containerized deployments:

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

## Core CLI Commands

### `octave validate`

Validates OCTAVE documents against the specification and optional schema.

```bash
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.

```bash
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.

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

**Available Modes:**
| Mode | Purpose |
|------|---------|
| `canonical` | Full OCTAVE format |
| `executive` | High-level summary for decision-makers |
| `developer` | Implementation-focused view |
| `template` | Template with placeholders |

## Standalone Validation Tools

### `lint-octave.py`

Fast syntax validation script optimized for rapid feedback.

**Usage:**
```bash
python3 lint-octave.py < document.oct.md
```

**Output:**
- `OCTAVE_VALID` - Document passes all checks
- `OCTAVE_INVALID: <reason>` - Document fails with specific reason

**Validation Checks:**

| Check | Description |
|-------|-------------|
| Document Markers | Verifies `===NAME===` and `===END===` envelope markers |
| META Section | Confirms presence of `META:` after optional preface comments |
| Indentation | Validates 2-space multiples |
| Assignment Syntax | Ensures `KEY::VALUE` format |
| Balanced Brackets | Checks `[]` bracket matching |
| Trailing Commas | Rejects trailing commas in lists |

资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/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:**
```bash
# Single file validation
python3 octave-validator.py document.oct.md

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

**Command-Line Arguments:**

| Argument | Short | Description | Default |
|----------|-------|-------------|---------|
| `--version` | `-v` | OCTAVE version label (informational) | `6.0.0` |
| `--profile` | `-p` | Validation profile | `protocol` |
| `--schema` | - | Schema name for validation | None |
| `--require-frontmatter` | - | Fail on missing YAML frontmatter | False |
| `--path` | `-d` | Scan directory for `*.oct.md` files | None |

**Validation Profiles:**

| Profile | Description |
|---------|-------------|
| `protocol` | Standard OCTAVE protocol validation |
| `hestai-agent` | Agent document format with YAML frontmatter |
| `hestai-skill` | Skill document format with YAML frontmatter |
| `hestai-pattern` | Pattern document format |

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

资料来源：[tools/octave-validator.py](https://github.com/elevanaltd/octave-mcp/blob/main/tools/octave-validator.py)

## Format Conversion Tools

### `octave-to-json.py`

Converts OCTAVE documents to JSON for system integration.

**Usage:**
```bash
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

资料来源：[tools/README.md](https://github.com/elevanaltd/octave-mcp/blob/main/tools/README.md)

### `json-to-octave.py`

Converts JSON back to OCTAVE format, restoring original formatting.

**Usage:**
```bash
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:

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

| CLI Command | MCP Tool | Function |
|------------|----------|----------|
| `octave validate` | `octave_validate` | Validate against schema |
| `octave write` | `octave_write` | Write files with validation |
| `octave eject` | `octave_eject` | Project to different views |
| - | `octave_compile_grammar` | Compile schema constraints to GBNF |

资料来源：[README.md](https://github.com/elevanaltd/octave-mcp/blob/main/README.md)

### `octave_write` Parameters

The `octave_write` MCP tool provides comprehensive file writing capabilities:

| Parameter | Type | Description |
|-----------|------|-------------|
| `target_path` | string | File path to write to |
| `content` | string | Full content for new files (mutually exclusive with `changes`) |
| `changes` | object | Field updates for existing files (mutually exclusive with `content`) |
| `mutations` | object | Optional META field overrides |
| `base_hash` | string | Optional CAS consistency check hash |
| `schema` | string | Optional schema name for validation |
| `debug_grammar` | boolean | Include compiled grammar in output (default: false) |
| `format_style` | string | Output formatting: `"preserve"`, `"expanded"`, or `"compact"` |

**Return Value Structure:**

| Field | Description |
|-------|-------------|
| `status` | `"success"` or `"error"` |
| `path` | Written file path (on success) |
| `canonical_hash` | SHA-256 hash of canonical content (on success) |
| `corrections` | List of corrections applied |
| `diff` | Compact diff of changes |
| `errors` | List of errors (on failure) |
| `validation_status` | `VALIDATED` or `UNVALID` |

资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)

## Format Style Options

The `format_style` parameter controls output formatting:

| Style | Description | Use Case |
|-------|-------------|----------|
| `preserve` | Maintains original formatting and blank lines | Default (future v1.14.0+) |
| `expanded` | Canonical re-emit with full structure | Current default, archival |
| `compact` | Minimizes whitespace | Storage-constrained environments |

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

资料来源：[src/octave_mcp/mcp/write.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/mcp/write.py)

## Workflow Examples

### CI/CD Integration

```bash
#!/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

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

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

```mermaid
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:**

| Scenario | Recommended Tool | Reason |
|----------|-----------------|--------|
| Quick syntax check during editing | `lint-octave.py` | Fast, no imports required |
| CI/CD validation pipeline | `octave-validator.py` | Full validation, exit codes |
| Integration with JSON systems | `octave-to-json.py` / `json-to-octave.py` | Round-trip capable |
| Claude Desktop/Code integration | MCP tools via server | Full feature set |
| Batch directory validation | `octave-validator.py --path` | Processes all `.oct.md` files |

## Error Handling

### Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success / Validation passed |
| `1` | Failure (validation failed, file error, etc.) |

### 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:

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

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

---

<a id='page-python-api'></a>

## Python API Reference

### 相关页面

相关主题：[CLI Interface](#page-cli-interface), [MCP Tools Reference](#page-mcp-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/octave_mcp/__init__.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/__init__.py)
- [src/octave_mcp/core/parser.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/parser.py)
- [src/octave_mcp/core/emitter.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/emitter.py)
- [src/octave_mcp/core/repair.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/core/repair.py)
- [src/octave_mcp/schemas/loader.py](https://github.com/elevanaltd/octave-mcp/blob/main/src/octave_mcp/schemas/loader.py)
- [docs/api.md](https://github.com/elevanaltd/octave-mcp/blob/main/docs/api.md)
</details>

# 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:

| Category | Count | Description |
|----------|-------|-------------|
| Functions | 9 | Core operations: parse, emit, tokenize, repair, project, hydrate |
| Classes | 16 | Parser, Validator, TokenType, Token, Document, Block, Assignment, etc. |
| AST Nodes | 8 | Document, Block, Assignment, Section, ListValue, InlineMap, Absent |
| Hydration | 3 | HydrationPolicy, VocabularyRegistry, hydrate |
| Schema | 2 | SchemaDefinition, FieldDefinition |
| Repair | 4 | RepairLog, RepairEntry, RepairTier, RoutingLog |
| Exceptions | 8 | VocabularyError, CollisionError, ParserError, LexerError, etc. |

*资料来源：[src/octave_mcp/__init__.py:12-45]()

## Core Functions

### parse()

```python
def parse(content: str) -> Document
```

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

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `content` | `str` | OCTAVE document string to parse |

**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

*资料来源：[src/octave_mcp/__init__.py:27]()

### parse_with_warnings()

```python
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

*资料来源：[src/octave_mcp/core/parser.py:340-350]()

### emit()

```python
def emit(doc: Document) -> str
```

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

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `doc` | `Document` | The AST document to emit |

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

*资料来源：[src/octave_mcp/__init__.py:27](), [src/octave_mcp/core/emitter.py]()

### tokenize()

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

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

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `content` | `str` | OCTAVE document string |

**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`

*资料来源：[src/octave_mcp/__init__.py:27]()

### repair()

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

Attempts to automatically fix malformed OCTAVE content.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `content` | `str` | Potentially malformed OCTAVE content |

**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

*资料来源：[src/octave_mcp/__init__.py:27](), [src/octave_mcp/core/repair.py]()

### project()

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

Transforms a document into different output views.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `doc` | `Document` | Source document |
| `mode` | `str` | Projection mode: canonical, executive, developer, template |

**Returns:** `ProjectionResult` - Transformed document with routing log

*资料来源：[src/octave_mcp/__init__.py:27]()

### hydrate()

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

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

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `doc` | `Document` | Document to hydrate |
| `policy` | `HydrationPolicy` | Hydration configuration |

**Returns:** `Document` - Hydrated document with substitutions applied

*资料来源：[src/octave_mcp/__init__.py:27]()

### extract_schema_from_document()

```python
def extract_schema_from_document(doc: Document) -> SchemaDefinition
```

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

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `doc` | `Document` | Document to analyze |

**Returns:** `SchemaDefinition` - Inferred schema with field definitions

*资料来源：[src/octave_mcp/__init__.py:27]()

### seal_document() / verify_seal()

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

Integrity management functions for document sealing.

*资料来源：[src/octave_mcp/__init__.py:27]()

## Core Classes

### Parser

The `Parser` class provides detailed control over the parsing process.

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

**Key Methods:**

| Method | Description |
|--------|-------------|
| `parse_document()` | Parse complete OCTAVE document with ADR-0006 SR2-T2 support for `start_byte`/`end_byte` |
| `parse_with_warnings()` | Returns document with META region byte positions |

**Grammar Sentinel Support:**
- Recognizes `OCTAVE::VERSION` pattern
- Populates `doc.grammar_version` from lexer

*资料来源：[src/octave_mcp/core/parser.py:150-180]()

### Document

The AST representation of an OCTAVE document.

```python
@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:**

| Attribute | Type | Description |
|-----------|------|-------------|
| `name` | `str` | Document envelope name (e.g., "MY_DOC") or "INFERRED" |
| `grammar_version` | `str \| None` | Version from grammar sentinel |
| `start_byte` | `int` | Document start byte offset (always 0 for NFC base) |
| `end_byte` | `int` | Document end byte offset |
| `meta_start_byte` | `int \| None` | META block start (when present) |
| `meta_end_byte` | `int \| None` | META block end (when present) |
| `sections` | `list[Block]` | Parsed section blocks |

*资料来源：[src/octave_mcp/core/parser.py:150-160]()

### Block

Represents a structural block within a document.

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

### Assignment

Represents a key-value assignment.

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

### HydrationPolicy

Configuration for document hydration.

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

### SchemaDefinition

Schema definition for validation.

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

*资料来源：[src/octave_mcp/__init__.py:30-45]()

## Exception Classes

| Exception | Description |
|-----------|-------------|
| `VocabularyError` | Vocabulary-related validation failure |
| `CollisionError` | Key or name collision detected |
| `VersionMismatchError` | Grammar version incompatibility |
| `CycleDetectionError` | Circular dependency in hydration |
| `SourceUriSecurityError` | Unsafe URI reference detected |
| `ParserError` | Parsing failure |
| `LexerError` | Lexical analysis failure |
| `ValidationError` | Schema validation failure |

*资料来源：[src/octave_mcp/__init__.py:43-45]()

## Repair System

### RepairLog

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

### RepairTier

| Tier | Description |
|------|-------------|
| `LENIENT_PARSE` | Minor fixes that preserve semantics |
| `MODERATE` | Structural corrections |
| `STRICT` | Breaking changes required |

### RepairEntry

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

**Common Repair Codes:**

| Code | Tier | Description |
|------|------|-------------|
| `W_STRUCT_RAW_WRAP` | LENIENT_PARSE | Wrapped plain text into BODY: RAW carrier |

*资料来源：[src/octave_mcp/core/repair.py]()

## Schema Loading

### load_schema_by_name()

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

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

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `schema_name` | `str` | Schema name (e.g., "META", "SKILL", "SESSION_LOG") |

**Returns:** `SchemaDefinition` or `None` if not found

**Builtin Schemas:**
- `META` - Document metadata schema
- `SKILL` - Skill definition schema
- `SESSION_LOG` - Session logging schema

*资料来源：[src/octave_mcp/schemas/loader.py]()

## Usage Examples

### Basic Parsing

```python
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

```python
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

```python
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

```python
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)
```

*资料来源：[docs/api.md]()

## Architecture Diagram

```mermaid
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

| Feature | CLI | Python API |
|---------|-----|------------|
| Quick validation | ✓ | ✓ via `parse()` |
| File operations | ✓ | Manual |
| Streaming | ✓ | ✓ via generators |
| Custom repair strategies | ✗ | ✓ via `repair()` |
| AST manipulation | ✗ | ✓ |
| Integration into Python apps | ✗ | ✓ |
| MCP tools | ✓ | ✗ |

## Advanced: Grammar Compilation

```python
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

*资料来源：[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](docs/usage.md) - CLI and integration examples
- [Specs](../specs/) - OCTAVE specification documents
- [Primers](../resources/primers/) - Quick-start primers for specific use cases

---

---

## Doramagic Pitfall Log

Project: elevanaltd/octave-mcp

Summary: Found 38 potential pitfall items; 4 are high/blocking. Highest priority: security_permissions - 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc....

## 1. security_permissions · 失败模式：security_permissions: octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oc...

- Severity: high
- Evidence strength: source_linked
- 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
- Suggested 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.
- Guardrail action: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/elevanaltd/octave-mcp/issues/424
- 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_permissions · 失败模式：security_permissions: octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)

- Severity: high
- Evidence strength: source_linked
- 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)
- Suggested 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.
- Guardrail action: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/elevanaltd/octave-mcp/issues/420
- 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_permissions · 来源证据：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)

- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: octave_write surgical edit primitives unsafe on inline-array top-level entries (APPEND + expanded modes)
- User impact: 可能影响升级、迁移或版本选择。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_75dbe0c2c20b479a9afc619c467acc20 | https://github.com/elevanaltd/octave-mcp/issues/411 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. security_permissions · 来源证据：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks

- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_744a11a12c0340e08087ea951c281000 | https://github.com/elevanaltd/octave-mcp/issues/426 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. installation · 失败模式：installation: octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed findin...

- Severity: medium
- Evidence strength: source_linked
- 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
- Suggested 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.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- 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, failure_mode_cluster:github_issue | fmev_aa61ed66e510ebfae83228fb28ae6e11 | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_6046cbe1d9f5946d7c5f3b4a9e75cd5a | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks, failure_mode_cluster:github_issue | fmev_6450b53644007e96c1fa966585fe47ea | https://github.com/elevanaltd/octave-mcp/issues/426 | octave_validate: CRS_REVIEW §FINDINGS section uncovered → false negatives on malformed finding blocks

## 6. installation · 失败模式：installation: octave_write/octave_validate: add DECISION_LOG schema for DECISIONS_OCTAVE_v20260417 type doc...

- Severity: medium
- Evidence strength: source_linked
- 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
- Suggested 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.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- 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 · 来源证据：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: _find_target_start backslash-run quote-escape mishandling (sibling of cubic P1 on PR #431)
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_8284755b0fa74799b1f881f624677141 | https://github.com/elevanaltd/octave-mcp/issues/432 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. configuration · 失败模式：configuration: RFC v1.14: wire #191 META schema compilation into pre-parse pipeline (Shape G — self-describi...

- Severity: medium
- Evidence strength: source_linked
- 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)
- Suggested 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
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- 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 · 失败模式：configuration: bug: emitter normalises backslash counts in string literals (round-trip byte-loss)

- Severity: medium
- Evidence strength: source_linked
- 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)
- Suggested 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.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- 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 · 失败模式：configuration: bug: lexer requires ∧ constraint chain for AST-level holographic recognition (target-only pat...

- Severity: medium
- Evidence strength: source_linked
- 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)
- Suggested 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.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- 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 · 失败模式：configuration: bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say fu...

- Severity: medium
- Evidence strength: source_linked
- 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...
- Suggested 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
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- 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 · 失败模式：configuration: governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate

- Severity: medium
- Evidence strength: source_linked
- 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
- Suggested 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.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- 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

## 13. configuration · 失败模式：configuration: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered
- User impact: Developers may misconfigure credentials, environment, or host setup: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: octave_validate: SKILL schema only validates frontmatter; §-section body uncovered. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_339fb57ac390e565b548c1bea78abc66 | https://github.com/elevanaltd/octave-mcp/issues/428 | octave_validate: SKILL schema only validates frontmatter; §-section body uncovered, failure_mode_cluster:github_issue | fmev_338bf1f21059e0d238b9fcb8084aea71 | https://github.com/elevanaltd/octave-mcp/issues/428 | octave_validate: SKILL schema only validates frontmatter; §-section body uncovered

## 14. configuration · 来源证据：bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_6236e7ed154c4976ac4a7deee1e5e95d | https://github.com/elevanaltd/octave-mcp/issues/447 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 15. configuration · 来源证据：octave_validate: DEBATE_TRANSCRIPT STATUS enum missing 'PAUSED' (live false negative)

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：octave_validate: DEBATE_TRANSCRIPT STATUS enum missing 'PAUSED' (live false negative)
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_b0ee99f7200a4686b5de382a2c70d9b2 | https://github.com/elevanaltd/octave-mcp/issues/423 | 来源类型 github_issue 暴露的待验证使用条件。

## 16. capability · 能力判断依赖假设

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: 假设不成立时，用户拿不到承诺的能力。
- Suggested check: 将假设转成下游验证清单。
- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。
- Evidence: capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass.

## 17. runtime · 失败模式：runtime: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP cr...

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock
- User impact: Developers may hit a documented source-backed failure mode: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_9022259172bcd98fea3c615e38180f11 | https://github.com/elevanaltd/octave-mcp/issues/440 | bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock

## 18. runtime · 失败模式：runtime: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement
- User impact: Developers may hit a documented source-backed failure mode: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_4667399fae050529c3b6df294209996d | https://github.com/elevanaltd/octave-mcp/issues/439 | enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement

## 19. runtime · 失败模式：runtime: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on...

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)
- User impact: Developers may hit a documented source-backed failure mode: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444). Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_d71a3524d919da6f5900dcc0df04304b | https://github.com/elevanaltd/octave-mcp/issues/445 | enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)

## 20. runtime · 来源证据：bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug/governance: octave_validate vs octave_write asymmetric handling of E_NESTED_INLINE_MAP creates write-gate deadlock
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_2512797d818a4840822d948795de8588 | https://github.com/elevanaltd/octave-mcp/issues/440 | 来源类型 github_issue 暴露的待验证使用条件。

## 21. runtime · 来源证据：bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_a8d2b9e12cb2477499d2ada52aed438e | https://github.com/elevanaltd/octave-mcp/issues/436 | 来源类型 github_issue 暴露的待验证使用条件。

## 22. runtime · 来源证据：enhancement: octave_validate ENUM constraint non-enforcement (PARTIAL → IMPLEMENTED)

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: octave_validate ENUM constraint non-enforcement (PARTIAL → IMPLEMENTED)
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_c9882e67c42642b0864690256d8258e6 | https://github.com/elevanaltd/octave-mcp/issues/435 | 来源类型 github_issue 暴露的待验证使用条件。

## 23. runtime · 来源证据：enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: octave_validate consume SCHEMA_REQUIRED_EXCEPTIONS for conditional REQ enforcement
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_ed6a5fd931ec45489d58f2763b403513 | https://github.com/elevanaltd/octave-mcp/issues/439 | 来源类型 github_issue 暴露的待验证使用条件。

## 24. runtime · 来源证据：enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：enhancement: validator section-bucket merging may mask path-isolated requirements (raised on PR #444)
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_28e0ef9cb32e4e918dafd0e22960d639 | https://github.com/elevanaltd/octave-mcp/issues/445 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 25. maintenance · 维护活跃度未知

- Severity: medium
- Evidence strength: source_linked
- Finding: 未记录 last_activity_observed。
- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。
- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing

## 26. security_permissions · 下游验证发现风险项

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 下游已经要求复核，不能在页面中弱化。
- Suggested check: 进入安全/权限治理复核队列。
- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。
- Evidence: downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium

## 27. security_permissions · 存在评分风险

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 风险会影响是否适合普通用户安装。
- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。
- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。
- Evidence: risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium

## 28. security_permissions · 来源证据：DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports 68 STRICT validation_errors

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：DECISION_LOG schema v1.1 conformance: reference DECISIONS.oct.md reports 68 STRICT validation_errors
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_8d4d0aa8843f448b8151f98bb89a5d32 | https://github.com/elevanaltd/octave-mcp/issues/448 | 来源类型 github_issue 暴露的待验证使用条件。

## 29. security_permissions · 来源证据：bug: emitter normalises backslash counts in string literals (round-trip byte-loss)

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: emitter normalises backslash counts in string literals (round-trip byte-loss)
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_2c50ae54a6ed47aa92320c3c9a40fdc2 | https://github.com/elevanaltd/octave-mcp/issues/434 | 来源类型 github_issue 暴露的待验证使用条件。

## 30. security_permissions · 来源证据：bug: octave_write changes-mode bare-dict on top-level KEY silently acts as MERGE (docs say full replacement) + scalar-o…

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：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 duplic…
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_694f815fe5af49db82e637268c4346ca | https://github.com/elevanaltd/octave-mcp/issues/443 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 31. security_permissions · 来源证据：governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：governance: amend pre-merge CI gate to use octave_write --dry-run, not just octave_validate
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_6d91773d5074499aa595b7e38bddbb0d | https://github.com/elevanaltd/octave-mcp/issues/441 | 来源类型 github_issue 暴露的待验证使用条件。

## 32. security_permissions · 来源证据：octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_write/octave_validate: add AGENT_DEFINITION schema for .hestai-sys/library/agents/*.oct.md
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_7c17465d2f4a474e8516a911c69b6427 | https://github.com/elevanaltd/octave-mcp/issues/424 | 来源类型 github_issue 暴露的待验证使用条件。

## 33. security_permissions · 来源证据：octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)

- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：octave_write: add FRAME_CARD multi-envelope schema (Facet ABI per hestai-context-mcp RFC #38)
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_86500177a232460e83ffd2da0f3bf682 | https://github.com/elevanaltd/octave-mcp/issues/420 | 来源类型 github_issue 暴露的待验证使用条件。

## 34. capability · 失败模式：capability: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)
- User impact: Developers may hit a documented source-backed failure mode: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only). Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_5da92869a244d36ecaf3e556113dc916 | https://github.com/elevanaltd/octave-mcp/issues/436 | bug: octave_write diff_unified field wraps lines mid-content on byte boundaries (display-only)

## 35. capability · 失败模式：conceptual: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form...

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)
- User impact: Developers may hit a documented source-backed failure mode: bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)
- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_7310a80e89468fb4bd5c6e61aadaa05b | https://github.com/elevanaltd/octave-mcp/issues/447 | bug: octave_write changes_mode adds nested block instead of mutating existing flat atom (form-preservation gap)

## 36. capability · 失败模式：conceptual: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced
- User impact: Developers may hit a documented source-backed failure mode: octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced
- Suggested check: 复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_8978c0e787312f231a947da5f5c4e156 | https://github.com/elevanaltd/octave-mcp/issues/427 | octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced, failure_mode_cluster:github_issue | fmev_ea0f8b5de25b570660810c386051af8e | https://github.com/elevanaltd/octave-mcp/issues/427 | octave_validate: DEBATE_TRANSCRIPT TURN_SCHEMA documented but not parsed/enforced

## 37. maintenance · issue/PR 响应质量未知

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: 用户无法判断遇到问题后是否有人维护。
- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。
- Guardrail action: issue/PR 响应未知时，必须提示维护风险。
- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown

## 38. maintenance · 发布节奏不明确

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。
- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。
- Evidence: evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown

<!-- canonical_name: elevanaltd/octave-mcp; human_manual_source: deepwiki_human_wiki -->