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.

Common causes

  • A Windows console code-page transcoding loss — check this first, and it is about how the two processes talk, not your engine install. The vouchfx CLI writes its standard output in the console's active output code page. This server now decodes that output with that same code page (the issue #70 fix), which removes the false positive entirely on any console whose code page can represent every character in the schema — for example Windows-1252, where the schema's §, —, and … all have encodings and round-trip cleanly (measured clean). The residual case is an OEM console code page that cannot represent some of those characters — for example code page 852 or 437, neither of which has an em-dash (—) or an ellipsis (…). When the engine writes a character its console code page cannot encode, .NET best-fit-maps it at the source, before any byte reaches this server: under code page 852 the schema's § is recovered correctly (it is byte 0xF5), but its — is replaced with - and its … with a raw control byte, and no decoding on this server's side can recover a character the engine already replaced. So on such a console the received document genuinely still differs from the vendored one, and this diagnostic still fires — now for a real transcoding loss rather than a decode bug. Measured: re-running the server under chcp 65001 (UTF-8) produces output identical to the vendored file apart from line endings, which this comparison already ignores. The blast radius stays narrow at the currently pinned engine (v1.0.0-rc.4): vouchfx list --json — the other output this server decodes — is pure ASCII and byte-identical under every code page, so this affects only the vouchfx schema cross-verification, and no tool's content is affected. The complete fix for the OEM-console residual is the engine emitting UTF-8 whenever its output is redirected; that engine-side half keeps issue #70 open. Until then chcp 65001 is a full workaround.
  • 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.

Fixes

  • On Windows, apply the code-page workaround before investigating anything else: run chcp to see the active page, then chcp 65001 and restart the MCP server. If the diagnostic disappears, there was never any schema drift — your console's code page could not represent every character the engine emits, and nothing about your engine install needs changing. (This server already decodes the CLI's output with your console's code page, which is enough to clear the diagnostic on code pages like Windows-1252 that can represent those characters; chcp 65001 is what also covers OEM pages such as 852 or 437 that cannot.)
  • 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.