@booyaka/mcp-vet 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,64 @@ 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.3.0]
+
+The completeness release — full detection coverage, a real migration path, and a
+programmatic API. Informed by a deep audit of the spec and the codebase.
+
+### Added
+
+- **Two removed-method rules**: `TASKS_LIST_REMOVED` and `TASKS_RESULT_REMOVED`
+  (both BREAKING). `tasks/list` and `tasks/result` are removed on 2026-07-28
+  (SEP-2663); previously `tasks/list` was (incorrectly) treated as a non-issue.
+- **Deprecated-capability *method* strings** — `roots/list`,
+  `notifications/roots/list_changed`, `sampling/createMessage`, `logging/setLevel`,
+  `notifications/message` are now flagged (SEP-2577 deprecates the methods, not just
+  the capability keys), catching servers that reference them without a literal
+  `capabilities` object nearby.
+- **SDK schema-constant detection** — `server.setRequestHandler(InitializeRequestSchema, …)`
+  and friends are how real SDK servers register handlers; these are now mapped to the
+  right rule (previously only bare string literals matched — a major false negative).
+- **SDK capability-constructor detection** — the Python SDK's
+  `ClientCapabilities(roots=RootsCapability())` is now recognized structurally (high
+  confidence, not proximity-medium), and `RootsCapability`/`SamplingCapability`/
+  `LoggingCapability` are matched directly. (Found by validating against the official
+  reference servers — a broad real-corpus run measured **0 false positives**.)
+- **`--fix --dry-run`** — preview the rewrites `--fix` would make without touching files.
+- **`sessionIdGenerator`** detection (value-aware) — flagged only when it is a real
+  generator, not the migrated `sessionIdGenerator: undefined`.
+- **`--fix`** — auto-applies the safe mechanical rewrites in place (`-32002` →
+  `-32602`). Fixed findings are dropped from the report and the exit code.
+- **`--json`** — prints findings as a JSON array to stdout (pure JSON; notices go to
+  stderr), for piping in CI.
+- **Programmatic API** — the package now exposes `main`/`types`/`exports` with
+  bundled `.d.ts`: `scan`, `applyFixes`, `renderJson`/`renderMarkdown`/`renderSarif`,
+  `RULES`, and the public types.
+- **"Needs manual review" awareness** — changes that can't be found statically (SSE
+  push-channel removal, required `Mcp-Method`/`Mcp-Name` headers, auth hardening,
+  JSON Schema 2020-12 schemas) are documented and the CLI prints a reminder after
+  every scan.
+- Config JSON Schema (`schema/mcpvetrc.schema.json`), a tag-triggered `release.yml`
+  with npm provenance, and README husky/pre-commit examples.
+
+### Fixed
+
+- **`--fix` file corruption on Python (multibyte lines)** — the bundled `ast`
+  scanner emitted UTF-8 *byte* column offsets; on a line with non-ASCII characters
+  autofix could rewrite an unrelated `-32002` inside a string. Columns are now
+  character-accurate, and autofix requires an exact column match (no blind
+  `indexOf` fallback).
+- **`--fix` false success** — findings were marked fixed even when the file write
+  failed; they are now only cleared after a successful write.
+- **Config precedence** — a config-file `only` no longer silently cancels a CLI
+  `--disable`; `--disable` always applies on top.
+- Negative numeric literals are anchored consistently at the `-` across the TS and
+  Python analyzers (correct SARIF regions and autofix positions).
+
+### Changed
+
+- Rule count is now 9 (was 7); SARIF advertises all 9 rules.
+
 ## [0.2.0]
 
 The robustness and precision release. Everything below is covered by the test suite.
@@ -50,5 +108,6 @@ Initial release.
   shared rule engine, and four report formats (terminal, Markdown, JSON, GitHub
   Actions annotations).
 
+[0.3.0]: https://github.com/Booyaka101/mcp-vet/releases/tag/v0.3.0
 [0.2.0]: https://github.com/Booyaka101/mcp-vet/releases/tag/v0.2.0
 [0.1.0]: https://github.com/Booyaka101/mcp-vet/releases/tag/v0.1.0

package/README.md

@@ -14,6 +14,10 @@
 npx @booyaka/mcp-vet .
 ```
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Booyaka101/mcp-vet/main/assets/demo.svg" 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.
 
 ---
@@ -25,17 +29,21 @@ Pointed at the [official MCP TypeScript SDK's own example servers](https://githu
 ```text
 legacy-routing.ts:36:29  BREAKING   MCP_SESSION_ID [high]
     const sid = req.headers['mcp-session-id'] as string | undefined;
+legacy-routing.ts:41:13  BREAKING   MCP_SESSION_ID [medium]
+    sessionIdGenerator: () => randomUUID(),
 legacy-routing.ts:70:26  BREAKING   MCP_SESSION_ID [high]
     exposedHeaders: ['Mcp-Session-Id', 'WWW-Authenticate', ...]
 sse-polling.ts:34:29     DEPRECATED LOGGING_CAP    [high]
     capabilities: { logging: {} }
 sse-polling.ts:102:29    BREAKING   MCP_SESSION_ID [high]
     const sid = req.headers['mcp-session-id'] as string | undefined;
+sse-polling.ts:107:13    BREAKING   MCP_SESSION_ID [medium]
+    sessionIdGenerator: () => randomUUID(),
 
-4 finding(s): 3 BREAKING, 1 DEPRECATED
+6 finding(s): 5 BREAKING, 1 DEPRECATED
 ```
 
-And it stays quiet where it should — the `initialize` mentioned in a *comment* in `dual-era.ts`, and the `sampling/createMessage` **method** in `sampling.ts`, are not flagged, because only the `sampling` **capability declaration** is deprecated, not the method. That precision (structural AST checks, not text matching) is what keeps the noise down on a real codebase.
+Note it catches the `sessionIdGenerator` session usage — the real signal in SDK-based servers, which usually never write the literal `Mcp-Session-Id` string. And it stays quiet where it should: the `Mcp-Session-Id` mentioned in a *comment*, the `initialize` in a comment in `dual-era.ts`, and the `sampling/createMessage` in `sampling.ts` (which appears only in comments and behind the `requestSampling()` helper) are all left alone. That precision — structural AST checks, not text matching — is what keeps the noise down on a real codebase: **6 findings, 0 false positives.**
 
 ---
 
@@ -49,6 +57,8 @@ And it stays quiet where it should — the `initialize` mentioned in a *comment*
 | `INITIALIZE_HANDLER` | `initialize` / `notifications/initialized` handler registration |
 | `ERROR_CODE_32002` | the numeric error code `-32002` |
 | `TASKS_LEGACY` | `tasks/get` · `tasks/update` · `tasks/cancel` legacy method strings |
+| `TASKS_LIST_REMOVED` | `tasks/list` — removed entirely (no replacement listing method) |
+| `TASKS_RESULT_REMOVED` | `tasks/result` — removed; poll with `tasks/get` instead (SEP-2663) |
 
 ### 🟡 DEPRECATED (warns only — exit code 0, 12-month grace period)
 
@@ -113,6 +123,8 @@ return { error: { code: -32002, message: 'Resource not found' } };
 return { error: { code: -32602, message: 'Invalid params' } };
 ```
 
