feat(codemod): rewrite v1 validator paths to the v2 subpaths

v1 source code that imports built-in validators looks like:

  import { CfWorkerJsonSchemaValidator } from
    '@modelcontextprotocol/sdk/validation/cfworker-provider.js';

The v1-to-v2 codemod now rewrites this to the v2 subpath that ships
the named class, picking the right base package per file:

  import { CfWorkerJsonSchemaValidator } from
    '@modelcontextprotocol/{client,server}/validators/cf-worker';

Covers all six v1 paths users wrote in the wild:
  validation/ajv-provider.js, validation/ajv.js, validation/ajv
  validation/cfworker-provider.js, validation/cfworker.js, validation/cfworker
plus the (rarer) validation/index.js and validation/types.js barrels
which carry only the jsonSchemaValidator interface — those route to
the base client/server package, which already re-exports those types.

Resolution uses the same sibling-import + project-type heuristic as
the rest of the importPaths transform: if the file already imports
from sdk/client/* it routes to /client/validators/..., otherwise it
routes to /server/validators/..., otherwise it falls back to the
project type from package.json.

Adds a subpathSuffix field to ImportMapping so the existing
RESOLVE_BY_CONTEXT logic can append a subpath after picking the base.
Eight new tests cover all six v1 paths, both base packages, and the
usedPackages output. Verified against the agents repo (the real-world
v1 caller this PR is unblocking).

Author: mattzcarey

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

@@ -7,6 +7,11 @@ export interface ImportMapping {
     removalMessage?: string;
     /** No entries currently set this; scaffolding for when a v1 symbol has no v2 equivalent yet. */
     isV2Gap?: boolean;
+    /**
+     * Subpath suffix appended after `RESOLVE_BY_CONTEXT` resolves the base package (e.g. `/validators/ajv`).
+     * The final target becomes `@modelcontextprotocol/{client,server}<subpathSuffix>`.
+     */
+    subpathSuffix?: string;
 }
 
 export const IMPORT_MAP: Record<string, ImportMapping> = {
@@ -160,6 +165,53 @@ export const IMPORT_MAP: Record<string, ImportMapping> = {
     '@modelcontextprotocol/sdk/inMemory.js': {
         target: 'RESOLVE_BY_CONTEXT',
         status: 'moved'
+    },
+
+    // JSON Schema validator providers. In v1, these were importable from `@modelcontextprotocol/sdk/validation/*`.
+    // In v2, they live under explicit subpaths on `@modelcontextprotocol/{client,server}`. The base package
+    // is resolved per file by `RESOLVE_BY_CONTEXT`; the validator subpath is appended via `subpathSuffix`.
+    // Note the v1 source path naming used both `*-provider.js` (the canonical d.ts names) and short
+    // aliases like `validation/ajv` / `validation/cfworker` documented in the v1 README; both forms
+    // are listed here so the codemod handles whichever form a user wrote.
+    '@modelcontextprotocol/sdk/validation/ajv-provider.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved',
+        subpathSuffix: '/validators/ajv'
+    },
+    '@modelcontextprotocol/sdk/validation/ajv.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved',
+        subpathSuffix: '/validators/ajv'
+    },
+    '@modelcontextprotocol/sdk/validation/ajv': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved',
+        subpathSuffix: '/validators/ajv'
+    },
+    '@modelcontextprotocol/sdk/validation/cfworker-provider.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved',
+        subpathSuffix: '/validators/cf-worker'
+    },
+    '@modelcontextprotocol/sdk/validation/cfworker.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved',
+        subpathSuffix: '/validators/cf-worker'
+    },
+    '@modelcontextprotocol/sdk/validation/cfworker': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved',
+        subpathSuffix: '/validators/cf-worker'
+    },
+    // The barrel-only `validation/index` exports just the `jsonSchemaValidator` interface + helpers.
+    // Map it to the core types path so the type-only imports continue to resolve.
+    '@modelcontextprotocol/sdk/validation/index.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved'
+    },
+    '@modelcontextprotocol/sdk/validation/types.js': {
+        target: 'RESOLVE_BY_CONTEXT',
+        status: 'moved'
     }
 };
 

packages/codemod/src/migrations/v1-to-v2/transforms/importPaths.ts

@@ -102,6 +102,9 @@ export const importPathsTransform: Transform = {
                     line,
                     diagnostics
                 });
