@orkestrel/mcp 0.0.9 → 0.0.11

package/dist/src/server/index.d.cts

@@ -14,6 +14,7 @@ import { MCPTransportInterface } from '../core/index.ts';
 import { MCPVersion } from '../core/index.ts';
 import { MiddlewareHandler } from '@orkestrel/server';
 import { NodeWebSocketInterface } from '@orkestrel/websocket';
+import { RouteContext } from '@orkestrel/router';
 import { RouteInput } from '@orkestrel/router';
 import { StreamInterface } from '@orkestrel/server';
 import { UpgradeHandler } from '@orkestrel/server';
@@ -140,10 +141,13 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  * explicitly delegated upstream. Modern dispatch errors use their protocol status map; legacy
  * errors remain in-band at HTTP `200`. A streamed response composes the fetch-standard request
  * signal with response-body cancellation and supplies the result to every dispatched modern
- * handler through `MCPDispatchOptions.signal`.
+ * handler through `MCPDispatchOptions.signal`. After every transport validation and immediately
+ * before dispatch, the optional synchronous `caller` extractor reads front-middleware state; a
+ * defined value is added to `MCPDispatchOptions`, while `undefined` is omitted.
  *
+ * @typeParam TState - The consumer's opaque per-request route state type
  * @param mcp - The transport-agnostic MCP server to dispatch through
- * @param options - Optional streaming, origin-validation, and SSE keepalive options
+ * @param options - Optional streaming, origin-validation, SSE keepalive, and caller-extraction options
  * @returns A request handler for the stateless MCP POST route
  *
  * @example
@@ -160,11 +164,7 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  * }))
  * ```
  */
-export declare function createMCPPostHandler(mcp: MCPServerInterface, options?: {
-    readonly streaming?: boolean;
-    readonly origin?: MCPOriginOptions;
-    readonly keepalive?: MCPKeepaliveOptions;
-}): (request: Request) => Promise<Response>;
+export declare function createMCPPostHandler<TState = unknown>(mcp: MCPServerInterface, options?: HTTPHandlerOptions<TState>): (request: Request, context?: RouteContext<string, TState>) => Promise<Response>;
 
 /**
  * Create the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
@@ -207,7 +207,7 @@ export declare function createMCPPostHandler(mcp: MCPServerInterface, options?:
  * @typeParam TState - The consumer's opaque per-request state type
  * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over HTTP
  * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `streaming`
- *   (default `true`), plus the shared `origin` validation options; see
+ *   (default `true`), plus shared origin, keepalive, and synchronous caller-extraction options; see
  *   {@link HTTPTransportOptions}
  * @returns The {@link RouteInput}s to register with the router
  *
@@ -220,7 +220,7 @@ export declare function createMCPPostHandler(mcp: MCPServerInterface, options?:
  * const routes = createMCPRoutes(mcp) // POST /mcp dispatches JSON-RPC (JSON or SSE per Accept)
  * ```
  */
-export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterface, options?: HTTPTransportOptions): readonly RouteInput<string, TState>[];
+export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterface, options?: HTTPTransportOptions<TState>): readonly RouteInput<string, TState>[];
 
 /**
  * Create the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
@@ -631,16 +631,9 @@ export declare interface HTTPClientTransportOptions {
 }
 
 /**
- * Options for `createMCPRoutes` — the path the transport is mounted at and whether an SSE
- * response is allowed. `createMCPRoutes` is STATELESS; sessions are a separate middleware
- * ({@link import('./middlewares.js').createMCPSession}), composed via `server.use`.
+ * Options shared by the MCP Streamable-HTTP POST handler and route factory.
  *
  * @remarks
- * - `path` — the request path the single `POST` route answers; defaults to
- *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`). `GET` / `DELETE` to this
- *   path get the spine's automatic `405` unless a {@link
- *   import('./middlewares.js').createMCPSession} middleware (which owns the same `path`) is
- *   mounted IN FRONT to serve them.
  * - `streaming` — when `true` (the DEFAULT) the transport MAY answer with a
  *   Server-Sent-Events response (one `data:` event carrying the JSON-RPC reply, then
  *   the stream ends) whenever the client's `Accept` header includes
@@ -656,13 +649,32 @@ export declare interface HTTPClientTransportOptions {
  * - `keepalive` — the SSE liveness options for held-open responses. `interval` defaults to
  *   {@link import('./constants.js').DEFAULT_MCP_KEEPALIVE_INTERVAL}. Keepalives never apply
  *   to unary responses.
+ * - `caller` — the synchronous extractor for consumer-asserted caller context already resolved
+ *   by front middleware. It runs only for a validated request that will dispatch. Returning
+ *   `undefined` omits caller context; a throw propagates.
  */
