feat: add v2 codemod draft

.github/workflows/publish.yml

@@ -40,4 +40,4 @@ jobs:
             - name: Publish preview packages
               run:
                   pnpm dlx pkg-pr-new publish --packageManager=npm --pnpm './packages/server' './packages/client'
-                  './packages/middleware/express' './packages/middleware/fastify' './packages/middleware/hono' './packages/middleware/node'
+                  './packages/codemod' './packages/middleware/express' './packages/middleware/fastify' './packages/middleware/hono' './packages/middleware/node'

packages/codemod/eslint.config.mjs

@@ -0,0 +1,5 @@
+// @ts-check
+
+import baseConfig from '@modelcontextprotocol/eslint-config';
+
+export default [...baseConfig];

packages/codemod/package.json

@@ -0,0 +1,66 @@
+{
+    "name": "@modelcontextprotocol/codemod",
+    "version": "2.0.0-alpha.0",
+    "description": "Codemod to migrate MCP TypeScript SDK code from v1 to v2",
+    "license": "MIT",
+    "author": "Anthropic, PBC (https://anthropic.com)",
+    "homepage": "https://modelcontextprotocol.io",
+    "bugs": "https://github.com/modelcontextprotocol/typescript-sdk/issues",
+    "type": "module",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/modelcontextprotocol/typescript-sdk.git"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "keywords": [
+        "modelcontextprotocol",
+        "mcp",
+        "codemod",
+        "migration"
+    ],
+    "bin": {
+        "mcp-codemod": "./dist/cli.mjs"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.mts",
+            "import": "./dist/index.mjs"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "typecheck": "tsgo -p tsconfig.json --noEmit",
+        "build": "tsdown",
+        "build:watch": "tsdown --watch",
+        "prepack": "pnpm run build",
+        "lint": "eslint src/ && prettier --ignore-path ../../.prettierignore --check .",
+        "lint:fix": "eslint src/ --fix && prettier --ignore-path ../../.prettierignore --write .",
+        "check": "pnpm run typecheck && pnpm run lint",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "dependencies": {
+        "commander": "^13.0.0",
+        "ts-morph": "^28.0.0"
+    },
+    "devDependencies": {
+        "@modelcontextprotocol/tsconfig": "workspace:^",
+        "@modelcontextprotocol/vitest-config": "workspace:^",
+        "@modelcontextprotocol/eslint-config": "workspace:^",
+        "@eslint/js": "catalog:devTools",
+        "@typescript/native-preview": "catalog:devTools",
+        "eslint": "catalog:devTools",
+        "eslint-config-prettier": "catalog:devTools",
+        "eslint-plugin-n": "catalog:devTools",
+        "prettier": "catalog:devTools",
+        "tsdown": "catalog:devTools",
+        "tsx": "catalog:devTools",
+        "typescript": "catalog:devTools",
+        "typescript-eslint": "catalog:devTools",
+        "vitest": "catalog:devTools"
+    }
+}

