1. 项目简介

Octave MCP（Olympian Common Text And Vocabulary Engine - Model Context Protocol Server）是一个开源的语义文档格式处理系统，通过 MCP 协议为大型语言模型提供结构化的文档验证、转换和编译能力。

1.1 核心定位

Octave MCP 解决了多代理协作场景下的文档一致性问题。当文档需要在多个 Agent、工具或压缩步骤之间传递时，OCTAVE 格式确保了语义信息的完整性和可解析性。

资料来源：README.md:1-5

1.2 适用场景

资料来源：README.md:35-42

2. 系统架构

2.1 整体架构图

graph TD
    subgraph "客户端层"
        CLAUDE["Claude Code / Claude Desktop"]
        HTTP_CLIENT["HTTP 客户端"]
    end
    
    subgraph "MCP 服务器层"
        MCP_SERVER["octave-mcp-server"]
        HTTP_TRANSPORT["HTTP Transport"]
        STDIO_TRANSPORT["stdio Transport"]
    end
    
    subgraph "核心处理层"
        VALIDATOR["验证器"]
        WRITER["写入器"]
        EJECTOR["投影器"]
        GRAMMAR_COMPILER["语法编译器"]
    end
    
    subgraph "资源层"
        SPECS["OCTAVE 规范 v6.0.0"]
        PRIMERS["引导文档"]
        SKILLS["技能定义"]
        SCHEMAS["Schema 定义"]
    end
    
    CLAUDE -->|MCP Protocol| MCP_SERVER
    HTTP_CLIENT -->|HTTP| HTTP_TRANSPORT
    HTTP_TRANSPORT --> MCP_SERVER
    STDIO_TRANSPORT --> MCP_SERVER
    MCP_SERVER --> VALIDATOR
    MCP_SERVER --> WRITER
    MCP_SERVER --> EJECTOR
    MCP_SERVER --> GRAMMAR_COMPILER
    GRAMMAR_COMPILER --> SPECS
    WRITER --> SCHEMAS
    EJECTOR --> PRIMERS

2.2 核心模块

资料来源：src/octave_mcp/resources/README.md:1-15

3. 安装与配置

3.1 安装方式

# 通过 pip 安装
pip install octave-mcp

# 验证安装
octave --version

3.2 MCP 服务器配置

#### Claude Code 配置

编辑 ~/.claude.json：

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

#### Claude Desktop 配置

编辑 claude_desktop_config.json：

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

#### HTTP 传输模式

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

资料来源：README.md:15-25

4. MCP 工具集

4.1 工具列表

资料来源：README.md:27-34

4.2 CLI 命令

# 验证文档
octave validate document.oct.md

# 写入标准化输出
octave write output.oct.md --stdin

# 投影为执行摘要格式
octave eject document.oct.md --mode executive --format markdown

5. OCTAVE 格式规范

5.1 格式概述

OCTAVE（Olympian Common Text And Vocabulary Engine）是一种专为 LLM 设计的语义 DSL（领域特定语言），采用结构化文本格式实现高效的信息压缩与精确解析。

资料来源：src/octave_mcp/resources/skills/octave-literacy/SKILL.md:12-14

5.2 文档结构

===DOCUMENT_NAME===
META:
  TYPE::"文档类型"
  VERSION::"1.0.0"
  STATUS::"ACTIVE"

§1::SECTION_NAME
  CONTENT::"节内容"

§2::ANOTHER_SECTION
  KEY::VALUE
  LIST::[item1,item2]
===END===

5.3 核心语法元素

资料来源：src/octave_mcp/resources/skills/octave-literacy/SKILL.md:20-35

5.4 L3 Agent Format

L3 Agent Format 是 OCTAVE 在 HestAI Agent 文件中的具体应用标准：

什么是 Octave-MCP

Octave-MCP 是基于 Olympian Common Text And Vocabulary Engine (OCTAVE) 的语义 DSL 工具，专为 LLM 原生通信设计，提供结构化文档格式与压缩能力。该系统包含 MCP (Model Context Protocol) 服务端和命令行工具，支持 OCTAVE 文档的验证、写入、编译等操作。资料来源：README.md:1

环境要求与依赖

安装方式

通过 pip 安装

pip install octave-mcp

安装完成后，octave-mcp-server 和 octave 命令行工具将自动添加到系统 PATH。资料来源：README.md:15

从源码构建

git clone https://github.com/elevanaltd/octave-mcp.git
cd octave-mcp
pip install -e .

