fix: skip outputSchema validation when isError is true

.changeset/add-extensions-capability.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/sdk': minor
+---
+
+Add `extensions` field to `ClientCapabilities` and `ServerCapabilities` to allow servers and clients to advertise extension support per SEP-2133

.changeset/add-resource-size-field.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/sdk': patch
+---
+
+Add missing `size` field to `ResourceSchema` to match the MCP specification

.changeset/add-types-export-condition.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/sdk': patch
+---
+
+Add `"types"` condition to `exports` map for subpath imports (`.`, `./client`, `./server`, `./*`), enabling TypeScript to resolve type declarations with `moduleResolution: "bundler"` or `"node16"` without requiring manual `tsconfig.json` `paths` workarounds.

.changeset/add-url-to-request-info.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/sdk': patch
+---
+
+Add `url` property to `RequestInfo` interface as a `URL` type, exposing the full request URL to server handlers. The URL is unified across all HTTP transports (SSE and Streamable HTTP) to always provide the complete URL including protocol, host, and path.

.changeset/fix-listchanged-backport.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/sdk': patch
+---
+
+Respected explicit `listChanged: false` capability settings in `McpServer`. Previously, registering a tool, resource, or prompt would unconditionally overwrite `listChanged` to `true`, ignoring any explicit `false` set at construction time.

.changeset/fix-stdio-windows-hide.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/sdk': patch
+---
+
+Always set windowsHide to true when spawning stdio server processes on Windows, not just in Electron environments.

.changeset/fix-zod-error-message-priority.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/sdk': patch
+---
+
+Prioritize `error.issues[].message` over `error.message` in `getParseErrorMessage` so custom Zod error messages surface correctly. In Zod v4, `error.message` is a JSON blob of all issues, not a readable string.

.changeset/rfc8252-loopback-port-relaxation.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/sdk': patch
+---
+
+The authorization handler now applies RFC 8252 §7.3 loopback port relaxation when validating `redirect_uri` against a client's registered URIs. For `localhost`, `127.0.0.1`, and `[::1]` hosts, any port is accepted as long as scheme, host, path, and query match. This fixes native
+clients that obtain an ephemeral port from the OS but register a portless loopback URI (e.g., via CIMD / SEP-991).

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+    - package-ecosystem: 'github-actions'
+      directory: '/'
+      schedule:
+          interval: monthly
+      groups:
+          github-actions:
+              patterns:
+                  - '*'

.github/workflows/conformance.yml

@@ -0,0 +1,40 @@
+name: Conformance Tests
+
+on:
+    push:
+        branches: [v1.x]
+    pull_request:
+        branches: [v1.x]
+    workflow_dispatch:
+
+concurrency:
+    group: conformance-${{ github.ref }}
+    cancel-in-progress: true
+
+permissions:
+    contents: read
+
+jobs:
+    client-conformance:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 24
+                  cache: npm
+            - run: npm ci
+            - run: npm run build
+            - run: npm run test:conformance:client:all
+
+    server-conformance:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 24
+                  cache: npm
+            - run: npm ci
+            - run: npm run build
+            - run: npm run test:conformance:server

.github/workflows/main.yml

@@ -1,7 +1,7 @@
 on:
     push:
         branches:
-            - main
+            - v1.x
     pull_request:
     workflow_dispatch:
     release:
@@ -59,19 +59,21 @@ jobs:
               with:
                   node-version: 24
                   cache: npm
-                  registry-url: 'https://registry.npmjs.org'
 
             - run: npm ci
 
+            - name: Ensure npm CLI supports OIDC trusted publishing
+              run: npm install -g npm@11.5.1
+
             - name: Determine npm tag
               id: npm-tag
               run: |
                   VERSION=$(node -p "require('./package.json').version")
                   # Check if this is a beta release
                   if [[ "$VERSION" == *"-beta"* ]]; then
                     echo "tag=--tag beta" >> $GITHUB_OUTPUT