+                if (mapping.subpathSuffix) {
+                    targetPackage = `${targetPackage}${mapping.subpathSuffix}`;
+                }
             }
 
             const symbolsToRenameInFile: Array<[string, string]> = [];
@@ -250,6 +253,9 @@ function rewriteExportDeclarations(
                 return spec.includes('/server/') || spec === '@modelcontextprotocol/server';
             });
             targetPackage = resolveTypesPackage(context, hasClientImport, hasServerImport);
+            if (mapping.subpathSuffix) {
+                targetPackage = `${targetPackage}${mapping.subpathSuffix}`;
+            }
         }
 
         if (mapping.symbolTargetOverrides) {

packages/codemod/test/v1-to-v2/transforms/importPaths.test.ts

@@ -448,4 +448,85 @@ describe('import-paths transform', () => {
         expect(result).toContain(`from "@modelcontextprotocol/client"`);
         expect(result).toContain('InMemoryTransport');
     });
+
+    describe('validator subpath rewrites', () => {
+        it('rewrites CfWorkerJsonSchemaValidator from v1 cfworker-provider to client subpath', () => {
+            const input = [
+                `import { Client } from '@modelcontextprotocol/sdk/client/index.js';`,
+                `import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/cfworker-provider.js';`,
+                ''
+            ].join('\n');
+            const result = applyTransform(input, { projectType: 'client' });
+            expect(result).toContain(`from "@modelcontextprotocol/client/validators/cf-worker"`);
+            expect(result).toContain('CfWorkerJsonSchemaValidator');
+            expect(result).not.toContain('@modelcontextprotocol/sdk');
+        });
+
+        it('rewrites CfWorkerJsonSchemaValidator from v1 cfworker short alias to server subpath', () => {
+            const input = [
+                `import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';`,
+                `import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/cfworker';`,
+                ''
+            ].join('\n');
+            const result = applyTransform(input, { projectType: 'server' });
+            expect(result).toContain(`from "@modelcontextprotocol/server/validators/cf-worker"`);
+            expect(result).toContain('CfWorkerJsonSchemaValidator');
+        });
+
+        it('rewrites AjvJsonSchemaValidator from v1 ajv-provider to server subpath', () => {
+            const input = [
+                `import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';`,
+                `import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv-provider.js';`,
+                ''
+            ].join('\n');
+            const result = applyTransform(input, { projectType: 'server' });
+            expect(result).toContain(`from "@modelcontextprotocol/server/validators/ajv"`);
+            expect(result).toContain('AjvJsonSchemaValidator');
+        });
+
+        it('rewrites AjvJsonSchemaValidator from v1 ajv short alias to server subpath', () => {
+            const input = [
+                `import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';`,
+                `import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';`,
+                ''
+            ].join('\n');
+            const result = applyTransform(input, { projectType: 'server' });
+            expect(result).toContain(`from "@modelcontextprotocol/server/validators/ajv"`);
+            expect(result).toContain('AjvJsonSchemaValidator');
+        });
+
+        it('routes validator subpath to client when only client siblings exist', () => {
+            const input = [
+                `import { Client } from '@modelcontextprotocol/sdk/client/index.js';`,
+                `import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv-provider.js';`,
+                ''
+            ].join('\n');
+            const result = applyTransform(input, { projectType: 'both' });
+            expect(result).toContain(`from "@modelcontextprotocol/client/validators/ajv"`);
+        });
+
+        it('routes validator subpath via project type when no SDK siblings', () => {
+            const input = `import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/cfworker-provider.js';\n`;
+            const result = applyTransform(input, { projectType: 'server' });
+            expect(result).toContain(`from "@modelcontextprotocol/server/validators/cf-worker"`);
+        });
+
+        it('includes the validator subpath in usedPackages', () => {
+            const project = new Project({ useInMemoryFileSystem: true });
+            const sourceFile = project.createSourceFile(
+                'test.ts',
+                `import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/cfworker-provider.js';\n`
+            );
+            const result = importPathsTransform.apply(sourceFile, { projectType: 'client' });
+            expect(result.usedPackages).toBeDefined();
+            expect(result.usedPackages!.has('@modelcontextprotocol/client/validators/cf-worker')).toBe(true);
+        });
+
+        it('rewrites the validation/index type-only import to the resolved base package', () => {
+            const input = `import type { jsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/index.js';\n`;
+            const result = applyTransform(input, { projectType: 'server' });
+            expect(result).toContain(`from "@modelcontextprotocol/server"`);
+            expect(result).toContain('jsonSchemaValidator');
+        });
+    });
 });