+This one is purely mechanical, so `mcp-vet --fix` rewrites it for you in place.
+
 ### 4. Legacy Tasks methods — redesigned to a handle-based lifecycle
 
 > *"A server can answer `tools/call` with a task handle, and the client drives it with `tasks/get`, `tasks/update`, and `tasks/cancel`. Anyone who shipped against the `2025-11-25` experimental Tasks API will need to migrate to the new lifecycle."*
@@ -130,12 +142,36 @@ switch (method) {
 // the 2026-07-28 schema.
 ```
 
+### 5. `tasks/list` — removed entirely
+
+> *"The `tasks/list` method is removed — it was unsafe once protocol-level sessions were gone. There is no replacement listing method."*
+
+```ts
+// ❌ before
+case 'tasks/list': return listTasks();
+
+// ✅ after — there is nothing to enumerate server-side. A client tracks the
+// task handles it got back from its own tools/call responses.
+```
+
 ---
 
+## Needs manual review (not statically detectable)
+
+`mcp-vet` catches every 2026-07-28 change that has a concrete code-level signal (a header, a method string, an error code, a capability key). A few changes are real but **can't be found reliably by static analysis** — they're architectural or depend on runtime wiring. A clean scan is not a promise that these are handled, so check them by hand:
+
+- **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.
+
+The CLI prints a one-line reminder of these after every scan.
+
 ## Usage
 
 ```bash
 npx @booyaka/mcp-vet [paths...]        # scan directories and/or files (default: current directory)
+npx @booyaka/mcp-vet . --fix           # scan, and auto-apply the mechanical -32002 → -32602 rewrite
 npx @booyaka/mcp-vet ./src ./packages  # multiple roots
 npx @booyaka/mcp-vet server.py         # a single file
 ```
@@ -153,6 +189,9 @@ Globs `**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}` and `**/*.py`, skipping `node_modul
 | `--only <ids>` | only run these pattern ids (comma/space separated) |
 | `--disable <ids>` | skip these pattern ids |
 | `--fail-on <level>` | non-zero exit on `breaking` (default), `any`, or `none` |
+| `--fix` | auto-apply the safe mechanical fixes in place (currently `-32002` → `-32602`) |
+| `--dry-run` | with `--fix`: print the rewrites that would be made, without changing files |
+| `--json` | print findings as a JSON array to stdout (pure JSON — notices go to stderr) |
 | `--min-confidence <level>` | report only findings at/above `high`, `medium`, or `low` (default) |
 | `--ignore <glob>` | ignore paths matching a gitignore-style glob (repeatable) |
 | `--max-file-size <kb>` | skip files larger than N KB (default 1536; `0` = no limit) |
@@ -237,13 +276,88 @@ To upload results to GitHub code scanning instead:
         with: { sarif_file: mcp-vet.sarif }
 ```
 
+### Local git hooks
+
+Catch it before it reaches CI. With [husky](https://typicode.github.io/husky/) + [lint-staged](https://github.com/lint-staged/lint-staged):
+
+```json
+// package.json
+{
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,mjs,cjs,py}": "mcp-vet"
+  }
+}
+```
+
+Or with [pre-commit](https://pre-commit.com) (Python projects):
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: mcp-vet
+        name: mcp-vet
+        entry: npx @booyaka/mcp-vet
+        language: system
+        files: \.(ts|tsx|js|jsx|mjs|cjs|py)$
+```
+
+### Why there's no `--baseline`
+
+Some linters let you "grandfather" existing findings so CI stays green. `mcp-vet` deliberately doesn't: this is a **one-time migration to a spec that ships on a fixed date**, and a suppressed finding is code that will break on July 28. The point is for the build to fail until it's actually fixed. For the rare intentional exception, use targeted [inline suppression](#suppressing-findings-inline) — an explicit, reviewable, per-line decision.
+
+### Large repositories
+
+`mcp-vet` skips `node_modules`, `.git`, `dist`, `build`, and `__pycache__` by default, chunks the Python subprocess, and takes `--max-file-size`. On a big monorepo, scope the scan to the packages that ship MCP servers (`mcp-vet ./packages/server ./services/mcp`) and add `--ignore` globs for generated code.
+
 ---
 
 ## How it works
 
 - **TypeScript / JavaScript** — parsed with [`ts-morph`](https://ts-morph.com); the analyzer walks the AST and emits normalized tokens (string literals, signed numeric literals, identifiers, object keys) annotated with structural capability context and registration context.
-- **Python** — a bundled script (`dist/python/mcp_ast_scan.py`) runs `ast.parse` + a context-tracking walk in a subprocess (chunked for large repos) and emits the same token shape. When no interpreter exists, a regex fallback covers the deterministic rules.
-- A single rule engine applies all 7 rules to those tokens, so TS and Python behave identically. Findings are de-duplicated per (line, column, rule) and can be suppressed inline.
+- **Python** — a bundled script (`dist/python/mcp_ast_scan.py`) runs `ast.parse` + a context-tracking walk in a subprocess (chunked for large repos) and emits the same token shape (with character-accurate columns). When no interpreter exists, a regex fallback covers the deterministic rules.
+- A single rule engine applies all 9 rules to those tokens, so TS and Python behave identically. Findings are de-duplicated per (line, column, rule) and can be suppressed inline.
+
+It matches the ways real servers are actually written, not just raw method strings:
+
+- **literal method strings** — `'tasks/list'`, `'sampling/createMessage'`, `'logging/setLevel'`, …
+- **SDK schema-constant registration** — `server.setRequestHandler(InitializeRequestSchema, …)` (how the official SDKs register handlers) maps `InitializeRequestSchema`, `ListRootsRequestSchema`, `CreateMessageRequestSchema`, `SetLevelRequestSchema`, `ListTasksRequestSchema`, `GetTaskResultRequestSchema`, … to the right rule.
+- **SDK capability constructors** — the Python SDK's `ClientCapabilities(roots=RootsCapability())` is recognized structurally (high confidence), and `RootsCapability` / `SamplingCapability` / `LoggingCapability` are matched directly.
+- **`sessionIdGenerator`** — flagged only when it's a real generator, not the migrated `sessionIdGenerator: undefined`.
+
+Validated against a broad corpus of real MCP servers (the official reference servers, TS + Python): **0 false positives**.
+
+### Known limitations
+
+- **Python SDK decorator/method registration** — a handler wired purely as `@server.list_roots()` or a bare `session.list_roots()` call (with no capability declaration or method string in the file) is not matched, to avoid false positives on generic method names. The capability declaration in the same server is normally caught.
+- **Split/computed method strings** — `"tasks" + "/list"` or `f"tasks/{x}"` are not reconstructed.
+- The **regex fallback** (no Python interpreter) covers only the deterministic rules at reduced precision; install Python for full `.py` fidelity.
+
+## Programmatic API
+
+The scanner is usable as a library (typed) as well as a CLI — for editor extensions, custom CI steps, or migration harnesses:
+
+```ts
+import { scan, ALL_PATTERN_IDS, IgnoreMatcher, applyFixes } from '@booyaka/mcp-vet';
+
+const result = scan(['./src'], {
+  enabled: new Set(ALL_PATTERN_IDS),
+  ignore: new IgnoreMatcher([]),
+  maxFileSizeKb: 0,
+  pythonFallback: true,
+  minConfidence: 'low',
+});
+
+for (const f of result.findings) {
+  console.log(`${f.file}:${f.line} ${f.severity} ${f.patternId}`);
+}
+
+// Apply the safe mechanical fixes:
+applyFixes(result.findings);
+```
+
+Also exported: `renderJson` / `renderMarkdown` / `renderSarif`, `RULES`, and the `Finding` / `PatternId` / `Severity` / `Confidence` types.
 
 ## Requirements
 
@@ -255,7 +369,7 @@ To upload results to GitHub code scanning instead:
 ```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 (18 tests)
+npm test         # builds, then runs the Node.js built-in test runner (30 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).

package/dist/autofix.d.ts

@@ -0,0 +1,26 @@
+import { Finding, PatternId } from './types';
+export interface FixPreview {
+    file: string;
+    line: number;
+    before: string;
+    after: string;
+}
+export interface FixResult {
+    fixedCount: number;
+    filesChanged: string[];
+    fixedFindings: Finding[];
+    /** Every planned rewrite (populated in both real and dry-run modes). */
+    preview: FixPreview[];
+}
+export interface FixOptions {
+    /** Compute and return the rewrites without touching any files. */
+    dryRun?: boolean;
+}
+export declare function isFixable(id: PatternId): 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.
+ * Replacements are same-length, so multiple fixes on one line never shift each
+ * other's positions.
+ */
+export declare function applyFixes(findings: Finding[], opts?: FixOptions): FixResult;

