Stateless Migrator

Part of the StudioMeyer MCP Stack — Built in Mallorca 🌴 · ⭐ if you use it

mcp-stateless-migrator

CLI tool that scans MCP-server codebases for incompatibilities with MCP-Spec 2026-07-28 RC (Stateless Core, mandatory headers, deprecated features, error-code shift, OAuth hardening, endpoint-shape changes) and applies safe AST-rewrites where mechanically possible.

Target users: maintainers of TypeScript/JavaScript MCP servers (the largest SDK userbase, @modelcontextprotocol/sdk).

Status: v0.1.2 — pre-final-RC. Detection rules are tagged with specRevision: 2026-07-28-rc-2026-05-21 and cite the canonical SEP files. v0.2.0 will re-validate against the Tier-1 SDK final release.

Install

npm install -g mcp-stateless-migrator
# or one-shot:
npx mcp-stateless-migrator scan ./src

Requires Node >= 20.

CLI

#	Command	Args	Output	Read-only	Destructive
1	scan	<path> [--format json|text|md|html]	violations + severity	yes	no
2	diff	<path> [--output <file>]	unified diff of planned patches	yes	no
3	patch	<path> [--dry-run] [--no-backup] [--only <id...>]	rewrites files + writes backup folder	no	yes
4	verify	<path> [--spec <rev>]	exit 0 = clean	yes	no
5	report	<path> [--format json|md|html]	coverage report	yes	no
6	rules	[--verbose]	list all detection rules	yes	no

Detection rules

Rule	Severity	Auto-patch	Source
r01-stateless-core	warn	no	SEP-2567
r02-mandatory-headers	info	no	SEP-2243
r03-tasks-extension	warn	no	SEP-2663
r04-apps-extension	info	no	SEP-1865
r05-deprecations	warn	no	SEP-2577
r06-error-code-shift	error	yes	SEP-2164
r07-oauth-hardening	warn	no	SEP-2468
r08-endpoint-shape	warn	no	SEP-2596

Only r06 rewrites code automatically — it swaps -32002 -> -32602 inside any property named code (identifier key, "code"/'code' string key, or class field), and leaves computed keys and same-value-but-different-name properties untouched. SEP-2164 is Draft status as of the RC, so re-validate before the final spec; every patch is backed up by default. Every other rule requires a human reviewing the planned change — server architecture varies too much for blind auto-patching.

Usage

# 1. See what the migrator finds
mcp-stateless-migrator scan ./src --format text

# 2. Preview the auto-patch as a unified diff
mcp-stateless-migrator diff ./src

# 3. Apply only the safe error-code shift, with backup
mcp-stateless-migrator patch ./src --only r06-error-code-shift

# 4. Confirm the codebase is clean
mcp-stateless-migrator verify ./src

# 5. Generate a Markdown report for the team
mcp-stateless-migrator report ./src --format md > migration-report.md

Exit codes:

• 0 — clean (no violations OR patch applied successfully)
• 1 — violations remaining / diff non-empty
• 2 — invalid CLI arguments

Backup folder

patch creates <path>/.bak.<ISO-timestamp>/ containing the original file tree for every file it touched. Pass --no-backup to disable (not recommended). Restore via cp -r .bak.<timestamp>/. ..

Programmatic API

import { scanPath, patchPath, formatScan } from "mcp-stateless-migrator";

const report = await scanPath("./src");
console.log(formatScan(report, "json"));

await patchPath("./src", { dryRun: false, backup: true, only: ["r06-error-code-shift"] });

Custom patterns accept at most 128 strings. Each string is limited to 1024 UTF-16 code units and 16 unescaped opening grouping characters ((, {, [). Inputs above these budgets raise a controlled error before matching. Use patterns relative to the scan root. Ignore rules apply within that root; an ignored name in an ancestor path does not exclude an explicitly selected root.

Ecosystem

This tool complements:

• mcp-spec-migrator — TypeScript CLI for the previous spec step (2025-06-18 -> 2025-11-25).
• mcp-protocol-conformance — Rust runtime conformance validator.

See ECOSYSTEM.md for the full positioning matrix.

License

MIT — Copyright © 2026 Matthias Meyer (StudioMeyer).