@@ -275,25 +275,35 @@ of the server's stderr. Re-run a subset with
275275
276276### ` interface-diff `
277277
278- The last stage diffs the ` everything ` server's MCP interface (capabilities,
279- tools, prompts, resources, resource templates) in this checkout's build
280- against the same server built from the merge-base with ` origin/v2/main ` , and
281- prints the report. ** A changed interface does not fail it** : the report is
278+ The last stage diffs the MCP interface (capabilities, tools, prompts,
279+ resources, resource templates) of each server the change touches, in this
280+ checkout's build, against the same server built from the merge-base with
281+ ` origin/v2/main ` , and prints one report per server. Each report says why that
282+ server was selected; a change that touches no server prints
283+ ` no server changed ` and passes. What selects a server is in
284+ [ ` docs/quality-gate.md ` ] ( ../../../docs/quality-gate.md ) . ** A changed interface does not fail it** : the report is
282285what the PR's sticky comment will show, so read it, and if a change is not
283286one you meant, that is the finding. It fails only when the diff cannot run,
284287with ` ❌ The interface diff could not run ` and the reason:
285288
286289- ** "origin/v2/main is not available"** : ` git fetch origin v2/main ` .
287- - ** "src/everything/dist/index.js does not exist"** : you ran it on its own
288- before building: ` npm run build -w src/everything ` .
289- - ** An ` npm ci ` or ` npm run build ` failure** : the _ base_ did not install or
290- build. Offline with a cold npm cache is the usual cause; otherwise name a
290+ - ** "src/<server >/dist/index.js does not exist"** : you ran it on its own
291+ before building: ` npm run build -w src/<server> ` .
292+ - ** "src/<server >/.venv does not exist"** : a Python server was not synced:
293+ ` cd src/<server> && uv sync --frozen --all-extras --dev ` (the gate's
294+ ` validate:py ` does it).
295+ - ** "does not exist at the base"** : the server is new on this branch, so
296+ there is no base to diff it against.
297+ - ** An ` npm ci ` , ` npm run build ` or ` uv sync ` failure** : the _ base_ did not
298+ install or build. Offline with a cold npm cache is the usual cause; otherwise name a
291299 base that builds with ` npm run interface-diff -- --base <ref> ` .
292300- ** "Base server probe failed" / "Target probe failed"** : a server did not
293301 answer the probe. A target failure is this checkout's server and is the
294302 real defect; the smoke stage before it usually fails first.
295303
296- Re-run it on its own with ` npm run interface-diff ` (about ten seconds). What
304+ Re-run it on its own with ` npm run interface-diff ` (about ten seconds for
305+ every server), ` -- --server <name> ` for one, or ` -- --list ` to see what it
306+ would select and why. What
297307it compares against in CI, and why it is a script rather than an action, is
298308in [ ` docs/quality-gate.md ` ] ( ../../../docs/quality-gate.md ) and the header of
299309` scripts/interface-diff.mjs ` .
0 commit comments