package/dist/autofix.js

@@ -0,0 +1,130 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFixable = isFixable;
+exports.applyFixes = applyFixes;
+const fs = __importStar(require("node:fs"));
+/**
+ * Rules whose fix is a safe, purely mechanical text substitution. Only the
+ * resource-not-found error code qualifies: -32002 -> -32602 is a same-length
+ * swap with no semantic ambiguity. Everything else (removed handshake, removed
+ * sessions, tasks/list removal, capability deprecations) requires human
+ * judgement and is deliberately NOT auto-fixed.
+ */
+const FIXABLE = new Set(['ERROR_CODE_32002']);
+function isFixable(id) {
+    return FIXABLE.has(id);
+}
+/**
+ * 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.
+ * Replacements are same-length, so multiple fixes on one line never shift each
+ * other's positions.
+ */
+function applyFixes(findings, opts = {}) {
+    const byFile = new Map();
+    for (const f of findings) {
+        if (!isFixable(f.patternId) || !f.absPath)
+            continue;
+        const list = byFile.get(f.absPath) ?? [];
+        list.push(f);
+        byFile.set(f.absPath, list);
+    }
+    const filesChanged = [];
+    const fixedFindings = [];
+    const preview = [];
+    let fixedCount = 0;
+    for (const [absPath, fileFindings] of byFile) {
+        let raw;
+        try {
+            raw = fs.readFileSync(absPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const hasBom = raw.charCodeAt(0) === 0xfeff;
+        const text = hasBom ? raw.slice(1) : raw;
+        // Split on \n only; any \r stays attached to the line content, so CRLF
+        // endings are preserved verbatim on rejoin.
+        const lines = text.split('\n');
+        const applied = [];
+        const localPreview = [];
+        for (const f of fileFindings) {
+            const idx = f.line - 1;
+            if (idx < 0 || idx >= lines.length)
+                continue;
+            const L = lines[idx];
+            const col = (f.column ?? 0) - 1; // anchored at the '-' (both analyzers), else the first digit
+            // Require an exact column match. We deliberately do NOT fall back to a
+            // blind indexOf: a mislocated column (e.g. a skewed offset) could otherwise
+            // rewrite an unrelated `-32002` inside a string or comment and corrupt it.
+            let next = null;
+            if (col >= 0 && L.startsWith('-32002', col)) {
+                next = L.slice(0, col) + '-32602' + L.slice(col + 6);
+            }
+            else if (col >= 0 && L.startsWith('32002', col)) {
+                next = L.slice(0, col) + '32602' + L.slice(col + 5);
+            }
+            if (next !== null && next !== L) {
+                localPreview.push({ file: f.file, line: f.line, before: L.replace(/\r$/, ''), after: next.replace(/\r$/, '') });
+                lines[idx] = next;
+                applied.push(f);
+            }
+        }
+        if (applied.length === 0)
+            continue;
+        if (opts.dryRun) {
+            // Report what WOULD change; touch nothing.
+            preview.push(...localPreview);
+            continue;
+        }
+        // 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');
+        try {
+            fs.writeFileSync(absPath, out, 'utf8');
+        }
+        catch {
+            continue; // nothing fixed for this file
+        }
+        filesChanged.push(absPath);
+        preview.push(...localPreview);
+        for (const f of applied) {
+            fixedFindings.push(f);
+            fixedCount++;
+        }
+    }
+    return { fixedCount, filesChanged, fixedFindings, preview };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -43,6 +43,7 @@ const config_1 = require("./config");
 const types_1 = require("./types");
 const constants_1 = require("./constants");
 const reporters_1 = require("./reporters");
+const autofix_1 = require("./autofix");
 const CONF_VALUES = ['high', 'medium', 'low'];
 const FAILON_VALUES = ['breaking', 'any', 'none'];
 function fail(msg) {
@@ -98,6 +99,9 @@ program
     .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')
@@ -141,7 +145,8 @@ 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)));
-else if (disable && disable.length) {
+// `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);
 }
@@ -194,19 +199,52 @@ catch (err) {
         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 {
+        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);
 }
-if (!opts.quiet) {
+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 (!opts.quiet)
-            console.log(`Wrote ${sarifPath}`);
+        if (!quiet)
+            notify(`Wrote ${sarifPath}`);
     }
     catch (err) {
         console.error(`mcp-vet: failed to write SARIF: ${err.message}`);
@@ -216,9 +254,9 @@ if (opts.files) {
     try {
         const md = (0, reporters_1.writeMarkdown)(result, opts.outDir);
         const json = (0, reporters_1.writeJson)(result, opts.outDir);
-        if (!opts.quiet) {
-            console.log(`Wrote ${md}`);
-            console.log(`Wrote ${json}`);
+        if (!quiet) {
+            notify(`Wrote ${md}`);
+            notify(`Wrote ${json}`);
         }
     }
     catch (err) {

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+import { PatternId, Confidence } from './types';
+export type FailOn = 'breaking' | 'any' | 'none';
+export interface Config {
+    ignore?: string[];
+    only?: PatternId[];
+    disable?: PatternId[];
+    failOn?: FailOn;
+    minConfidence?: Confidence;
+    maxFileSizeKb?: number;
+    pythonFallback?: boolean;
+}
+export declare class ConfigError extends Error {
+}
+/**
+ * Load config. If `explicitPath` is given it must exist and parse (throws
+ * ConfigError otherwise). Otherwise the first known config file found in `cwd`
+ * is used; missing config is not an error.
+ */
+export declare function loadConfig(cwd: string, explicitPath?: string): Config;

package/dist/constants.d.ts

@@ -0,0 +1,11 @@
+export declare const SPEC_DATE = "July 28, 2026";
+export declare const SPEC_URL = "https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/";
+export declare const CHANGELOG_URL = "https://tokenmix.ai/blog/mcp-updates-changelog-every-protocol-change-2026";
+/**
+ * 2026-07-28 changes that are real but NOT reliably detectable by static token
+ * analysis — surfaced to the user so the tool is honest about its scope rather
+ * than implying "clean === fully migrated".
+ */
+export declare const MANUAL_REVIEW: string[];
+/** Resolve the package version from package.json, tolerating layout differences. */
+export declare function getVersion(): string;

package/dist/constants.js

@@ -33,13 +33,24 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CHANGELOG_URL = exports.SPEC_URL = exports.SPEC_DATE = void 0;
+exports.MANUAL_REVIEW = exports.CHANGELOG_URL = exports.SPEC_URL = exports.SPEC_DATE = void 0;
 exports.getVersion = getVersion;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 exports.SPEC_DATE = 'July 28, 2026';
 exports.SPEC_URL = 'https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/';
 exports.CHANGELOG_URL = 'https://tokenmix.ai/blog/mcp-updates-changelog-every-protocol-change-2026';
+/**
+ * 2026-07-28 changes that are real but NOT reliably detectable by static token
+ * analysis — surfaced to the user so the tool is honest about its scope rather
+ * than implying "clean === fully migrated".
+ */
+exports.MANUAL_REVIEW = [
+    'the long-lived server→client SSE push channel is removed (a server may only send requests while handling one)',
+    'Streamable HTTP now requires Mcp-Method and Mcp-Name headers that mirror the JSON-RPC body',
+    'auth hardening: validate the RFC 9207 `iss` param, send OIDC `application_type`, bind tokens to the issuer',
+    'tool inputSchema/outputSchema may now be full JSON Schema 2020-12 (do not auto-dereference external $ref)',
+];
 /** Resolve the package version from package.json, tolerating layout differences. */
 function getVersion() {
     const candidates = [

package/dist/ignore.d.ts

@@ -0,0 +1,6 @@
+export declare class IgnoreMatcher {
+    private readonly regexes;
+    constructor(patterns: string[]);
+    get size(): number;
+    matches(relPosixPath: string): boolean;
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Programmatic API for mcp-vet.
+ *
+ * The CLI (`dist/cli.js`) is the primary entry point, but the scanner and its
+ * reporters are usable as a library — e.g. from an editor extension, a custom CI
+ * step, or a migration harness:
+ *
+ * ```ts
+ * import { scan, renderJson, applyFixes } from '@booyaka/mcp-vet';
+ * const result = scan(['./src'], {
+ *   enabled: new Set(ALL_PATTERN_IDS),
+ *   ignore: new IgnoreMatcher([]),
+ *   maxFileSizeKb: 0,
+ *   pythonFallback: true,
+ *   minConfidence: 'low',
+ * });
+ * console.log(result.findings);
+ * ```
+ */
+export { scan, ScanError } from './scanner';
+export type { ScanOptions, ScanResult, PythonMode } from './scanner';
+export { applyFixes, isFixable } from './autofix';
+export type { FixResult } from './autofix';
+export { renderJson, renderMarkdown, renderSarif, toPublicFinding } from './reporters';
+export { RULES } from './rules';
+export { IgnoreMatcher } from './ignore';
+export { SPEC_URL, SPEC_DATE, CHANGELOG_URL, MANUAL_REVIEW, getVersion } from './constants';
+export { ALL_PATTERN_IDS } from './types';
+export type { Finding, PatternId, Severity, Confidence, Token } from './types';

package/dist/index.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_PATTERN_IDS = exports.getVersion = exports.MANUAL_REVIEW = exports.CHANGELOG_URL = exports.SPEC_DATE = exports.SPEC_URL = exports.IgnoreMatcher = exports.RULES = exports.toPublicFinding = exports.renderSarif = exports.renderMarkdown = exports.renderJson = exports.isFixable = exports.applyFixes = exports.ScanError = exports.scan = void 0;
+/**
+ * Programmatic API for mcp-vet.
+ *
+ * The CLI (`dist/cli.js`) is the primary entry point, but the scanner and its
+ * reporters are usable as a library — e.g. from an editor extension, a custom CI
+ * step, or a migration harness:
+ *
+ * ```ts
+ * import { scan, renderJson, applyFixes } from '@booyaka/mcp-vet';
+ * const result = scan(['./src'], {
+ *   enabled: new Set(ALL_PATTERN_IDS),
+ *   ignore: new IgnoreMatcher([]),
+ *   maxFileSizeKb: 0,
+ *   pythonFallback: true,
+ *   minConfidence: 'low',
+ * });
+ * console.log(result.findings);
+ * ```
+ */
+var scanner_1 = require("./scanner");
+Object.defineProperty(exports, "scan", { enumerable: true, get: function () { return scanner_1.scan; } });
+Object.defineProperty(exports, "ScanError", { enumerable: true, get: function () { return scanner_1.ScanError; } });
+var autofix_1 = require("./autofix");
+Object.defineProperty(exports, "applyFixes", { enumerable: true, get: function () { return autofix_1.applyFixes; } });
+Object.defineProperty(exports, "isFixable", { enumerable: true, get: function () { return autofix_1.isFixable; } });
+var reporters_1 = require("./reporters");
+Object.defineProperty(exports, "renderJson", { enumerable: true, get: function () { return reporters_1.renderJson; } });
+Object.defineProperty(exports, "renderMarkdown", { enumerable: true, get: function () { return reporters_1.renderMarkdown; } });
+Object.defineProperty(exports, "renderSarif", { enumerable: true, get: function () { return reporters_1.renderSarif; } });
+Object.defineProperty(exports, "toPublicFinding", { enumerable: true, get: function () { return reporters_1.toPublicFinding; } });
+var rules_1 = require("./rules");
+Object.defineProperty(exports, "RULES", { enumerable: true, get: function () { return rules_1.RULES; } });
+var ignore_1 = require("./ignore");
+Object.defineProperty(exports, "IgnoreMatcher", { enumerable: true, get: function () { return ignore_1.IgnoreMatcher; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "SPEC_URL", { enumerable: true, get: function () { return constants_1.SPEC_URL; } });
+Object.defineProperty(exports, "SPEC_DATE", { enumerable: true, get: function () { return constants_1.SPEC_DATE; } });
+Object.defineProperty(exports, "CHANGELOG_URL", { enumerable: true, get: function () { return constants_1.CHANGELOG_URL; } });
+Object.defineProperty(exports, "MANUAL_REVIEW", { enumerable: true, get: function () { return constants_1.MANUAL_REVIEW; } });
+Object.defineProperty(exports, "getVersion", { enumerable: true, get: function () { return constants_1.getVersion; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "ALL_PATTERN_IDS", { enumerable: true, get: function () { return types_1.ALL_PATTERN_IDS; } });

package/dist/py-analyzer.d.ts

@@ -0,0 +1,11 @@
+import { Token } from './types';
+/** Locate a usable Python 3 interpreter, trying platform-appropriate names. */
+export declare function findPython(): string | null;
+export declare function pythonAvailable(): boolean;
+/**
+ * Analyze a batch of Python files via the bundled subprocess script. Files are
+ * processed in chunks so a single pathological file can only lose its own chunk,
+ * and so stdin/stdout stay well under buffer limits on large repos.
+ * Returns a map of absolute-file-path -> tokens.
+ */
+export declare function analyzePyBatch(absFiles: string[]): Record<string, Token[]>;

package/dist/py-fallback.d.ts

@@ -0,0 +1,9 @@
+import { Token } from './types';
+/**
+ * Degraded, regex-based tokenizer for Python source, used ONLY when no Python
+ * interpreter is available. It cannot verify AST structure, so capability
+ * findings fall back to the line-proximity heuristic (medium confidence) and it
+ * may over-report inside comments/docstrings. Deterministic string/number rules
+ * (session id, initialize, -32002, tasks/*) remain reliable.
+ */
+export declare function regexFallbackTokens(text: string): Token[];

package/dist/python/mcp_ast_scan.py

@@ -22,9 +22,23 @@ sys.setrecursionlimit(20000)
 CAP = {"roots", "sampling", "logging"}
 INIT_STRINGS = {"initialize", "notifications/initialized"}
 HANDLERISH = re.compile(r"handler|handle|register|route|request|notification|method|^on$", re.I)
+CAPS_RE = re.compile(r"capabilit", re.I)
 METHODISH = ("method", "type")
 
 
+def _func_mentions_caps(func):
+    """True when a call target names a capabilities container, e.g.
+    ClientCapabilities(...) / ServerCapabilities(...) — the Python SDK's way of
+    declaring capabilities, so `roots=`/`sampling=`/`logging=` kwargs inside are
+    structural (high confidence), not merely near the word 'capabilities'."""
+    name = ""
+    if isinstance(func, ast.Attribute):
+        name = func.attr
+    elif isinstance(func, ast.Name):
+        name = func.id
+    return bool(CAPS_RE.search(name))
+
+
 def _is_int_constant(node):
     return (
         isinstance(node, ast.Constant)
@@ -33,9 +47,14 @@ def _is_int_constant(node):
     )
 
 
-def _col(node):
-    c = getattr(node, "col_offset", None)
-    return (c + 1) if isinstance(c, int) else None
+def _byte_to_char_col(line, byte_off):
+    """Convert a CPython ``ast`` UTF-8 *byte* col_offset to a 1-based *character*
+    column, matching ts-morph and JS string indexing. col_offset always lands on
+    a character boundary (start of a node), so the truncated decode is clean."""
+    if line is None:
+        return byte_off + 1
+    prefix = line.encode("utf-8", "surrogatepass")[:byte_off]
+    return len(prefix.decode("utf-8", "ignore")) + 1
 
 
 def _mentions_method(o):
@@ -85,13 +104,22 @@ def _is_registration(node):
 
 
 class Scanner:
-    def __init__(self):
+    def __init__(self, lines):
         self.tokens = []
+        self.lines = lines
+
+    def _col(self, node):
+        c = getattr(node, "col_offset", None)
+        if not isinstance(c, int):
+            return None
+        ln = getattr(node, "lineno", None)
+        line = self.lines[ln - 1] if isinstance(ln, int) and 1 <= ln <= len(self.lines) else None
+        return _byte_to_char_col(line, c)
 
     def emit_for(self, node, in_caps):
         if isinstance(node, ast.Constant):
             if isinstance(node.value, str):
-                tok = {"kind": "string", "value": node.value, "line": node.lineno, "col": _col(node)}
+                tok = {"kind": "string", "value": node.value, "line": node.lineno, "col": self._col(node)}
                 if node.value in CAP:
                     tok["inCapabilities"] = in_caps
                 if node.value in INIT_STRINGS:
@@ -99,17 +127,17 @@ class Scanner:
                 self.tokens.append(tok)
             elif _is_int_constant(node):
                 self.tokens.append(
-                    {"kind": "number", "value": str(node.value), "line": node.lineno, "col": _col(node)}
+                    {"kind": "number", "value": str(node.value), "line": node.lineno, "col": self._col(node)}
                 )
         elif isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub) and _is_int_constant(node.operand):
-            op = node.operand
+            # Anchor negative numbers at the '-' (the UnaryOp), matching ts-morph.
             self.tokens.append(
-                {"kind": "number", "value": str(-op.value), "line": op.lineno, "col": _col(node)}
+                {"kind": "number", "value": str(-node.operand.value), "line": node.lineno, "col": self._col(node)}
             )
         elif isinstance(node, ast.Name):
-            self.tokens.append({"kind": "name", "value": node.id, "line": node.lineno, "col": _col(node)})
+            self.tokens.append({"kind": "name", "value": node.id, "line": node.lineno, "col": self._col(node)})
         elif isinstance(node, ast.Attribute):
-            self.tokens.append({"kind": "name", "value": node.attr, "line": node.lineno, "col": _col(node)})
+            self.tokens.append({"kind": "name", "value": node.attr, "line": node.lineno, "col": self._col(node)})
 
     def visit(self, node, in_caps):
         self.emit_for(node, in_caps)
@@ -119,7 +147,7 @@ class Scanner:
                 if k is not None:
                     self.visit(k, in_caps)
                     if isinstance(k, ast.Constant) and isinstance(k.value, str):
-                        tok = {"kind": "key", "value": k.value, "line": k.lineno, "col": _col(k)}
+                        tok = {"kind": "key", "value": k.value, "line": k.lineno, "col": self._col(k)}
                         if k.value in CAP:
                             tok["inCapabilities"] = in_caps
                         self.tokens.append(tok)
@@ -128,17 +156,20 @@ class Scanner:
             return
 
         if isinstance(node, ast.Call):
+            # A call to ClientCapabilities(...) / ServerCapabilities(...) is itself
+            # a capabilities container — its args/kwargs are structurally in-caps.
+            caps_ctx = in_caps or _func_mentions_caps(node.func)
             self.visit(node.func, in_caps)
             for a in node.args:
-                self.visit(a, in_caps)
+                self.visit(a, caps_ctx)
             for kw in node.keywords:
                 if kw.arg is not None:
                     line = getattr(kw, "lineno", None) or getattr(kw.value, "lineno", 0)
-                    tok = {"kind": "key", "value": kw.arg, "line": line, "col": _col(kw)}
+                    tok = {"kind": "key", "value": kw.arg, "line": line, "col": self._col(kw)}
                     if kw.arg in CAP:
-                        tok["inCapabilities"] = in_caps
+                        tok["inCapabilities"] = caps_ctx
                     self.tokens.append(tok)
-                child_caps = in_caps or (kw.arg == "capabilities")
+                child_caps = caps_ctx or (kw.arg == "capabilities")
                 self.visit(kw.value, child_caps)
             return
 
@@ -154,7 +185,7 @@ def scan_source(src):
     for n in ast.walk(tree):
         for c in ast.iter_child_nodes(n):
             c.parent = n
-    scanner = Scanner()
+    scanner = Scanner(src.split("\n"))
     try:
         scanner.visit(tree, False)
     except RecursionError:

package/dist/reporters.d.ts

@@ -0,0 +1,34 @@
+import { Finding, Severity } from './types';
+import { ScanResult } from './scanner';
+export interface TerminalOptions {
+    color?: boolean;
+}
+/** (a) Terminal report — red for BREAKING, yellow for DEPRECATED, compiler-style. */
+export declare function reportTerminal(result: ScanResult, opts?: TerminalOptions): void;
+/** (b) Markdown table report. */
+export declare function renderMarkdown(result: ScanResult): string;
+export declare function writeMarkdown(result: ScanResult, outDir: string): string;
+/** Public projection of a finding for serialized output (drops internal fields). */
+export declare function toPublicFinding(f: Finding): {
+    file: string;
+    line: number;
+    column: number | null;
+    endColumn: number | null;
+    patternId: import("./types").PatternId;
+    patternLabel: string;
+    severity: Severity;
+    confidence: import("./types").Confidence;
+    explanation: string;
+    docUrl: string;
+    source: "ts-morph" | "python-ast" | "regex" | null;
+    before: string;
+    after: string;
+};
+/** (c) Structured JSON array of all findings. */
+export declare function renderJson(result: ScanResult): string;
+export declare function writeJson(result: ScanResult, outDir: string): string;
+/** (d) GitHub Actions native annotations. ::error for BREAKING, ::warning for DEPRECATED. */
+export declare function printGithubAnnotations(findings: Finding[]): void;
+/** (e) SARIF 2.1.0 for GitHub code scanning / other SARIF consumers. */
+export declare function renderSarif(result: ScanResult): string;
+export declare function writeSarif(result: ScanResult, outPath: string): string;

package/dist/reporters.js

@@ -86,6 +86,7 @@ function reportTerminal(result, opts = {}) {
         const suffix = result.suppressedCount > 0 ? ` (${result.suppressedCount} suppressed)` : '';
         console.log(c.green('✔ mcp-vet: no matching 2026-07-28 breaking or deprecated patterns found') +
             c.gray(` — ${result.filesScanned} file(s) scanned${suffix}`));
+        printManualReview(c);
         return;
     }
     let currentFile = '';
@@ -111,6 +112,11 @@ function reportTerminal(result, opts = {}) {
     const suppressed = result.suppressedCount > 0 ? c.gray(` (${result.suppressedCount} suppressed)`) : '';
     console.log((breaking > 0 ? c.red.bold(summary) : c.yellow.bold(summary)) + suppressed);
     console.log(c.gray(`See ${constants_1.SPEC_URL}`));
+    printManualReview(c);
+}
+/** One-line pointer to the changes static analysis can't catch — keeps the tool honest. */
+function printManualReview(c) {
+    console.error(c.gray(`note: ${constants_1.MANUAL_REVIEW.length} more 2026-07-28 changes need manual review (SSE push, required headers, auth, JSON Schema 2020-12) — see the README "Needs manual review" section.`));
 }
 function mdEscape(s) {
     return s.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');

package/dist/rules.d.ts

@@ -0,0 +1,27 @@
+import { Token, Finding, PatternId, Severity } from './types';
+interface RuleMeta {
+    id: PatternId;
+    label: string;
+    severity: Severity;
+    explanation: string;
+    after: string;
+}
+/**
+ * Canonical metadata for each of the 7 patterns. The `after` strings are the
+ * corrected 2026-07-28 patterns, authored from the official RC post
+ * (blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate) and the
+ * tokenmix protocol changelog.
+ */
+export declare const RULES: Record<PatternId, RuleMeta>;
+export interface EngineOptions {
+    /** the set of pattern IDs to evaluate (already resolved from only/disable) */
+    enabled: Set<PatternId>;
+    absPath: string;
+    source: NonNullable<Finding['source']>;
+}
+/**
+ * Apply the enabled detection rules to the tokens of a single file, producing
+ * findings with a confidence score.
+ */
+export declare function applyRules(relPath: string, lines: string[], tokens: Token[], opts: EngineOptions): Finding[];
+export {};

package/dist/rules.js

@@ -50,6 +50,26 @@ exports.RULES = {
             '// using the NEW argument shapes — review your params against the RC schema.',
         ].join('\n'),
     },
+    TASKS_LIST_REMOVED: {
+        id: 'TASKS_LIST_REMOVED',
+        label: 'removed tasks/list method',
+        severity: 'BREAKING',
+        explanation: 'The tasks/list method is removed entirely on 2026-07-28 (unsafe once protocol-level sessions are gone); there is no drop-in replacement — stop calling/handling it and track task handles yourself.',
+        after: [
+            '// 2026-07-28: tasks/list is REMOVED — there is no server-side task listing.',
+            '// A client tracks the task handles it received from tools/call; there is nothing to enumerate.',
+        ].join('\n'),
+    },
+    TASKS_RESULT_REMOVED: {
+        id: 'TASKS_RESULT_REMOVED',
+        label: 'removed tasks/result method',
+        severity: 'BREAKING',
+        explanation: 'The blocking tasks/result method is removed on 2026-07-28 (SEP-2663); poll for completion and read the result with tasks/get instead.',
+        after: [
+            '// 2026-07-28: tasks/result is REMOVED — the blocking result call is gone.',
+            '// Poll tasks/get until the task is terminal and read its result from there.',
+        ].join('\n'),
+    },
     ROOTS_CAP: {
         id: 'ROOTS_CAP',
         label: 'roots capability',
@@ -78,6 +98,39 @@ const CAP_NAMES = {
     sampling: 'SAMPLING_CAP',
     logging: 'LOGGING_CAP',
 };
+// Method-name strings of the deprecated capabilities (SEP-2577). The methods are
+// deprecated, not just the capability keys — a server that references these by
+// method string (with no literal `capabilities` object nearby) is caught here.
+const DEPRECATED_METHODS = {
+    'roots/list': 'ROOTS_CAP',
+    'notifications/roots/list_changed': 'ROOTS_CAP',
+    'sampling/createMessage': 'SAMPLING_CAP',
+    'logging/setLevel': 'LOGGING_CAP',
+    'notifications/message': 'LOGGING_CAP',
+};
+// SDK request/notification *schema constants* — how real MCP SDK servers register
+// handlers (e.g. `server.setRequestHandler(InitializeRequestSchema, ...)`). Matching
+// the exact string literal alone misses these entirely.
+const SCHEMA_CONSTANTS = {
+    InitializeRequestSchema: 'INITIALIZE_HANDLER',
+    InitializedNotificationSchema: 'INITIALIZE_HANDLER',
+    ListRootsRequestSchema: 'ROOTS_CAP',
+    RootsListChangedNotificationSchema: 'ROOTS_CAP',
+    CreateMessageRequestSchema: 'SAMPLING_CAP',
+    SetLevelRequestSchema: 'LOGGING_CAP',
+    LoggingMessageNotificationSchema: 'LOGGING_CAP',
+    ListTasksRequestSchema: 'TASKS_LIST_REMOVED',
+    GetTaskResultRequestSchema: 'TASKS_RESULT_REMOVED',
+    GetTaskRequestSchema: 'TASKS_LEGACY',
+    CancelTaskRequestSchema: 'TASKS_LEGACY',
+};
+// SDK capability *constructor* identifiers (esp. the Python SDK:
+// `ClientCapabilities(roots=RootsCapability())`). Unambiguous deprecated-feature use.
+const CAP_CONSTRUCTORS = {
+    RootsCapability: 'ROOTS_CAP',
+    SamplingCapability: 'SAMPLING_CAP',
+    LoggingCapability: 'LOGGING_CAP',
+};
 function snippet(lines, line) {
     const idx = line - 1;
     const out = [];
@@ -150,6 +203,35 @@ function applyRules(relPath, lines, tokens, opts) {
             (v === 'tasks/get' || v === 'tasks/update' || v === 'tasks/cancel')) {
             push('TASKS_LEGACY', t, 'high');
         }
+        // Rule 4b — tasks/list is removed entirely (exact string literal)
+        if (t.kind === 'string' && v === 'tasks/list') {
+            push('TASKS_LIST_REMOVED', t, 'high');
+        }
+        // Rule 4c — tasks/result is removed (exact string literal)
+        if (t.kind === 'string' && v === 'tasks/result') {
+            push('TASKS_RESULT_REMOVED', t, 'high');
+        }
+        // Rule 8 — deprecated-capability method strings (exact, high confidence)
+        if (t.kind === 'string' && DEPRECATED_METHODS[v]) {
+            push(DEPRECATED_METHODS[v], t, 'high');
+        }
+        // Rule 9 — SDK schema-constant identifiers used to register handlers
+        if (t.kind === 'name' && SCHEMA_CONSTANTS[v]) {
+            push(SCHEMA_CONSTANTS[v], t, 'high');
+        }
+        // Rule 9b — SDK capability constructor identifiers (RootsCapability, ...)
+        if (t.kind === 'name' && CAP_CONSTRUCTORS[v]) {
+            push(CAP_CONSTRUCTORS[v], t, 'high');
+        }
+        // Rule 10 — `sessionIdGenerator` option (TS SDK session usage). The correct
+        // migration is `sessionIdGenerator: undefined`, so the analyzer marks that
+        // benign; only a real generator is flagged, at medium confidence. TS only.
+        if (opts.source === 'ts-morph' &&
+            t.kind === 'key' &&
+            v === 'sessionIdGenerator' &&
+            !t.benign) {
+            push('MCP_SESSION_ID', t, 'medium');
+        }
         // Rules 5-7 — deprecated capabilities.
         // High confidence when structurally inside a `capabilities` object (AST);
         // medium when only within 5 lines of a "capabilities" mention.

package/dist/scanner.d.ts

@@ -0,0 +1,23 @@
+import { Finding, PatternId, Confidence } from './types';
+import { IgnoreMatcher } from './ignore';
+export interface ScanOptions {
+    enabled: Set<PatternId>;
+    ignore: IgnoreMatcher;
+    /** 0 = no limit */
+    maxFileSizeKb: number;
+    pythonFallback: boolean;
+    minConfidence: Confidence;
+}
+export type PythonMode = 'ast' | 'regex' | 'none' | 'n/a';
+export interface ScanResult {
+    findings: Finding[];
+    filesScanned: number;
+    pythonFilesFound: number;
+    pythonMode: PythonMode;
+    suppressedCount: number;
+    skippedLargeFiles: string[];
+    roots: string[];
+}
+export declare class ScanError extends Error {
+}
+export declare function scan(roots: string[], opts: ScanOptions): ScanResult;

package/dist/suppress.d.ts

@@ -0,0 +1,15 @@
+import { PatternId } from './types';
+export interface Suppressions {
+    fileDisabled: boolean;
+    /** line (1-indexed) -> set of suppressed pattern IDs (empty set = all) */
+    byLine: Map<number, Set<PatternId>>;
+    isSuppressed(line: number, id: PatternId): boolean;
+}
+/**
+ * Parse inline suppression directives from a file's raw lines. Recognized in any
+ * comment style (they are matched textually):
+ *   mcp-vet-disable-file
+ *   mcp-vet-disable-line [PATTERN_ID ...]
+ *   mcp-vet-disable-next-line [PATTERN_ID ...]
+ */
+export declare function parseSuppressions(lines: string[]): Suppressions;

package/dist/ts-analyzer.d.ts

@@ -0,0 +1,7 @@
+import { Token } from './types';
+/**
+ * Parse a TypeScript/JavaScript file with ts-morph and emit normalized tokens:
+ * string literals, numeric literals (with sign), identifiers, and object keys —
+ * annotated with structural capability context and registration context.
+ */
+export declare function analyzeTs(absPath: string, text: string): Token[];

package/dist/ts-analyzer.js

@@ -168,13 +168,16 @@ function analyzeTs(absPath, text) {
             if (kind === ts_morph_1.SyntaxKind.NumericLiteral) {
                 const raw = node.getText();
                 let value = raw;
+                let anchor = node; // for negatives, anchor at the '-' so col + value.length is exact
                 const parent = node.getParent();
                 if (parent && parent.getKind() === ts_morph_1.SyntaxKind.PrefixUnaryExpression) {
                     const pu = parent.asKind(ts_morph_1.SyntaxKind.PrefixUnaryExpression);
-                    if (pu && pu.getOperatorToken() === ts_morph_1.SyntaxKind.MinusToken)
+                    if (pu && pu.getOperatorToken() === ts_morph_1.SyntaxKind.MinusToken) {
                         value = '-' + raw;
+                        anchor = parent;
+                    }
                 }
-                const { line, col } = posOf(node);
+                const { line, col } = posOf(anchor);
                 tokens.push({ kind: 'number', value, line, col });
                 return;
             }
@@ -185,16 +188,25 @@ function analyzeTs(absPath, text) {
             }
         });
         // Object literal keys (roots:, "sampling":, logging shorthand, ...)
-        const emitKey = (nameNode, value) => {
+        const emitKey = (nameNode, value, benign = false) => {
             const { line, col } = posOf(nameNode);
             const tok = { kind: 'key', value, line, col };
             if (CAP.has(value))
                 tok.inCapabilities = isInCapabilities(nameNode);
+            if (benign)
+                tok.benign = true;
             tokens.push(tok);
         };
         for (const pa of sf.getDescendantsOfKind(ts_morph_1.SyntaxKind.PropertyAssignment)) {
             try {
-                emitKey(pa.getNameNode(), pa.getName());
+                const name = pa.getName();
+                // `sessionIdGenerator: undefined` (or null) is the migrated, stateless form.
+                let benign = false;
+                if (name === 'sessionIdGenerator') {
+                    const init = pa.getInitializer()?.getText();
+                    benign = init === 'undefined' || init === 'null';
+                }
+                emitKey(pa.getNameNode(), name, benign);
             }
             catch {
                 /* computed / unusual key */

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+export type Severity = 'BREAKING' | 'DEPRECATED';
+export type Confidence = 'high' | 'medium' | 'low';
+export type PatternId = 'MCP_SESSION_ID' | 'INITIALIZE_HANDLER' | 'ERROR_CODE_32002' | 'TASKS_LEGACY' | 'TASKS_LIST_REMOVED' | 'TASKS_RESULT_REMOVED' | 'ROOTS_CAP' | 'SAMPLING_CAP' | 'LOGGING_CAP';
+export declare const ALL_PATTERN_IDS: PatternId[];
+/**
+ * A normalized syntactic token emitted by a language analyzer. Every analyzer
+ * (ts-morph, the Python subprocess, and the regex fallback) emits this exact
+ * shape so the rule engine can be written once and applied uniformly.
+ */
+export interface Token {
+    /** string literal, numeric literal, identifier/variable name, or object key */
+    kind: 'string' | 'number' | 'name' | 'key';
+    /** literal text of the token. For numbers, the signed decimal (e.g. "-32002"). */
+    value: string;
+    /** 1-indexed line number */
+    line: number;
+    /** 1-indexed column number, when known */
+    col?: number;
+    /**
+     * True when this token is *structurally* inside a `capabilities`
+     * object/argument (AST-verified). Drives high-confidence capability findings.
+     */
+    inCapabilities?: boolean;
+    /**
+     * True when a string literal appears in a method-registration / switch-case /
+     * method-comparison context (used to raise confidence for `initialize`).
+     */
+    registration?: boolean;
+    /**
+     * True when this token is an already-migrated no-op that must NOT be flagged —
+     * e.g. `sessionIdGenerator: undefined`, the documented stateless migration.
+     */
+    benign?: boolean;
+}
+export interface Finding {
+    /** path relative to the scan root, forward-slashed */
+    file: string;
+    line: number;
+    /** 1-indexed column, when known */
+    column?: number;
+    /** 1-indexed end column, when known (for SARIF regions / editor selection) */
+    endColumn?: number;
+    patternId: PatternId;
+    patternLabel: string;
+    severity: Severity;
+    confidence: Confidence;
+    /** one-sentence explanation of what changes */
+    explanation: string;
+    /** canonical docs anchor for this pattern */
+    docUrl: string;
+    /** the offending line + one line of context */
+    before: string;
+    /** the correct 2026-07-28 pattern */
+    after: string;
+    /** absolute path — internal only, stripped from serialized output */
+    absPath?: string;
+    /** the analyzer that produced it — internal only */
+    source?: 'ts-morph' | 'python-ast' | 'regex';
+}

package/dist/types.js

@@ -6,6 +6,8 @@ exports.ALL_PATTERN_IDS = [
     'INITIALIZE_HANDLER',
     'ERROR_CODE_32002',
     'TASKS_LEGACY',
+    'TASKS_LIST_REMOVED',
+    'TASKS_RESULT_REMOVED',
     'ROOTS_CAP',
     'SAMPLING_CAP',
     'LOGGING_CAP',

package/package.json

@@ -1,13 +1,24 @@
 {
   "name": "@booyaka/mcp-vet",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scan MCP server source code for patterns that break under the 2026-07-28 Model Context Protocol spec release candidate.",
   "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
   "bin": {
     "mcp-vet": "dist/cli.js"
   },
   "files": [
     "dist",
+    "schema",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/schema/mcpvetrc.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/Booyaka101/mcp-vet/main/schema/mcpvetrc.schema.json",
+  "title": "mcp-vet configuration",
+  "description": "Configuration for the mcp-vet CLI (.mcpvetrc.json / mcp-vet.config.json). CLI flags override these values.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional JSON Schema reference for editor autocomplete/validation."
+    },
+    "ignore": {
+      "type": "array",
+      "description": "Gitignore-style globs to skip.",
+      "items": { "type": "string" }
+    },
+    "only": {
+      "type": "array",
+      "description": "Run only these pattern ids.",
+      "items": { "$ref": "#/$defs/patternId" }
+    },
+    "disable": {
+      "type": "array",
+      "description": "Skip these pattern ids.",
+      "items": { "$ref": "#/$defs/patternId" }
+    },
+    "failOn": {
+      "description": "Which findings cause a non-zero exit.",
+      "enum": ["breaking", "any", "none"],
+      "default": "breaking"
+    },
+    "minConfidence": {
+      "description": "Report only findings at or above this confidence.",
+      "enum": ["high", "medium", "low"],
+      "default": "low"
+    },
+    "maxFileSizeKb": {
+      "type": "number",
+      "description": "Skip files larger than this many KB (0 = no limit).",
+      "minimum": 0,
+      "default": 1536
+    },
+    "pythonFallback": {
+      "type": "boolean",
+      "description": "Use the regex fallback when no Python interpreter is available.",
+      "default": true
+    }
+  },
+  "$defs": {
+    "patternId": {
+      "type": "string",
+      "enum": [
+        "MCP_SESSION_ID",
+        "INITIALIZE_HANDLER",
+        "ERROR_CODE_32002",
+        "TASKS_LEGACY",
+        "TASKS_LIST_REMOVED",
+        "ROOTS_CAP",
+        "SAMPLING_CAP",
+        "LOGGING_CAP"
+      ]
+    }
+  }
+}