@booyaka/mcp-vet 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,87 @@ All notable changes to `mcp-vet` are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0]
+
+The full 2026-07-28 compliance suite — `mcp-vet probe --spec-version 2026-07-28`
+now covers all three breaking changes the release candidate makes to server
+behavior, not just the removed handshake.
+
+### Added
+
+- **`missing-server-discover` (ERROR, `--spec-version 2026-07-28`)** — calls
+  the `server/discover` RPC that every 2026-07-28 server MUST implement
+  (SEP-2575; it replaces the removed initialize handshake for up-front
+  capability discovery) and flags a server whose answer is an error, a hang, or
+  a result missing the required `capabilities` key. The spec defines
+  `server/discover` as JSON-RPC only — 2026-07-28 removes the HTTP GET
+  endpoint, so no `GET /mcp/discover` variant is probed.
+- **`legacy-resource-error-code` (ERROR, `--spec-version 2026-07-28`)** — reads
+  a deliberately nonexistent resource URI (`mcp-vet://probe/...`) and flags a
+  server that still answers `-32002` instead of the JSON-RPC standard `-32602`
+  (Invalid Params). Servers without `resources/read` (`-32601`) are skipped,
+  not flagged; unexpected codes are reported as inconclusive notes.
+- **`mcp-vet run`** — an alias for `mcp-vet probe`.
+- **`test/probe-fixtures/server-partial.mjs`** — a hybrid (handshake +
+  stateless) fixture with exactly one migration defect per mode
+  (`legacy-error-code` / `no-discover` / `bad-discover`), isolating each new
+  rule; 7 new tests (62 total), including proof that the new checks are gated
+  behind `--spec-version 2026-07-28` and the default probe is unchanged.
+
+### Changed
+
+- The stateless first request now sends the RC's exact namespaced `_meta` key
+  `io.modelcontextprotocol/clientCapabilities` (was the incorrect
+  `io.modelcontextprotocol/capabilities`); the stateless fixtures now *require*
+  the namespaced keys, locking the wire format into the tests.
+- The new checks run on whichever contact path succeeded (stateless or classic
+  fallback), so a handshake-only legacy server gets its complete 2026-07-28
+  migration report — handshake + discover findings — in a single probe.
+- `ProbeResult` gains `discoverOk` and `errorCodeOk` verdict fields.
+
+## [0.5.0]
+
+The runtime-probe release — `mcp-vet probe` connects to a *running* MCP server
+(stdio command or Streamable HTTP URL) and detects the two 2026-07-28 violation
+categories that only exist on the wire, not in source.
+
+### Added
+
+- **`mcp-vet probe [options] <url | command...>`** — a runtime prober with two
+  new violation categories, reported in the same JSON + SARIF formats as the
+  static scan:
+  - **`json-schema-dialect` (WARN)** — calls `tools/list` and inspects every
+    tool's `inputSchema`/`outputSchema` (SEP-2106 lifts both to full JSON
+    Schema 2020-12). Flags an explicit draft-04/-06/-07 (or 2019-09) `$schema`
+    at high confidence, and — when `$schema` is absent — draft-only keyword
+    forms (`definitions`, `$ref: "#/definitions/…"`, boolean
+    `exclusiveMinimum`/`exclusiveMaximum`, array-form `items`, schema-form
+    `dependencies`) at medium confidence. The walker recurses only into schema
+    positions, so a *property* named `definitions` is never a false positive,
+    and an explicit 2020-12 `$schema` is trusted.
+  - **`requires-initialize-handshake` (ERROR)** — with
+    `--spec-version 2026-07-28`, makes a stateless first request (no
+    `initialize`; protocolVersion/clientInfo/capabilities travel in `_meta`
+    per the RC) and flags a server that rejects it or hangs. Cross-checked:
+    only emitted when the classic 2025-11-25 handshake path *does* work, so a
+    dead server is an operational error (exit 2), never a false violation.
+- **`--spec-version <2025-11-25|2026-07-28>`** (default `2025-11-25`) selects
+  the revision to vet against; `--timeout <ms>` bounds each request and doubles
+  as the hang-detection window; `--json` / `--sarif [file]` / `--fail-on` /
+  `--quiet` / `--color` work as in the scan.
+- **Runtime rules in SARIF** — probe rules join the driver metadata when they
+  fire (`ERROR` → `error`, `WARN` → `warning`); the static-scan SARIF keeps its
+  stable 9-rule shape.
+- **`test/probe-fixtures/`** — minimal real MCP servers used by 18 new tests:
+  `server-draft07.mjs` (explicit + inferable draft-07 tools, a modern 2020-12
+  tool, and a property literally named `definitions`), `server-requires-init.mjs`
+  (rejects pre-initialize requests with `-32002`), `server-stateless.mjs`
+  (2026-07-28-native, requires `_meta`, no initialize), and `server-http.mjs`
+  (Streamable HTTP, sessionful *and* stateless modes).
+- Verified against the official `@modelcontextprotocol/server-everything@2026.7.4`:
+  it answers stateless requests, but all of its tool schemas still declare
+  draft-07 — `probe` reports 14 true `json-schema-dialect` findings.
+
 ## [0.4.0]
 
 The community-feedback release — everything in it traces to reader comments on

