Merge branch 'main' into fweinberger/browser-stdio-conditional-export

Author: KKonstantinov

.changeset/fix-validate-client-metadata-url.md

@@ -0,0 +1,9 @@
+---
+'@modelcontextprotocol/client': minor
+---
+
+Add `validateClientMetadataUrl()` utility for early validation of `clientMetadataUrl`
+
+Exports a `validateClientMetadataUrl()` function that `OAuthClientProvider` implementations
+can call in their constructors to fail fast on invalid URL-based client IDs, instead of
+discovering the error deep in the auth flow.

.github/workflows/release.yml

@@ -63,17 +63,20 @@ jobs:
                   node-version: 24
                   cache: pnpm
                   cache-dependency-path: pnpm-lock.yaml
-                  registry-url: 'https://registry.npmjs.org'
 
             - name: Install dependencies
               run: pnpm install
 
+            # pnpm@10 delegates `pnpm publish` to the npm CLI; OIDC trusted publishing
+            # requires npm >=11.5.1, which Node 24's bundled npm only satisfies from
+            # ~24.6 onward. Install a recent-enough npm so we don't depend on which Node patch resolves.
+            - name: Ensure npm CLI supports OIDC trusted publishing
+              run: npm install -g npm@11.5.1
+
             - name: Publish to npm
               uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1
               with:
                   publish: pnpm run ci:publish
               env:
                   GITHUB_TOKEN: ${{ github.token }}
-                  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
                   NPM_CONFIG_PROVENANCE: 'true'

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

@@ -51,14 +51,17 @@ jobs:
               if: steps.check_changes.outputs.has_changes == 'true'
               env:
                   GH_TOKEN: ${{ github.token }}
+                  # Skip lefthook pre-push (typecheck/lint/build); spec drift that breaks
+                  # typecheck should still open a PR so it can be fixed there.
+                  LEFTHOOK: 0
               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 packages/core/src/types/spec.types.ts
                   git commit -m "chore: update spec.types.ts from upstream"
-                  git push -f origin update-spec-types
+                  git push -f --no-verify origin update-spec-types
 
                   # Create PR if it doesn't exist, or update if it does
                   PR_BODY="This PR updates \`packages/core/src/types/spec.types.ts\` from the Model Context Protocol specification.
@@ -67,9 +70,11 @@ jobs:
 
                   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"
+                  # `gh pr view <branch>` matches closed PRs too, so check for an *open* PR explicitly.
+                  EXISTING_PR=$(gh pr list --head update-spec-types --state open --json number --jq '.[0].number // empty')
+                  if [ -n "$EXISTING_PR" ]; then
+                    echo "PR #$EXISTING_PR already exists, updating description..."
+                    gh pr edit "$EXISTING_PR" --body "$PR_BODY"
                   else
                     gh pr create \
                       --title "chore: update spec.types.ts from upstream" \

REVIEW.md