MCP 接入配置

Octave-MCP 支持通过 MCP 协议与多种客户端集成，提供 MCP 工具调用能力。

Claude Desktop 配置

编辑 Claude Desktop 配置文件 (claude_desktop_config.json)：

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

HTTP 传输模式

如需通过 HTTP 协议访问 MCP 服务：

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

资料来源：README.md:25-35

MCP 工具一览

资料来源：README.md:38-48

CLI 命令行操作

octave CLI 提供完整的命令行接口，支持验证、写入和格式转换操作。

基本命令

# 验证 OCTAVE 文档
octave validate document.oct.md

# 从标准输入写入
octave write output.oct.md --stdin

# 导出为不同格式
octave eject document.oct.md --mode executive --format markdown

工作流程图

graph TD
    A[创建 .oct.md 文件] --> B[octave validate 验证]
    B --> C{验证通过?}
    C -->|是| D[octave write 写入]
    C -->|否| E[修复错误]
    E --> B
    D --> F[octave eject 导出视图]
    F --> G[完成]

工具脚本集

Octave-MCP 提供了独立的 Python 工具脚本，位于 tools/ 目录，用于 OCTAVE 文档的快速验证与转换。

lint-octave.py

功能：快速语法验证 用法：python3 lint-octave.py < document.oct.md 返回值：OCTAVE_VALID 或 OCTAVE_INVALID: <reason>

检查项目包括：

• 文档标记（===NAME=== 和 ===END===）
• META 区域存在性
• 缩进（2 空格倍数）
• 赋值语法（KEY::VALUE）
• 括号平衡
• 列表中无尾随逗号

资料来源：tools/README.md:8-25

octave-to-json.py

功能：将 OCTAVE 转换为 JSON 用法：python3 octave-to-json.py document.oct.md > output.json

特性：

• 保留语义操作符（synthesis、tension、progression）
• 追踪空行以确保往返保真度
• 维护引号字符串
• 处理嵌套结构

json-to-octave.py

功能：将 JSON 转换回 OCTAVE 格式 用法：python3 json-to-octave.py input.json > document.oct.md

特性：

• 还原原始格式包括空行
• 重建语义操作符
• 保留文档结构

资料来源：tools/README.md:26-45

octave-validator.py

功能：仓库验证器，包装 OCTAVE-MCP 核心解析器/验证器

此工具用于防止运行时验证（CLI/MCP 工具）与仓库/文档验证之间的漂移。

支持的 envelope 标记：===NAME=== ... ===END===

# 验证单个文件
python3 tools/octave-validator.py document.oct.md

# 扫描目录
python3 tools/octave-validator.py --path ./docs --profile hestai-agent

资料来源：tools/README.md:46-58

OCTAVE 文档结构

OCTAVE 文档采用标准化结构，包含信封标记、YAML frontmatter（可选）和语义化 body 区域。

标准信封格式

===DOCUMENT_NAME===
META:
  TYPE::DOCUMENT_TYPE
  VERSION::"1.0.0"

概述

octave-mcp 是一个基于 Model Context Protocol (MCP) 的 Octave 数学解释器服务器项目。该项目将 GNU Octave 集成到 MCP 生态系统中，使大型语言模型 (LLM) 能够通过标准化的 MCP 协议与 Octave 进行交互，执行数学计算、信号处理和科学计算任务。

资料来源：src/octave_mcp/resources/README.md:1

架构设计原则

根据架构决策记录 (ADR)，本项目遵循以下核心设计原则：

资料来源：docs/adr/adr-0001-configurability-and-modularity-architecture.md:1-20

整体架构

graph TD
    subgraph "MCP 协议层"
        MCP[MCP Server]
        STDIO[STDIO 传输]
    end
    
    subgraph "核心处理层"
        CORE[Core 模块]
        TOOL[Tool 管理系统]
        RESOURCE[Resource 资源管理]
    end
    
    subgraph "Octave 集成层"
        OCTAVE[Octave 解释器]
        EXEC[执行引擎]
    end
    
    subgraph "外部接口"
        LLM[大型语言模型]
        USER[用户终端]
    end
    
    LLM --> STDIO
    USER --> STDIO
    STDIO --> MCP
    MCP --> CORE
    CORE --> TOOL
    CORE --> RESOURCE
    TOOL --> EXEC
    RESOURCE --> EXEC
    EXEC --> OCTAVE

核心模块架构

模块职责矩阵