packages/codemod/src/cli.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+import { existsSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { Command } from 'commander';
+
+import { listMigrations } from './migrations/index.js';
+import { run } from './runner.js';
+import { DiagnosticLevel } from './types.js';
+import { formatDiagnostic } from './utils/diagnostics.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json') as { version: string };
+
+const program = new Command();
+
+program.name('mcp-codemod').description('Codemod to migrate MCP TypeScript SDK code between versions').version(version);
+
+for (const [name, migration] of listMigrations()) {
+    program
+        .command(`${name} [target-dir]`)
+        .description(migration.description)
+        .option('-d, --dry-run', 'Preview changes without writing files')
+        .option('-t, --transforms <ids>', 'Comma-separated transform IDs to run (default: all)')
+        .option('-v, --verbose', 'Show detailed per-change output')
+        .option('--ignore <patterns...>', 'Additional glob patterns to ignore')
+        .option('--list', 'List available transforms for this migration')
+        .action((targetDir: string | undefined, opts: Record<string, unknown>) => {
+            try {
+                if (opts['list']) {
+                    console.log(`\nAvailable transforms for ${name}:\n`);
+                    for (const t of migration.transforms) {
+                        console.log(`  ${t.id.padEnd(20)} ${t.name}`);
+                    }
+                    console.log('');
+                    return;
+                }
+
+                if (!targetDir) {
+                    console.error(`\nError: missing required argument <target-dir>.\n`);
+                    process.exitCode = 1;
+                    return;
+                }
+
+                const resolvedDir = path.resolve(targetDir);
+
+                if (!existsSync(resolvedDir) || !statSync(resolvedDir).isDirectory()) {
+                    console.error(`\nError: "${resolvedDir}" is not a valid directory.\n`);
+                    process.exitCode = 1;
+                    return;
+                }
+
+                console.log(`\n@modelcontextprotocol/codemod — ${migration.name}\n`);
+                console.log(`Scanning ${resolvedDir}...`);
+                if (opts['dryRun']) {
+                    console.log('(dry run — no files will be modified)\n');
+                } else {
+                    console.log('');
+                }
+
+                const transforms = opts['transforms'] ? (opts['transforms'] as string).split(',').map(s => s.trim()) : undefined;
+
+                const result = run(migration, {
+                    targetDir: resolvedDir,
+                    dryRun: opts['dryRun'] as boolean | undefined,
+                    verbose: opts['verbose'] as boolean | undefined,
+                    transforms,
+                    ignore: opts['ignore'] as string[] | undefined
+                });
+
+                if (result.filesChanged === 0 && result.diagnostics.length === 0) {
+                    console.log('No changes needed — code already migrated or no SDK imports found.\n');
+                    return;
+                }
+
+                if (result.filesChanged > 0) {
+                    console.log(`Changes: ${result.totalChanges} across ${result.filesChanged} file(s)\n`);
+                }
+
+                if (opts['verbose']) {
+                    console.log('Files modified:');
+                    for (const fr of result.fileResults) {
+                        console.log(`  ${fr.filePath} (${fr.changes} change(s))`);
+                    }
+                    console.log('');
+                }
+
+                const errors = result.diagnostics.filter(d => d.level === DiagnosticLevel.Error);
+                if (errors.length > 0) {
+                    console.log(`Errors (${errors.length}):`);
+                    for (const d of errors) {
+                        console.log(formatDiagnostic(d));
+                    }
+                    console.log('');
+                    process.exitCode = 1;
+                }
+
+                const warnings = result.diagnostics.filter(d => d.level === DiagnosticLevel.Warning);
+                if (warnings.length > 0) {
+                    console.log(`Warnings (${warnings.length}):`);
+                    for (const d of warnings) {
+                        console.log(formatDiagnostic(d));
+                    }
+                    console.log('');
+                }
+
+                const infos = result.diagnostics.filter(d => d.level === DiagnosticLevel.Info);
+                if (infos.length > 0) {
+                    console.log(`Info (${infos.length}):`);
+                    for (const d of infos) {
+                        console.log(formatDiagnostic(d));
+                    }
+                    console.log('');
+                }
+
+                if (opts['dryRun']) {
+                    console.log('Run without --dry-run to apply changes.\n');
+                } else {
+                    console.log('Migration complete. Review the changes and run your build/tests.\n');
+                }
+            } catch (error) {
+                console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+                process.exitCode = 1;
+            }
+        });
+}
+
+program.parse();

packages/codemod/src/index.ts

@@ -0,0 +1,13 @@
+export { getMigration, listMigrations } from './migrations/index.js';
+export { run } from './runner.js';
+export type {
+    Diagnostic,
+    FileResult,
+    Migration,
+    RunnerOptions,
+    RunnerResult,
+    Transform,
+    TransformContext,
+    TransformResult
+} from './types.js';
+export { DiagnosticLevel } from './types.js';

packages/codemod/src/migrations/index.ts

@@ -0,0 +1,12 @@
+import type { Migration } from '../types.js';
+import { v1ToV2Migration } from './v1-to-v2/index.js';
+
+const migrations = new Map<string, Migration>([['v1-to-v2', v1ToV2Migration]]);
+
+export function getMigration(name: string): Migration | undefined {
+    return migrations.get(name);
+}
+
+export function listMigrations(): Map<string, Migration> {
+    return migrations;
+}

packages/codemod/src/migrations/v1-to-v2/index.ts

@@ -0,0 +1,8 @@
+import type { Migration } from '../../types.js';
+import { v1ToV2Transforms } from './transforms/index.js';
+
+export const v1ToV2Migration: Migration = {
+    name: 'v1-to-v2',
+    description: 'Migrate from @modelcontextprotocol/sdk (v1) to v2 packages (@modelcontextprotocol/client, /server, etc.)',
+    transforms: v1ToV2Transforms
+};

packages/codemod/src/migrations/v1-to-v2/mappings/contextPropertyMap.ts

