add strip types

Author: ihrpr

.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,8 @@
   ],
   "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)",
     "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",

scripts/generateStrictTypes.ts

@@ -0,0 +1,69 @@
+#!/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');
+
+// 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 .strip()
+content = content.replace(/\.passthrough\(\)/g, '.strip()');
+
+// 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\(\{\}\)\.strip\(\)\)/g,
+  // Keep _meta fields open as they're meant for arbitrary metadata
+  /_meta: z\.optional\(z\.object\(\{\}\)\.strip\(\)\)/g,
+  // Keep JSON Schema properties open as they can have arbitrary fields
+  /properties: z\.optional\(z\.object\(\{\}\)\.strip\(\)\)/g,
+];
+
+// Revert strip back to passthrough for these special cases
+patternsToKeepOpen.forEach(pattern => {
+  content = content.replace(pattern, (match) =>
+    match.replace('.strip()', '.passthrough()')
+  );
+});
+
+// Add a comment explaining the difference
+const explanation = `
+/**
+ * Note: The following fields remain open (using .passthrough()):
+ * - experimental: Designed for protocol extensions
+ * - _meta: Designed for arbitrary metadata
+ * - properties: JSON Schema properties that can have arbitrary fields
+ * 
+ * All other objects use .strip() 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!');

src/examples/strictTypesExample.ts

@@ -0,0 +1,57 @@
+/**
+ * Example showing the difference between regular types and strict types
+ */
+
+import { ToolSchema as OpenToolSchema } from "../types.js";
+import { ToolSchema as StrictToolSchema } from "../strictTypes.js";
+
+// With regular (open) types - this is valid
+const openTool = OpenToolSchema.parse({
+  name: "get-weather",
+  description: "Get weather for a location",
+  inputSchema: {
+    type: "object",
+    properties: {
+      location: { type: "string" }
+    }
+  },
+  // Extra properties are allowed
+  customField: "This is allowed in open types",
+  anotherExtra: 123
+});
+
+console.log("Open tool accepts extra properties:", openTool);
+
+// With strict types - this would throw an error
+try {
+  StrictToolSchema.parse({
+    name: "get-weather",
+    description: "Get weather for a location",
+    inputSchema: {
+      type: "object",
+      properties: {
+        location: { type: "string" }
+      }
+    },
+    // Extra properties cause validation to fail
+    customField: "This is NOT allowed in strict types",
+    anotherExtra: 123
+  });
+} catch (error) {
+  console.log("Strict tool rejects extra properties:", error instanceof Error ? error.message : String(error));
+}
+
+// Correct usage with strict types
+const strictToolCorrect = StrictToolSchema.parse({
+  name: "get-weather",
+  description: "Get weather for a location",
+  inputSchema: {
+    type: "object",
+    properties: {
+      location: { type: "string" }
+    }
+  }
+  // No extra properties
+});
+
+console.log("Strict tool with no extra properties:", strictToolCorrect);