资料来源：src/octave_mcp/core/__init__.py:1-50 资料来源：src/octave_mcp/mcp/__init__.py:1-50

核心模块 (core)

核心模块是系统的主要业务逻辑处理单元，负责：

• Octave 解释器的生命周期管理
• 代码执行请求的处理
• 执行结果的解析与格式化
• 错误处理与异常管理

# 核心模块典型调用流程
def execute_octave_code(code: str) -> ExecutionResult:
    # 1. 输入验证
    # 2. 调用 Octave 解释器
    # 3. 捕获输出
    # 4. 错误处理
    # 5. 结果格式化

资料来源：src/octave_mcp/core/__init__.py:20-40

MCP 模块 (mcp)

MCP 模块负责实现 Model Context Protocol 规范，提供：

• MCP 服务器初始化与配置
• STDIO 传输层支持
• 工具注册与发现
• 请求/响应协议处理

sequenceDiagram
    participant LLM as LLM 客户端
    participant MCP as MCP Server
    participant Core as Core 模块
    participant Octave as Octave
    
    LLM->>MCP: initialize 请求
    MCP-->>LLM: 初始化响应 (协议版本、能力)
    LLM->>MCP: tools/list 请求
    MCP-->>LLM: 可用工具列表
    LLM->>MCP: tools/call 请求 (execute_octave)
    MCP->>Core: 执行 Octave 代码
    Core->>Octave: 运行代码
    Octave-->>Core: 执行结果
    Core-->>MCP: 格式化结果
    MCP-->>LLM: 工具调用响应

资料来源：src/octave_mcp/mcp/__init__.py:1-80

工具系统

工具注册机制

graph LR
    A[工具定义] --> B[注册中心]
    B --> C[MCP 协议暴露]
    C --> D[LLM 调用]
    
    subgraph "工具类型"
        T1[execute_code]
        T2[get_help]
        T3[list_functions]
    end
    
    A --> T1
    A --> T2
    A --> T3

核心工具接口

资料来源：src/octave_mcp/mcp/__init__.py:50-70

资源管理

资源类型

资源模块提供 Octave 相关的静态内容访问：

资料来源：src/octave_mcp/resources/README.md:1-30

配置与扩展

环境变量配置

扩展机制

项目支持通过以下方式进行扩展：

1. 自定义工具插件：实现标准工具接口并注册到 MCP 服务器
2. 资源提供者：添加新的资源类型或数据源
3. 传输层适配：支持不同的 MCP 传输机制

资料来源：docs/adr/adr-0001-configurability-and-modularity-architecture.md:30-50

项目结构

octave-mcp/
├── src/octave_mcp/
│   ├── __init__.py           # 包入口
│   ├── core/
│   │   └── __init__.py       # 核心业务逻辑
│   ├── mcp/
│   │   └── __init__.py       # MCP 协议实现
│   └── resources/
│       └── README.md         # 资源文档
├── docs/
│   └── adr/                  # 架构决策记录
├── pyproject.toml            # 项目配置
└── tests/                    # 测试套件

资料来源：pyproject.toml:1-30

数据流

graph LR
    A[用户输入<br/>Octave 代码] --> B[MCP 请求解析]
    B --> C[工具调用路由]
    C --> D[Core 执行器]
    D --> E[Octave 解释器]
    E --> F[结果捕获]
    F --> G[MCP 响应格式化]
    G --> H[返回给 LLM/用户]
    
    subgraph "错误处理路径"
    E -.->|执行错误| I[错误解析]
    I --> J[错误响应格式化]
    J --> H
    end

安全考量

• 代码隔离：每次执行在独立环境中运行
• 超时控制：防止无限循环或长时间占用
• 输入验证：防止注入攻击和危险操作
• 资源限制：限制内存和执行时间

依赖关系

资料来源：pyproject.toml:1-50

相关文档

• 资源模块文档
• 架构决策记录
• 项目根目录

概述

OCTAVE-MCP 实现了完整的文档规范化与标准化体系，确保 OCTAVE 文档在跨工具、跨代理、多步压缩流程中保持一致性和可互操作性。规范化与标准化是 OCTAVE v6.0.0 规范的核心设计目标，通过多层验证、自动修复和结构化输出机制实现。

核心组件架构

组件职责矩阵

工作流程图

graph TD
    A[原始 OCTAVE 文档] --> B[解析阶段]
    B --> C{验证检查}
    C -->|通过| D[emitter 输出]
    C -->|失败| E[repair 修复]
    E --> F[repair_log 记录]
    F --> G{修复后验证}
    G -->|通过| D
    G -->|仍失败| H[错误报告]
    
    D --> I[规范化文档]
    I --> J[标准化输出格式]
    
    style E fill:#ffcccc
    style D fill:#ccffcc
    style H fill:#ff6666

规范化机制

规范化层级

OCTAVE 的规范化发生在多个层级：

1. 词法层 (Lexer): 标准化 token 识别
2. 语法层 (Parser): 构建统一的 AST 结构
3. 语义层 (Validator): 验证语义一致性
4. 输出层 (Emitter): 生成规范化字符串

Emitter 模块

Emitter 负责将内部 AST 表示转换为符合规范的字符串输出。

核心功能：

• 将 Document、Block、Assignment、Section 等 AST 节点转换为 OCTAVE 格式字符串
• 保持操作符语义完整性
• 规范化空白和缩进

Repair 模块

Repair 模块提供自动修复功能，在验证失败时尝试修复常见问题。

修复层级 (RepairTier)：

RepairLog 模块

repair_log.py 维护修复操作的完整审计追踪。

@dataclass
class RepairEntry:
    """单条修复记录"""
    tier: RepairTier          # 修复层级
    field: str               # 修复的字段
    original: str            # 原始值
    repaired: str            # 修复后值
    reason: str              # 修复原因

@dataclass
class RepairLog:
    """修复日志容器"""
    entries: list[RepairEntry]
    timestamp: datetime
    document_name: str

标准化体系

规范版本控制

OCTAVE 文档通过 sentinel 标记规范版本：

OCTAVE::VERSION at document start

例如：OCTAVE::5.1.0 位于文档开头，启用前向兼容性检测和迁移路由。

Schema 验证

Schema 定义了文档的结构约束：

@dataclass
class SchemaDefinition:
    """Schema 定义"""
    name: str
    fields: list[FieldDefinition]
    constraints: list[Constraint]

@dataclass
class FieldDefinition:
    """字段定义"""
    name: str
    field_type: str
    required: bool
    default: Any

规范化配置文件

写入管道

write.py 实现了完整的写入验证管道：

graph LR
    A[write 输入] --> B[normalize 模式]
    B --> C[验证检查]
    C --> D{通过?}
    D -->|是| E[写入文件]
    D -->|否| F[返回错误/差异]
    E --> G[repair_log 更新]

写入模式

操作符标准化

OCTAVE 定义了标准化的操作符集合：

验证清单

规范化输出必须满足以下验证项：

异常处理

规范化过程中可能抛出以下异常：

最佳实践

1. 使用规范化模式测试: 在实际写入前使用 --mode normalize 验证
2. 检查 repair_log: 审查自动修复的变更记录
3. 保持版本一致: 确保文档 sentinel 版本与工具版本兼容
4. 验证 Schema: 对复杂文档使用 Schema 验证

相关资源

• 核心规范
• Schema 规范
• 压缩指南
• 验证工具

概述

OCTAVE（Olympian Common Text And Vocabulary Engine）模式验证系统是 octave-mcp 项目中负责确保 OCTAVE 文档符合规范的核心组件。该系统提供多层验证机制，从基础的语法检查到高级的语义约束验证，确保文档的结构完整性、类型安全性和语义正确性。

模式验证系统的主要职责包括：

• 语法验证：检查 OCTAVE 文档的标记结构、缩进、括号平衡等基础语法
• 语义验证：基于预定义模式验证文档的语义完整性
• 约束检查：验证文档是否符合指定模式的约束条件
• 错误修复：提供自动修复建议和修复日志

资料来源：src/octave_mcp/__init__.py:1-15

架构设计

验证系统分层架构

graph TD
    A[OCTAVE 文档] --> B[词法分析器 Lexer]
    B --> C[语法分析器 Parser]
    C --> D[验证器 Validator]
    D --> E{验证通过?}
    E -->|是| F[验证通过]
    E -->|否| G[修复建议 RepairLog]
    G --> H[重新验证]
    
    D --> I[Schema 定义]
    D --> J[Grammar 编译]
    I --> K[字段约束]
    J --> L[GBNF 语法]

模式验证系统采用分层架构设计，从底层的词法分析到高层的语义验证形成完整的验证管道。

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

公共 API 导出

验证系统的核心功能通过公共 API 暴露，供 MCP 工具和 CLI 工具调用：

