@frontmcp/sdk 1.4.1 → 1.5.0

package/transport/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transport/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,yCAAyC,EAAE,MAAM,sCAAsC,CAAC;AACjG,YAAY,EAAE,oCAAoC,EAAE,MAAM,sCAAsC,CAAC;AAEjG,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAC1E,YAAY,EAAE,qCAAqC,EAAE,MAAM,0BAA0B,CAAC;AAGtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAGhE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAE7E,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACrF,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;GAGG;AACH,YAAY,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEtE;;;;GAIG;AACH,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transport/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,yCAAyC,EAAE,MAAM,sCAAsC,CAAC;AACjG,YAAY,EAAE,oCAAoC,EAAE,MAAM,sCAAsC,CAAC;AAEjG,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAC1E,YAAY,EAAE,qCAAqC,EAAE,MAAM,0BAA0B,CAAC;AAGtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAGhE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAE7E,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACrF,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;GAGG;AACH,YAAY,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEtE;;;;GAIG;AACH,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;;;GAIG;AACH,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACnF,YAAY,EACV,eAAe,EACf,4BAA4B,EAC5B,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAE7B;;;;GAIG;AACH,OAAO,EAAE,iBAAiB,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AACtF,YAAY,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAEvF,2EAA2E;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,YAAY,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC"}

package/transport/web-fetch-handler.d.ts

@@ -0,0 +1,106 @@
+import { type Scope } from '../scope/scope.instance';
+import { type WebStandardMcpPair } from './web-standard-mcp';
+/**
+ * The host execution context — its `waitUntil` keeps the worker alive past the
+ * `fetch` return so a streaming (SSE) response body can finish. Optional: in
+ * Node there's no isolate teardown, so it's only needed on V8 isolates.
+ */
+export interface FetchHandlerCtx {
+    waitUntil?(promise: Promise<unknown>): void;
+}
+/** A Web-standard fetch handler: `(request, ctx?, env?) => Promise<Response>`. */
+export type WebFetchHandler = (request: Request, ctx?: FetchHandlerCtx, env?: unknown) => Promise<Response>;
+/**
+ * Routes an MCP request to a stateful session host (a Cloudflare Durable Object)
+ * instead of handling it statelessly. Receives the per-request `env` (for the DO
+ * binding). Returns a `Response` when it routed the request, or `undefined` to
+ * fall through to stateless handling (e.g. the binding isn't present).
+ */
+export type WebFetchSessionRouter = (request: Request, env: unknown, ctx?: FetchHandlerCtx) => Promise<Response | undefined>;
+/**
+ * CORS for the web-fetch adapter — the transport-level analog of the Express
+ * host's `cors` middleware (CORS is an adapter concern, not a flow stage), so a
+ * browser MCP client (e.g. the MCP Inspector in "Direct" mode) can connect.
+ */
+export interface WebFetchCorsOptions {
+    /** Allowed origin: `true` reflects the request `Origin`, `'*'` allows any, or a specific origin / list. */
+    origin?: boolean | string | string[];
+    /** Allowed methods. Default `GET, POST, OPTIONS, DELETE`. */
+    methods?: string[];
+    /** Allowed request headers. Default: reflect `Access-Control-Request-Headers`, else a sensible MCP set. */
+    headers?: string[];
+    /** Response headers exposed to the browser. Default `Mcp-Session-Id, WWW-Authenticate`. */
+    exposeHeaders?: string[];
+    /** Send `Access-Control-Allow-Credentials: true`. Default `false`. */
+    credentials?: boolean;
+    /** `Access-Control-Max-Age` (seconds) on the preflight response. */
+    maxAge?: number;
+}
+export interface CreateWebFetchHandlerOptions {
+    /**
+     * Path the MCP endpoint (both Streamable HTTP `POST` and the SSE `GET`
+     * stream) is served at. **Config-driven**: when omitted, it falls back to the
+     * scope's `http.entryPath` (the same gateway prefix the Express host mounts
+     * under), and to the worker root `/` when that too is unset. So one config
+     * decides the path — set `http.entryPath: '/mcp'` for `<domain>/mcp`, or leave
+     * it for `mcp.<domain>` at root. The worker serves exactly that one path.
+     *
+     * An explicit value here overrides the config. A trailing slash is normalized
+     * (`/mcp/` matches `/mcp`). An array opts into a custom multi-path allow-list.
+     * Requests to any other path (besides {@link
+     * CreateWebFetchHandlerOptions.healthPaths}) get a 404.
+     */
+    entryPath?: string | string[];
+    /**
+     * Paths answered with a liveness/readiness 200 instead of being routed to
+     * the MCP transport. Defaults to `/healthz` and `/readyz`.
+     */
+    healthPaths?: string[];
+    /**
+     * CORS for browser MCP clients (Inspector "Direct" mode, web apps). A
+     * transport-adapter concern, not a flow stage. **Config-driven**: when
+     * omitted, it mirrors the scope's `http.cors` (the same config the Express
+     * host uses), so `@FrontMcp({ http: { cors } })` covers both. An explicit
+     * value here overrides that.
+     */
+    cors?: WebFetchCorsOptions;
+    /**
+     * Optional stateful-session router (Cloudflare Durable Object host). When set,
+     * MCP requests at the entry path are offered to it first; if it returns a
+     * `Response` the request was routed to a session DO, otherwise handling falls
+     * through to the stateless path. CORS / health / entry-path routing stay here
+     * in the adapter regardless.
+     */
+    sessionRouter?: WebFetchSessionRouter;
+}
+/**
+ * Build a Web-standard fetch handler for a Scope.
+ *
+ * @example
+ * ```ts
+ * const handler = createWebFetchHandler(scope);
+ * export default { fetch: (request) => handler(request) };
+ * ```
+ */
+export declare function createWebFetchHandler(scope: Scope, options?: CreateWebFetchHandlerOptions): WebFetchHandler;
+/**
+ * Run a Web `Request` through the `http:request` flow and render its normalized
+ * output to a Web `Response`. Shared by {@link createWebFetchHandler} (stateless)
+ * and the Durable Object session host (which passes its `persistent` transport
+ * so the GET notification stream + server push work). Returns `undefined` when
+ * the flow produced no response (`next`/`handled`) — the caller decides the
+ * fallback (typically 404).
+ */
+export declare function runHttpRequestFlowWeb(scope: Scope, request: Request, opts?: {
+    ctx?: FetchHandlerCtx;
+    persistent?: WebStandardMcpPair;
+}): Promise<Response | undefined>;
+/**
+ * Dispatch a non-entry-path request through the FrontMCP flow that claims it
+ * (auth / well-known / oauth flows match by `middleware.path` + `canActivate`).
+ * Mirrors the Express host's route dispatch for runtimes with no middleware
+ * server (Cloudflare Worker / web-fetch). Returns the rendered Web `Response`,
+ * or `undefined` when no flow matches (caller 404s).
+ */
+export declare function runMatchingHttpFlowWeb(scope: Scope, request: Request): Promise<Response | undefined>;
+//# sourceMappingURL=web-fetch-handler.d.ts.map