package/README.md

@@ -18,7 +18,7 @@ npx @booyaka/mcp-vet .
   <img src="https://raw.githubusercontent.com/Booyaka101/mcp-vet/main/assets/demo.png" alt="mcp-vet scanning a server — BREAKING and DEPRECATED findings with before/after fixes and confidence tags" width="720">
 </p>
 
-No account, no API key, no network calls — it parses your code locally (ts-morph for TS/JS, a bundled Python `ast` script for `.py`) and exits non-zero if it finds anything **BREAKING**, so you can drop it straight into CI.
+No account, no API key — the scan parses your code locally (ts-morph for TS/JS, a bundled Python `ast` script for `.py`), makes no network calls, and exits non-zero if it finds anything **BREAKING**, so you can drop it straight into CI. (The opt-in [`mcp-vet probe`](#vet-a-running-server-mcp-vet-probe) is the one command that talks to a server — and only the one you point it at.)
 
 ## What actually happens on July 28
 
@@ -187,7 +187,7 @@ case 'tasks/list': return listTasks();
 - **The long-lived server→client SSE push channel is removed** — a server may only send requests to the client *while it is actively processing a client request*. Standing push streams / out-of-band notifications need rework.
 - **Streamable HTTP now requires `Mcp-Method` and `Mcp-Name` headers** that mirror the JSON-RPC body; servers must reject requests where headers and body disagree.
 - **Auth hardening** — validate the RFC 9207 `iss` parameter, declare OIDC `application_type` on Dynamic Client Registration, and bind tokens to the issuing authorization server.
-- **Tool schemas may now be full JSON Schema 2020-12** (`oneOf`/`anyOf`/`$ref`/conditionals); do not auto-dereference external `$ref` URIs.
+- **Tool schemas may now be full JSON Schema 2020-12** (`oneOf`/`anyOf`/`$ref`/conditionals); do not auto-dereference external `$ref` URIs. The *dialect* half of this — schemas still declaring or using draft-07 forms — **is** detectable at runtime: [`mcp-vet probe`](#vet-a-running-server-mcp-vet-probe) checks it against your live server.
 
 The CLI prints a one-line reminder of these after every scan.
 
@@ -213,6 +213,65 @@ writes nine ready-to-fire JSON fixtures plus a `CHECKLIST.md`, covering the runt
 
 Each fixture is a plain JSON description (`send` headers + JSON-RPC body, `expect` notes) you can replay with curl, supertest, pytest + httpx, or any HTTP harness. The checklist also spells out the **dual-version rollout matrix** — run both `2025-11-25` and `2026-07-28` paths until your clients have all moved — and a **client-side assumptions** list (session resume, per-request `_meta`, retries landing on other instances, `tools/list` revalidation).
 
+## Vet a running server (`mcp-vet probe`)
+
+Where the scan reads your *source*, `probe` talks to your *running server* over the wire — stdio (a command it spawns) or Streamable HTTP (a URL) — and checks the 2026-07-28 violations that only exist at runtime (`run` is an alias: `mcp-vet run …` ≡ `mcp-vet probe …`):
+
+| ID | Severity | What it checks |
+| --- | --- | --- |
+| `json-schema-dialect` | 🟡 WARN | calls `tools/list` and inspects every tool's `inputSchema`/`outputSchema` for a pre-2020-12 JSON Schema dialect ([SEP-2106](https://modelcontextprotocol.io/seps/2106-json-schema-2020-12)) — an explicit draft-04/-06/-07 `$schema` (**high** confidence), or no `$schema` but draft-only keyword forms: `definitions` instead of `$defs`, `$ref: "#/definitions/…"`, boolean `exclusiveMinimum`/`exclusiveMaximum`, array-form `items` (**medium** confidence) |
+| `requires-initialize-handshake` | 🔴 ERROR | with `--spec-version 2026-07-28`: makes a **stateless first request** — no `initialize`, protocolVersion/clientInfo/clientCapabilities in namespaced `_meta` keys per the RC — and flags a server that rejects it or hangs waiting for the removed handshake. A valid `tools` array in the answer is asserted, not just a 200 |
+| `missing-server-discover` | 🔴 ERROR | with `--spec-version 2026-07-28`: calls the **`server/discover`** RPC that every 2026-07-28 server MUST implement ([SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575) — it replaces the handshake for up-front capability discovery) and flags a server whose answer is an error or lacks the required `capabilities` key. (The spec defines `server/discover` as JSON-RPC only — 2026-07-28 *removes* the HTTP GET endpoint, so there is no `GET /mcp/discover` to fall back to) |
+| `legacy-resource-error-code` | 🔴 ERROR | with `--spec-version 2026-07-28`: reads a deliberately nonexistent resource URI and flags a server that still answers with the MCP-custom **`-32002`** instead of the JSON-RPC standard **`-32602`** (Invalid Params). Servers without `resources/read` (`-32601`) are skipped, not flagged |
+
+```bash
+# vet the schemas of a stdio server (spawns the command; a lone .js file runs with Node)
+npx @booyaka/mcp-vet probe node ./dist/server.js
+
+# full 2026-07-28 readiness: stateless first contact + server/discover +
+# resource error code + schema dialects
+npx @booyaka/mcp-vet probe --spec-version 2026-07-28 http://localhost:3000/mcp
+```
+
+```text
+mcp-vet probe — node ./dist/server.js · spec 2026-07-28 · stdio · 12 tool(s) listed
+  stateless probe: stateless tools/list was rejected: -32002 Server not initialized
+  fallback probe: initialize handshake + tools/list succeeded
+  server/discover: rejected (-32601)
+  resource error-code check skipped — server does not implement resources/read (-32601)
+
+ERROR  requires-initialize-handshake [high]
+    The server rejected (or hung on) a stateless 2026-07-28-style first request ...
+ERROR  missing-server-discover [high]
+    The 2026-07-28 spec requires every server to implement the server/discover RPC ...
+WARN   json-schema-dialect [high]
+    tool "echo" inputSchema: $schema = http://json-schema.org/draft-07/schema# (draft-07)
+```
+
+The stateless verdict is **cross-checked** before it becomes a violation: `requires-initialize-handshake` is only emitted when the classic `2025-11-25` handshake path *does* work — a dead or non-MCP server is an operational error (exit 2), never a false violation. The `server/discover` and error-code checks then run on whichever contact path succeeded, so even a handshake-only server gets its complete migration report in one probe. The dialect walker recurses only into schema positions (applicators like `properties`/`allOf`), so a *property* literally named `definitions` is never mistaken for the draft-07 keyword, and an explicit 2020-12 `$schema` declaration is trusted.
+
+### `--spec-version` — which revision to vet against
+
+| Value | Behavior |
+| --- | --- |
+| `2025-11-25` *(default)* | today's stable contract: classic `initialize` handshake, then the `json-schema-dialect` check. **No 2026-07-28 assertions run** — a fully 2025-era server probes clean |
+| `2026-07-28` | the full new-spec compliance suite: stateless first contact, required `server/discover`, `-32602` resource error code, plus the dialect check |
+
+**Migration note.** The default stays `2025-11-25` so existing CI invocations keep their exact behavior — add the flag when *you* are ready, not when the spec ships. A practical rollout:
+
+1. Today: `mcp-vet probe <server>` (unchanged) plus the static scan in CI.
+2. When you start migrating: add a second CI job with `--spec-version 2026-07-28 --fail-on none` to *see* the new-spec violations without failing the build.
+3. When your server targets `2026-07-28` (e.g. after moving to `@modelcontextprotocol/server` 2.x): drop `--fail-on none` so the three ERROR-level checks gate the build. A correctly migrated server passes all of them; the pre-migration server fails `requires-initialize-handshake` and `missing-server-discover` immediately.
+4. Keep a `2025-11-25` probe in the matrix until every client you serve has moved (the rollout is a window, not a day — see [What actually happens on July 28](#what-actually-happens-on-july-28)).
+
+Probe findings use the same report formats as the scan: `--json` (machine-readable array on stdout) and `--sarif [file]` (SARIF 2.1.0 — `ERROR` maps to `error`, `WARN` to `warning`), plus `--fail-on breaking|any|none` (default `breaking`: exit 1 only on `ERROR`), `--timeout <ms>` (default 8000, also the hang-detection window), `--quiet`, and `--color`/`--no-color`.
+
+Try it against the official reference server — the July 2026 `@modelcontextprotocol/server-everything` (beta 2026-07-28 SDK) answers stateless requests and already returns the new `-32602` resource error code, but it does not implement `server/discover` yet and its tool schemas still declare draft-07 — `probe` reports exactly that (1 ERROR, 13 WARN):
+
+```bash
+npx @booyaka/mcp-vet probe --spec-version 2026-07-28 npx -y @modelcontextprotocol/server-everything stdio
+```
+
 ## Usage
 
 ```bash
@@ -221,6 +280,7 @@ npx @booyaka/mcp-vet . --fix           # scan, and auto-apply the mechanical -32
 npx @booyaka/mcp-vet ./src ./packages  # multiple roots
 npx @booyaka/mcp-vet server.py         # a single file
 npx @booyaka/mcp-vet fixtures ./dir    # write runtime conformance fixtures + checklist (default: ./mcp-vet-fixtures)
+npx @booyaka/mcp-vet probe <url|cmd>   # vet a RUNNING server's wire behavior (see section above; alias: run)
 ```
 
 Globs `**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}` and `**/*.py`, skipping `node_modules`, `.git`, `__pycache__`, `dist`, and `build`.
@@ -426,10 +486,10 @@ Also exported: `renderJson` / `renderMarkdown` / `renderSarif`, `RULES`, and the
 ```bash
 npm install      # installs deps and builds (via prepare)
 npm run build    # tsc -> dist/ + copies the Python script
-npm test         # builds, then runs the Node.js built-in test runner (30 tests)
+npm test         # builds, then runs the Node.js built-in test runner (62 tests)
 ```
 
-Test fixtures live in `test/fixtures/` (dirty TS + Python servers, a `clean/` server with zero violations, `negatives/` true-negatives, a `confidence/` gradient, and `suppress/` cases).
+Test fixtures live in `test/fixtures/` (dirty TS + Python servers, a `clean/` server with zero violations, `negatives/` true-negatives, a `confidence/` gradient, and `suppress/` cases). Runtime-probe fixtures live in `test/probe-fixtures/` — minimal stdio + Streamable-HTTP MCP servers: one returning draft-07 schemas, one requiring the initialize handshake, one fully migrated 2026-07-28-native (stateless + `server/discover` + `-32602`), and a `server-partial.mjs` with one deliberate migration defect per mode (`legacy-error-code` / `no-discover` / `bad-discover`).
 
 ## License
 

package/dist/autofix.d.ts

@@ -1,4 +1,4 @@
-import { Finding, PatternId } from './types';
+import { Finding, ViolationId } from './types';
 export interface FixPreview {
     file: string;
     line: number;
@@ -16,7 +16,7 @@ export interface FixOptions {
     /** Compute and return the rewrites without touching any files. */
     dryRun?: boolean;
 }
-export declare function isFixable(id: PatternId): boolean;
+export declare function isFixable(id: ViolationId): boolean;
 /**
  * Apply the safe mechanical fixes in place. Returns which findings were fixed so
  * the caller can drop them from the report and the exit-code calculation.

package/dist/autofix.js

@@ -110,9 +110,9 @@ function applyFixes(findings, opts = {}) {
             preview.push(...localPreview);
             continue;
         }
-        // Only count/return findings as fixed once the write actually succeeds — a
+        // Only count/return findings as fixed once the write actually succeeds — a
         // failed write (read-only file, EACCES) must not report the code as fixed.
-        const out = (hasBom ? '' : '') + lines.join('\n');
+        const out = (hasBom ? '' : '') + lines.join('\n');
         try {
             fs.writeFileSync(absPath, out, 'utf8');
         }

package/dist/cli.js

@@ -45,6 +45,7 @@ const constants_1 = require("./constants");
 const reporters_1 = require("./reporters");
 const autofix_1 = require("./autofix");
 const conformance_1 = require("./conformance");
+const probe_cli_1 = require("./probe-cli");
 const CONF_VALUES = ['high', 'medium', 'low'];
 const FAILON_VALUES = ['breaking', 'any', 'none'];
 function fail(msg) {
@@ -97,199 +98,218 @@ if (process.argv[2] === 'fixtures') {
         fail(`could not write fixtures: ${err.message}`);
     }
 }
-const program = new commander_1.Command();
-program
-    .name('mcp-vet')
-    .description('Scan MCP server source code for patterns that break under the 2026-07-28 MCP spec release candidate.')
-    .argument('[paths...]', 'files or directories to scan', ['.'])
-    .option('--github-annotations', 'emit GitHub Actions ::error/::warning annotations to stdout')
-    .option('--sarif [file]', 'write a SARIF 2.1.0 report (default file: mcp-vet.sarif)')
-    .option('--out-dir <dir>', 'directory for mcp-vet-report.md and mcp-vet-results.json', process.cwd())
-    .option('--no-files', 'do not write the markdown/json report files')
-    .option('--only <ids>', 'only run these pattern ids (comma/space separated)')
-    .option('--disable <ids>', 'skip these pattern ids (comma/space separated)')
-    .option('--fail-on <level>', `exit non-zero on: ${FAILON_VALUES.join(' | ')}`, 'breaking')
-    .option('--min-confidence <level>', `report only findings at/above: ${CONF_VALUES.join(' | ')}`, 'low')
-    .option('--ignore <glob>', 'ignore paths matching glob (repeatable)', (v, acc) => {
-    acc.push(v);
-    return acc;
-}, [])
-    .option('--max-file-size <kb>', 'skip files larger than this many KB (0 = no limit)', '1536')
-    .option('--no-py-fallback', 'disable the regex fallback when no Python interpreter is found')
-    .option('--config <path>', 'path to a config file (.mcpvetrc.json)')
-    .option('--fix', 'auto-apply the safe mechanical fixes in place (currently: -32002 → -32602)')
-    .option('--dry-run', 'with --fix: print the rewrites that would be made, without changing files')
-    .option('--json', 'print findings as a JSON array to stdout (implies a quiet terminal report)')
-    .option('--color', 'force colored output')
-    .option('--no-color', 'disable colored output')
-    .option('--quiet', 'suppress the human-readable terminal report')
-    .version((0, constants_1.getVersion)(), '-v, --version')
-    .addHelpText('after', '\nCommands:\n  fixtures [dir]  write protocol-level conformance fixtures + CHECKLIST.md (default: ./mcp-vet-fixtures)')
-    .showHelpAfterError();
-program.parse(process.argv);
-const opts = program.opts();
-const paths = program.args.length ? program.args : ['.'];
-// --- Resolve configuration (CLI over config file over defaults) ---
-let config = {};
-try {
-    config = (0, config_1.loadConfig)(process.cwd(), opts.config);
+// `mcp-vet probe [options] <url | command...>` — connect to a RUNNING server and
+// vet its wire behavior (JSON Schema dialect, stateless-protocol readiness,
+// server/discover, resource error code). `run` is an alias for `probe`.
+// Async, so the scan pipeline only runs in the else-branch.
+if (process.argv[2] === 'probe' || process.argv[2] === 'run') {
+    (0, probe_cli_1.runProbeCli)(process.argv.slice(3)).then((code) => process.exit(code), (err) => fail(err.message));
 }
-catch (err) {
-    if (err instanceof config_1.ConfigError)
-        fail(err.message);
-    throw err;
+else {
+    scanMain();
 }
-// Validate enums
-if (!FAILON_VALUES.includes(opts.failOn)) {
-    fail(`invalid --fail-on "${opts.failOn}". Valid: ${FAILON_VALUES.join(', ')}`);
-}
-if (!CONF_VALUES.includes(opts.minConfidence)) {
-    fail(`invalid --min-confidence "${opts.minConfidence}". Valid: ${CONF_VALUES.join(', ')}`);
-}
-// CLI value wins when explicitly set; otherwise fall back to the config file.
-const fromCli = (key) => program.getOptionValueSource(key) === 'cli';
-const failOn = fromCli('failOn')
-    ? opts.failOn
-    : config.failOn ?? opts.failOn;
-const minConfidence = fromCli('minConfidence')
-    ? opts.minConfidence
-    : config.minConfidence ?? opts.minConfidence;
-const normalizeIds = (ids) => ids
-    ?.map((s) => String(s).toUpperCase())
-    .filter((s) => types_1.ALL_PATTERN_IDS.includes(s));
-const cliOnly = parsePatternIds(opts.only);
-const cliDisable = parsePatternIds(opts.disable);
-const only = cliOnly ?? normalizeIds(config.only);
-const disable = cliDisable ?? normalizeIds(config.disable);
-let enabled = new Set(types_1.ALL_PATTERN_IDS);
-if (only && only.length)
-    enabled = new Set(only.filter((id) => types_1.ALL_PATTERN_IDS.includes(id)));
-// `disable` always applies on top — so a CLI --disable still narrows a config `only`.
-if (disable && disable.length) {
-    for (const id of disable)
-        enabled.delete(id);
-}
-if (enabled.size === 0)
-    fail('no rules enabled after applying --only/--disable.');
-const maxKbRaw = Number(opts.maxFileSize);
-if (!Number.isFinite(maxKbRaw) || maxKbRaw < 0)
-    fail(`invalid --max-file-size "${opts.maxFileSize}".`);
-const maxFileSizeKb = fromCli('maxFileSize')
-    ? maxKbRaw
-    : config.maxFileSizeKb != null
-        ? config.maxFileSizeKb
-        : maxKbRaw;
-const pythonFallback = fromCli('pyFallback')
-    ? opts.pyFallback
-    : config.pythonFallback != null
-        ? config.pythonFallback
-        : opts.pyFallback;
-const color = fromCli('color') ? opts.color : undefined;
-// Ignore patterns: config + CLI + .mcpvetignore in cwd and each root dir
-const ignorePatterns = new Set([...(config.ignore ?? []), ...opts.ignore]);
-for (const line of readIgnoreFile(process.cwd()))
-    ignorePatterns.add(line);
-for (const p of paths) {
+function scanMain() {
+    const program = new commander_1.Command();
+    program
+        .name('mcp-vet')
+        .description('Scan MCP server source code for patterns that break under the 2026-07-28 MCP spec release candidate.')
+        .argument('[paths...]', 'files or directories to scan', ['.'])
+        .option('--github-annotations', 'emit GitHub Actions ::error/::warning annotations to stdout')
+        .option('--sarif [file]', 'write a SARIF 2.1.0 report (default file: mcp-vet.sarif)')
+        .option('--out-dir <dir>', 'directory for mcp-vet-report.md and mcp-vet-results.json', process.cwd())
+        .option('--no-files', 'do not write the markdown/json report files')
+        .option('--only <ids>', 'only run these pattern ids (comma/space separated)')
+        .option('--disable <ids>', 'skip these pattern ids (comma/space separated)')
+        .option('--fail-on <level>', `exit non-zero on: ${FAILON_VALUES.join(' | ')}`, 'breaking')
+        .option('--min-confidence <level>', `report only findings at/above: ${CONF_VALUES.join(' | ')}`, 'low')
+        .option('--ignore <glob>', 'ignore paths matching glob (repeatable)', (v, acc) => {
+        acc.push(v);
+        return acc;
+    }, [])
+        .option('--max-file-size <kb>', 'skip files larger than this many KB (0 = no limit)', '1536')
+        .option('--no-py-fallback', 'disable the regex fallback when no Python interpreter is found')
+        .option('--config <path>', 'path to a config file (.mcpvetrc.json)')
+        .option('--fix', 'auto-apply the safe mechanical fixes in place (currently: -32002 → -32602)')
+        .option('--dry-run', 'with --fix: print the rewrites that would be made, without changing files')
+        .option('--json', 'print findings as a JSON array to stdout (implies a quiet terminal report)')
+        .option('--color', 'force colored output')
+        .option('--no-color', 'disable colored output')
+        .option('--quiet', 'suppress the human-readable terminal report')
+        .version((0, constants_1.getVersion)(), '-v, --version')
+        .addHelpText('after', [
+        '',
+        'Commands:',
+        '  fixtures [dir]                 write protocol-level conformance fixtures + CHECKLIST.md (default: ./mcp-vet-fixtures)',
+        '  probe [options] <url|command>  connect to a RUNNING server and vet its wire behavior (alias: run)',
+        '                                 (JSON Schema 2020-12 dialect; with --spec-version 2026-07-28, also stateless',
+        '                                 readiness, the required server/discover RPC, and the -32602 resource error code)',
+    ].join('\n'))
+        .showHelpAfterError();
+    program.parse(process.argv);
+    const opts = program.opts();
+    const paths = program.args.length ? program.args : ['.'];
+    // --- Resolve configuration (CLI over config file over defaults) ---
+    let config = {};
     try {
-        const abs = path.resolve(p);
-        if (fs.statSync(abs).isDirectory()) {
-            for (const line of readIgnoreFile(abs))
-                ignorePatterns.add(line);
+        config = (0, config_1.loadConfig)(process.cwd(), opts.config);
+    }
+    catch (err) {
+        if (err instanceof config_1.ConfigError)
+            fail(err.message);
+        throw err;
+    }
+    // Validate enums
+    if (!FAILON_VALUES.includes(opts.failOn)) {
+        fail(`invalid --fail-on "${opts.failOn}". Valid: ${FAILON_VALUES.join(', ')}`);
+    }
+    if (!CONF_VALUES.includes(opts.minConfidence)) {
+        fail(`invalid --min-confidence "${opts.minConfidence}". Valid: ${CONF_VALUES.join(', ')}`);
+    }
+    // CLI value wins when explicitly set; otherwise fall back to the config file.
+    const fromCli = (key) => program.getOptionValueSource(key) === 'cli';
+    const failOn = fromCli('failOn')
+        ? opts.failOn
+        : config.failOn ?? opts.failOn;
+    const minConfidence = fromCli('minConfidence')
+        ? opts.minConfidence
+        : config.minConfidence ?? opts.minConfidence;
+    const normalizeIds = (ids) => ids
+        ?.map((s) => String(s).toUpperCase())
+        .filter((s) => types_1.ALL_PATTERN_IDS.includes(s));
+    const cliOnly = parsePatternIds(opts.only);
+    const cliDisable = parsePatternIds(opts.disable);
+    const only = cliOnly ?? normalizeIds(config.only);
+    const disable = cliDisable ?? normalizeIds(config.disable);
+    let enabled = new Set(types_1.ALL_PATTERN_IDS);
+    if (only && only.length)
+        enabled = new Set(only.filter((id) => types_1.ALL_PATTERN_IDS.includes(id)));
+    // `disable` always applies on top — so a CLI --disable still narrows a config `only`.
+    if (disable && disable.length) {
+        for (const id of disable)
+            enabled.delete(id);
+    }
+    if (enabled.size === 0)
+        fail('no rules enabled after applying --only/--disable.');
+    const maxKbRaw = Number(opts.maxFileSize);
+    if (!Number.isFinite(maxKbRaw) || maxKbRaw < 0)
+        fail(`invalid --max-file-size "${opts.maxFileSize}".`);
+    const maxFileSizeKb = fromCli('maxFileSize')
+        ? maxKbRaw
+        : config.maxFileSizeKb != null
+            ? config.maxFileSizeKb
+            : maxKbRaw;
+    const pythonFallback = fromCli('pyFallback')
+        ? opts.pyFallback
+        : config.pythonFallback != null
+            ? config.pythonFallback
+            : opts.pyFallback;
+    const color = fromCli('color') ? opts.color : undefined;
+    // Ignore patterns: config + CLI + .mcpvetignore in cwd and each root dir
+    const ignorePatterns = new Set([...(config.ignore ?? []), ...opts.ignore]);
+    for (const line of readIgnoreFile(process.cwd()))
+        ignorePatterns.add(line);
+    for (const p of paths) {
+        try {
+            const abs = path.resolve(p);
+            if (fs.statSync(abs).isDirectory()) {
+                for (const line of readIgnoreFile(abs))
+                    ignorePatterns.add(line);
+            }
+        }
+        catch {
+            /* validated later in scan() */
         }
     }
-    catch {
-        /* validated later in scan() */
+    const ignore = new ignore_1.IgnoreMatcher([...ignorePatterns]);
+    // --- Scan ---
+    let result;
+    try {
+        result = (0, scanner_1.scan)(paths, {
+            enabled,
+            ignore,
+            maxFileSizeKb,
+            pythonFallback,
+            minConfidence,
+        });
     }
-}
-const ignore = new ignore_1.IgnoreMatcher([...ignorePatterns]);
-// --- Scan ---
-let result;
-try {
-    result = (0, scanner_1.scan)(paths, {
-        enabled,
-        ignore,
-        maxFileSizeKb,
-        pythonFallback,
-        minConfidence,
-    });
-}
-catch (err) {
-    if (err instanceof scanner_1.ScanError)
-        fail(err.message);
-    throw err;
-}
-// --- Autofix (before reporting, so the report/exit reflect what remains) ---
-if (opts.fix) {
-    const say = opts.json ? console.error : console.log; // keep stdout clean for --json
-    const fr = (0, autofix_1.applyFixes)(result.findings, { dryRun: opts.dryRun });
-    if (opts.dryRun) {
-        if (fr.preview.length === 0) {
-            say('mcp-vet: --fix --dry-run — nothing to auto-fix.');
+    catch (err) {
+        if (err instanceof scanner_1.ScanError)
+            fail(err.message);
+        throw err;
+    }
+    // --- Autofix (before reporting, so the report/exit reflect what remains) ---
+    if (opts.fix) {
+        const say = opts.json ? console.error : console.log; // keep stdout clean for --json
+        const fr = (0, autofix_1.applyFixes)(result.findings, { dryRun: opts.dryRun });
+        if (opts.dryRun) {
+            if (fr.preview.length === 0) {
+                say('mcp-vet: --fix --dry-run — nothing to auto-fix.');
+            }
+            else {
+                say(`mcp-vet: --fix --dry-run — ${fr.preview.length} rewrite(s) that would be applied (no files changed):`);
+                for (const p of fr.preview) {
+                    say(`  ${p.file}:${p.line}`);
+                    say(`    - ${p.before.trim()}`);
+                    say(`    + ${p.after.trim()}`);
+                }
+            }
         }
         else {
-            say(`mcp-vet: --fix --dry-run — ${fr.preview.length} rewrite(s) that would be applied (no files changed):`);
-            for (const p of fr.preview) {
-                say(`  ${p.file}:${p.line}`);
-                say(`    - ${p.before.trim()}`);
-                say(`    + ${p.after.trim()}`);
+            if (fr.fixedCount > 0) {
+                const fixed = new Set(fr.fixedFindings);
+                result.findings = result.findings.filter((f) => !fixed.has(f));
             }
+            say(fr.fixedCount > 0
+                ? `mcp-vet: fixed ${fr.fixedCount} occurrence(s) of -32002 → -32602 in ${fr.filesChanged.length} file(s).`
+                : 'mcp-vet: --fix found nothing to auto-fix.');
         }
     }
-    else {
-        if (fr.fixedCount > 0) {
-            const fixed = new Set(fr.fixedFindings);
-            result.findings = result.findings.filter((f) => !fixed.has(f));
-        }
-        say(fr.fixedCount > 0
-            ? `mcp-vet: fixed ${fr.fixedCount} occurrence(s) of -32002 → -32602 in ${fr.filesChanged.length} file(s).`
-            : 'mcp-vet: --fix found nothing to auto-fix.');
+    // --- Report ---
+    const quiet = opts.quiet || opts.json;
+    // Notices (Wrote ...) go to stderr in --json mode so stdout stays pure JSON.
+    const notify = (msg) => (opts.json ? console.error(msg) : console.log(msg));
+    if (opts.githubAnnotations) {
+        (0, reporters_1.printGithubAnnotations)(result.findings);
     }
-}
-// --- Report ---
-const quiet = opts.quiet || opts.json;
-// Notices (Wrote ...) go to stderr in --json mode so stdout stays pure JSON.
-const notify = (msg) => (opts.json ? console.error(msg) : console.log(msg));
-if (opts.githubAnnotations) {
-    (0, reporters_1.printGithubAnnotations)(result.findings);
-}
-if (!quiet) {
-    (0, reporters_1.reportTerminal)(result, { color });
-}
-if (opts.json) {
-    process.stdout.write((0, reporters_1.renderJson)(result) + '\n');
-}
-if (opts.sarif) {
-    const sarifPath = path.resolve(process.cwd(), typeof opts.sarif === 'string' ? opts.sarif : 'mcp-vet.sarif');
-    try {
-        (0, reporters_1.writeSarif)(result, sarifPath);
-        if (!quiet)
-            notify(`Wrote ${sarifPath}`);
+    if (!quiet) {
+        (0, reporters_1.reportTerminal)(result, { color });
     }
-    catch (err) {
-        console.error(`mcp-vet: failed to write SARIF: ${err.message}`);
+    if (opts.json) {
+        process.stdout.write((0, reporters_1.renderJson)(result) + '\n');
     }
-}
-if (opts.files) {
-    try {
-        const md = (0, reporters_1.writeMarkdown)(result, opts.outDir);
-        const json = (0, reporters_1.writeJson)(result, opts.outDir);
-        if (!quiet) {
-            notify(`Wrote ${md}`);
-            notify(`Wrote ${json}`);
+    if (opts.sarif) {
+        const sarifPath = path.resolve(process.cwd(), typeof opts.sarif === 'string' ? opts.sarif : 'mcp-vet.sarif');
+        try {
+            (0, reporters_1.writeSarif)(result, sarifPath);
+            if (!quiet)
+                notify(`Wrote ${sarifPath}`);
+        }
+        catch (err) {
+            console.error(`mcp-vet: failed to write SARIF: ${err.message}`);
         }
     }
-    catch (err) {
-        console.error(`mcp-vet: failed to write report files: ${err.message}`);
+    if (opts.files) {
+        try {
+            const md = (0, reporters_1.writeMarkdown)(result, opts.outDir);
+            const json = (0, reporters_1.writeJson)(result, opts.outDir);
+            if (!quiet) {
+                notify(`Wrote ${md}`);
+                notify(`Wrote ${json}`);
+            }
+        }
+        catch (err) {
+            console.error(`mcp-vet: failed to write report files: ${err.message}`);
+        }
     }
+    // --- Exit code ---
+    const hasBreaking = result.findings.some((f) => f.severity === 'BREAKING' || f.severity === 'ERROR');
+    const hasAny = result.findings.length > 0;
+    let failing = false;
+    if (failOn === 'breaking')
+        failing = hasBreaking;
+    else if (failOn === 'any')
+        failing = hasAny;
+    else
+        failing = false; // 'none'
+    process.exit(failing ? 1 : 0);
 }
-// --- Exit code ---
-const hasBreaking = result.findings.some((f) => f.severity === 'BREAKING');
-const hasAny = result.findings.length > 0;
-let failing = false;
-if (failOn === 'breaking')
-    failing = hasBreaking;
-else if (failOn === 'any')
-    failing = hasAny;
-else
-    failing = false; // 'none'
-process.exit(failing ? 1 : 0);