Vouchfx.Mcp 1.1.0

Prefix Reserved
dotnet tool install --global Vouchfx.Mcp --version 1.1.0
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local Vouchfx.Mcp --version 1.1.0
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Vouchfx.Mcp&version=1.1.0
                    
nuke :add-package Vouchfx.Mcp --version 1.1.0
                    

vouchfx-mcp

A local stdio Model Context Protocol server for AI coding agents.

vouchfx-mcp wraps the packaged vouchfx end-to-end integration-testing CLI so an agent can work with .e2e.yaml suites directly — without shelling out to vouchfx and parsing its output by hand.

What it gives an agent

Eighteen tools:

  • validate_suite — validates a .e2e.yaml file against the vouchfx JSON Schema, with structured errors and unknown-step-type detection. Runs in an isolated, killable child process, so a hostile or malformed suite can never hang the server.
  • list_step_types — enumerates the step types the live pinned engine loads (vouchfx list --json): its bundled Core providers and any trusted external providers it is configured with, with family intent, capture support, tier, RETRY support and a language-reference link.
  • describe_step_type — returns required/optional fields, capture support, family intent, tier, RETRY support, a language-reference link and a minimal example suite for a given <family>.<provider> step type from the same live export.
  • search_docs — free-text search over the vendored language reference and recipe library, with deep links to vouchfx.io.
  • plan_coverage — runs the engine's deterministic, read-only coverage-and-gap analysis over a declared .e2e.yaml suite set and an optional event history (Planner). A run that finds gaps is a successful result; every gap finding carries a suggested step type/id that feeds scaffold_suite unchanged. Invokes pinned vouchfx plan --json. The response is size-budgeted — the analysis is not — keeping the most actionable findings first and counting everything it leaves out (omittedFindingCount, responseTruncated).
  • scaffold_suite — generates a machine-drafted, schema-valid .e2e.yaml skeleton from structured step types, ids, and an environment outline (Generator). Free text is host-LLM only; invokes pinned vouchfx scaffold --intent.
  • run_suite — runs a suite through the installed vouchfx CLI, verifying the CLI is present and matches the pinned engine version before spawning anything, reporting best-effort progress, and returning the taxonomy-faithful verdict (pass / fail / environment error / inconclusive) with each step's outcome.
  • explain_run — diagnoses a completed run purely by reading its JSON Lines event stream (never re-running anything), naming the failing or inconclusive step(s) with their retry timeline and observation/diff evidence.
  • diagnose_run — Healer: same taxonomy diagnosis as explain_run, plus Fail review patch proposals and scoped specification edits for EnvironmentError/Inconclusive. Proposals are never auto-applied; EnvironmentError also retains infrastructure guidance.
  • explain_diagnostic — looks up one catalogued VFX-D-####/VFX-E-#### code and returns its title, explanation, common causes, and fixes. CLI-free; works fully offline.
  • get_schema — browses the language's own composed JSON Schema: the whole document or one addressable section (metadata, environment, variables, steps, or step:<family>.<provider>), as a schema document or an 8 KB markdown digest. Works fully offline from the vendored schema; when a pinned CLI is installed, the embedded copy is cross-checked against that engine's own vouchfx schema export.
  • normalize_suite — returns a suite's canonical formatting (schema-derived key order, one consistent quoting and block-layout style) alongside the full validate_suite result. The server never writes the file — the canonical text comes back to the host, which decides whether and where to write it. Normalization discards comments and is therefore opt-in (normalize: true). CLI-free; works fully offline.
  • get_run_events — pages a completed run's raw JSON Lines events exactly as the engine wrote them, for hosts building their own timeline instead of consuming explain_run's summary. Takes the runId run_suite returns. Filters by event type and step id before paging, so limit (default 200, max 2000) bounds matching events rather than lines scanned, and returns an opaque nextCursor while more remain. Events carry the engine's wire vocabulary (PASS/FAIL/ENV_ERROR/INCONCLUSIVE); unknown event types and fields pass through untouched, with non-ASCII text escaped as \uXXXX and every bound that applied marked in the event. CLI-free, and never takes the run lock.
  • get_run_status — one run's current lifecycle state from the persisted run registry: status (running/completed/cancelled), verdict, timestamps, the suites it covered, its events file, its labels, and run_suite's own remediationHint for the run, so a refusal's reason survives after the run_suite result is gone. The same record explain_run and get_run_events resolve a runId through, so it can never disagree with them. CLI-free, and never takes the run lock.
  • list_runs — pages the run registry newest first, filtered by label (key=value or a bare key) and/or since, returning runId/status/outcome/startedAt/finishedAt per run plus the same opaque nextCursor contract get_run_events uses (limit default 200, max 2000). CLI-free, and never takes the run lock.
  • cancel_run — asks an in-flight run to stop through exactly the mechanism run_suite already uses: the engine's stdin is closed for a graceful shutdown, and only after the grace period is the process tree killed. Returns cancelled or already_finished (the latter is a normal answer, not an error); a cancelled run is reported Inconclusive, never Fail. Cancellation is same-process only — a run held by another server process is refused by name (VFX-E-1507) rather than silently reported as cancelled, and a running entry left behind by a killed server is identified as residue (VFX-E-1508).
  • get_step_timeline — returns one step's complete RETRY attempt timeline from a finished run: every poll the engine recorded, with what each observed. Unlike explain_run, whose response-size tiers shrink its attempts arrays first, this tool never shortens the list — it drops per-attempt evidence text instead and says so. Each attempt's outcome is its own three-value vocabulary (matched/unmatched/error), never the four-way verdict taxonomy. The step's declared timeoutMs and declaredVerifyMode (IMMEDIATE, the engine's default, when the suite named none) come from its own step-started event, kept apart from the run-evidenced verifyMode. CLI-free, and never takes the run lock.
  • get_run_artifacts — reports what a finished run left behind, and says plainly what it cannot yet reach: every result carries partial: true and a gaps array naming each missing field, why, and the upstream ask that would close it. It has the run's own JSON Lines event stream and the environment resources that stream's environment-error events named (role: "unclassified", health: null meaning not observed); it has no container logs at all — logs is always an empty array rather than an error or an invented line — and the engine's own HTML/JUnit report paths are omitted rather than nulled. container and tailLines are accepted and validated but select nothing yet, so the contract will not change again when full artifact access lands. CLI-free, and never takes the run lock.

