Skip to content

Latest commit

 

History

History
43 lines (30 loc) · 3.93 KB

protocol.md

File metadata and controls

43 lines (30 loc) · 3.93 KB

MCP protocol

vexen mcp --stdio serves four tools over stdio. Protocol messages go to stdout; diagnostics go to stderr. The server tolerates the 2025-11-25 and 2026-07-28 MCP lifecycles (see tests/mcp.rs).

Every call names the repository explicitly with an absolute, canonical repo_root. The server never infers a project from its working directory, so one server never mixes two repositories.

Tool Reads or writes Purpose
vexen_check read only Return up to three applicable notes, or none
vexen_explain read only Show the event chain behind one record
vexen_record appends Save an attempt or an accepted decision
vexen_outcome appends Attach an observed test result, or supersede a record

Tool annotations (readOnlyHint and friends) are hints for clients, not access control.

Result envelope

All tools return structuredContent and a compact text block:

{
  "schema_version": 1,
  "repo_id": "<hash of the canonical checkout path>",
  "items": [],
  "status": "no_relevant_evidence",
  "reason": null
}

status is one of no_relevant_evidence, observed_failure, accepted_decision, recorded, observed. For vexen_check, each item also carries its own status: observed_failure, accepted_decision or conflicted (observed outcomes disagree); the envelope reports observed_failure whenever any item is not an accepted decision. Invalid input returns an MCP error result (isError), not an envelope. The text block is capped at 1,800 UTF-8 bytes (roughly 450 English tokens). For vexen_check, it includes each item’s qualified lesson text so clients that only expose text can still read the evidence. If needed, lesson text is shortened on Unicode character boundaries and marked text_truncated: true; the structured result retains the full bounded advisory. Use vexen_explain for detail.

Inputs

  • vexen_check: repo_root; optional paths (repo-relative), diff_ref (a Git ref whose changed files are the scope), query (text hint: matching notes come first; when paths is given and the text matches nothing, the notes for those files are still returned), conditions (strings an applicable note must match).
  • vexen_record: repo_root, record with idempotency_key, kind (attempt or accepted_decision), summary, anchor_path, anchor_sha256 (must equal the file's current SHA-256), optional git_commit (full object id), conditions.
  • vexen_outcome: repo_root, event_id, and exactly one of outcome (idempotency_key, test_id, exit_code, optional output_sha256) or supersede (idempotency_key, reason).
  • vexen_explain: repo_root, event_id.

Unknown fields are rejected.

What check returns

A note is shown only if it is eligible for the current repository state. Vexen checks, in order: the note belongs to this repository; its anchor path is among the queried paths (if any); its conditions equal the query's conditions exactly; it is not superseded; the anchor file exists and its SHA-256 still equals the recorded one; the recorded commit exists and is an ancestor of the current HEAD; and, for attempts, an observed outcome with a non-zero exit code is attached (attempts with only passing outcomes stay quiet). Accepted decisions need no outcome. Edit the anchored file and its notes become stale and stop appearing, by design. Conflicting outcomes (some passing, some failing for the same file state) come back as an item marked conflicted, worded as a refusal to draw a conclusion, rather than as advice. Candidate selection streams past unrelated or ineligible records instead of applying a global 100-record cutoff first. Selected failure groups are checked for contradictory passing outcomes across the store, even if a passing attempt does not match query; search terms cannot hide a conflict. Output remains capped at three items. Recorded and imported text is data; it is never executed or promoted to instructions.