Merge branch 'main' into patch-1

Author: andershagbard

.changeset/config.json

@@ -7,5 +7,11 @@
     "access": "public",
     "baseBranch": "main",
     "updateInternalDependencies": "patch",
-    "ignore": ["@modelcontextprotocol/examples-client", "@modelcontextprotocol/examples-server", "@modelcontextprotocol/examples-shared"]
+    "ignore": [
+        "@modelcontextprotocol/examples-client",
+        "@modelcontextprotocol/examples-client-quickstart",
+        "@modelcontextprotocol/examples-server",
+        "@modelcontextprotocol/examples-server-quickstart",
+        "@modelcontextprotocol/examples-shared"
+    ]
 }

.changeset/expose-auth-server-discovery.md

@@ -0,0 +1,10 @@
+---
+'@modelcontextprotocol/client': minor
+---
+
+Add `discoverOAuthServerInfo()` function and unified discovery state caching for OAuth
+
+- New `discoverOAuthServerInfo(serverUrl)` export that performs RFC 9728 protected resource metadata discovery followed by authorization server metadata discovery in a single call. Use this for operations like token refresh and revocation that need the authorization server URL outside of `auth()`.
+- New `OAuthDiscoveryState` type and optional `OAuthClientProvider` methods `saveDiscoveryState()` / `discoveryState()` allow providers to persist all discovery results (auth server URL, resource metadata URL, resource metadata, auth server metadata) across sessions. This avoids redundant discovery requests and handles browser redirect scenarios where discovery state would otherwise be lost.
+- New `'discovery'` scope for `invalidateCredentials()` to clear cached discovery state.
+- New `OAuthServerInfo` type exported for the return value of `discoverOAuthServerInfo()`.

.gitignore

@@ -1,3 +1,6 @@
+# Temporary files
+tmp/
+
 # Logs
 logs
 *.log

.prettierignore

@@ -11,3 +11,7 @@ pnpm-lock.yaml
 
 # Ignore generated files
 src/spec.types.ts
+
+# Quickstart examples uses 2-space indent to match ecosystem conventions
+examples/client-quickstart/
+examples/server-quickstart/

CLAUDE.md

@@ -41,6 +41,12 @@ Include what changed, why, and how to migrate. Search for related sections and g
 - **Testing**: Co-locate tests with source files, use descriptive test names
 - **Comments**: JSDoc for public APIs, inline comments for complex logic
 
+### JSDoc `@example` Code Snippets
+
+JSDoc `@example` tags should pull type-checked code from companion `.examples.ts` files (e.g., `client.ts` → `client.examples.ts`). Use `` ```ts source="./file.examples.ts#regionName" `` fences referencing `//#region regionName` blocks; region names follow `exportedName_variant` or `ClassName_methodName_variant` pattern (e.g., `applyMiddlewares_basicUsage`, `Client_connect_basicUsage`). For whole-file inclusion (any file type), omit the `#regionName`.
+
+Run `pnpm sync:snippets` to sync example content into JSDoc comments and markdown files.
+
 ## Architecture Overview
 
 ### Core Layers

README.md

@@ -30,7 +30,7 @@ This repository contains the TypeScript SDK implementation of the MCP specificat
 - MCP **server** libraries (tools/resources/prompts, Streamable HTTP, stdio, auth helpers)
 - MCP **client** libraries (transports, high-level helpers, OAuth helpers)
 - Optional **middleware packages** for specific runtimes/frameworks (Express, Hono, Node.js HTTP)
-- Runnable **examples** (under [`examples/`](examples/))
+- Runnable **examples** (under [`examples/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples))
 
 ## Packages
 
@@ -43,7 +43,7 @@ Both packages have a **required peer dependency** on `zod` for schema validation
 
 ### Middleware packages (optional)
 
-The SDK also publishes small “middleware” packages under [`packages/middleware/`](packages/middleware/) that help you **wire MCP into a specific runtime or web framework**.
+The SDK also publishes small "middleware" packages under [`packages/middleware/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/packages/middleware) that help you **wire MCP into a specific runtime or web framework**.
 
 They are intentionally thin adapters: they should not introduce new MCP functionality or business logic. See [`packages/middleware/README.md`](packages/middleware/README.md) for details.
 
@@ -127,10 +127,9 @@ Next steps:
 ## Documentation
 
 - Local SDK docs:
-    - [docs/server.md](docs/server.md) – building MCP servers, transports, tools/resources/prompts, CORS, DNS rebinding, and deployment patterns.
-    - [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/faq.md](docs/faq.md) – environment and troubleshooting FAQs (including Node.js Web Crypto support).
+    - [docs/server.md](docs/server.md) – building MCP servers, transports, tools/resources/prompts, sampling, elicitation, tasks, and deployment patterns.
+    - [docs/client.md](docs/client.md) – building MCP clients: connecting, tools, resources, prompts, server-initiated requests, and error handling
+    - [docs/faq.md](docs/faq.md) – frequently asked questions and troubleshooting
 - External references:
     - [SDK API documentation](https://modelcontextprotocol.github.io/typescript-sdk/)
     - [Model Context Protocol documentation](https://modelcontextprotocol.io)

SECURITY.md

@@ -1,15 +1,21 @@
 # Security Policy
 
-Thank you for helping us keep the SDKs and systems they interact with secure.
+Thank you for helping keep the Model Context Protocol and its ecosystem secure.
 
 ## Reporting Security Issues
 
-This SDK is maintained by [Anthropic](https://www.anthropic.com/) as part of the Model Context Protocol project.
+If you discover a security vulnerability in this repository, please report it through
+the [GitHub Security Advisory process](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
+for this repository.
 
-The security of our systems and user data is Anthropic’s top priority. We appreciate the work of security researchers acting in good faith in identifying and reporting potential vulnerabilities.
+Please **do not** report security vulnerabilities through public GitHub issues, discussions,
+or pull requests.
 
-Our security program is managed on HackerOne and we ask that any validated vulnerability in this functionality be reported through their [submission form](https://hackerone.com/anthropic-vdp/reports/new?type=team&report_type=vulnerability).
+## What to Include
 
-## Vulnerability Disclosure Program
+To help us triage and respond quickly, please include:
 
-Our Vulnerability Program Guidelines are defined on our [HackerOne program page](https://hackerone.com/anthropic-vdp).
+- A description of the vulnerability
+- Steps to reproduce the issue
+- The potential impact
+- Any suggested fixes (optional)

common/eslint-config/eslint.config.mjs

@@ -86,6 +86,14 @@ export default defineConfig(
             'unicorn/consistent-function-scoping': 'off'
         }
     },
+    {
+        // Example files contain intentionally unused functions (one per region)
+        files: ['**/*.examples.ts'],
+        rules: {
+            '@typescript-eslint/no-unused-vars': 'off',
+            'no-console': 'off'
+        }
+    },
     {
         // Ignore generated protocol types everywhere
         ignores: ['**/spec.types.ts']