-                  # Check if this release is from a non-main branch (patch/maintenance release)
-                  elif [[ "${{ github.event.release.target_commitish }}" != "main" ]]; then
+                  # Check if this release is from a non-primary branch (patch/maintenance release)
+                  elif [[ "${{ github.event.release.target_commitish }}" != "main" && "${{ github.event.release.target_commitish }}" != "v1.x" ]]; then
                     # Use "release-X.Y" as tag for old branch releases (e.g., "release-1.23" for 1.23.x)
                     # npm tags are mutable pointers to versions (like "latest" pointing to 1.24.3).
                     # Using "release-1.23" means users can `npm install @modelcontextprotocol/sdk@release-1.23`
@@ -85,5 +87,3 @@ jobs:
                   fi
 
             - run: npm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
-              env:
-                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -133,3 +133,4 @@ dist/
 
 # IDE
 .idea/
+test/conformance/node_modules/

CLAUDE.md

@@ -22,7 +22,7 @@ npm run typecheck    # Type-check without emitting
 - **Files**: Lowercase with hyphens, test files with `.test.ts` suffix
 - **Imports**: ES module style, include `.js` extension, group imports logically
 - **Formatting**: 2-space indentation, semicolons required, single quotes preferred
-- **Testing**: Co-locate tests with source files, use descriptive test names
+- **Testing**: Co-locate tests with source files, use descriptive test names. Use `vi.useFakeTimers()` instead of real `setTimeout`/`await` delays in tests
 - **Comments**: JSDoc for public APIs, inline comments for complex logic
 
 ## Architecture Overview

DEPENDENCY_POLICY.md

@@ -0,0 +1,29 @@
+# Dependency Policy
+
+As a library consumed by downstream projects, the MCP TypeScript SDK takes a conservative approach to dependency updates. Dependencies are kept stable unless there is a specific reason to update, such as a security vulnerability, a bug fix, or a need for new functionality.
+
+## Update Triggers
+
+Dependencies are updated when:
+
+- A **security vulnerability** is disclosed (via GitHub security alerts).
+- A bug in a dependency directly affects the SDK.
+- A new dependency feature is needed for SDK development.
+- A dependency drops support for a Node.js version the SDK still targets.
+
+Routine version bumps without a clear motivation are avoided to minimize churn for downstream consumers.
+
+## What We Don't Do
+
+The SDK does not run scheduled version bumps for npm dependencies. Updating a dependency can force downstream consumers to adopt that update transitively, which can be disruptive for projects with strict dependency policies.
+
+Dependencies are only updated when there is a concrete reason, not simply because a newer version is available.
+
+## Automated Tooling
+
+- **GitHub security updates** are enabled at the repository level and automatically open pull requests for npm packages with known vulnerabilities. This is a GitHub repo setting, separate from the `dependabot.yml` configuration.
+- **GitHub Actions versions** are kept up to date via Dependabot on a monthly schedule (see `.github/dependabot.yml`).
+
+## Pinning and Ranges
+
+Production dependencies use caret ranges (`^`) to allow compatible updates within a major version. Exact versions are pinned only when necessary to work around a specific issue.

README.md

@@ -1,4 +1,4 @@
-# MCP TypeScript SDK ![NPM Version](https://img.shields.io/npm/v/%40modelcontextprotocol%2Fsdk) ![MIT licensed](https://img.shields.io/npm/l/%40modelcontextprotocol%2Fsdk)
+# MCP TypeScript SDK [![NPM Version](https://img.shields.io/npm/v/%40modelcontextprotocol%2Fsdk)](https://www.npmjs.com/package/@modelcontextprotocol/sdk) [![MIT licensed](https://img.shields.io/npm/l/%40modelcontextprotocol%2Fsdk)](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/LICENSE)
 
 <details>
 <summary>Table of Contents</summary>
