@booyaka/mcp-vet 0.2.0 → 0.4.0

package/BENCHMARK.md

@@ -0,0 +1,112 @@
+# Benchmark: corpus, methodology, and honest limits
+
+The README claims high precision on real MCP code. This file is the evidence
+behind that claim — corpus, pinned commits, counts, labels, and what the
+scanner is *known to miss* — so the claim is checkable rather than vibes.
+
+> Prompted by community feedback on the launch post: *"'0 false positives' is
+> encouraging but incomplete without corpus size, commit SHAs, labeled
+> negatives, and recall."* Correct. Here they are.
+
+## Corpus (pinned)
+
+Scanned with `mcp-vet` v0.4.0 (`node dist/cli.js <roots> --json`), all rules
+enabled, default confidence (`low`), on 2026-07-23:
+
+| Repo | Commit | Scanned root | Files | LOC |
+| --- | --- | --- | --- | --- |
+| [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | `d31124c982401739917fd817c2a59db344529c16` | `src/` | 78 | 14,742 |
+| [modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk) | `1e1392e3f91583884fe82a0b4b91335875c3fba6` | `examples/` | 144 | 17,224 |
+| [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) | `3a6f2996cdd8358957479791e8b26198c07d6a75` | `examples/` | 225 | 12,013 |
+| **Total** | | | **447** | **43,979** |
+
+File counts are candidate files (`.ts/.tsx/.js/.mjs/.cjs/.py`) under the
+scanned roots, excluding `node_modules`.
+
+## Results
+
+**105 findings across 41 files** (TypeScript/JavaScript: 93, Python: 12).
+By confidence: 66 high, 38 medium, 1 low.
+
+| Pattern | Findings |
+| --- | --- |
+| `MCP_SESSION_ID` | 49 |
+| `LOGGING_CAP` | 17 |
+| `SAMPLING_CAP` | 16 |
+| `ROOTS_CAP` | 15 |
+| `INITIALIZE_HANDLER` | 4 |
+| `TASKS_LEGACY` | 2 |
+| `TASKS_RESULT_REMOVED` | 2 |
+
+### Labeling
+
+Every finding was manually reviewed against its source line:
+
+- **104 / 105 true positives** — real references to a removed or deprecated
+  protocol surface (session headers/ids, handshake registration, legacy task
+  methods, deprecated capability declarations and method strings).
+- **1 / 105 false positive (0.95%)** —
+  `stories/json_response/client.py:62` in the typescript-sdk examples:
+  `assert "mcp-session-id" not in response.headers`. That line is
+  *already-migrated* test code asserting the header is **absent**; flagging it
+  as "will break" is wrong. It is exactly what inline suppression
+  (`# mcp-vet-disable-line MCP_SESSION_ID`) is for, but we count it as a false
+  positive rather than defining it away. So the honest headline is
+  **"1 false positive in 44k LOC"**, not zero.
+
+Notes on reading the numbers:
+
+- Two occurrences on one line (e.g. `transport.sessionId && sessions.delete(transport.sessionId)`)
+  are reported as two findings — column-level dedup, not line-level.
+- Findings in test files (`__tests__/…`) are counted as true positives: a test
+  that registers `sampling/createMessage` breaks the same way production code
+  does.
+
+### Labeled negatives
+
+Files asserted to stay **clean** are part of the repo's test suite and run in CI:
+
+- `test/fixtures/clean/` — a full server written in the 2026-07-28 style
+  (per-request `_meta`, `sessionIdGenerator: undefined`, `-32602`).
+- `test/fixtures/negatives/` — "false friend" patterns: `sessionId` on plain
+  app-level objects, `-32002` inside strings/comments, capability-like words
+  with no capabilities context.
+- `test/fixtures/adversarial/caught/` — obfuscations the scanner **must**
+  catch: aliased imports (TS + Python), namespace-qualified SDK constants,
+  client transports resuming a `sessionId`.
+
+Additionally, in the corpus above, comment-only mentions (e.g. `Mcp-Session-Id`
+in a comment, `initialize` in prose) produced zero findings — the AST layer
+distinguishes executable tokens from comments by construction.
+
+## Recall — what the scanner is known to miss
+
+Static token analysis proves known patterns are **absent**; it cannot prove
+your server **speaks the new wire contract**. Recall is bounded by
+construction, and the misses are locked into the test suite
+(`test/fixtures/adversarial/missed/`, asserted to produce zero findings so any
+silent claim-inflation fails CI):
+
+- split/computed method strings — `'tasks' + '/list'`, `` `tasks/${op}` ``, f-strings
+- computed capability keys — `{ ['roo'+'ts']: {} }`
+- generated/loop-driven registration from string fragments
+- framework-adapter indirection (route tables built at runtime)
+- cross-module renames — a wrapper re-exporting an SDK constant under a new
+  name is flagged in the wrapper file, but a consumer importing only the new
+  name scans clean on its own
+
+There is no corpus-wide recall *percentage*: that would require a labeled set
+of every legacy usage in the wild, which nobody has. What we can say is: for
+the pattern shapes listed in the README, detection is exact; for the shapes
+above, it is zero, and the tool says so — pair the scan with runtime checks
+(`mcp-vet fixtures`) to cover the difference.
+
+## Reproducing
+
+```bash
+git clone --depth 1 https://github.com/modelcontextprotocol/servers
+git clone --depth 1 https://github.com/modelcontextprotocol/typescript-sdk
+git clone --depth 1 https://github.com/modelcontextprotocol/python-sdk
+# check out the pinned SHAs above, then:
+npx @booyaka/mcp-vet servers/src typescript-sdk/examples python-sdk/examples --json --no-files
+```

package/CHANGELOG.md

@@ -4,6 +4,106 @@ 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.4.0]
+
+The community-feedback release — everything in it traces to reader comments on
+the launch post (issues #1–#6). Static analysis got sharper, and the tool now
+ships the runtime half it was honest about not covering.
+
+### Added
+
+- **Client-side session-ownership detection** (#1) — a client transport
+  constructed with a real `sessionId`/`session_id` and reads of
+  `transport.sessionId` are flagged (`MCP_SESSION_ID`, medium). The migrated
+  `sessionId: undefined` / `session_id=None` forms are recognized as benign.
+  Servers going stateless is only half the migration; clients that still behave
+  as if they own a session break too.
+- **Aliased-import resolution** (#2) — `import { InitializeRequestSchema as Init }`
+  (TS) and `from mcp.types import RootsCapability as RC` (Python) now flag both
+  the import line and the aliased usage sites. Python import lines surface
+  imported names even when only the alias is used later.
+- **Adversarial regression suite** (#3) — `test/fixtures/adversarial/` locks in
+  what the scanner catches (`caught/`) *and* what it is known to miss
+  (`missed/`, asserted zero findings): computed strings, computed capability
+  keys, generated registration, framework adapters, cross-module renames.
+- **`mcp-vet fixtures [dir]`** (#4) — emits nine protocol-level conformance
+  fixtures + `CHECKLIST.md`: `server/discover`, per-request `_meta`,
+  `Mcp-Method`/`Mcp-Name` routing headers (incl. mismatch rejection), stateless
+  auth, task-handle lifecycle, duplicate deliveries, retry on another instance,
+  `tools/list` cache invalidation, and downgrade/refusal behavior. Also exported
+  programmatically (`CONFORMANCE_FIXTURES`, `emitConformanceFixtures`).
+- **BENCHMARK.md** (#5) — the precision claim is now evidence: pinned corpus
+  SHAs, 447 files / ~44k LOC, every finding labeled (105 findings, 104 TP,
+  1 FP), labeled negatives, and an explicit recall discussion.
+
+### Changed
+
+- **Docs: spec-date semantics** (#6) — July 28 is a specification release, not
+  a remote kill switch; breakage appears when a client/server pair negotiates
+  the new revision. README and the post-scan notice now say so, and recommend
+  the dual-version (2025-11-25 + 2026-07-28) rollout test matrix.
+- The README "0 false positives" claim is replaced by the measured, reproducible
+  numbers in BENCHMARK.md (1 FP in 44k LOC — an already-migrated negative
+  assertion in test code).
+
+## [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 +150,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,8 +14,23 @@
 npx @booyaka/mcp-vet .
 ```
 
+<p align="center">
+  <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.
 
+## What actually happens on July 28
+
+**July 28 is a specification release date, not a switch that remotely disables your deployment.** Nothing reaches into running servers and turns them off. Breakage appears when a **client and server pair negotiates or requires the new revision** — a client that sends `2026-07-28`-style requests (per-request `_meta`, no handshake, routing headers) against a server that still expects `2025-11-25` semantics, or vice versa.
+
+Two practical consequences:
+
+- **Your rollout is a window, not a day.** Until every client you care about has moved, keep **both** revisions in your production test matrix: a `2025-11-25` path and a `2026-07-28` path. `mcp-vet fixtures` emits wire-level test fixtures for exactly this (see [Runtime conformance fixtures](#runtime-conformance-fixtures)).
+- **Silent acceptance is the worst failure mode.** A server that quietly processes an old-revision request under new semantics (or the reverse) corrupts behavior instead of failing loudly. Verify *refusal* behavior, not just the happy path.
+
+The scan tells you *what to change in your source*; the date tells you *when clients start expecting it*.
+
 ---
 
 ## Real-world example
@@ -25,17 +40,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 on these files.** (Across the full labeled corpus it's 104/105 true positives — see [BENCHMARK.md](./BENCHMARK.md).)
 
 ---
 
@@ -45,10 +64,12 @@ And it stays quiet where it should — the `initialize` mentioned in a *comment*
 
 | ID | Pattern |
 | --- | --- |
-| `MCP_SESSION_ID` | `Mcp-Session-Id` header / `mcpSessionId` variable |
+| `MCP_SESSION_ID` | `Mcp-Session-Id` header / `mcpSessionId` variable / client-side session ownership (`sessionId` passed to or read from a client transport) |
 | `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)
 
@@ -63,7 +84,7 @@ And it stays quiet where it should — the `initialize` mentioned in a *comment*
 Every finding carries a **confidence** so you can tune signal-to-noise with `--min-confidence`:
 
 - **high** — exact/deterministic match (session id, `-32002`, tasks methods), a structurally-verified capability (the `roots`/`sampling`/`logging` key is really *inside* a `capabilities` object), or an `initialize` string used as a method name (handler registration, `switch` case, or `req.method === 'initialize'`).
-- **medium** — a `roots`/`sampling`/`logging` key/string within 5 lines of a `capabilities` mention but not structurally verified.
+- **medium** — a `roots`/`sampling`/`logging` key/string within 5 lines of a `capabilities` mention but not structurally verified; a real `sessionIdGenerator`; client-side session ownership (`sessionId`/`session_id` passed to or read from a transport/client).
 - **low** — a bare `'initialize'` string with no registration context.
 
 ---
@@ -86,6 +107,19 @@ function handle(req) {
 }
 ```
 
+This cuts both ways — **client-side session ownership breaks too**, even against a server that scans clean. A lot of tool-reliability bugs only show up when the server is stateless but the client still behaves as if it owns a session:
+
+```ts
+// ❌ before — the client resumes a stored session
+const transport = new StreamableHTTPClientTransport(url, { sessionId: stored });
+persist(transport.sessionId);
+
+// ✅ after — stateless: no stored session id, full _meta on every request
+const transport = new StreamableHTTPClientTransport(url, { sessionId: undefined });
+```
+
+`mcp-vet` flags a client transport constructed with a real `sessionId`/`session_id` and reads of `transport.sessionId` (medium confidence). The migrated `sessionId: undefined` / `session_id=None` forms are recognized and left alone.
+
 ### 2. `initialize` / `notifications/initialized` — the handshake is removed
 
 > *"The `initialize`/`initialized` handshake is removed. The protocol version, client info, and client capabilities that used to be exchanged once at connection time now travel in `_meta` on every request."*
@@ -113,6 +147,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,14 +166,61 @@ 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.
+
+## Runtime conformance fixtures
+
+Static analysis proves known legacy patterns are *absent* from your source. Only wire-level tests prove your running server actually *speaks* the 2026-07-28 contract. `mcp-vet` ships both halves:
+
+```bash
+npx @booyaka/mcp-vet fixtures ./mcp-fixtures
+```
+
+writes nine ready-to-fire JSON fixtures plus a `CHECKLIST.md`, covering the runtime behaviors a linter cannot see:
+
+1. `server/discover` replaces the initialize handshake
+2. per-request `_meta` (protocolVersion, clientInfo, capabilities) — including explicit refusal when `_meta` is missing
+3. `Mcp-Method` / `Mcp-Name` routing headers, including the header/body-mismatch rejection case
+4. stateless auth context (no session-bound token cache)
+5. task-handle lifecycle: creation, `tasks/get` polling, resume on another instance, `tasks/list` and `tasks/result` returning method-not-found
+6. duplicate request delivery (idempotency under retries)
+7. retry against a different server instance (no sticky in-memory state)
+8. `tools/list` cache invalidation
+9. downgrade/refusal: old-revision requests get an explicit error, never silent acceptance under the wrong semantics
+
+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).
+
 ## 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
+npx @booyaka/mcp-vet fixtures ./dir    # write runtime conformance fixtures + checklist (default: ./mcp-vet-fixtures)
 ```
 
 Globs `**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}` and `**/*.py`, skipping `node_modules`, `.git`, `__pycache__`, `dist`, and `build`.
@@ -153,6 +236,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 +323,98 @@ 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`.
+- **aliased imports** — `import { InitializeRequestSchema as Init }` (TS) and `from mcp.types import RootsCapability as RC` (Python) are resolved back to their canonical names, so both the import line and the aliased usage sites are flagged. Namespace access (`types.InitializeRequestSchema`) is matched too.
+- **client-side session ownership** — a client transport constructed with a real `sessionId`/`session_id`, or a read of `transport.sessionId`; the migrated `sessionId: undefined` / `session_id=None` forms are recognized as benign.
+
+**Measured, not vibes:** scanned against the official MCP reference servers and both SDK example suites at pinned commits — 447 files / ~44k LOC — every finding manually labeled: **105 findings, 104 true positives, 1 false positive**. Corpus, commit SHAs, per-pattern counts, labeled negatives, and the recall discussion are in [BENCHMARK.md](./BENCHMARK.md).
+
+### Known limitations
+
+These are locked into the test suite as `test/fixtures/adversarial/missed/` — fixtures asserted to produce **zero** findings, so the claims below can't silently rot in either direction:
+
+- **Split/computed method strings** — `"tasks" + "/list"`, `` `tasks/${op}` ``, or `f"tasks/{x}"` are not reconstructed.
+- **Computed capability keys** — `{ ['roo'+'ts']: {} }` never exists as a single token.
+- **Generated/loop-driven registration** — method tables assembled from string fragments at runtime.
+- **Framework-adapter indirection** — routes built dynamically (`app.post('/rpc/' + ns + '/' + action, ...)`).
+- **Cross-module renames** — a wrapper module re-exporting an SDK constant under a new name is flagged *in the wrapper file*, but a consumer importing only the new name scans clean on its own. Scan whole projects, not single files.
+- **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.
+- The **regex fallback** (no Python interpreter) covers only the deterministic rules at reduced precision; install Python for full `.py` fidelity.
+
+This is the recall boundary of static analysis: it proves known patterns are *absent*, not that the server *speaks the new wire contract*. Cover the difference with the [runtime conformance fixtures](#runtime-conformance-fixtures).
+
+## 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 +426,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 };
+}