Vouchfx.Mcp
1.1.0
Prefix Reserved
dotnet tool install --global Vouchfx.Mcp --version 1.1.0
dotnet new tool-manifest
dotnet tool install --local Vouchfx.Mcp --version 1.1.0
#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.yamlfile 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.yamlsuite 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 feedsscaffold_suiteunchanged. Invokes pinnedvouchfx 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.yamlskeleton from structured step types, ids, and an environment outline (Generator). Free text is host-LLM only; invokes pinnedvouchfx scaffold --intent.run_suite— runs a suite through the installedvouchfxCLI, 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 asexplain_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 cataloguedVFX-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, orstep:<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 ownvouchfx schemaexport.normalize_suite— returns a suite's canonical formatting (schema-derived key order, one consistent quoting and block-layout style) alongside the fullvalidate_suiteresult. 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 consumingexplain_run's summary. Takes therunIdrun_suitereturns. Filters by event type and step id before paging, solimit(default 200, max 2000) bounds matching events rather than lines scanned, and returns an opaquenextCursorwhile 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\uXXXXand 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, andrun_suite's ownremediationHintfor the run, so a refusal's reason survives after therun_suiteresult is gone. The same recordexplain_runandget_run_eventsresolve arunIdthrough, so it can never disagree with them. CLI-free, and never takes the run lock.list_runs— pages the run registry newest first, filtered bylabel(key=valueor a barekey) and/orsince, returningrunId/status/outcome/startedAt/finishedAtper run plus the same opaquenextCursorcontractget_run_eventsuses (limitdefault 200, max 2000). CLI-free, and never takes the run lock.cancel_run— asks an in-flight run to stop through exactly the mechanismrun_suitealready uses: the engine's stdin is closed for a graceful shutdown, and only after the grace period is the process tree killed. Returnscancelledoralready_finished(the latter is a normal answer, not an error); a cancelled run is reportedInconclusive, neverFail. 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 arunningentry 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. Unlikeexplain_run, whose response-size tiers shrink itsattemptsarrays first, this tool never shortens the list — it drops per-attempt evidence text instead and says so. Each attempt'soutcomeis its own three-value vocabulary (matched/unmatched/error), never the four-way verdict taxonomy. The step's declaredtimeoutMsanddeclaredVerifyMode(IMMEDIATE, the engine's default, when the suite named none) come from its ownstep-startedevent, kept apart from the run-evidencedverifyMode. 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 carriespartial: trueand agapsarray 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'senvironment-errorevents named (role: "unclassified",health: nullmeaning not observed); it has no container logs at all —logsis 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.containerandtailLinesare 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
- Source: https://github.com/tomas-rampas/vouchfx-mcp (Apache-2.0)
- The engine this server wraps: https://github.com/tomas-rampas/vouchfx
- Documentation: https://vouchfx-mcp.vouchfx.io/
- Engine documentation: https://vouchfx.io/
Support. NuGet package versions are independent of the server's fixed
serverInfo.version(0.1.0) reported during the MCP handshake.vouchfx-mcpexposes 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 ofvouchfx --version.
| Product | Versions 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. |
This package has no dependencies.
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.