octave

OCTAVE MCP Server provides a deterministic document infrastructure for LLM pipelines. It offers a structured document format with canonical normalisation, schema validation, grammar compilation, and a suite of MCP tools to manage transformation logs and artifact quality. The server exposes an HTTP transport option and ships with commands to validate, write, and view documents through the OCTAVE pipeline. Core tools include octave_validate for schema validation and error reporting, octave_write for running documents through the full validation and normalisation pipeline, octave_eject for exporting different views (canonical, executive summary, developer, template), and octave_compile_grammar to generate constrained grammars for generation time control. These capabilities enable durable AI artifacts that survive multi-agent handoffs and audit requirements.

To use the server, run the octave-mcp-server process (optionally with HTTP transport) and then interact with the included tools. The project also documents how to configure the MCP server in client configurations (for Claude-style tooling or HTTP clients) and exposes a CLI for end-to-end workflows. Typical usage involves validating documents, normalising or repairing them, and then exporting preferred representations for downstream agents or auditors. The server is designed to be integrated into Python-based workflows and can be run as a standalone service or embedded behind an API gateway.

Prerequisites:

• Python 3.11 or newer
• Pip (comes with Python)
• Optional: a virtual environment tool (venv, virtualenv) for isolation

Step-by-step installation:

1. Create and activate a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # on Unix/macOS
venv\Scripts\activate     # on Windows

2. Install the OCTAVE MCP package from PyPI:

pip install octave-mcp

3. Run the MCP server locally with HTTP transport (example):

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

4. Optional: configure Claude/Desktop style clients with the following JSON snippet:

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

5. Verify installation by validating a simple document (example elsewhere in the docs):

octave validate sample.oct.md

Notes:

• If you need to run under a different environment (docker, uv, etc.), adjust the mcp_config accordingly.
• Ensure port availability and proper firewall rules when exposing HTTP transport.

Tips and common issues:

• Ensure Python 3.11+ is installed; some environments may default to an older Python version.
• If octave-mcp-server fails to start, check that the port is not in use and that the Python environment has write permissions to the working directory.
• The server supports HTTP transport; you can point clients to http://<host>:8080 by default. You can customize the port with --port.
• When using the Claude configuration snippet, keep the client config in sync with the server command to avoid misalignment.
• The MCP tools (octave_validate, octave_write, octave_eject, octave_compile_grammar) each expose specific capabilities for validation, transformation, and grammar generation; consult the docs for exact flags and modes.
• If you encounter schema or grammar errors, the validation receipts include actionable repair suggestions and zone coverage information.