@dereekb/firebase-server 13.36.0 → 13.37.0

package/mcp/src/lib/controller/mcp.wellknown.controller.d.ts

@@ -12,7 +12,8 @@ export interface OAuthProtectedResourceMetadata {
     /**
      * Scopes the resource accepts (RFC 9728 §2). Advertised so dynamic-registration
      * MCP clients (e.g. the Claude Code CLI) know which scopes to request on the
-     * authorization call. Omitted when {@link McpModuleConfig.scopesSupported} is unset.
+     * authorization call — they request this list verbatim, so it carries only scopes
+     * such a client can actually be granted. Omitted when the resolved list is empty.
      */
     readonly scopes_supported?: ReadonlyArray<OidcScope>;
 }
@@ -25,10 +26,29 @@ export interface OAuthProtectedResourceMetadata {
  * URIs must live at the host root. Apps need to exclude `.well-known/{*path}`
  * from any global API route prefix (see `FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE`
  * in `firebase-server/oidc` for the corresponding OIDC excludes).
+ *
+ * Because the document must be reachable at the origin root, the MCP endpoint has to be
+ * exposed through a host that serves the app at `/` — Firebase Hosting, or the hosting
+ * emulator in development. Pointing a client straight at the Functions emulator origin
+ * (`http://localhost:<port>/<project>/<region>/<function>/mcp`) breaks discovery: that
+ * runtime only routes `/<project>/<region>/<function>/…`, so nothing answers at the root
+ * and a client that has not yet seen a 401 challenge cannot find the issuer.
  */
 export declare class McpWellKnownController {
     private readonly mcpConfig;
     private readonly oidcProviderConfigService;
     constructor(mcpConfig: McpModuleConfig, oidcProviderConfigService: OidcProviderConfigService);
+    /**
+     * Serves both RFC 9728 discovery URLs — the primary form (§3.1), which inserts the resource's
+     * path after the well-known prefix (`/.well-known/oauth-protected-resource/mcp`), and the bare
+     * form (`/.well-known/oauth-protected-resource`) that clients probe as a fallback.
+     *
+     * The document is identical either way; the resource identity comes from
+     * {@link McpModuleConfig.mcpUrl}, not from the request path. Serving the primary form means
+     * discovery succeeds on a client's first probe rather than depending on it implementing the
+     * fallback.
+     *
+     * @returns The protected-resource metadata document.
+     */
     getProtectedResourceMetadata(): OAuthProtectedResourceMetadata;
 }

package/mcp/src/lib/mcp.config.d.ts

@@ -83,8 +83,9 @@ export interface McpReasonParameterConfig {
 /**
  * Filter applied to the OIDC provider's advertised scope list when building the MCP
  * protected-resource metadata's `scopes_supported`. Receives every scope the provider
- * issues (from `OidcProviderConfigService.scopesSupported`) and returns the subset to
- * advertise. Supplied via {@link McpModuleConfig.scopesSupported}; when unset, all are advertised.
+ * issues to an arbitrary client (from `OidcProviderConfigService.clientRequestableScopesSupported`)
+ * and returns the subset to advertise. Supplied via {@link McpModuleConfig.scopesSupported};
+ * when unset, all of them are advertised.
  */
 export type McpScopesSupportedFilter = (allScopes: readonly OidcScope[]) => readonly OidcScope[];
 /**
@@ -127,11 +128,12 @@ export declare abstract class McpModuleConfig {
      * protected-resource discovery document's `scopes_supported` (RFC 9728 §2).
      *
      * The base list is pulled automatically from the OIDC provider config via the
-     * injected {@link OidcProviderConfigService.scopesSupported} (i.e.
-     * `Object.keys(providerConfig.claims)`), so the MCP resource advertises exactly
-     * the scopes the issuer supports without the app restating them. Provide this
-     * only to narrow that set — it receives every scope the provider issues and
-     * returns the subset to advertise. When unset, all of them are advertised.
+     * injected {@link OidcProviderConfigService.clientRequestableScopesSupported}, so
+     * the MCP resource advertises the scopes the issuer grants an arbitrary client
+     * without the app restating them. Scopes only an admin-assigned provider profile
+     * unlocks are already excluded — requesting one is fatal at the consent unlock
+     * gate. Provide this only to narrow the set further; it returns the subset to
+     * advertise. When unset, the whole base list is advertised.
      *
      * Advertising these matters because dynamic-registration MCP clients (the Claude
      * Code CLI) read `scopes_supported` to decide which scopes to request on the

package/mcp/src/lib/mcp.module.d.ts

@@ -17,7 +17,8 @@ export interface McpModuleMetadataConfig extends Pick<ModuleMetadata, 'imports'
      * - {@link ModelApiDispatchConfig} — so the MCP server can reuse the call model dispatch chain.
      * - {@link McpModuleConfig} — issuer + resource URLs for protected-resource discovery.
      * - `OidcProviderConfigService` (from `@dereekb/firebase-server/oidc`) — the `McpWellKnownController`
-     *   reads the provider's `scopesSupported` to advertise them on the protected-resource document.
+     *   reads the provider's `clientRequestableScopesSupported` to advertise them on the
+     *   protected-resource document.
      *
      * In practice, downstream apps typically import their own `*ModelApiModule` first (which provides
      * `ModelApiCallModelDispatchService` + `MODEL_API_NEST_APPLICATION_CONTEXT`) and add the

package/mcp/src/lib/service/mcp.server.factory.d.ts

@@ -1,4 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import { type Request } from 'express';
 import { ModelApiCallModelDispatchService, ModelApiGetService, FirebaseServerStorageService, type FirebaseServerAuthData } from '@dereekb/firebase-server';
 import { McpModuleConfig, type McpAuthRoleReader } from '../mcp.config';
@@ -17,9 +17,10 @@ export interface McpRequestContext {
  * Injectable factory that builds {@link McpServer} instances pre-wired to the
  * call model dispatch chain.
  *
- * The factory is invoked per Streamable HTTP request — `@modelcontextprotocol/sdk`
- * recommends a fresh `McpServer` + transport pair per stateless JSON-RPC request,
- * which sidesteps session bookkeeping for the common Claude-connector case.
+ * The factory is invoked per Streamable HTTP request. That is the shape the MCP
+ * SDK's 2026-07-28 entry (`createMcpHandler`) requires — it builds a fresh server
+ * per request and has no session concept at all — and it is equally what the SDK
+ * recommends for stateless 2025-era serving, so one factory backs both eras.
  */
 export declare class McpServerFactoryService {
     private readonly mcpConfig;

package/mcp/src/lib/service/mcp.tool-generator.d.ts

@@ -2,7 +2,7 @@ import { type Maybe } from '@dereekb/util';
 import { type FirestoreModelType, type KnownOnCallFunctionType, type OidcModelScopeRequirement, type OidcScopeTerm } from '@dereekb/firebase';
 import { type ModelApiDetailsResult, type OnCallModelFunctionApiDetails, type FirebaseServerAuthData, type McpToolDetailsBuilder, type McpVisibilityRule } from '@dereekb/firebase-server';
 import { type Request } from 'express';
-import { type CallToolResult, type ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/server';
 import { type McpManifestToolEntry } from './mcp.manifest';
 import { type McpToolFilterMetadata } from './mcp.visibility';
 /**

package/mcp/src/lib/service/mcp.visibility.d.ts

@@ -1,7 +1,7 @@
 import { type Maybe } from '@dereekb/util';
 import { type CallModelOidcScope, type OidcScopeTerm } from '@dereekb/firebase';
 import { type McpToolVisibility, type McpVisibilityContext, type McpVisibilityRule } from '@dereekb/firebase-server';
-import { type ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolAnnotations } from '@modelcontextprotocol/server';
 /**
  * Normalized classification of a {@link McpToolVisibility} value computed at boot.
  *

package/mcp/src/lib/transport/streamable-http.transport.d.ts

@@ -1,21 +1,26 @@
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { type McpServer } from '@modelcontextprotocol/server';
 import { type Request, type Response } from 'express';
 /**
- * Handles a single Streamable HTTP JSON-RPC request against the supplied MCP server.
+ * Handles a single Streamable HTTP JSON-RPC request, building a fresh MCP server for it.
  *
- * Each call creates a fresh `StreamableHTTPServerTransport` in stateless mode — the
- * transport binds the server, processes one request, and is discarded. Stateless
- * mode is adequate for Claude custom-connector usage and avoids the bookkeeping
- * cost of session-tracked transports for the common case.
+ * Both protocol eras are served, each by its own leg:
+ *
+ * - **2026-07-28 (modern)** — `createMcpHandler`, which is per-request and stateless by
+ *   construction: there is no `Mcp-Session-Id` and no transport bookkeeping.
+ * - **2025-era (legacy)** — a `NodeStreamableHTTPServerTransport` in stateless mode, which is
+ *   byte-for-byte what this endpoint served before the SDK v2 upgrade.
+ *
+ * The legacy leg is wired by hand (the SDK's documented `isLegacyRequest` composition) rather
+ * than left to `createMcpHandler`'s built-in `legacy: 'stateless'` fallback, because that
+ * fallback builds its transport with `sessionIdGenerator` alone and therefore answers in
+ * `text/event-stream`. See {@link handleLegacyMcpRequest} for why that framing is not viable
+ * here.
  *
  * The caller is expected to have already validated the bearer token (via the
  * OIDC bearer middleware) before this function runs.
  *
  * @param req - The Express request carrying the JSON-RPC body.
  * @param res - The Express response.
- * @param server - The MCP server instance to back the transport.
- * @param server.connect - The MCP server's connect method that binds the transport before request handling.
+ * @param buildServer - Factory producing the MCP server that backs this request.
  */
-export declare function handleStreamableHttpMcpRequest(req: Request, res: Response, server: {
-    connect: (transport: StreamableHTTPServerTransport) => Promise<void>;
-}): Promise<void>;
+export declare function handleStreamableHttpMcpRequest(req: Request, res: Response, buildServer: () => McpServer): Promise<void>;

package/model/index.cjs.js

@@ -14770,7 +14770,7 @@ function enrichSignedUploadUrlInputSchema(defaultInputSchema, purposeKeys) {
     if (defaultInputSchema != null && (typeof defaultInputSchema === "undefined" ? "undefined" : _type_of$3(defaultInputSchema)) === 'object') {
         var _base_properties;
         var base = defaultInputSchema;
-        var purposeProperty = (_base_properties = base.properties) === null || _base_properties === void 0 ? void 0 : _base_properties.purpose;
+        var purposeProperty = (_base_properties = base.properties) === null || _base_properties === void 0 ? void 0 : _base_properties['purpose'];
         if (purposeProperty != null && (typeof purposeProperty === "undefined" ? "undefined" : _type_of$3(purposeProperty)) === 'object') {
             var quotedPurposes = purposeKeys.map(function(purpose) {
                 return '"'.concat(purpose, '"');

package/model/index.esm.js

@@ -14768,7 +14768,7 @@ function enrichSignedUploadUrlInputSchema(defaultInputSchema, purposeKeys) {
     if (defaultInputSchema != null && (typeof defaultInputSchema === "undefined" ? "undefined" : _type_of$3(defaultInputSchema)) === 'object') {
         var _base_properties;
         var base = defaultInputSchema;
-        var purposeProperty = (_base_properties = base.properties) === null || _base_properties === void 0 ? void 0 : _base_properties.purpose;
+        var purposeProperty = (_base_properties = base.properties) === null || _base_properties === void 0 ? void 0 : _base_properties['purpose'];
         if (purposeProperty != null && (typeof purposeProperty === "undefined" ? "undefined" : _type_of$3(purposeProperty)) === 'object') {
             var quotedPurposes = purposeKeys.map(function(purpose) {
                 return '"'.concat(purpose, '"');

package/model/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.36.0",
+  "version": "13.37.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.36.0",
-    "@dereekb/date": "13.36.0",
-    "@dereekb/firebase": "13.36.0",
-    "@dereekb/firebase-server": "13.36.0",
-    "@dereekb/model": "13.36.0",
-    "@dereekb/nestjs": "13.36.0",
-    "@dereekb/rxjs": "13.36.0",
-    "@dereekb/util": "13.36.0",
+    "@dereekb/analytics": "13.37.0",
+    "@dereekb/date": "13.37.0",
+    "@dereekb/firebase": "13.37.0",
+    "@dereekb/firebase-server": "13.37.0",
+    "@dereekb/model": "13.37.0",
+    "@dereekb/nestjs": "13.37.0",
+    "@dereekb/rxjs": "13.37.0",
+    "@dereekb/util": "13.37.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",