-export declare interface HTTPTransportOptions {
-    readonly path?: string;
+export declare interface HTTPHandlerOptions<TState = unknown> {
     readonly streaming?: boolean;
     /** Must match the session layer's value; `origins` is ignored when `enabled` is `false`. */
     readonly origin?: MCPOriginOptions;
     readonly keepalive?: MCPKeepaliveOptions;
+    readonly caller?: MCPCallerHandler<TState>;
+}
+
+/**
+ * Options for `createMCPRoutes` — the mount path plus the shared POST-handler options.
+ * `createMCPRoutes` is STATELESS; sessions are a separate middleware ({@link
+ * import('./middlewares.js').createMCPSession}), composed via `server.use`.
+ *
+ * @remarks
+ * `path` is the request path the single `POST` route answers; it defaults to {@link
+ * import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`). `GET` / `DELETE` to this path get
+ * the spine's automatic `405` unless a {@link import('./middlewares.js').createMCPSession}
+ * middleware owning the same path is mounted in front. The remaining options are inherited
+ * from {@link HTTPHandlerOptions}.
+ */
+export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHandlerOptions<TState> {
+    readonly path?: string;
 }
 
 /**
@@ -759,6 +771,23 @@ export declare const MCP_SESSION_HEADER = "mcp-session-id";
  */
 export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
 
+/**
+ * Synchronously extract consumer-asserted caller context from an HTTP request after the
+ * transport has validated it for dispatch.
+ *
+ * @remarks
+ * Authentication belongs to middleware composed in front of the MCP route. This handler only
+ * reads what that middleware already resolved. Returning `undefined` supplies no caller; a
+ * throw propagates as a route-handler throw. The result remains `unknown` because this package
+ * cannot verify caller identity.
+ *
+ * @typeParam TState - The consumer's opaque per-request route state type
+ * @param request - The validated Fetch request that will dispatch
+ * @param context - The router context, or `undefined` for direct handler invocation
+ * @returns Consumer-asserted caller context, or `undefined` for no caller
+ */
+export declare type MCPCallerHandler<TState = unknown> = (request: Request, context: RouteContext<string, TState> | undefined) => unknown;
+
 /**
  * Shared SSE keepalive options for held-open HTTP responses.
  *

package/dist/src/server/index.d.ts

@@ -14,6 +14,7 @@ import { MCPTransportInterface } from '../core/index.ts';
 import { MCPVersion } from '../core/index.ts';
 import { MiddlewareHandler } from '@orkestrel/server';
 import { NodeWebSocketInterface } from '@orkestrel/websocket';
+import { RouteContext } from '@orkestrel/router';
 import { RouteInput } from '@orkestrel/router';
 import { StreamInterface } from '@orkestrel/server';
 import { UpgradeHandler } from '@orkestrel/server';
@@ -140,10 +141,13 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  * explicitly delegated upstream. Modern dispatch errors use their protocol status map; legacy
  * errors remain in-band at HTTP `200`. A streamed response composes the fetch-standard request
  * signal with response-body cancellation and supplies the result to every dispatched modern
- * handler through `MCPDispatchOptions.signal`.
+ * handler through `MCPDispatchOptions.signal`. After every transport validation and immediately
+ * before dispatch, the optional synchronous `caller` extractor reads front-middleware state; a
+ * defined value is added to `MCPDispatchOptions`, while `undefined` is omitted.
  *
+ * @typeParam TState - The consumer's opaque per-request route state type
  * @param mcp - The transport-agnostic MCP server to dispatch through
- * @param options - Optional streaming, origin-validation, and SSE keepalive options
+ * @param options - Optional streaming, origin-validation, SSE keepalive, and caller-extraction options
  * @returns A request handler for the stateless MCP POST route
  *
  * @example
@@ -160,11 +164,7 @@ export declare function createHTTPClientTransport(options: HTTPClientTransportOp
  * }))
  * ```
  */
-export declare function createMCPPostHandler(mcp: MCPServerInterface, options?: {
-    readonly streaming?: boolean;
-    readonly origin?: MCPOriginOptions;
-    readonly keepalive?: MCPKeepaliveOptions;
-}): (request: Request) => Promise<Response>;
+export declare function createMCPPostHandler<TState = unknown>(mcp: MCPServerInterface, options?: HTTPHandlerOptions<TState>): (request: Request, context?: RouteContext<string, TState>) => Promise<Response>;
 
 /**
  * Create the MCP Streamable-HTTP transport routes — mounts a transport-agnostic
@@ -207,7 +207,7 @@ export declare function createMCPPostHandler(mcp: MCPServerInterface, options?:
  * @typeParam TState - The consumer's opaque per-request state type
  * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over HTTP
  * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `streaming`
- *   (default `true`), plus the shared `origin` validation options; see
+ *   (default `true`), plus shared origin, keepalive, and synchronous caller-extraction options; see
  *   {@link HTTPTransportOptions}
  * @returns The {@link RouteInput}s to register with the router
  *
@@ -220,7 +220,7 @@ export declare function createMCPPostHandler(mcp: MCPServerInterface, options?:
  * const routes = createMCPRoutes(mcp) // POST /mcp dispatches JSON-RPC (JSON or SSE per Accept)
  * ```
  */
-export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterface, options?: HTTPTransportOptions): readonly RouteInput<string, TState>[];
+export declare function createMCPRoutes<TState = unknown>(mcp: MCPServerInterface, options?: HTTPTransportOptions<TState>): readonly RouteInput<string, TState>[];
 
 /**
  * Create the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
@@ -631,16 +631,9 @@ export declare interface HTTPClientTransportOptions {
 }
 
 /**
- * Options for `createMCPRoutes` — the path the transport is mounted at and whether an SSE
- * response is allowed. `createMCPRoutes` is STATELESS; sessions are a separate middleware
- * ({@link import('./middlewares.js').createMCPSession}), composed via `server.use`.
+ * Options shared by the MCP Streamable-HTTP POST handler and route factory.
  *
  * @remarks
- * - `path` — the request path the single `POST` route answers; defaults to
- *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`). `GET` / `DELETE` to this
- *   path get the spine's automatic `405` unless a {@link
- *   import('./middlewares.js').createMCPSession} middleware (which owns the same `path`) is
- *   mounted IN FRONT to serve them.
  * - `streaming` — when `true` (the DEFAULT) the transport MAY answer with a
  *   Server-Sent-Events response (one `data:` event carrying the JSON-RPC reply, then
  *   the stream ends) whenever the client's `Accept` header includes
@@ -656,13 +649,32 @@ export declare interface HTTPClientTransportOptions {
  * - `keepalive` — the SSE liveness options for held-open responses. `interval` defaults to
  *   {@link import('./constants.js').DEFAULT_MCP_KEEPALIVE_INTERVAL}. Keepalives never apply
  *   to unary responses.
+ * - `caller` — the synchronous extractor for consumer-asserted caller context already resolved
+ *   by front middleware. It runs only for a validated request that will dispatch. Returning
+ *   `undefined` omits caller context; a throw propagates.
  */