# 验证相关类
Validator, TokenType, Token

# 修复相关类
RepairLog, RepairEntry, RepairTier, RoutingLog, RoutingEntry

# 异常类
ValidationError, LexerError, ParserError

资料来源：src/octave_mcp/__init__.py:10-40

验证核心组件

Validator 类

Validator 是模式验证的核心执行者，负责对解析后的文档进行深层验证。

主要验证功能：

RepairLog 修复日志

当验证失败时，系统生成详细的修复日志：

资料来源：src/octave_mcp/__init__.py:25-30

GBNF 语法编译器

编译器架构

GBNF（Generalized Backus-Naur Form）语法编译器将模式定义转换为可用于约束生成的语法规范。

graph LR
    A[Schema 定义] --> B[GBNFCompiler]
    B --> C[GBNF 语法字符串]
    C --> D[约束生成引擎]
    D --> E[结构化输出]

编译接口

from octave_mcp.core.grammar_compiler import compile_document_grammar, emit_grammar_for_schema

# 编译文档语法
grammar = compile_document_grammar(schema_name)

# 发射特定模式语法
schema_grammar = emit_grammar_for_schema(schema_def)

资料来源：src/octave_mcp/core/grammar_compiler/__init__.py:8-18

编译缓存机制

编译器实现了缓存机制以提升性能：

if schema_name in self._cache:
    return self._cache[schema_name]  # 返回缓存的语法

缓存键基于模式名称，编译结果在首次编译后被存储供后续使用。

MCP 资源集成

语法资源提供者

GrammarResourcesProvider 类为 MCP 协议提供语法资源访问接口：

class GrammarResourcesProvider:
    def __init__(self):
        self._cache = {}  # 语法缓存
    
    def _compile_grammar(self, schema_name: str) -> str:
        """编译指定模式的 GBNF 语法"""
        if schema_name in self._cache:
            return self._cache[schema_name]
        
        schema_def = load_schema_by_name(schema_name)
        compiler = GBNFCompiler()
        grammar = compiler.compile_schema(schema_def, include_envelope=True)
        self._cache[schema_name] = grammar
        return grammar

资料来源：src/octave_mcp/mcp/grammar_resources.py:50-80

资源模板

系统提供动态资源模板以支持按需访问语法：

模板采用 URI 参数化设计，将 {schema_name} 替换为有效模式名称（如 META、SKILL）即可获取对应语法。

验证配置与参数

验证配置文件

# 验证器参数定义
args = parser.parse_args()

# 验证配置项
profile = args.profile      # 验证配置文件
version = args.version     # OCTAVE 版本标签
schema = args.schema       # 模式名称
require_frontmatter = args.require_frontmatter  # 前置文档要求

支持的验证配置

资料来源：tools/octave-validator.py:15-35

CLI 验证工具

命令行接口

# 单文件验证
octave validate document.oct.md

# 目录批量验证
python3 octave-validator.py --path ./documents/

# 指定模式验证
python3 octave-validator.py document.oct.md --schema SKILL

验证输出格式

# 成功输出
OCTAVE_VALID

# 失败输出
OCTAVE_INVALID: <reason>

错误消息包含具体的问题描述和修复建议。

目录扫描模式

工具支持批量扫描目录中的所有 .oct.md 文件：

def scan_directory(path, profile, version, schema, require_frontmatter):
    """扫描目录并验证所有 OCTAVE 文档"""
    results = []
    for file in Path(path).glob("**/*.oct.md"):
        result = validate_octave_file(file, ...)
        results.append(result)
    return results

验证流程

完整验证管道

flowchart TD
    A[输入 OCTAVE 文档] --> B[文件格式检查]
    B --> C{格式正确?}
    C -->|否| D[返回格式错误]
    C -->|是| E[解析文档结构]
    E --> F[加载 Schema]
    F --> G[执行验证规则]
    G --> H{所有规则通过?}
    H -->|是| I[生成验证结果]
    H -->|否| J[记录失败条目]
    J --> K[生成修复建议]
    K --> I
    I --> L[返回 OCTAVE_VALID 或 OCTAVE_INVALID]

验证检查清单

根据 OCTAVE 核心规范，验证过程必须检查以下项目：

资料来源：src/octave_mcp/resources/primers/octave-mastery-primer.oct.md:35-40

模式约束系统

约束类型

资料来源：src/octave_mcp/resources/skills/octave-mastery/SKILL.md:45-55

CONTRACT 块约束