@@ -154,8 +154,11 @@ For more details on how to run these examples (including recommended commands an
     - [docs/server.md](docs/server.md) – building and running MCP servers, transports, tools/resources/prompts, CORS, DNS rebinding, and multi-node deployment.
     - [docs/client.md](docs/client.md) – using the high-level client, transports, backwards compatibility, and OAuth helpers.
     - [docs/capabilities.md](docs/capabilities.md) – sampling, elicitation (form and URL), and experimental task-based execution.
+    - [docs/protocol.md](docs/protocol.md) – protocol features: ping, progress, cancellation, pagination, capability negotiation, and JSON Schema.
     - [docs/faq.md](docs/faq.md) – environment and troubleshooting FAQs (including Node.js Web Crypto support).
 - External references:
+    - [V1 API reference](https://modelcontextprotocol.github.io/typescript-sdk/)
+    - [V2 API reference](https://modelcontextprotocol.github.io/typescript-sdk/v2/)
     - [Model Context Protocol documentation](https://modelcontextprotocol.io)
     - [MCP Specification](https://spec.modelcontextprotocol.io)
     - [Example Servers](https://github.com/modelcontextprotocol/servers)

ROADMAP.md

@@ -0,0 +1,22 @@
+# Roadmap
+
+## Spec Implementation Tracking
+
+The SDK tracks implementation of MCP spec components via GitHub Projects, with a dedicated project board for each spec revision. For example, see the [2025-11-25 spec revision board](https://github.com/orgs/modelcontextprotocol/projects/26).
+
+## Current Focus Areas
+
+### Next Spec Revision
+
+The next MCP specification revision is being developed in the [protocol repository](https://github.com/modelcontextprotocol/modelcontextprotocol). Key areas expected in the next revision include extensions and stateless transports.
+
+The SDK has historically implemented spec changes promptly as they are finalized, with dedicated project boards tracking component-level progress for each revision.
+
+### v2
+
+A major version of the SDK is in active development, tracked via [GitHub Project](https://github.com/orgs/modelcontextprotocol/projects/31). Target milestones:
+
+- **Alpha**: ~mid-March 2026
+- **Beta**: ~May 2026
+
+The v2 release is planned to align with the next spec release, expected around mid-2026.

VERSIONING.md

@@ -0,0 +1,40 @@
+# Versioning Policy
+
+The MCP TypeScript SDK (`@modelcontextprotocol/sdk`) follows [Semantic Versioning 2.0.0](https://semver.org/).
+
+## Version Format
+
+`MAJOR.MINOR.PATCH`
+
+- **MAJOR**: Incremented for breaking changes (see below).
+- **MINOR**: Incremented for new features that are backward-compatible.
+- **PATCH**: Incremented for backward-compatible bug fixes.
+
+## What Constitutes a Breaking Change
+
+The following changes are considered breaking and require a major version bump:
+
+- Removing or renaming a public API export (class, function, type, or constant).
+- Changing the signature of a public function or method in a way that breaks existing callers (removing parameters, changing required/optional status, changing types).
+- Removing or renaming a public type or interface field.
+- Changing the behavior of an existing API in a way that breaks documented contracts.
+- Dropping support for a Node.js LTS version.
+- Removing support for a transport type.
+- Changes to the MCP protocol version that require client/server code changes.
+
+The following are **not** considered breaking:
+
+- Adding new optional parameters to existing functions.
+- Adding new exports, types, or interfaces.
+- Adding new optional fields to existing types.
+- Bug fixes that correct behavior to match documented intent.
+- Internal refactoring that does not affect the public API.
+- Adding support for new MCP spec features.
+- Changes to dev dependencies or build tooling.
+
+## How Breaking Changes Are Communicated
+
+1. **Changelog**: All breaking changes are documented in the GitHub release notes with migration instructions.
+2. **Deprecation**: When feasible, APIs are deprecated for at least one minor release before removal using `@deprecated` JSDoc annotations, which surface warnings through TypeScript tooling and editors.
+3. **Migration guide**: Major version releases include a migration guide describing what changed and how to update.
+4. **PR labels**: Pull requests containing breaking changes are labeled with `breaking change`.

docs/capabilities.md

@@ -27,6 +27,99 @@ Runnable example:
 
 The `simpleStreamableHttp` server also includes a `collect-user-info` tool that demonstrates how to drive elicitation from a tool and handle the response.
 
+#### Schema validation
+
+Elicitation schemas support validation constraints on each field. The server validates responses automatically against the `requestedSchema` using the SDK's JSON Schema validator.
+
+```typescript
+const result = await server.server.elicitInput({
+    mode: 'form',
+    message: 'Enter your details:',
+    requestedSchema: {
+        type: 'object',
+        properties: {
+            email: {
+                type: 'string',
+                title: 'Email',
+                format: 'email',
+                minLength: 5
+            },
+            age: {
+                type: 'integer',
+                title: 'Age',
+                minimum: 0,
+                maximum: 150
+            }
+        },
+        required: ['email']
+    }
+});
+```
+
+String fields support `minLength`, `maxLength`, and `format` (`'email'`, `'uri'`, `'date'`, `'date-time'`). Number fields support `minimum` and `maximum`.
+
+#### Default values
+
+Schema properties can include `default` values. When the client declares the `applyDefaults` capability, the SDK automatically fills in defaults for fields the user doesn't provide.
+
+> **Note:** `applyDefaults` is a TypeScript SDK extension — it is not part of the MCP protocol specification.
+
+```typescript
+// Client declares applyDefaults:
+const client = new Client(
+  { name: 'my-client', version: '1.0.0' },
+  { capabilities: { elicitation: { form: { applyDefaults: true } } } }
+);
+
+// Server schema with defaults:
+requestedSchema: {
+  type: 'object',
+  properties: {
+    newsletter: { type: 'boolean', title: 'Newsletter', default: false },
+    theme: { type: 'string', title: 'Theme', default: 'dark' }
+  }
+}
+```
+
+#### Enum values
+
+Elicitation schemas support several enum patterns for single-select and multi-select fields:
+
+```typescript
+requestedSchema: {
+  type: 'object',
+  properties: {
+    // Simple enum (untitled options)
+    color: {
+      type: 'string',
+      title: 'Favorite Color',
+      enum: ['red', 'green', 'blue'],
+      default: 'blue'
+    },
+    // Titled enum with display labels
+    priority: {
+      type: 'string',
+      title: 'Priority',
+      oneOf: [
+        { const: 'low', title: 'Low Priority' },
+        { const: 'medium', title: 'Medium Priority' },
+        { const: 'high', title: 'High Priority' }
+      ]
+    },
+    // Multi-select
+    tags: {
+      type: 'array',
+      title: 'Tags',
+      items: { type: 'string', enum: ['frontend', 'backend', 'docs'] },
+      minItems: 1,
+      maxItems: 3
+    }
+  }
+}
+```
+
+For a full example with validation, defaults, and enums, see [`elicitationFormExample.ts`](../src/examples/server/elicitationFormExample.ts).
+
 ### URL elicitation
 
 URL elicitation is designed for sensitive data and secure web‑based flows (e.g., collecting an API key, confirming a payment, or doing third‑party OAuth). Instead of returning form data, the server asks the client to open a URL and the rest of the flow happens in the browser.
@@ -46,6 +139,23 @@ Key points:
 
 Sensitive information **must not** be collected via form elicitation; always use URL elicitation or out‑of‑band flows for secrets.
 
+#### Complete notification
+
+When a URL elicitation flow finishes (the user completes the browser-based action), the server sends a `notifications/elicitation/complete` notification to the client. This tells the client the out-of-band flow is done and any pending UI can be dismissed.
+
+Use `createElicitationCompletionNotifier` on the low-level server to create a callback that sends this notification:
+
+```typescript
+// Create a notifier for a specific elicitation:
+const notifyComplete = server.server.createElicitationCompletionNotifier('setup-123');
+
+// Later, when the browser flow completes (e.g. via webhook):
+await notifyComplete();
+// Client receives: { method: 'notifications/elicitation/complete', params: { elicitationId: 'setup-123' } }
+```
+
+See [`elicitationUrlExample.ts`](../src/examples/server/elicitationUrlExample.ts) for a full working example.
+
 ## Task-based execution (experimental)
 
 Task-based execution enables “call-now, fetch-later” patterns for long-running operations. Instead of returning a result immediately, a tool creates a task that can be polled or resumed later.
@@ -70,7 +180,7 @@ For a runnable example that uses the in-memory store shipped with the SDK, see:
 On the client, you use:
 
 - `client.experimental.tasks.callToolStream(...)` to start a tool call that may create a task and emit status updates over time.
-- `client.getTask(...)` and `client.getTaskResult(...)` to check status and fetch results after reconnecting.
+- `client.experimental.tasks.getTask(...)` and `client.experimental.tasks.getTaskResult(...)` to check status and fetch results after reconnecting.
 
 The interactive client in: