Provides tools for posting structured review comments to GitHub Pull Requests.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@HestAI-MCP start a new session for implementing user login"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Governance and session management layer of the HestAI ecosystem — pre-release, B1 Foundation phase
HestAI-MCP is the governance and session management layer of the HestAI ecosystem — a five-system stack for AI-assisted software development. It is currently pre-release at B1 (Foundation phase): functional and in daily use, but still discovering its full scope.
Its role in the ecosystem: knows WHO agents are and HOW they should behave — provider-agnostic. It does not spawn CLIs or know which model runs underneath; that is the workbench's job.
What it does today:
Injects system governance (.hestai-sys/) into projects at runtime — agent constitutions, skills, rules — without copy-pasting between projects
Tracks sessions (clock_in/clock_out) and archives transcripts in OCTAVE format
Bootstraps agent binding (bind)
Posts structured review comments to GitHub PRs (submit_review)
What it's building toward: persistent memory across sessions (the context feedback loop requires context_update, planned Phase 4), Orchestra Map dependency tracking (ADR-0034 MVP validated, automation not yet built), and document routing (document_submit, Phase 4).
Where it fits: built on octave-mcp (document format foundation), works alongside odyssean-anchor-mcp (identity binding ceremony, merger planned), debate-hall-mcp (structured deliberation), and hestai-workbench (execution/UI layer).
Related MCP server: ControlKeel
YOUR PROJECT (using HestAI)
├── .hestai-sys/ # TIER 1: SYSTEM (read-only, injected by MCP at runtime, gitignored)
│ ├── CONSTITUTION.md # Immutable laws
│ ├── governance/ # Rules, North Stars
│ ├── library/
│ │ ├── agents/ # Agent definitions
│ │ ├── skills/ # Capability definitions
│ │ └── patterns/ # Reusable solution patterns
│ └── templates/ # Document templates
│
├── .hestai/ # TIER 2: PROJECT GOVERNANCE (committed, PR-controlled)
│ ├── north-star/ # Project North Star
│ ├── decisions/ # Architectural Decision Records
│ ├── rules/ # Project-wide standards
│ └── state/ → .hestai-state/ # TIER 3: WORKING STATE (symlink, gitignored)
│ ├── context/ # Living context files (generated by clock_in)
│ ├── sessions/
│ │ ├── active/ # Current sessions
│ │ └── archive/ # Completed sessions (OCTAVE compressed)
│ └── reports/ # Generated reports
│
├── docs/ # Developer documentation (ADRs, guides)
└── src/ # Your codeNote for AI Agents: Even though .hestai-sys/ is gitignored, you can still read it! Use:
Read .hestai-sys/README.md - Start here for governance overview
Glob .hestai-sys/**/*.md - Discover all governance files
All .hestai/state/ writes go through MCP tools. No direct file creation.
Agent → MCP Tool (clock_in/clock_out/bind) → System Steward → FilesThis prevents:
Multi-agent conflicts
Governance drift
Inconsistent documentation
Tier | Location | Git | Mutability |
1: System Governance |
| Gitignored | Read-only (MCP-injected at runtime) |
2: Project Governance |
| Committed | Human via PR |
3: Working State |
| Gitignored | Via MCP tools (clock_in/clock_out) |
For detailed architecture, see docs/ARCHITECTURE.md.
Tool | Purpose | Status |
| Start session, create session dir, return context paths | Implemented |
| End session, compress transcript to OCTAVE, archive | Implemented |
| Lightweight agent binding bootstrap | Implemented |
| Post structured review comments to GitHub PRs | Implemented |
| Route docs to correct location | Planned (Phase 4) |
| Update context with conflict resolution | Planned (Phase 4) |
.oct.md)Agent constitutions
Governance rules
North Stars
Context files (PROJECT-CONTEXT, etc)
Session archives
.md)Developer guides
ADRs
READMEs
Setup instructions
Decision: Primary audience AI agents? → .oct.md. Human developers? → .md
# Clone and install (uv recommended)
git clone https://github.com/elevanaltd/HestAI-MCP.git
cd hestai-mcp
uv sync --all-extras
# Run tests
.venv/bin/python -m pytest
# Check quality
.venv/bin/python -m ruff check src tests scripts && .venv/bin/python -m mypy src && .venv/bin/python -m black --check src tests scriptsDefault behavior (simplest): .hestai-sys is created in the current working directory where the server runs:
{
"mcpServers": {
"hestai": {
"command": "python",
"args": ["-m", "hestai_mcp.mcp.server"]
}
}
}Optional override: Control location via HESTAI_PROJECT_ROOT env var:
# .env file (optional - only if you want a custom location)
HESTAI_PROJECT_ROOT=/path/to/shared/locationOpt-in: Governance injection only runs if the project has a
.hestai/directory orHESTAI_GOVERNANCE_ENABLED=truein.env. New projects must opt in explicitly.
Design: Follows the debate-hall pattern - creates governance in CWD by default, just like
./debates/. Each project/worktree gets its own.hestai-sysunless explicitly configured otherwise.
Documentation placement is governed by rules injected to .hestai-sys/governance/rules/ (source: src/hestai_mcp/_bundled_hub/governance/rules/):
Rule | Document | Purpose |
Visibility |
| Where docs belong (product placement) |
Hub Authoring |
| What goes in system governance ( |
Naming |
| How to name files |
Format | In visibility-rules | When to use OCTAVE vs Markdown |
✅ Phase 0-2: Foundation, porting, MCP server
✅ Phase 2.5: Hub architecture, bundled governance
✅ Odyssean Anchor: Agent identity binding (ADR-0036)
✅ Clock tools: Session lifecycle with AI synthesis
✅ Submit review: GitHub PR review comment tool
🚧 Phase 3: Single writer tools (document_submit, context_update)
🚧 Phase 5: Fractal refactor and modularization (ADR-0184)
docs/ARCHITECTURE.md - Detailed architecture
Apache License 2.0 - see LICENSE for details.
"Odyssean Anchor" is a registered trademark of Shaun Buswell - see docs/trademarks.md for usage guidelines.
Compile OCTAVE schema or contract to constraint grammar. Supports GBNF (llama.cpp) and JSON Schema (vLLM) output formats. Provide either a builtin schema name or inline OCTAVE content.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format: gbnf (default) or json_schema. | |
| schema | No | Builtin schema name to compile grammar from (e.g., 'SKILL', 'META'). Mutually exclusive with content. | |
| content | No | Inline OCTAVE document content with META.CONTRACT or FIELDS block. Mutually exclusive with schema. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions input and output format options but does not disclose behavioral traits like side effects, error handling, or performance implications. The information is adequate but not enhanced beyond schema details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, covering purpose, supported outputs, and input methods without any wasted words. It is well-structured and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a compile tool with three parameters and no output schema, the description covers essential usage. It lacks a description of the return value (the compiled grammar), which is a minor gap given the tool's output-oriented nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds context about the format parameter (associating GBNF with llama.cpp and JSON Schema with vLLM) but does not significantly enhance understanding beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compiles OCTAVE schemas/contracts into constraint grammars, distinguishing it from sibling tools (octave_eject, octave_validate, octave_write) which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies the supported output formats (GBNF, JSON Schema) and input options (builtin schema vs inline content), providing clear context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Eject OCTAVE content with projection modes. Supports canonical, authoring, executive, and developer views. Can generate templates when content is null. Output formats: octave, json, yaml, markdown, gbnf.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Projection mode: canonical (full), authoring (lenient), executive (STATUS,RISKS,DECISIONS), developer (TESTS,CI,DEPS) | |
| format | No | Output format (gbnf exports llama.cpp GBNF grammar) | |
| schema | Yes | Schema name for validation or template generation | |
| content | No | OCTAVE content to eject (null for template generation) | |
| sections | No | List of section identifiers to extract (Issue #341). When provided, only matching sections + META are included in output. Accepts flexible formats: '§3', '3', '§3::CAPABILITIES' all match section 3. Non-existent sections are silently omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, description discloses key behavioral traits: supports multiple projection modes, output formats, template generation, and sections parameter with flexible matching and silent omission. Does not cover permissions or side effects but provides substantial behavioral context beyond basic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two effective sentences: first defines primary action, second summarizes modes, template generation, and output formats. No wasted words, information is front-loaded and accessible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, description covers all parameters and their behavior (modes, formats, sections, template generation). It lacks details on return values or error cases, but is sufficient for a conversion tool. Missing only minor context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds significant value by explaining modes (e.g., 'executive: STATUS,RISKS,DECISIONS'), format implications (gbnf exports llama.cpp GBNF grammar), and sections parameter behavior (flexible matching, silent omission). This enriches the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool ejects OCTAVE content with projection modes, listing specific modes and output formats. It distinguishes from siblings (compile_grammar, validate, write) by focusing on projection and conversion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings. However, the description hints at template generation when content is null, providing some context. Lack of usage alternatives or exclusions reduces clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schema check + repair suggestions for OCTAVE content. Validates content against schema, returns canonical form with optional repairs. Focus on I3 (Mirror Constraint) and I5 (Schema Sovereignty).
| Name | Required | Description | Default |
|---|---|---|---|
| fix | No | If True, apply repairs to canonical output. If False (default), suggest repairs only. | |
| schema | Yes | Schema name to validate against (e.g., 'META', 'SESSION_LOG') | |
| compact | No | If True, return warning/error counts instead of full lists. Saves tokens. | |
| content | No | OCTAVE content to validate (mutually exclusive with file_path) | |
| profile | No | Validation strictness profile: STRICT (full compliance, reject unknown), STANDARD (default), LENIENT (warnings not errors, auto-repairs), ULTRA (minimal validation). | |
| diff_only | No | If True, return diff instead of canonical content. Saves tokens when validating. | |
| file_path | No | Path to OCTAVE file to validate (mutually exclusive with content) | |
| grammar_hint | No | If True and validation returns INVALID, include compiled GBNF grammar in response to guide correction. | |
| debug_grammar | No | If True, include compiled regex/grammar in output for debugging constraint evaluation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses validation and optional repairs, focus on specific constraints, but does not detail side effects, permissions, or whether modifications are persisted. Some behavioral context is present via parameters like fix and profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences concisely convey purpose, behavior, and focus areas without unnecessary detail. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no output schema, the description effectively summarizes tool behavior (validation, repair, canonical form) and key features (diff, grammar hints). It covers the main use cases but could elaborate on return value structure and error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by linking parameters to purpose (e.g., 'fix' for repairs, 'profile' for strictness) and highlighting focus on I3/I5 constraints, providing meaningful context beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs schema checking and repair suggestions for OCTAVE content, specifies it validates against schema and returns canonical form, and identifies focus on I3 and I5 constraints. This distinguishes it from siblings like compile_grammar and eject.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description does not mention prerequisites, scenarios, or when not to use it. Siblings are not referenced for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified entry point for writing OCTAVE files. Handles creation (new files) and modification (existing files). Use content for full payload, changes for delta updates. Omit both content and changes to normalize an existing file in-place. Replaces octave_create and octave_amend.
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Schema name for validation (I5). Common schemas: META, SKILL, CRS_REVIEW, COGNITION_DEFINITION, DEBATE_TRANSCRIPT. Use 'frozen@<hash>' or 'latest' for hermetic resolution. If an unknown schema is provided, the response includes available_schemas. | |
| changes | No | Dictionary of field updates for existing files. Each value is either a bare value (full replacement, default) or a $op descriptor: {"$op":"DELETE"} removes the target; {"$op":"APPEND","value":x} pushes x (or each item of list x) onto the end of an array target; {"$op":"PREPEND","value":x} unshifts onto the front of an array; {"$op":"MERGE","value":{...}} deep-merges into a block target, preserving unmentioned children (use inner $op:DELETE to remove). Op/target-type mismatches return E_OP_TARGET_MISMATCH; missing paths return E_UNRESOLVABLE_PATH (no auto-create, I3); malformed descriptors return E_INVALID_OP_DESCRIPTOR. Paths support: top-level KEY, META.FIELD, PARENT.CHILD into a top-level Block, and §N.KEY / §N::NAME.KEY into Sections. (GH#373) | |
| content | No | Full content for new files or overwrites. Accepts raw OCTAVE or a single markdown fenced code block. Mutually exclusive with changes. | |
| dry_run | No | Alias for corrections_only. If True, return corrections/diff without writing to disk (default: false). | |
| lenient | No | If True, enable deterministic lenient parsing + optional schema repairs. Default: false (strict parsing). | |
| base_hash | No | Expected SHA-256 hash of existing file for consistency check (CAS). | |
| mutations | No | META field overrides (applies to both modes). | |
| target_path | Yes | File path to write to | |
| format_style | No | Output formatting style for canonical emission. 'preserve' (Strategy A, GH#377): span-aware preserve mode — clean nodes slice from baseline_bytes, dirty/repaired nodes re-emit canonically. Diff footprint ≤0.5% of file size on single-key edits against representative documents. Subsumes GH#248 mixed annotation form drift. 'expanded': lift inline-map shapes (KEY::[K::V,...]) into Block form before emit. 'compact': collapse atom-only Blocks (no comments, arity-bounded) into inline-list-of-InlineMap form. Comment-bearing subtrees vetoed with W_COMPACT_REFUSED (I3 Mirror Constraint, I4 Auditability). DEPRECATED v1.13.0: Passing format_style=null explicitly emits a DeprecationWarning; the default will change from full canonical re-emit to 'preserve' in v1.14.0. To keep canonical re-emit past the flip, pass 'expanded' explicitly. To opt in to the new default early, pass 'preserve'. Omitting the parameter accepts the future default silently. | |
| grammar_hint | No | If True and validation returns INVALID, include compiled GBNF grammar in response to guide correction. | |
| debug_grammar | No | If True, include compiled regex/grammar in output for debugging constraint evaluation. | |
| corrections_only | No | If True, return corrections/diff without writing to disk (dry run). | |
| parse_error_policy | No | Policy when tokenization/parsing fails in lenient mode: "error" (default) or "salvage". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses behavioral traits such as handling creation and modification, detailed op descriptors for changes, error codes, format_style options with deprecation, dry_run behavior, lenient parsing, and parse_error_policy. This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured, starting with a summary and then detailing modes, deprecation, and options. Every sentence adds value, though the op descriptor details could be slightly more concise. Still efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (13 params, nested objects, no output schema), the description is very complete. It covers use cases, op structure, error handling, formatting, and deprecation. It does not explain return values, but that is acceptable without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline is 3. The description adds significant extra context beyond schema descriptions, explaining the relationship between content and changes, op descriptors, format_style future changes, and the effect of lenient and parse_error_policy. This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is the unified entry point for writing OCTAVE files, handling both creation and modification. It explicitly distinguishes itself by noting it replaces octave_create and octave_amend, and describes different usage modes (content, changes, normalize).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use content vs changes vs omit both, and that it replaces older tools. However, it does not explicitly contrast with sibling tools like octave_validate or octave_compile_grammar, leaving some ambiguity about when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.2.0octave_compile_grammaroctave_ejectoctave_validateoctave_writeEach tool has a distinct, non-overlapping purpose: grammar compilation, content ejection, validation, and writing. No ambiguity.
All tools follow a consistent 'octave_verb' pattern with clear action nouns (compile_grammar, eject, validate, write).
4 tools is well-scoped for a domain-specific server covering compilation, validation, output, and file manipulation.
The tool set covers the core lifecycle of OCTAVE content: compile, validate, output (eject), and write (create/modify/normalize). No obvious gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Governance layer for AI coding agents: knowledge-graph grounding, session audit, policy controls.
Deterministic AI code review, with an audit record. Governance inside the agent loop.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/elevanaltd/HestAI-MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