package/transport/web-fetch-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch-handler.d.ts","sourceRoot":"","sources":["../../src/transport/web-fetch-handler.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE5G;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,OAAO,EACZ,GAAG,CAAC,EAAE,eAAe,KAClB,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,2GAA2G;IAC3G,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;IACrC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,2GAA2G;IAC3G,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAqBD,MAAM,WAAW,4BAA4B;IAC3C;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,4BAAiC,GAAG,eAAe,CA6G/G;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,eAAe,CAAC;IAAC,UAAU,CAAC,EAAE,kBAAkB,CAAA;CAAO,GACpE,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAa/B;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAe1G"}

package/transport/web-response.renderer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Render a normalized {@link HttpOutput} (the `http:request` flow's output) to a
+ * Web `Response`. This is the web-fetch (worker) analog of the Node
+ * `writeHttpResponse` renderer — it lets a V8-isolate adapter run the SAME flow
+ * every other transport runs and render its normalized result, instead of
+ * bypassing the pipeline.
+ *
+ * Returns `undefined` for outputs that mean "no response produced" (`next`,
+ * `consumed`) so the caller can fall through (e.g. to a 404).
+ */
+import { type HttpOutput } from '../common/schemas/http-output.schema';
+export declare function renderHttpOutputToWebResponse(output: HttpOutput): Response | undefined;
+//# sourceMappingURL=web-response.renderer.d.ts.map

package/transport/web-response.renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-response.renderer.d.ts","sourceRoot":"","sources":["../../src/transport/web-response.renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAyDvE,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,CAmDtF"}

package/transport/web-standard-mcp.d.ts

@@ -0,0 +1,63 @@
+/**
+ * MCP-over-web-standard-transport adapter used by the `handleWebFetch` execute
+ * stage of the `http:request` flow (V8 isolates / Cloudflare Workers).
+ *
+ * Two modes, both speaking the SAME `WebStandardStreamableHTTPServerTransport`:
+ *
+ * - **Stateless** ({@link runWebStandardMcp} with no `persistent`): a fresh
+ *   `McpServer` + transport per request (`sessionIdGenerator: undefined`). The
+ *   default serverless model.
+ * - **Stateful** (a Durable Object passes `persistent`): one persistent
+ *   `McpServer` + session-bound transport built once via {@link
+ *   buildPersistentWebStandardMcp} and reused across the session's requests, so
+ *   the standalone GET notification stream stays open and a `tools/call`'s
+ *   notifications reach it. The DO owns the lifecycle — no per-request teardown.
+ *
+ * Auth / quota / router / audit / metrics + hooks have already run in the flow
+ * around this call; this only translates the MCP request↔response.
+ */
+import { type AuthInfo } from '@frontmcp/protocol';
+import { type Scope } from '../scope/scope.instance';
+import { type ScopedServerOptions } from './build-scoped-server-options';
+/** A persistent MCP server + transport bound to one session (Durable Object). */
+export interface WebStandardMcpPair {
+    mcpServer: {
+        close(): Promise<void>;
+    };
+    transport: {
+        handleRequest(request: Request, options?: {
+            authInfo?: AuthInfo;
+        }): Promise<Response>;
+        onclose?: () => void;
+    };
+}
+export interface RunWebStandardMcpOptions {
+    /** Capability/server options for the `McpServer` (from `buildScopedServerOptions`). */
+    serverOptions: ScopedServerOptions;
+    /** Verified auth info to expose to handlers (derived from the flow's session:verify result). */
+    authInfo?: Partial<AuthInfo>;
+    /** Allow SSE streaming responses on POST when the client accepts `text/event-stream` (stateless mode). */
+    sse: boolean;
+    /** Worker `ExecutionContext` so an SSE body can keep the isolate alive past `fetch` (stateless mode). */
+    ctx?: {
+        waitUntil?(promise: Promise<unknown>): void;
+    };
+    /**
+     * A persistent, session-bound server+transport (Durable Object / stateful
+     * sessions). When provided, the request is handled on it and no fresh server
+     * is created or torn down — the DO owns its lifecycle.
+     */
+    persistent?: WebStandardMcpPair;
+}
+/**
+ * Build a persistent, session-bound MCP server + transport for a Durable Object.
+ * Stateful (`sessionIdGenerator: () => sessionId`) and streaming-capable
+ * (`enableJsonResponse: false`) so the standalone GET notification stream and
+ * server-initiated notifications work. Call once per session; the DO keeps it
+ * alive and passes it back via `RunWebStandardMcpOptions.persistent`.
+ */
+export declare function buildPersistentWebStandardMcp(scope: Scope, options: {
+    sessionId: string;
+}): Promise<WebStandardMcpPair>;
+export declare function runWebStandardMcp(scope: Scope, request: Request, options: RunWebStandardMcpOptions): Promise<Response>;
+//# sourceMappingURL=web-standard-mcp.d.ts.map

package/transport/web-standard-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-standard-mcp.d.ts","sourceRoot":"","sources":["../../src/transport/web-standard-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEnG,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE;QAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IACtC,SAAS,EAAE;QACT,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;YAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;SAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtF,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;KACtB,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,uFAAuF;IACvF,aAAa,EAAE,mBAAmB,CAAC;IACnC,gGAAgG;IAChG,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7B,0GAA0G;IAC1G,GAAG,EAAE,OAAO,CAAC;IACb,yGAAyG;IACzG,GAAG,CAAC,EAAE;QAAE,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC;IACtD;;;;OAIG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AA+BD;;;;;;GAMG;AACH,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAG7B;AAED,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CA4CnB"}