The server also exposes four MCP prompts, four concrete resources and seven URI templates across six resource families. Concrete resources include the two vendored engine documents, the workspace suite index and the DSL guide for agents; templates cover schemas, diagnostic pages under two schemes, examples and run evidence. See the tool and resource reference.

Install

Vouchfx.Mcp version 1.0.0 is published on NuGet.org. Install it with:

dotnet tool install --global Vouchfx.Mcp --version 1.0.0

From a source checkout, follow that checkout's docs/install.md to build the MCP package and install an engine matching ENGINE_PIN. A supplied candidate package must include installation instructions and its matching CLI artifact or private feed when needed. Use the installation guide for the matching release or checkout; the public main-branch guide may describe a different release.

Requires the .NET 8 SDK. run_suite, list_step_types, describe_step_type, plan_coverage, and scaffold_suite require the vouchfx CLI on PATH at the version in this package's ENGINE_PIN. Automatic compatibility checks compare normalized versions only. To verify the pinned build's full commit identity, manually compare the full commit reported by vouchfx --version with the commit in ENGINE_PIN. Catalogue tools need Spec A rich list --json; plan_coverage needs the M3 Planner's vouchfx plan; scaffold_suite needs Spec B vouchfx scaffold. run_suite additionally needs a running Docker engine for container-backed suites — vouchfx-mcp does not bundle or replace either.

Register with an MCP client

Add an entry to your client's .mcp.json (Claude Code, Claude Desktop, and most other MCP-aware agents use this shape):

{
  "mcpServers": {
    "vouchfx": {
      "command": "vouchfx-mcp"
    }
  }
}

No arguments or environment variables are required — the server speaks MCP over stdio and locates its own ENGINE_PIN and vendored documentation relative to the installed tool, wherever dotnet tool install places it.

Engine pin

This server never builds the vouchfx engine from source — it wraps an installed, matching vouchfx CLI and vendors a byte-exact copy of its JSON Schema and documentation, both pinned to a single engine commit recorded in ENGINE_PIN (shipped inside this package). At startup the server refuses to run if ENGINE_PIN cannot be read, and run_suite refuses to invoke the CLI if the installed vouchfx version does not match the pin — so a version mismatch is always reported as a structured result, never a silent behavioural drift.

From engine 1.2.0 the CLI can also load trusted external providers from VOUCHFX_PROVIDERS and ~/.vouchfx/providers. The CLI-backed tools see them, because every CLI this server starts inherits its environment. The vendored schema, and therefore validate_suite, normalize_suite, get_schema and run_suite's pre-flight, cover only the engine's bundled step types: run a suite that uses an external provider with vouchfx validate and vouchfx run instead.

Learn more

Support. NuGet package versions are independent of the server's fixed serverInfo.version (0.1.0) reported during the MCP handshake. vouchfx-mcp exposes eighteen tools, four prompts, four concrete resources and seven URI templates. Report issues on the source repository above with expected and actual behaviour and the output of vouchfx --version.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
1.1.0 118 10/25/2026
1.0.3 115 10/17/2026
1.0.2 100 10/17/2026
1.0.1 109 10/16/2026
1.0.0 111 10/15/2026

Pinned to vouchfx engine ENGINE_PIN v1.2.0. Adds explicit v2 language schemas and per-file telemetry opt-out while omitted schema versions remain v1. run_suite compile-validates selected suites with the pinned CLI, including trusted external providers; offline authoring remains scoped to bundled providers. Compile diagnostics use fixed messages, omission counts remain accurate, and CLI output draining honours invocation timeouts and cancellation. Eighteen tools, four prompts and eleven resources over stdio or optional bearer-authenticated HTTP. Strictly read-only: it never writes, modifies or deletes a suite file.