Merge remote-tracking branch 'upstream/main' into feat/user-agent

Author: LucaButBoring

.github/workflows/main.yml

@@ -3,6 +3,7 @@ on:
         branches:
             - main
     pull_request:
+    workflow_dispatch:
     release:
         types: [published]
 
@@ -18,19 +19,35 @@ jobs:
             - uses: actions/checkout@v4
             - uses: actions/setup-node@v4
               with:
-                  node-version: 18
+                  node-version: 24
                   cache: npm
 
             - run: npm ci
+            - run: npm run check
             - run: npm run build
+
+    test:
+        runs-on: ubuntu-latest
+        strategy:
+            fail-fast: false
+            matrix:
+                node-version: [18, 24]
+
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: ${{ matrix.node-version }}
+                  cache: npm
+
+            - run: npm ci
             - run: npm test
-            - run: npm run lint
 
     publish:
         runs-on: ubuntu-latest
         if: github.event_name == 'release'
         environment: release
-        needs: build
+        needs: [build, test]
 
         permissions:
             contents: read
@@ -40,12 +57,22 @@ jobs:
             - uses: actions/checkout@v4
             - uses: actions/setup-node@v4
               with:
-                  node-version: 18
+                  node-version: 24
                   cache: npm
                   registry-url: 'https://registry.npmjs.org'
 
             - run: npm ci
 
-            - run: npm publish --provenance --access public
+            - name: Determine npm tag
+              id: npm-tag
+              run: |
+                  VERSION=$(node -p "require('./package.json').version")
+                  if [[ "$VERSION" == *"-beta"* ]]; then
+                    echo "tag=--tag beta" >> $GITHUB_OUTPUT
+                  else
+                    echo "tag=" >> $GITHUB_OUTPUT
+                  fi
+
+            - run: npm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
               env:
                   NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish Any Commit
+permissions:
+    contents: read
+on:
+    pull_request:
+    push:
+        branches:
+            - '**'
+        tags:
+            - '!**'
+
+jobs:
+    pkg-publish:
+        runs-on: ubuntu-latest
+
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 24
+                  cache: npm
+
+            - run: npm ci
+            - name: Build
+              run: npm run build
+            - name: Publish
+              run: npx pkg-pr-new publish

.github/workflows/update-spec-types.yml

@@ -0,0 +1,71 @@
+name: Update Spec Types
+
+on:
+    schedule:
+        # Run nightly at 4 AM UTC
+        - cron: '0 4 * * *'
+    workflow_dispatch:
+
+permissions:
+    contents: write
+    pull-requests: write
+
+jobs:
+    update-spec-types:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: '24'
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Fetch latest spec types
+              run: npm run fetch:spec-types
+
+            - name: Check for changes
+              id: check_changes
+              run: |
+                  if git diff --quiet src/spec.types.ts; then
+                    echo "has_changes=false" >> $GITHUB_OUTPUT
+                  else
+                    echo "has_changes=true" >> $GITHUB_OUTPUT
+                    LATEST_SHA=$(grep "Last updated from commit:" src/spec.types.ts | cut -d: -f2 | tr -d ' ')
+                    echo "sha=$LATEST_SHA" >> $GITHUB_OUTPUT
+                  fi
+
+            - name: Create Pull Request
+              if: steps.check_changes.outputs.has_changes == 'true'
+              env:
+                  GH_TOKEN: ${{ github.token }}
+              run: |
+                  git config user.name "github-actions[bot]"
+                  git config user.email "github-actions[bot]@users.noreply.github.com"
+
+                  git checkout -B update-spec-types
+                  git add src/spec.types.ts
+                  git commit -m "chore: update spec.types.ts from upstream"
+                  git push -f origin update-spec-types
+
+                  # Create PR if it doesn't exist, or update if it does
+                  PR_BODY="This PR updates \`src/spec.types.ts\` from the Model Context Protocol specification.
+
+                  Source file: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/${{ steps.check_changes.outputs.sha }}/schema/draft/schema.ts
+
+                  This is an automated update triggered by the nightly cron job."
+
+                  if gh pr view update-spec-types &>/dev/null; then
+                    echo "PR already exists, updating description..."
+                    gh pr edit update-spec-types --body "$PR_BODY"
+                  else
+                    gh pr create \
+                      --title "chore: update spec.types.ts from upstream" \
+                      --body "$PR_BODY" \
+                      --base main \
+                      --head update-spec-types
+                  fi

.gitignore

@@ -69,9 +69,6 @@ web_modules/
 # Output of 'npm pack'
 *.tgz
 
-# Output of 'npm run fetch:spec-types'
-spec.types.ts
-
 # Yarn Integrity file
 .yarn-integrity
 
@@ -133,3 +130,6 @@ out
 
 .DS_Store
 dist/
+
+# IDE
+.idea/

.prettierignore

@@ -7,4 +7,7 @@ node_modules
 **/build
 **/dist
 .github/CODEOWNERS
-pnpm-lock.yaml
+pnpm-lock.yaml
+
+# Ignore generated files
+src/spec.types.ts

README.md

@@ -47,9 +47,11 @@ The Model Context Protocol allows applications to provide context for LLMs in a
 ## Installation
 
 ```bash
-npm install @modelcontextprotocol/sdk
+npm install @modelcontextprotocol/sdk zod
 ```
 
+This SDK has a **required peer dependency** on `zod` for schema validation. The SDK internally imports from `zod/v4`, but maintains backwards compatibility with projects using Zod v3.25 or later. You can use either API in your code by importing from `zod/v3` or `zod/v4`:
+
 ## Quick Start
 
 Let's create a simple MCP server that exposes a calculator tool and some data. Save the following as `server.ts`:
@@ -58,7 +60,7 @@ Let's create a simple MCP server that exposes a calculator tool and some data. S
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import express from 'express';
-import { z } from 'zod';
+import * as z from 'zod/v4';
 
 // Create an MCP server
 const server = new McpServer({
@@ -130,7 +132,7 @@ app.listen(port, () => {
 });
 ```
 
-Install the deps with `npm install @modelcontextprotocol/sdk express zod@3`, and run with `npx -y tsx server.ts`.
+Install the deps with `npm install @modelcontextprotocol/sdk express zod`, and run with `npx -y tsx server.ts`.
 
 You can connect to it using any MCP client that supports streamable http, such as:
 
@@ -477,7 +479,7 @@ MCP servers can request LLM completions from connected clients that support samp
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import express from 'express';
-import { z } from 'zod';
+import * as z from 'zod/v4';
 
 const mcpServer = new McpServer({
     name: 'tools-with-sample-server',
@@ -561,7 +563,7 @@ For most use cases where session management isn't needed:
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import express from 'express';
-import { z } from 'zod';
+import * as z from 'zod/v4';
 
 const app = express();
 app.use(express.json());
@@ -796,7 +798,7 @@ A simple server demonstrating resources, tools, and prompts:
 
 ```typescript
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
+import * as z from 'zod/v4';
 
 const server = new McpServer({
     name: 'echo-server',
@@ -866,7 +868,7 @@ A more complex example showing database integration:
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import sqlite3 from 'sqlite3';
 import { promisify } from 'util';
-import { z } from 'zod';
+import * as z from 'zod/v4';
 
 const server = new McpServer({
     name: 'sqlite-explorer',
@@ -961,7 +963,7 @@ If you want to offer an initial set of tools/prompts/resources, but later add ad
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import express from 'express';
-import { z } from 'zod';
+import * as z from 'zod/v4';
 
 const server = new McpServer({
     name: 'Dynamic Example',
@@ -1175,7 +1177,7 @@ await server.connect(transport);
 
 ### Eliciting User Input
 
-MCP servers can request additional information from users through the elicitation feature. This is useful for interactive workflows where the server needs user input or confirmation:
+MCP servers can request non-sensitive information from users through the form elicitation capability. This is useful for interactive workflows where the server needs user input or confirmation:
 
 ```typescript
 // Server-side: Restaurant booking tool that asks for alternatives
@@ -1208,6 +1210,7 @@ server.registerTool(
         if (!available) {
             // Ask user if they want to try alternative dates
             const result = await server.server.elicitInput({
+                mode: 'form',
                 message: `No tables available at ${restaurant} on ${date}. Would you like to check alternative dates?`,
                 requestedSchema: {
                     type: 'object',
@@ -1274,7 +1277,7 @@ server.registerTool(
 );
 ```
 
-Client-side: Handle elicitation requests
+On the client side, handle form elicitation requests:
 
 ```typescript
 // This is a placeholder - implement based on your UI framework
@@ -1299,7 +1302,85 @@ client.setRequestHandler(ElicitRequestSchema, async request => {
 });
 ```
 
-**Note**: Elicitation requires client support. Clients must declare the `elicitation` capability during initialization.
+When calling `server.elicitInput`, prefer to explicitly set `mode: 'form'` for new code. Omitting the mode continues to work for backwards compatibility and defaults to form elicitation.
+
+Elicitation is a client capability. Clients must declare the `elicitation` capability during initialization:
+
+```typescript
+const client = new Client(
+    {
+        name: 'example-client',
+        version: '1.0.0'
+    },
+    {
+        capabilities: {
+            elicitation: {
+                form: {}
+            }
+        }
+    }
+);
+```
+
+**Note**: Form elicitation **must** only be used to gather non-sensitive information. For sensitive information such as API keys or secrets, use URL elicitation instead.
+
+### Eliciting URL Actions
+
+MCP servers can prompt the user to perform a URL-based action through URL elicitation. This is useful for securely gathering sensitive information such as API keys or secrets, or for redirecting users to secure web-based flows.
+
+```typescript
+// Server-side: Prompt the user to navigate to a URL
+const result = await server.server.elicitInput({
+    mode: 'url',
+    message: 'Please enter your API key',
+    elicitationId: '550e8400-e29b-41d4-a716-446655440000',
+    url: 'http://localhost:3000/api-key'
+});
+
+// Alternative, return an error from within a tool:
+throw new UrlElicitationRequiredError([
+    {
+        mode: 'url',
+        message: 'This tool requires a payment confirmation. Open the link to confirm payment!',
+        url: `http://localhost:${MCP_PORT}/confirm-payment?session=${sessionId}&elicitation=${elicitationId}&cartId=${encodeURIComponent(cartId)}`,
+        elicitationId: '550e8400-e29b-41d4-a716-446655440000'
+    }
+]);
+```
+
+On the client side, handle URL elicitation requests:
+
+```typescript
+client.setRequestHandler(ElicitRequestSchema, async request => {
+    if (request.params.mode !== 'url') {
+        throw new McpError(ErrorCode.InvalidParams, `Unsupported elicitation mode: ${request.params.mode}`);
+    }
+
+    // At a minimum, implement a UI that:
+    // - Display the full URL and server reason to prevent phishing
+    // - Explicitly ask the user for consent, with clear decline/cancel options
+    // - Open the URL in the system (not embedded) browser
+    // Optionally, listen for a `nofifications/elicitation/complete` message from the server
+});
+```
+
+Elicitation is a client capability. Clients must declare the `elicitation` capability during initialization:
+
+```typescript
+const client = new Client(
+    {
+        name: 'example-client',
+        version: '1.0.0'
+    },
+    {
+        capabilities: {
+            elicitation: {
+                url: {}
+            }
+        }
+    }
+);
+```
 
 ### Writing MCP Clients
 

eslint.config.mjs

@@ -15,6 +15,9 @@ export default tseslint.config(
             '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }]
         }
     },
+    {
+        ignores: ['src/spec.types.ts']
+    },
     {
         files: ['src/client/**/*.ts', 'src/server/**/*.ts'],
         ignores: ['**/*.test.ts'],