vouchfx-mcp GitHub
Documentation / VFX-D-1106

VFX-D-1106

Title

LiveSchemaMismatch

Explanation

get_schema found that the vouchfx CLI installed on your PATH emits a composed JSON Schema that differs from the vendored schema this MCP server embeds. This is a diagnostic, not an error: the call succeeded and returned a usable schema. The document you received is the vendored one — the copy taken byte-for-byte from the engine repository at the commit named in this server's ENGINE_PIN, and the same copy validate_suite evaluates your suites against, so the tool that serves the contract and the tool that enforces it can never disagree with each other.

The comparison ignores formatting (whitespace, indentation, and line endings), so this code never fires merely because the CLI pretty-prints its output differently from the committed file. It is sensitive to property ORDER, and deliberately so: an engine that emits the same keywords in a different order has changed its schema generator, which is itself worth telling you about.

The practical consequence: a suite you author strictly against the schema get_schema returned may still be rejected (or accepted where you did not expect it) by the engine you actually run it with, because the two describe different versions of the language.

The matching pinned engine emits redirected stdout and stderr as UTF-8 without a BOM. This server uses that same byte contract for schema, scaffold and live run output, independently of the Windows console code page or how the host launches its child. Unicode labels such as Café — naïve ✓ remain intact. Changing chcp is unnecessary. The comparison preserves character differences; an em-dash changed to a hyphen is schema drift rather than an accepted console substitution.

Common causes

  • The globally-installed vouchfx tool is a different build from the one this server is pinned to, even though its reported version still satisfies the pin handshake (for example a rebuilt pre-release with the same version number but a newer schema).
  • This server was upgraded, or downgraded, independently of the engine — the two now sit either side of a language-schema change.
  • A local development build of the engine is first on PATH and includes schema changes that are not yet published.
  • The engine emitted schema output that this server could not parse at all, which is reported as a divergence rather than silently ignored.
  • The CLI loaded trusted external providers from VOUCHFX_PROVIDERS or ~/.vouchfx/providers (engine v1.2.0 and later), so its vouchfx schema export includes their step types. The installed engine can be exactly the pinned build in this case.

Fixes

  • Compare versions: run vouchfx --version and check it against the version on the first line of this server's ENGINE_PIN.
  • Reinstall the engine at the pinned version: dotnet tool update --global vouchfx --version <version-from-ENGINE_PIN>.
  • Or upgrade this MCP server to a release pinned to the engine you actually have installed.
  • If you are developing the engine locally, either remove the local build from PATH while authoring suites, or accept that get_schema will serve the pinned contract until this server's vendored/ tree is refreshed (pwsh ./scripts/sync-vendored.ps1 -Update) against a new pin.
  • Until the two are reconciled, trust validate_suite's verdict over the raw schema for anything you intend to run with the installed engine, and re-check any suite that depends on a recently-changed field.
  • If external providers are loaded on purpose, the warning is expected. The returned schema covers the pinned engine's bundled step types, and vouchfx validate is the authority for steps that use a provider. Run vouchfx providers list as the account this server runs as, and check VOUCHFX_PROVIDERS in its environment, to see what is loaded. With no providers loaded, the pinned engine's export matches the vendored schema.