@@ -0,0 +1,95 @@
+# typescript-sdk Review Conventions
+
+Guidance for reviewing pull requests on this repository. The first three sections are
+stable principles; the **Recurring Catches** section is auto-maintained from past human
+review rounds and grows over time.
+
+## Guiding Principles
+
+1. **Minimalism** — The SDK should do less, not more. Protocol correctness, transport
+   lifecycle, types, and clean handler context belong in the SDK. Middleware engines,
+   registry managers, builder patterns, and content helpers belong in userland.
+2. **Burden of proof is on addition** — The default answer to "should we add this?" is
+   no. Removing something from the public API is far harder than not adding it.
+3. **Justify with concrete evidence** — Every new abstraction needs a concrete consumer
+   today. Ask for real issues, benchmarks, real-world examples; apply the same standard
+   to your own review (link spec sections, link code, show the simpler alternative).
+4. **Spec is the anchor** — The SDK implements the protocol spec. The further a feature
+   drifts from the spec, the stronger the justification needs to be.
+5. **Kill at the highest level** — If the design is wrong, don't review the
+   implementation. Lead with the highest-level concern; specific bugs are supporting
+   detail.
+6. **Decompose by default** — A PR doing multiple things should be multiple PRs unless
+   there's a strong reason to bundle.
+
+## Review Ordering
+
+1. **Design justification** — Is the overall approach sound? Is the complexity warranted?
+2. **Structural concerns** — Is the architecture right? Are abstractions justified?
+3. **Correctness** — Bugs, regressions, missing functionality.
+4. **Style and naming** — Nits, conventions, documentation.
+
+## Checklist
+
+**Protocol & spec**
+- Types match [`schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/draft/schema.ts) exactly (optional vs required fields)
+- Correct `ProtocolError` codes (enum `ProtocolErrorCode`); HTTP status codes match spec (e.g., 404 vs 410)
+- Works for both stdio and Streamable HTTP transports — no transport-specific assumptions
+- Cross-SDK consistency: check what `python-sdk` does for the same feature
+
+**API surface**
+- Every new export is intentional (see CLAUDE.md § Public API Exports); helpers users can write themselves belong in a cookbook, not the SDK
+- New abstractions have at least one concrete callsite in the PR
+- One way to do things — improving an existing API beats adding a parallel one
+
+**Correctness**
+- Async: race conditions, cleanup on cancellation, unhandled rejections, missing `await`
+- Error propagation: caught/rethrown properly, resources cleaned up on error paths
+- Type safety: no unjustified `any`, no unsafe `as` assertions
+- Backwards compat: public-interface changes, default changes, removed exports — flagged and justified
+
+**Tests & docs**
+- New behavior has vitest coverage including error paths
+- Breaking changes documented in `docs/migration.md` and `docs/migration-SKILL.md`
+- Bugfix or behavior change: check whether `docs/**/*.md` describes the old behavior and needs updating; flag prose that now contradicts the implementation
+- New feature: verify prose documentation is added (not just JSDoc), and assess whether `examples/` needs a new or updated example
+- Behavior change: assess whether existing `examples/` still compile and demonstrate the current API
+
+## Reference
+
+When verifying spec compliance, consult the spec directly rather than relying on memory:
+
+- MCP documentation server: `https://modelcontextprotocol.io/mcp`
+- Full spec text (single file, LLM-friendly): `https://modelcontextprotocol.io/llms-full.txt` — fetch to a temp file and grep for the relevant section
+- Schema source of truth: [`schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/draft/schema.ts)
+
+## Recurring Catches
+
+### HTTP Transport
+
+- When validating `Mcp-Session-Id`, return **400** for a missing header and **404** for an unknown/expired session — never conflate `!sessionId || !transports[sessionId]` into one status, because the client needs to distinguish "fix your request" from "start a new session". Flag any diff that branches on session-id presence/lookup with a single 4xx. (#1707, #1770)
+
+### Error Handling
+
+- Broad `catch` blocks must not emit client-fault JSON-RPC codes (`-32700` ParseError, `-32602` InvalidParams) for server-internal failures like stream setup, task-store misses, or polling errors — map those to `-32603` InternalError so clients don't retry/reformat pointlessly. Flag any catch-all that hard-codes ParseError/InvalidParams without discriminating the thrown cause. (#1752, #1769)
+
+### Schema Compliance
+
+- When editing Zod protocol schemas in `schemas.ts`, verify unknown-key handling matches the spec `schema.ts`: if the spec type has no `additionalProperties: false`, the SDK schema must use `z.looseObject()` / `.catchall(z.unknown())` rather than implicit strict — over-strict Zod (incl. `z.literal('object')` on `type`) rejects spec-valid payloads from other SDKs. Also confirm `spec.types.test.ts` still passes bidirectionally. (#1768, #1849, #1169)
+
+### Async / Lifecycle
+
+- In `close()` / shutdown paths, wrap user-supplied or chained callbacks (`onclose?.()`, cancel fns) in `try/finally` so a throw can't skip the remaining teardown (`abort()`, `_onclose()`, map clears) — otherwise the transport is left half-open. (#1735, #1763)
+- Deferred callbacks (`setTimeout`, `.finally()`, reconnect closures) must check closed/aborted state before mutating `this._*` or starting I/O — a callback scheduled pre-close can fire after close/reconnect and corrupt the new connection's state (e.g., delete the new request's `AbortController`). (#1735, #1763)
+
+### Completeness
+
+- When a PR replaces a pattern (error class, auth-flow step, catch shape), grep the package for surviving instances of the old form — partial migrations leave sibling code paths with the very bug the PR claims to fix. Flag every leftover site. (#1657, #1761, #1595)
+
+### Documentation & Changesets
+
+- Read added `.changeset/*.md` text and new inline comments against the implementation in the same diff — prose that promises behavior the code no longer ships misleads consumers and contradicts stated intent. Flag any claim the diff doesn't back. (#1718, #1838)
+
+### CI & GitHub Actions
+
+- Do **not** assert that a third-party GitHub Action or publish toolchain will fail or needs extra permissions/tokens without verifying its docs or source — `pnpm publish` delegates to the system npm CLI (so npm OIDC works), and `changesets/action` in publish mode has no PR-comment step requiring `pull-requests: write`. For diffs under `.github/workflows/`, confirm claimed behavior in the action's README/source before flagging. (#1838, #1836)

docs/migration-SKILL.md

@@ -86,7 +86,7 @@ Notes:
 | `JSONRPCError`                           | `JSONRPCErrorResponse`                                   |
 | `JSONRPCErrorSchema`                     | `JSONRPCErrorResponseSchema`                             |
 | `isJSONRPCError`                         | `isJSONRPCErrorResponse`                                 |
-| `isJSONRPCResponse`                      | `isJSONRPCResultResponse`                                |
+| `isJSONRPCResponse` (deprecated in v1)   | `isJSONRPCResultResponse` (**not** v2's new `isJSONRPCResponse`, which correctly matches both result and error) |
 | `ResourceReference`                      | `ResourceTemplateReference`                              |
 | `ResourceReferenceSchema`                | `ResourceTemplateReferenceSchema`                        |
 | `IsomorphicHeaders`                      | REMOVED (use Web Standard `Headers`)                     |
@@ -98,7 +98,7 @@ Notes:
 | `StreamableHTTPError`                    | REMOVED (use `SdkError` with `SdkErrorCode.ClientHttp*`) |
 | `WebSocketClientTransport`               | REMOVED (use `StreamableHTTPClientTransport` or `StdioClientTransport`) |
 
-All other symbols from `@modelcontextprotocol/sdk/types.js` retain their original names (e.g., `CallToolResultSchema`, `ListToolsResultSchema`, etc.).
+All other **type** symbols from `@modelcontextprotocol/sdk/types.js` retain their original names. **Zod schemas** (e.g., `CallToolResultSchema`, `ListToolsResultSchema`) are no longer part of the public API — they are internal to the SDK. For runtime validation, use type guard functions like `isCallToolResult` instead of `CallToolResultSchema.safeParse()`.
 
 ### Error class changes
 
@@ -435,6 +435,13 @@ const tool = await client.callTool({ name: 'my-tool', arguments: {} });
 
 Remove unused schema imports: `CallToolResultSchema`, `CompatibilityCallToolResultSchema`, `ElicitResultSchema`, `CreateMessageResultSchema`, etc., when they were only used in `request()`/`send()`/`callTool()` calls.
 
+If `CallToolResultSchema` was used for **runtime validation** (not just as a `request()` argument), replace with the `isCallToolResult` type guard:
+
+| v1 pattern                                          | v2 replacement             |
+| --------------------------------------------------- | -------------------------- |
+| `CallToolResultSchema.safeParse(value).success`     | `isCallToolResult(value)`  |
+| `CallToolResultSchema.parse(value)`                 | Use `isCallToolResult(value)` then cast, or use `CallToolResult` type |
+
 ## 12. Experimental: `TaskCreationParams.ttl` no longer accepts `null`
 
 `TaskCreationParams.ttl` changed from `z.union([z.number(), z.null()]).optional()` to `z.number().optional()`. Per the MCP spec, `null` TTL (unlimited lifetime) is only valid in server responses (`Task.ttl`), not in client requests. Omit `ttl` to let the server decide.

docs/migration.md

@@ -444,6 +444,18 @@ const result = await client.callTool({ name: 'my-tool', arguments: {} });
 
 The return type is now inferred from the method name via `ResultTypeMap`. For example, `client.request({ method: 'tools/call', ... })` returns `Promise<CallToolResult | CreateTaskResult>`.
 
+If you were using `CallToolResultSchema` for **runtime validation** (not just in `request()`/`callTool()` calls), use the new `isCallToolResult` type guard instead:
+
+```typescript
+// v1: runtime validation with Zod schema
+import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+if (CallToolResultSchema.safeParse(value).success) { /* ... */ }
+
+// v2: use the type guard
+import { isCallToolResult } from '@modelcontextprotocol/client';
+if (isCallToolResult(value)) { /* ... */ }
+```
+
 ### Client list methods return empty results for missing capabilities
 
 `Client.listPrompts()`, `listResources()`, `listResourceTemplates()`, and `listTools()` now return empty results when the server didn't advertise the corresponding capability, instead of sending the request. This respects the MCP spec's capability negotiation.
@@ -484,14 +496,16 @@ The following deprecated type aliases have been removed from `@modelcontextproto
 | `JSONRPCError`                           | `JSONRPCErrorResponse`                           |
 | `JSONRPCErrorSchema`                     | `JSONRPCErrorResponseSchema`                     |
 | `isJSONRPCError`                         | `isJSONRPCErrorResponse`                         |
-| `isJSONRPCResponse`                      | `isJSONRPCResultResponse`                        |
+| `isJSONRPCResponse`                      | `isJSONRPCResultResponse` (see note below)       |
 | `ResourceReferenceSchema`                | `ResourceTemplateReferenceSchema`                |
 | `ResourceReference`                      | `ResourceTemplateReference`                      |
 | `IsomorphicHeaders`                      | Use Web Standard `Headers`                       |
 | `AuthInfo` (from `server/auth/types.js`) | `AuthInfo` (now re-exported by `@modelcontextprotocol/client` and `@modelcontextprotocol/server`) |
 
 All other types and schemas exported from `@modelcontextprotocol/sdk/types.js` retain their original names — import them from `@modelcontextprotocol/client` or `@modelcontextprotocol/server`.
 
+> **Note on `isJSONRPCResponse`:** v1's `isJSONRPCResponse` was a deprecated alias that only checked for *result* responses (it was equivalent to `isJSONRPCResultResponse`). v2 removes the deprecated alias and introduces a **new** `isJSONRPCResponse` with corrected semantics — it checks for *any* response (either result or error). If you are migrating v1 code that used `isJSONRPCResponse`, rename it to `isJSONRPCResultResponse` to preserve the original behavior. Use the new `isJSONRPCResponse` only when you want to match both result and error responses.
+
 **Before (v1):**
 
 ```typescript

examples/client/src/simpleOAuthClientProvider.ts

@@ -1,4 +1,5 @@
 import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthClientProvider, OAuthTokens } from '@modelcontextprotocol/client';
+import { validateClientMetadataUrl } from '@modelcontextprotocol/client';
 
 /**
  * In-memory OAuth client provider for demonstration purposes
@@ -15,6 +16,9 @@ export class InMemoryOAuthClientProvider implements OAuthClientProvider {
         onRedirect?: (url: URL) => void,
         public readonly clientMetadataUrl?: string
     ) {
+        // Validate clientMetadataUrl at construction time (fail-fast)
+        validateClientMetadataUrl(clientMetadataUrl);
+
         this._onRedirect =
             onRedirect ||
             (url => {

packages/client/src/client/auth.ts

@@ -804,6 +804,28 @@ async function authInternal(
     return 'REDIRECT';
 }
 
+/**
+ * Validates that the given `clientMetadataUrl` is a valid HTTPS URL with a non-root pathname.
+ *
+ * No-op when `url` is `undefined` or empty (providers that do not use URL-based client IDs
+ * are unaffected). When the value is defined but invalid, throws an {@linkcode OAuthError}
+ * with code {@linkcode OAuthErrorCode.InvalidClientMetadata}.
+ *
+ * {@linkcode OAuthClientProvider} implementations that accept a `clientMetadataUrl` should
+ * call this in their constructors for early validation.
+ *
+ * @param url - The `clientMetadataUrl` value to validate (from `OAuthClientProvider.clientMetadataUrl`)
+ * @throws {OAuthError} When `url` is defined but is not a valid HTTPS URL with a non-root pathname
+ */
+export function validateClientMetadataUrl(url: string | undefined): void {
+    if (url && !isHttpsUrl(url)) {
+        throw new OAuthError(
+            OAuthErrorCode.InvalidClientMetadata,
+            `clientMetadataUrl must be a valid HTTPS URL with a non-root pathname, got: ${url}`
+        );
+    }
+}
+
 /**
  * SEP-991: URL-based Client IDs
  * Validate that the `client_id` is a valid URL with `https` scheme

packages/client/src/client/authExtensions.ts

@@ -233,6 +233,16 @@ export interface PrivateKeyJwtProviderOptions {
      * Space-separated scopes values requested by the client.
      */
     scope?: string;
+
+    /**
+     * Optional custom claims to include in the JWT assertion.
+     * These are merged with the standard claims (`iss`, `sub`, `aud`, `exp`, `iat`, `jti`),
+     * with custom claims taking precedence for any overlapping keys.
+     *
+     * Useful for including additional claims that help scope the access token
+     * with finer granularity than what scopes alone allow.
+     */
+    claims?: Record<string, unknown>;
 }
 
 /**
@@ -277,7 +287,8 @@ export class PrivateKeyJwtProvider implements OAuthClientProvider {
             subject: options.clientId,
             privateKey: options.privateKey,
             alg: options.algorithm,
-            lifetimeSeconds: options.jwtLifetimeSeconds
+            lifetimeSeconds: options.jwtLifetimeSeconds,
+            claims: options.claims
         });
     }
 

packages/client/src/index.ts

@@ -34,7 +34,8 @@ export {
     selectClientAuthMethod,
     selectResourceURL,
     startAuthorization,
-    UnauthorizedError
+    UnauthorizedError,
+    validateClientMetadataUrl
 } from './client/auth.js';
 export type {
     AssertionCallback,