模式验证支持 CONTRACT 块用于声明文档级约束：

CONTRACT::HOLOGRAPHIC<latest@local>

概述

OCTAVE-MCP 的语法编译系统负责将 OCTAVE 文档的 schema 定义转换为 GBNF（Garden Point Normal Form）语法规则。GBNF 是一种上下文无关文法描述语言，常用于约束 LLM 的输出格式，确保生成的文档严格符合 OCTAVE 规范。

该编译系统的核心职责包括：

• 从 META 元数据提取字段约束信息
• 将 Holographic Pattern 模式转换为 GBNF 语法规则
• 支持 schema 级别的完整性编译
• 提供 MCP 工具接口供外部调用

资料来源：grammar_compiler/__init__.py:1-15

架构设计

目录结构

src/octave_mcp/core/
├── grammar_compiler/
│   ├── __init__.py      # 公共 API 导出
│   └── gbnf.py          # GBNF 编译核心实现
└── grammar/
    └── __init__.py      # 统一解析前门（向后兼容）

根据 ADR-0006 SR1-T1 的设计决策，GBNF 编译器从旧的 octave_mcp.core.grammar 模块迁移到专用的 grammar_compiler 包，以解决命名冲突问题。

资料来源：grammar/__init__.py:1-20

编译流程

graph TD
    A[OCTAVE Schema 定义] --> B[SchemaDefinition]
    B --> C[META 元数据]
    C --> D[CONTRACT 字段规范]
    D --> E[parse_contract_field]
    E --> F[HolographicPattern]
    F --> G[GBNF 规则生成]
    G --> H[完整 GBNF 语法]

核心组件

SchemaDefinition

SchemaDefinition 是 schema 编译的基础数据模型，包含以下属性：

FieldDefinition

字段定义包含字段的完整约束信息：

资料来源：gbnf_compiler.py:30-50

GBNF 编译器

compile_gbnf_from_meta 函数

该函数是 GBNF 编译的核心入口，接受 META 元数据字典并返回 GBNF 语法字符串。

def compile_gbnf_from_meta(meta: dict) -> str:
    from octave_mcp.core.holographic import HolographicPattern
    from octave_mcp.core.schema_extractor import FieldDefinition, SchemaDefinition

    schema_type = meta.get("TYPE", "UNKNOWN")
    
    # 创建 schema
    schema = SchemaDefinition(
        name=schema_type,
        version=str(meta.get("VERSION", "1.0")),
    )

CONTRACT 字段提取

当 META 中存在 CONTRACT 字段时，系统会进行以下处理：

1. 检测 CONTRACT 是否为字符串列表或 ListValue 对象
2. 调用 _extract_contract_field_specs 提取字段规范
3. 对每个字段调用 parse_contract_field 解析约束
4. 创建 HolographicPattern 包装约束条件
5. 将字段添加到 schema

contract = meta.get("CONTRACT")
if contract:
    field_specs = _extract_contract_field_specs(contract)
    for field_spec in field_specs:
        field_name, constraints = parse_contract_field(field_spec)
        pattern = HolographicPattern(
            example=None,
            constraints=constraints,
            target=None,
        )
        schema.fields[field_name] = FieldDefinition(
            name=field_name,
            pattern=pattern,
            raw_value=field_spec,
        )

资料来源：gbnf_compiler.py:40-70

MCP 集成

GrammarResources 类

MCP 服务器通过 GrammarResources 类提供 GBNF 语法资源访问：

def _compile_grammar(self, schema_name: str) -> str:
    if schema_name in self._cache":
        return self._cache[schema_name]

    schema_def = load_schema_by_name(schema_name)
    if schema_def is None:
        raise ValueError(f"Schema '{schema_name}' not found")

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

    self._cache[schema_name] = grammar
    return grammar

资源模板

系统提供动态语法访问的 URI 模板：

支持的 schema 名称包括 META、SKILL 等内置类型。

资料来源：grammar_resources.py:60-90

语法编译 MCP 工具

octave_compile_grammar 工具是 MCP 接口的主要入口，用于将 schema 约束编译为 GBNF 语法。

公共 API

grammar_compiler 包导出以下公共函数：

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

__all__ = [
    "compile_document_grammar",
    "emit_grammar_for_schema",
]

这些函数可在 MCP 工具和 CLI 中直接调用。

资料来源：grammar_compiler/__init__.py:13-18

向后兼容性

为保证平滑迁移，系统通过 PEP 562 的 __getattr__ 机制提供向后兼容：

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

def __getattr__(name: str) -> Any:
    """PEP 562 惰性加载"""
    if name in _DEPRECATED_GBNF_EXPORTS:
        warnings.warn(f"{name} 已弃用...", DeprecationWarning)
        # 从 grammar_compiler.gbnf 导入

访问这些符号时会发出单次 DeprecationWarning，但不会影响新用户使用统一前门。

资料来源：grammar/__init__.py:50-70

使用示例

Python API 使用

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)

CLI 使用

octave compile_grammar --schema META

总结

OCTAVE-MCP 的语法编译系统通过 GBNF 实现了一个关键能力：约束 LLM 输出格式。核心设计包括：

• 模块化架构：grammar_compiler 专用包避免命名冲突
• Schema 驱动：通过 META 元数据自动提取编译规则
• MCP 集成：通过资源模板和工具提供灵活访问
• 向后兼容：通过惰性加载确保平滑迁移

该系统使得 OCTAVE 文档的验证和生成过程可以被精确控制和可重复执行。

概述

MCP（Model Context Protocol）工具集是 octave-mcp 项目为 LLM 与 OCTAVE 文档交互提供的核心工具层。该工具集通过 MCP 协议暴露验证、写入、导出和语法编译等功能，使 AI 模型能够直接操作和理解 OCTAVE 语义的文档结构。

MCP 工具集的主要职责包括：

• 验证：对 OCTAVE 文档进行 Schema 校验、字段错误检测、修复建议生成
• 写入：通过完整验证管道写入文件，支持 dry-run 模式
• 导出：将项目投影到不同视图（规范、执行摘要、开发者、模板）
• 语法编译：将 Schema 约束编译为 GBNF 语法用于受限生成
• 资源管理：提供 Grammar 资源的动态访问接口

资料来源：README.md

架构设计

组件关系

graph TD
    A[MCP客户端] --> B[octave-mcp-server]
    B --> C[MCP工具层]
    
    C --> D[octave_validate]
    C --> E[octave_write]
    C --> F[octave_eject]
    C --> G[octave_compile_grammar]
    
    D --> H[Validator核心]
    E --> I[Parser + Validator]
    F --> J[Project引擎]
    G --> K[GBNF编译器]
    
    H --> L[Schema Registry]
    I --> L
    J --> L
    K --> L
    
    M[Grammar Resources] --> B
    M --> N[Schema → GBNF]

工具入口点

MCP 服务器通过以下方式启动，暴露所有工具：

资料来源：README.md

核心工具详解

octave_validate

功能：根据 Schema 验证 OCTAVE 文档。

校验范围：

• 字段错误识别
• 修复建议生成
• 区域覆盖率检查
• Schema 合规性验证

# MCP 调用示例
result = await mcp__octave__validate({
    "document": "===DOC===\nMETA:\n  TYPE::TEST\n===\n===END===",
    "schema": "META"
})

octave_write

功能：通过完整验证管道写入文件。

# Dry-run 模式验证
result = await mcp__octave__write({
    "path": "output.oct.md",
    "content": content,
    "mode": "normalize"
})

# 实际写入
result = await mcp__octave__write({
    "path": "output.oct.md", 
    "content": content
})

octave_eject

功能：将项目投影到不同的视图格式。

格式输出：markdown（默认）

result = await mcp__octave__eject({
    "path": "document.oct.md",
    "mode": "executive",
    "format": "markdown"
})

octave_compile_grammar

功能：将 Schema 约束编译为 GBNF（Grid Language Backus-Naur Form）语法，用于约束 LLM 生成。

result = await mcp__octave__compile_grammar({
    "schema_name": "SKILL"
})

编译后的 GBNF 语法可用于：

• 受约束的文本生成
• 结构化输出验证
• 语法引导的补全

资料来源：src/octave_mcp/core/grammar_compiler/__init__.py

CLI 命令行接口

除了 MCP 协议访问外，工具集还提供独立的 CLI 命令：

# 验证文档
octave validate document.oct.md

# 写入文档（支持 stdin）
octave write output.oct.md --stdin

# 导出项目
octave eject document.oct.md --mode executive --format markdown

资料来源：README.md

离线工具集

lint-octave.py

快速语法验证工具，用于 CLI 环境。

用法：

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

返回结果：

• OCTAVE_VALID - 验证通过
• OCTAVE_INVALID: <reason> - 验证失败及原因

检查项：

资料来源：tools/README.md