@@ -0,0 +1,23 @@
+export interface ContextMapping {
+    from: string;
+    to: string;
+}
+
+export const CONTEXT_PROPERTY_MAP: ContextMapping[] = [
+    { from: '.signal', to: '.mcpReq.signal' },
+    { from: '.requestId', to: '.mcpReq.id' },
+    { from: '._meta', to: '.mcpReq._meta' },
+    { from: '.sendRequest', to: '.mcpReq.send' },
+    { from: '.sendNotification', to: '.mcpReq.notify' },
+    { from: '.authInfo', to: '.http?.authInfo' },
+    { from: '.sessionId', to: '.sessionId' },
+    { from: '.requestInfo', to: '.http?.req' },
+    { from: '.closeSSEStream', to: '.http?.closeSSE' },
+    { from: '.closeStandaloneSSEStream', to: '.http?.closeStandaloneSSE' },
+    { from: '.taskStore', to: '.task?.store' },
+    { from: '.taskId', to: '.task?.id' },
+    { from: '.taskRequestedTtl', to: '.task?.requestedTtl' }
+];
+
+export const EXTRA_PARAM_NAME = 'extra';
+export const CTX_PARAM_NAME = 'ctx';

packages/codemod/src/migrations/v1-to-v2/mappings/importMap.ts

@@ -0,0 +1,128 @@
+export interface ImportMapping {
+    target: string;
+    status: 'moved' | 'removed' | 'renamed';
+    renamedSymbols?: Record<string, string>;
+    removalMessage?: string;
+}
+
+export const IMPORT_MAP: Record<string, ImportMapping> = {
+    '@modelcontextprotocol/sdk/client/index.js': {
+        target: '@modelcontextprotocol/client',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/client/auth.js': {
+        target: '@modelcontextprotocol/client',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/client/streamableHttp.js': {
+        target: '@modelcontextprotocol/client',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/client/sse.js': {
+        target: '@modelcontextprotocol/client',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/client/stdio.js': {
+        target: '@modelcontextprotocol/client',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/client/websocket.js': {
+        target: '',
+        status: 'removed',
+        removalMessage: 'WebSocketClientTransport removed in v2. Use StreamableHTTPClientTransport or StdioClientTransport.'
+    },
+
+    '@modelcontextprotocol/sdk/server/mcp.js': {
+        target: '@modelcontextprotocol/server',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/server/index.js': {
+        target: '@modelcontextprotocol/server',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/server/stdio.js': {
+        target: '@modelcontextprotocol/server',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/server/streamableHttp.js': {
+        target: '@modelcontextprotocol/node',
+        status: 'renamed',
+        renamedSymbols: {
+            StreamableHTTPServerTransport: 'NodeStreamableHTTPServerTransport'
+        }
+    },
+    '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js': {
+        target: '@modelcontextprotocol/server',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/server/sse.js': {
+        target: '',
+        status: 'removed',
+        removalMessage: 'SSE server transport removed in v2. Migrate to NodeStreamableHTTPServerTransport from @modelcontextprotocol/node.'
+    },
+    '@modelcontextprotocol/sdk/server/middleware.js': {
+        target: '@modelcontextprotocol/express',
+        status: 'moved'
+    },
+
+    '@modelcontextprotocol/sdk/server/auth/types.js': {
+        target: '',
+        status: 'removed',
+        removalMessage:
+            'Server auth removed in v2. AuthInfo is now re-exported by @modelcontextprotocol/client and @modelcontextprotocol/server.'
+    },
+    '@modelcontextprotocol/sdk/server/auth/provider.js': {
+        target: '',
+        status: 'removed',
+        removalMessage: 'Server auth removed in v2. Use an external auth library (e.g., better-auth).'
+    },
+    '@modelcontextprotocol/sdk/server/auth/router.js': {
+        target: '',
+        status: 'removed',
+        removalMessage: 'Server auth removed in v2. Use an external auth library (e.g., better-auth).'
+    },
+    '@modelcontextprotocol/sdk/server/auth/middleware.js': {
+        target: '',
+        status: 'removed',
+        removalMessage: 'Server auth removed in v2. Use an external auth library (e.g., better-auth).'
+    },
+    '@modelcontextprotocol/sdk/server/auth/errors.js': {
+        target: '',
+        status: 'removed',
+        removalMessage: 'Server auth removed in v2. Use an external auth library (e.g., better-auth).'
+    },
+
+    '@modelcontextprotocol/sdk/types.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/shared/protocol.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/shared/transport.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/shared/uriTemplate.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/shared/auth.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/shared/stdio.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved'
+    },
+
+    '@modelcontextprotocol/sdk/inMemory.js': {
+        target: '@modelcontextprotocol/core',
+        status: 'moved'
+    }
+};
+
+export function isAuthImport(specifier: string): boolean {
+    return specifier.includes('/server/auth/') || specifier.includes('/server/auth.');
+}