Make zod types strip (default) instead of passthrough

.github/workflows/main.yml

@@ -22,6 +22,7 @@ jobs:
           cache: npm
 
       - run: npm ci
+      - run: npm run check:strict-types
       - run: npm run build
       - run: npm test
       - run: npm run lint

CONTRIBUTING.md

@@ -14,9 +14,10 @@ We welcome contributions to the Model Context Protocol TypeScript SDK! This docu
 
 1. Create a new branch for your changes
 2. Make your changes
-3. Run `npm run lint` to ensure code style compliance
-4. Run `npm test` to verify all tests pass
-5. Submit a pull request
+3. If you modify `src/types.ts`, run `npm run generate:strict-types` to update strict types
+4. Run `npm run lint` to ensure code style compliance
+5. Run `npm test` to verify all tests pass
+6. Submit a pull request
 
 ## Pull Request Guidelines
 

README.md

@@ -950,6 +950,69 @@ server.registerTool("tool3", ...).disable();
 // Only one 'notifications/tools/list_changed' is sent.
 ```
 
+### Type Safety
+
+The SDK provides type-safe definitions that validate schemas while maintaining protocol compatibility.
+
+```typescript
+// Recommended: Use safe types that strip unknown fields
+import { ToolSchema } from "@modelcontextprotocol/sdk/strictTypes.js";
+
+// ⚠️ Deprecated: Extensible types will be removed in a future version
+import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
+```
+
+**Safe types with .strip():**
+```typescript
+import { ToolSchema } from "@modelcontextprotocol/sdk/strictTypes.js";
+
+// Unknown fields are automatically removed, not rejected
+const tool = ToolSchema.parse({
+  name: "get-weather",
+  description: "Get weather",
+  inputSchema: { type: "object", properties: {} },
+  customField: "this will be stripped" // ✓ No error, field is removed
+});
+
+console.log(tool.customField); // undefined - field was stripped
+console.log(tool.name); // "get-weather" - known fields are preserved
+```
+
+**Benefits:**
+- **Type safety**: Only known fields are included in results
+- **Protocol compatibility**: Works seamlessly with extended servers/clients
+- **No runtime errors**: Unknown fields are silently removed
+- **Forward compatibility**: Your code won't break when servers add new fields
+
+**Migration Guide:**
+
+If you're currently using types.js and need extensibility:
+1. Switch to importing from `strictTypes.js`
+2. Add any additional fields you need explicitly to your schemas
+3. For true extensibility needs, create wrapper schemas that extend the base types
+
+Example migration:
+```typescript
+// Before (deprecated)
+import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
+const tool = { ...baseFields, customField: "value" };
+
+// After (recommended)
+import { ToolSchema } from "@modelcontextprotocol/sdk/strictTypes.js";
+import { z } from "zod";
+
+// Create your own extended schema
+const ExtendedToolSchema = ToolSchema.extend({
+  customField: z.string()
+});
+const tool = ExtendedToolSchema.parse({ ...baseFields, customField: "value" });
+```
+
+Note: The following fields remain extensible for protocol compatibility:
+- `experimental`: For protocol extensions
+- `_meta`: For arbitrary metadata  
+- `properties`: For JSON Schema objects
+
 ### Low-Level Server
 
 For more control, you can use the low-level Server class directly:

package.json

@@ -36,6 +36,9 @@
   ],
   "scripts": {
     "fetch:spec-types": "curl -o spec.types.ts https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/refs/heads/main/schema/draft/schema.ts",
+    "generate:strict-types": "tsx scripts/generateStrictTypes.ts",
+    "check:strict-types": "npm run generate:strict-types && git diff --exit-code src/strictTypes.ts || (echo 'Error: strictTypes.ts is out of date. Run npm run generate:strict-types' && exit 1)",
+    "test:strict-types": "node scripts/test-strict-types.js",
     "build": "npm run build:esm && npm run build:cjs",
     "build:esm": "mkdir -p dist/esm && echo '{\"type\": \"module\"}' > dist/esm/package.json && tsc -p tsconfig.prod.json",
     "build:esm:w": "npm run build:esm -- -w",
@@ -44,7 +47,7 @@
     "examples:simple-server:w": "tsx --watch src/examples/server/simpleStreamableHttp.ts --oauth",
     "prepack": "npm run build:esm && npm run build:cjs",
     "lint": "eslint src/",
-    "test": "npm run fetch:spec-types && jest",
+    "test": "npm run fetch:spec-types && jest && npm run test:strict-types",
     "start": "npm run server",
     "server": "tsx watch --clear-screen=false src/cli.ts server",
     "client": "tsx src/cli.ts client"

scripts/generateStrictTypes.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Read the original types.ts file
+const typesPath = join(__dirname, '../src/types.ts');
+const strictTypesPath = join(__dirname, '../src/strictTypes.ts');
+
+let content = readFileSync(typesPath, 'utf-8');
+
+// Remove the @deprecated comment block
+const deprecatedCommentPattern = /\/\*\*\s*\n\s*\*\s*@deprecated[\s\S]*?\*\/\s*\n/;
+content = content.replace(deprecatedCommentPattern, '');
+
+// Add header comment
+const header = `/**
+ * Types remove unknown
+ * properties to maintaining compatibility with protocol extensions.
+ * 
+ * - Protocol compatoble: Unknown fields from extended implementations are removed, not rejected
+ * - Forward compatibility: Works with servers/clients that have additional fields
+ * 
+ * @generated by scripts/generateStrictTypes.ts
+ */
+
+`;
+
+// Replace all .passthrough() with a temporary marker
+content = content.replace(/\.passthrough\(\)/g, '.__TEMP_MARKED_FOR_REMOVAL__()');
+
+// Special handling for experimental and capabilities that should remain open
+// These are explicitly designed to be extensible
+const patternsToKeepOpen = [
+  // Keep experimental fields open as they're meant for extensions
+  /experimental: z\.optional\(z\.object\(\{\}\)\.__TEMP_MARKED_FOR_REMOVAL__\(\)\)/g,
+  // Keep _meta fields open as they're meant for arbitrary metadata
+  /_meta: z\.optional\(z\.object\(\{\}\)\.__TEMP_MARKED_FOR_REMOVAL__\(\)\)/g,
+  // Keep JSON Schema properties open as they can have arbitrary fields
+  /properties: z\.optional\(z\.object\(\{\}\)\.__TEMP_MARKED_FOR_REMOVAL__\(\)\)/g,
+  // Keep BaseRequestParamsSchema passthrough for JSON-RPC param compatibility
+  /const BaseRequestParamsSchema = z\s*\n\s*\.object\([\s\S]*?\)\s*\n\s*\.__TEMP_MARKED_FOR_REMOVAL__\(\)/g,
+  // Keep BaseNotificationParamsSchema passthrough for JSON-RPC param compatibility  
+  /const BaseNotificationParamsSchema = z\s*\n\s*\.object\([\s\S]*?\)\s*\n\s*\.__TEMP_MARKED_FOR_REMOVAL__\(\)/g,
+  // Keep RequestMetaSchema passthrough for extensibility
+  /const RequestMetaSchema = z\s*\n\s*\.object\([\s\S]*?\)\s*\n\s*\.__TEMP_MARKED_FOR_REMOVAL__\(\)/g,
+  // Keep structuredContent passthrough for tool-specific output
+  /structuredContent: z\.object\(\{\}\)\.__TEMP_MARKED_FOR_REMOVAL__\(\)\.optional\(\)/g,
+  // Keep metadata passthrough for provider-specific data in sampling
+  /metadata: z\.optional\(z\.object\(\{\}\)\.__TEMP_MARKED_FOR_REMOVAL__\(\)\)/g,
+];
+
+// Revert marker back to passthrough for these special cases
+patternsToKeepOpen.forEach(pattern => {
+  content = content.replace(pattern, (match) =>
+    match.replace('.__TEMP_MARKED_FOR_REMOVAL__()', '.passthrough()')
+  );
+});
+
+// Remove the temporary marker from all remaining locations (these become no modifier)
+content = content.replace(/\.__TEMP_MARKED_FOR_REMOVAL__\(\)/g, '');
+
+// Add a comment explaining the difference
+const explanation = `
+/**
+ * Note: The following remain open (using .passthrough()):
+ * - experimental: Designed for protocol extensions
+ * - _meta: Designed for arbitrary metadata
+ * - properties: JSON Schema properties that can have arbitrary fields
+ * - BaseRequestParamsSchema: Required for JSON-RPC param compatibility
+ * - BaseNotificationParamsSchema: Required for JSON-RPC param compatibility
+ * - RequestMetaSchema: Required for protocol extensibility
+ * - structuredContent: Tool-specific output that can have arbitrary fields
+ * - metadata: Provider-specific metadata in sampling requests
+ * 
+ * All other objects use default behavior (no modifier) to remove unknown properties while
+ * maintaining compatibility with extended protocols.
+ */
+`;
+
+// Insert the explanation after the imports
+const importEndIndex = content.lastIndexOf('import');
+const importEndLineIndex = content.indexOf('\n', importEndIndex);
+content = content.slice(0, importEndLineIndex + 1) + explanation + content.slice(importEndLineIndex + 1);
+
+// Write the strict types file
+writeFileSync(strictTypesPath, header + content);
+
+console.log('Generated strictTypes.ts successfully!');

scripts/test-strict-types.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, '..');
+
+const files = [
+  'src/client/index.ts',
+  'src/server/index.ts',
+  'src/server/mcp.ts'
+];
+
+console.log('Testing strict types compatibility...');
+console.log('======================================\n');
+
+// Backup original files
+const backups = {};
+files.forEach(file => {
+  const fullPath = join(rootDir, file);
+  if (existsSync(fullPath)) {
+    backups[file] = readFileSync(fullPath, 'utf8');
+
+    // Replace imports
+    const content = backups[file];
+    const newContent = content.replace(/from "\.\.\/types\.js"/g, 'from "../strictTypes.js"');
+    writeFileSync(fullPath, newContent);
+    console.log(`✓ Replaced imports in ${file}`);
+  }
+});
+
+console.log('\nRunning TypeScript compilation...\n');
+
+try {
+  // Run TypeScript compilation
+  execSync('npm run build', { cwd: rootDir, stdio: 'pipe' });
+  console.log('✓ No type errors found!');
+} catch (error) {
+  // Extract and format type errors
+  const output = error.stdout?.toString() || error.stderr?.toString() || '';
+  const lines = output.split('\n');
+
+  const errors = [];
+  let currentError = null;
+
+  lines.forEach((line, i) => {
+    if (line.includes('error TS')) {
+      if (currentError) {
+        errors.push(currentError);
+      }
+      currentError = {
+        file: line.split('(')[0],
+        location: line.match(/\((\d+),(\d+)\)/)?.[0] || '',
+        code: line.match(/error (TS\d+)/)?.[1] || '',
+        message: line.split(/error TS\d+:/)[1]?.trim() || '',
+        context: []
+      };
+    } else if (currentError && line.trim() && !line.startsWith('npm ')) {
+      currentError.context.push(line);
+    }
+  });
+
+  if (currentError) {
+    errors.push(currentError);
+  }
+
+  // Display errors
+  console.log(`Found ${errors.length} type error(s):\n`);
+
+  errors.forEach((error, index) => {
+    console.log(`${index + 1}. ${error.file}${error.location}`);
+    console.log(`   Error ${error.code}: ${error.message}`);
+    if (error.context.length > 0) {
+      console.log(`   Context:`);
+      error.context.slice(0, 3).forEach(line => {
+        console.log(`     ${line.trim()}`);
+      });
+    }
+    console.log('');
+  });
+}
+
+// Restore original files
+console.log('Restoring original files...');
+Object.entries(backups).forEach(([file, content]) => {
+  const fullPath = join(rootDir, file);
+  writeFileSync(fullPath, content);
+});
+
+console.log('✓ Original files restored.');

scripts/test-strict-types.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# Script to test strict types by replacing imports and running tests
+
+echo "Testing strict types compatibility..."
+echo "======================================"
+
+# Save original files
+cp src/client/index.ts src/client/index.ts.bak
+cp src/server/index.ts src/server/index.ts.bak  
+cp src/server/mcp.ts src/server/mcp.ts.bak
+
+# Replace imports
+sed -i '' 's/from "\.\.\/types\.js"/from "..\/strictTypes.js"/g' src/client/index.ts
+sed -i '' 's/from "\.\.\/types\.js"/from "..\/strictTypes.js"/g' src/server/index.ts
+sed -i '' 's/from "\.\.\/types\.js"/from "..\/strictTypes.js"/g' src/server/mcp.ts
+
+echo "Replaced imports in:"
+echo "  - src/client/index.ts"
+echo "  - src/server/index.ts"
+echo "  - src/server/mcp.ts"
+echo ""
+
+# Run TypeScript compilation to get type errors
+echo "Running TypeScript compilation..."
+echo ""
+npm run build 2>&1 | grep -E "(error TS|src/)" | grep -B1 "error TS" || true
+
+# Restore original files
+mv src/client/index.ts.bak src/client/index.ts
+mv src/server/index.ts.bak src/server/index.ts
+mv src/server/mcp.ts.bak src/server/mcp.ts
+
+echo ""
+echo "Original files restored."