-export declare interface HTTPTransportOptions {
-    readonly path?: string;
+export declare interface HTTPHandlerOptions<TState = unknown> {
     readonly streaming?: boolean;
     /** Must match the session layer's value; `origins` is ignored when `enabled` is `false`. */
     readonly origin?: MCPOriginOptions;
     readonly keepalive?: MCPKeepaliveOptions;
+    readonly caller?: MCPCallerHandler<TState>;
+}
+
+/**
+ * Options for `createMCPRoutes` — the mount path plus the shared POST-handler options.
+ * `createMCPRoutes` is STATELESS; sessions are a separate middleware ({@link
+ * import('./middlewares.js').createMCPSession}), composed via `server.use`.
+ *
+ * @remarks
+ * `path` is the request path the single `POST` route answers; it defaults to {@link
+ * import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`). `GET` / `DELETE` to this path get
+ * the spine's automatic `405` unless a {@link import('./middlewares.js').createMCPSession}
+ * middleware owning the same path is mounted in front. The remaining options are inherited
+ * from {@link HTTPHandlerOptions}.
+ */
+export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHandlerOptions<TState> {
+    readonly path?: string;
 }
 
 /**
@@ -759,6 +771,23 @@ export declare const MCP_SESSION_HEADER = "mcp-session-id";
  */
 export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
 
+/**
+ * Synchronously extract consumer-asserted caller context from an HTTP request after the
+ * transport has validated it for dispatch.
+ *
+ * @remarks
+ * Authentication belongs to middleware composed in front of the MCP route. This handler only
+ * reads what that middleware already resolved. Returning `undefined` supplies no caller; a
+ * throw propagates as a route-handler throw. The result remains `unknown` because this package
+ * cannot verify caller identity.
+ *
+ * @typeParam TState - The consumer's opaque per-request route state type
+ * @param request - The validated Fetch request that will dispatch
+ * @param context - The router context, or `undefined` for direct handler invocation
+ * @returns Consumer-asserted caller context, or `undefined` for no caller
+ */
+export declare type MCPCallerHandler<TState = unknown> = (request: Request, context: RouteContext<string, TState> | undefined) => unknown;
+
 /**
  * Shared SSE keepalive options for held-open HTTP responses.
  *

package/dist/src/server/index.js

@@ -542,10 +542,13 @@ var HTTPDisconnect = class {
 * explicitly delegated upstream. Modern dispatch errors use their protocol status map; legacy
 * errors remain in-band at HTTP `200`. A streamed response composes the fetch-standard request
 * signal with response-body cancellation and supplies the result to every dispatched modern
-* handler through `MCPDispatchOptions.signal`.
+* handler through `MCPDispatchOptions.signal`. After every transport validation and immediately
+* before dispatch, the optional synchronous `caller` extractor reads front-middleware state; a
+* defined value is added to `MCPDispatchOptions`, while `undefined` is omitted.
 *
+* @typeParam TState - The consumer's opaque per-request route state type
 * @param mcp - The transport-agnostic MCP server to dispatch through
-* @param options - Optional streaming, origin-validation, and SSE keepalive options
+* @param options - Optional streaming, origin-validation, SSE keepalive, and caller-extraction options
 * @returns A request handler for the stateless MCP POST route
 *
 * @example
@@ -565,7 +568,7 @@ var HTTPDisconnect = class {
 function createMCPPostHandler(mcp, options) {
 	const streaming = options?.streaming ?? true;
 	const origin = options?.origin;
-	return async (request) => {
+	return async (request, context) => {
 		if (!allowsOrigin(request, origin)) return new Response(null, { status: 403 });
 		let text;
 		try {
@@ -595,7 +598,11 @@ function createMCPPostHandler(mcp, options) {
 			}), { status: 400 });
 		}
 		const disconnect = new HTTPDisconnect(request.signal, options?.keepalive);
-		const response = await mcp.dispatch(rpcRequest, { signal: disconnect.signal });
+		const caller = options?.caller?.(request, context);
+		const response = await mcp.dispatch(rpcRequest, {
+			signal: disconnect.signal,
+			...caller === void 0 ? {} : { caller }
+		});
 		if (response !== void 0 && Symbol.asyncIterator in response) {
 			const stream = openStream();
 			stream.response.headers.set(SSE_BUFFERING_HEADER, "no");
@@ -1307,7 +1314,7 @@ var StdioServerTransport = class {
 * @typeParam TState - The consumer's opaque per-request state type
 * @param mcp - The transport-agnostic {@link MCPServerInterface} to expose over HTTP
 * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}) and `streaming`
-*   (default `true`), plus the shared `origin` validation options; see
+*   (default `true`), plus shared origin, keepalive, and synchronous caller-extraction options; see
 *   {@link HTTPTransportOptions}
 * @returns The {@link RouteInput}s to register with the router
 *