octave-validator.py

仓库级验证器，防止运行时与文档层的规范漂移。

用法：

# 验证单个文件
python3 octave-validator.py document.oct.md

# 扫描目录
python3 octave-validator.py --path ./docs

# 强制要求 YAML frontmatter
python3 octave-validator.py --path ./docs --require-frontmatter

# Schema 验证
python3 octave-validator.py document.oct.md --schema META

支持的 Profile：

验证内容：

• 必需的 envelope 标记（===NAME=== ... ===END===）
• Profile 相关的 YAML frontmatter 策略
• 核心解析与警告处理
• 最小 META 合理性检查（TYPE + VERSION 必填）
• 可选的 Schema 验证

资料来源：tools/octave-validator.py

格式转换工具

#### octave-to-json.py

将 OCTAVE 文档转换为 JSON 格式，用于系统集成。

用法：

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

特性：

• 保留语义操作符（合成、紧张、递进）
• 跟踪空行以支持往返保真
• 维护引号字符串
• 处理嵌套结构

#### json-to-octave.py

将 JSON 转换回 OCTAVE 格式。

用法：

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

特性：

• 恢复原始格式包括空行
• 重建语义操作符
• 保留文档结构

往返验证：

# 转换并还原
python3 octave-to-json.py input.oct.md | python3 json-to-octave.py > output.oct.md

# 验证完全一致
diff input.oct.md output.oct.md

资料来源：tools/README.md

资源 API

MCP 工具集还通过 Resources 接口提供 Grammar 访问：

静态资源

资源模板

动态资源模板支持运行时编译：

octave://grammars/{schema_name}

其中 {schema_name} 可替换为：

• META - 元数据 Schema
• SKILL - 技能文档 Schema
• 其他注册的有效 Schema 名称

缓存机制

Grammar 资源使用内存缓存：

graph LR
    A[请求 Grammar] --> B{缓存命中?}
    B -->|是| C[返回缓存]
    B -->|否| D[加载 Schema]
    D --> E[编译为 GBNF]
    E --> F[存入缓存]
    F --> C

资料来源：src/octave_mcp/mcp/grammar_resources.py

使用场景

适合使用 MCP 工具集的场景

不适合的场景

• 单步提示
• 自由格式文本
• 代码输出

资料来源：README.md

错误处理

验证错误

{
  "valid": false,
  "errors": [
    {
      "field": "META.VERSION",
      "message": "Missing required field",
      "suggestion": "Add VERSION::\"1.0.0\" to META block"
    }
  ]
}

写入错误

MCP 工具通过 SystemExit(1) 退出码表示失败：

if out.startswith("OCTAVE_INVALID"):
    raise SystemExit(1)

资料来源：tools/octave-validator.py

扩展与定制

自定义 Schema 验证

# 使用自定义 Schema
python3 octave-validator.py document.oct.md --schema custom-schema

集成到 CI/CD

# .github/workflows/validate.yml
- name: Validate OCTAVE documents
  run: |
    for f in $(find docs -name "*.oct.md"); do
      python3 tools/octave-validator.py "$f" --require-frontmatter
    done

相关模块

资料来源：src/octave_mcp/core/grammar_compiler/__init__.py

概述

神话压缩原理（Mythological Compression Principle）是 OCTAVE（Olympian Common Text And Vocabulary Engine）文档系统中的一种语义压缩方法。该原理利用大型语言模型预训练阶段已习得的神话学知识，将复杂概念映射为神话原型（Archetype），从而实现高效的语义压缩。

核心定义：

神话 = 预训练权重中已存在的压缩语义，通过激活丰富的概率分布来实现意义传递

资料来源：src/octave_mcp/resources/skills/octave-mythology/SKILL.md:1-10

神话压缩不是叙事性散文、仪式性语言或拟人化框架，而是：

资料来源：src/octave_mcp/resources/skills/octave-mythology/SKILL.md:11-15

• 功能性语义绑定（Functional semantic binding）
• 领域快捷方式（Domain shortcuts）
• 模式词汇（Pattern vocabulary）
• LLM 受众的压缩速记，而非修辞装饰

Pitfall Log / 踩坑日志

项目：elevanaltd/octave-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | last_activity_observed missing

3. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium

4. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | No sandbox install has been executed yet; downstream must verify before user use.

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | art_03a23ce84d234d528c722af265f34ebc | https://github.com/elevanaltd/octave-mcp#readme | release_recency=unknown