Merge branch 'main' into generate-api-docs

Author: felixweinberger

src/server/zod-compat.ts

@@ -35,7 +35,6 @@ export interface ZodV4Internal {
             value?: unknown;
             values?: unknown[];
             shape?: Record<string, AnySchema> | (() => Record<string, AnySchema>);
-            description?: string;
         };
     };
     value?: unknown;
@@ -220,15 +219,12 @@ export function getParseErrorMessage(error: unknown): string {
 /**
  * Gets the description from a schema, if available.
  * Works with both Zod v3 and v4.
+ *
+ * Both versions expose a `.description` getter that returns the description
+ * from their respective internal storage (v3: _def, v4: globalRegistry).
  */
 export function getSchemaDescription(schema: AnySchema): string | undefined {
-    if (isZ4Schema(schema)) {
-        const v4Schema = schema as unknown as ZodV4Internal;
-        return v4Schema._zod?.def?.description;
-    }
-    const v3Schema = schema as unknown as ZodV3Internal;
-    // v3 may have description on the schema itself or in _def
-    return (schema as { description?: string }).description ?? v3Schema._def?.description;
+    return (schema as { description?: string }).description;
 }
 
 /**

src/types.ts

@@ -329,7 +329,16 @@ export const ImplementationSchema = BaseMetadataSchema.extend({
     /**
      * An optional URL of the website for this implementation.
      */
-    websiteUrl: z.string().optional()
+    websiteUrl: z.string().optional(),
+
+    /**
+     * An optional human-readable description of what this implementation does.
+     *
+     * This can be used by clients or servers to provide context about their purpose
+     * and capabilities. For example, a server might describe the types of resources
+     * or tools it provides, while a client might describe its intended use case.
+     */
+    description: z.string().optional()
 });
 
 const FormElicitationCapabilitySchema = z.intersection(

src/validation/ajv-provider.ts

@@ -2,7 +2,7 @@
  * AJV-based JSON Schema validator provider
  */
 
-import { Ajv } from 'ajv';
+import Ajv from 'ajv';
 import _addFormats from 'ajv-formats';
 import type { JsonSchemaType, JsonSchemaValidator, JsonSchemaValidatorResult, jsonSchemaValidator } from './types.js';
 

test/issues/test_1277_zod_v4_description.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Regression test for https://github.com/modelcontextprotocol/typescript-sdk/issues/1277
+ *
+ * Zod v4 stores `.describe()` descriptions directly on the schema object,
+ * not in `._zod.def.description`. This test verifies that descriptions are
+ * correctly extracted for prompt arguments.
+ */
+
+import { Client } from '../../src/client/index.js';
+import { InMemoryTransport } from '../../src/inMemory.js';
+import { ListPromptsResultSchema } from '../../src/types.js';
+import { McpServer } from '../../src/server/mcp.js';
+import { zodTestMatrix, type ZodMatrixEntry } from '../../src/__fixtures__/zodTestMatrix.js';
+
+describe.each(zodTestMatrix)('Issue #1277: $zodVersionLabel', (entry: ZodMatrixEntry) => {
+    const { z } = entry;
+
+    test('should preserve argument descriptions from .describe()', async () => {
+        const mcpServer = new McpServer({
+            name: 'test server',
+            version: '1.0'
+        });
+        const client = new Client({
+            name: 'test client',
+            version: '1.0'
+        });
+
+        mcpServer.prompt(
+            'test',
+            {
+                name: z.string().describe('The user name'),
+                value: z.string().describe('The value to set')
+            },
+            async ({ name, value }) => ({
+                messages: [
+                    {
+                        role: 'assistant',
+                        content: {
+                            type: 'text',
+                            text: `${name}: ${value}`
+                        }
+                    }
+                ]
+            })
+        );
+
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+        await Promise.all([client.connect(clientTransport), mcpServer.server.connect(serverTransport)]);
+
+        const result = await client.request(
+            {
+                method: 'prompts/list'
+            },
+            ListPromptsResultSchema
+        );
+
+        expect(result.prompts).toHaveLength(1);
+        expect(result.prompts[0].name).toBe('test');
+        expect(result.prompts[0].arguments).toEqual([
+            { name: 'name', required: true, description: 'The user name' },
+            { name: 'value', required: true, description: 'The value to set' }
+        ]);
+    });
+});

tsconfig.json

@@ -1,14 +1,15 @@
 {
     "compilerOptions": {
-        "target": "es2018",
-        "module": "Node16",
-        "moduleResolution": "Node16",
+        "target": "es2020",
+        "module": "es2022",
+        "moduleResolution": "bundler",
         "declaration": true,
         "declarationMap": true,
         "sourceMap": true,
         "outDir": "./dist",
         "strict": true,
         "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
         "forceConsistentCasingInFileNames": true,
         "resolveJsonModule": true,
         "isolatedModules": true,