@rekog/mcp-nest 1.9.10 → 2.0.0-alpha.1

package/src/mcp/transport/resource-matcher.ts

@@ -0,0 +1,107 @@
+import { match } from 'path-to-regexp';
+
+/** Strips the scheme (`mcp://foo` -> `foo`). */
+function stripScheme(uri: string): string {
+  return uri.includes('://') ? uri.split('://')[1] : uri;
+}
+
+/**
+ * RFC 6570 template -> path-to-regexp (v8) path:
+ * - drop the `{?query}` form,
+ * - turn a catch-all `{path*}` into a wildcard `*path` (matches one or more
+ *   segments across `/`),
+ * - turn a single `{p}` into `:p` (one segment).
+ *
+ * The catch-all rule MUST run before the single-param rule: `{(\w+)}` can't
+ * match `{path*}` (the `*` sits between `\w+` and `}`), which is the bug that
+ * previously left `{path*}` untouched so it never matched.
+ */
+function convertTemplate(template: string): string {
+  if (!template) return template;
+  return template
+    .replace(/\{\?[^}]+\}/g, '')
+    .replace(/\{(\w+)\*\}/g, '*$1')
+    .replace(/\{(\w+)\}/g, ':$1');
+}
+
+/**
+ * path-to-regexp v8 returns wildcard (`*path`) params as an array of segments,
+ * while named (`:id`) params come back as strings. Join wildcard arrays with
+ * `/` so a `{path*}` template hands the handler a single string
+ * (e.g. `docs/readme.md`), preserving the documented contract.
+ */
+function flattenParams(
+  params: Partial<Record<string, string | string[]>>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    out[key] = Array.isArray(value) ? value.join('/') : value;
+  }
+  return out;
+}
+
+function extractTemplateQueryParams(template: string): string[] {
+  const m = template.match(/\{\?([^}]+)\}/);
+  return m ? m[1].split(',').map((p) => p.trim()) : [];
+}
+
+function parseQueryString(uri: string): Record<string, string> {
+  const i = uri.indexOf('?');
+  if (i === -1) return {};
+  const params: Record<string, string> = {};
+  for (const pair of uri.substring(i + 1).split('&')) {
+    const [k, v] = pair.split('=');
+    if (k) params[decodeURIComponent(k)] = v ? decodeURIComponent(v) : '';
+  }
+  return params;
+}
+
+function stripQueryString(uri: string): string {
+  const i = uri.indexOf('?');
+  return i === -1 ? uri : uri.substring(0, i);
+}
+
+/** Finds a static resource whose URI matches `inputUri`, extracting any path params. */
+export function matchResourceByUri<T extends { uri?: string }>(
+  resources: T[],
+  inputUri: string,
+): { resource: T; params: Record<string, string> } | undefined {
+  const input = stripScheme(inputUri);
+  for (const resource of resources) {
+    if (!resource.uri) continue;
+    const matcher = match(convertTemplate(stripScheme(resource.uri)), {
+      decode: decodeURIComponent,
+    });
+    const result = matcher(input);
+    if (result) {
+      return { resource, params: flattenParams(result.params) };
+    }
+  }
+  return undefined;
+}
+
+/** Finds a resource template matching `inputUri`, extracting path + declared query params. */
+export function matchResourceTemplateByUri<T extends { uriTemplate?: string }>(
+  templates: T[],
+  inputUri: string,
+): { template: T; params: Record<string, string> } | undefined {
+  const input = stripQueryString(stripScheme(inputUri));
+  const inputQuery = parseQueryString(inputUri);
+  for (const template of templates) {
+    if (!template.uriTemplate) continue;
+    const matcher = match(convertTemplate(stripScheme(template.uriTemplate)), {
+      decode: decodeURIComponent,
+    });
+    const result = matcher(input);
+    if (result) {
+      const params = flattenParams(result.params);
+      const query: Record<string, string> = {};
+      for (const name of extractTemplateQueryParams(template.uriTemplate)) {
+        if (inputQuery[name] !== undefined) query[name] = inputQuery[name];
+      }
+      return { template, params: { ...params, ...query } };
+    }
+  }
+  return undefined;
+}

package/src/mcp/transport/streamable-http.controller.ts

@@ -0,0 +1,114 @@
+import { Delete, Get, Inject, Post, Req, Res } from '@nestjs/common';
+import { MCP_HTTP_HANDLER, type McpHttpHandler } from './mcp-http-handler';
+
+/** Anything that can hand out MCP HTTP verb handlers — i.e. a transport. */
+export interface McpHttpHandlerSource {
+  readonly httpHandlers: McpHttpHandler;
+}
+
+/**
+ * Build a base controller bound DIRECTLY to a specific transport — the
+ * legible way to wire a bring-your-own MCP controller.
+ *
+ * Instead of providing handlers under a DI token and hoping the right one
+ * resolves (which gets confusing with multiple servers), the controller simply
+ * names the transport it serves. The binding is a concrete reference you can
+ * click through to:
+ *
+ * ```ts
+ * @Controller('weather/mcp')
+ * @UseGuards(WeatherAuthGuard)
+ * export class WeatherMcpController extends McpHttpControllerFor(weatherTransport) {}
+ * ```
+ *
+ * No `MCP_HTTP_HANDLER` provider, no module-local resolution to reason about: a
+ * reader sees `weatherTransport`, jumps to where it's declared, and finds it in
+ * `weatherStrategy({ server: 'weather' })` next to the weather tools. One hop.
+ *
+ * Reading `source.httpHandlers` here (at class-definition / import time) also
+ * marks the route as claimed, so the transport auto-disables its own self-mount.
+ *
+ * You still own the subclass decorators — `@Controller(path)`, `@UseGuards`,
+ * `@UseInterceptors`, `@Version`, etc. all compose normally; the library only
+ * owns the `POST`/`GET`/`DELETE` wiring.
+ */
+export function McpHttpControllerFor(source: McpHttpHandlerSource) {
+  const handlers = source.httpHandlers;
+
+  abstract class BoundMcpHttpController {
+    @Post()
+    post(@Req() req: unknown, @Res() res: unknown): Promise<void> | void {
+      return handlers.handlePost(req, res);
+    }
+
+    @Get()
+    get(@Req() req: unknown, @Res() res: unknown): Promise<void> | void {
+      return handlers.handleGet(req, res);
+    }
+
+    @Delete()
+    delete(@Req() req: unknown, @Res() res: unknown): Promise<void> | void {
+      return handlers.handleDelete(req, res);
+    }
+  }
+
+  return BoundMcpHttpController;
+}
+
+/**
+ * Abstract base controller for the streamable-HTTP MCP endpoint.
+ *
+ * Extend it to mount the MCP route as a real NestJS controller — so guards,
+ * interceptors, exception filters and versioning apply the normal Nest way,
+ * while the library keeps ownership of the `POST`/`GET`/`DELETE` wiring
+ * (session handling, SSE streaming, raw-body reading). You never reimplement the
+ * verbs; you just decorate your subclass:
+ *
+ * ```ts
+ * @Controller('mcp')
+ * @UseGuards(MyAuthGuard)          // ← authenticate the whole MCP surface, once
+ * export class McpController extends StreamableHttpController {}
+ * ```
+ *
+ * Wiring is a single line — provide the transport's handlers under
+ * {@link MCP_HTTP_HANDLER} so this base can inject them:
+ *
+ * ```ts
+ * { provide: MCP_HTTP_HANDLER, useValue: mcpTransport.httpHandlers }
+ * ```
+ *
+ * Reading `httpHandlers` there also auto-disables the transport's own
+ * self-mount, so you do NOT need `{ mount: false }` — your controller owns the
+ * route and there is no double-registration. (Pass `mount` explicitly only to
+ * override that.) The path lives on YOUR `@Controller(...)` decorator, not on
+ * the transport.
+ *
+ * Implementation notes:
+ * - `@Controller()` must be on the concrete subclass; Nest registers the route
+ *   handlers it finds on the prototype chain, including these inherited ones.
+ * - The handler is injected via a property (not the constructor) so subclasses
+ *   need no constructor and no `super(...)` call — and so it survives NestJS's
+ *   inherited-constructor-metadata quirks.
+ * - `@Res()` puts Nest in manual-response mode: the SDK transport writes the
+ *   response (and SSE stream) directly, so Nest must not serialize a return
+ *   value.
+ */
+export abstract class StreamableHttpController {
+  @Inject(MCP_HTTP_HANDLER)
+  protected readonly mcpHandler!: McpHttpHandler;
+
+  @Post()
+  post(@Req() req: unknown, @Res() res: unknown): Promise<void> | void {
+    return this.mcpHandler.handlePost(req, res);
+  }
+
+  @Get()
+  get(@Req() req: unknown, @Res() res: unknown): Promise<void> | void {
+    return this.mcpHandler.handleGet(req, res);
+  }
+
+  @Delete()
+  delete(@Req() req: unknown, @Res() res: unknown): Promise<void> | void {
+    return this.mcpHandler.handleDelete(req, res);
+  }
+}

package/src/mcp/transport/transports/index.ts

@@ -0,0 +1,2 @@
+export * from './stdio.transport';
+export * from './streamable-http.transport';

package/src/mcp/transport/transports/read-body.ts

@@ -0,0 +1,39 @@
+import { HttpRequest } from '../../interfaces/http-adapter.interface';
+
+/**
+ * Resolves the JSON request body for an MCP HTTP request.
+ *
+ * Prefers an already-parsed body (`adaptedReq.body`) when a framework body-parser
+ * ran (e.g. Fastify parses before route handlers). Otherwise reads the raw Node
+ * stream — the case for Express, where MCP routes are mounted before NestJS adds
+ * its body-parser middleware, so `req.body` is undefined and the stream is intact.
+ * Reading once here also lets the transport inspect the payload (e.g. to detect an
+ * `initialize` request) before handing off to the SDK.
+ */
+export async function readJsonBody(adaptedReq: HttpRequest): Promise<unknown> {
+  if (adaptedReq.body !== undefined) {
+    return adaptedReq.body;
+  }
+  const rawReq = adaptedReq.raw;
+  if (rawReq?.body !== undefined) {
+    return rawReq.body;
+  }
+  return new Promise((resolve) => {
+    let data = '';
+    rawReq.on('data', (chunk: Buffer | string) => {
+      data += chunk.toString();
+    });
+    rawReq.on('end', () => {
+      if (!data) {
+        resolve(undefined);
+        return;
+      }
+      try {
+        resolve(JSON.parse(data));
+      } catch {
+        resolve(undefined);
+      }
+    });
+    rawReq.on('error', () => resolve(undefined));
+  });
+}

package/src/mcp/transport/transports/stdio.transport.ts

@@ -0,0 +1,35 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpTransport, McpTransportContext } from '../mcp-transport.interface';
+
+/**
+ * stdio transport. Starts a single long-lived MCP server bound to the process'
+ * stdin/stdout. Intended for CLI-style MCP servers launched by an MCP client.
+ *
+ * No HTTP adapter is required. As a persistent, session-aware connection, stdio
+ * supports progress notifications and server-side logging.
+ */
+export class StdioTransport implements McpTransport {
+  readonly kind = 'stdio' as const;
+
+  private server?: McpServer;
+  private transport?: StdioServerTransport;
+
+  async start(ctx: McpTransportContext): Promise<void> {
+    this.server = ctx.createServer();
+    ctx.bindRequestHandlers(this.server, {
+      transport: this.kind,
+      stateless: false,
+    });
+    this.transport = new StdioServerTransport();
+    await this.server.connect(this.transport);
+    ctx.logger.log('MCP stdio transport started');
+  }
+
+  async close(): Promise<void> {
+    await this.transport?.close();
+    await this.server?.close();
+    this.transport = undefined;
+    this.server = undefined;
+  }
+}

package/src/mcp/transport/transports/streamable-http.transport.ts

@@ -0,0 +1,384 @@
+import { randomUUID } from 'crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { HttpAdapterFactory } from '../../adapters/http-adapter.factory';
+import { HttpResponse } from '../../interfaces/http-adapter.interface';
+import { McpTransport, McpTransportContext } from '../mcp-transport.interface';
+import type { McpHttpHandler } from '../mcp-http-handler';
+import { readJsonBody } from './read-body';
+
+export interface StreamableHttpTransportOptions {
+  /**
+   * Path of the transport's **self-mounted** route.
+   *
+   * This ONLY applies when the transport self-mounts (no controller owns the
+   * route). A self-mounted route is registered directly on the HTTP adapter,
+   * OUTSIDE Nest's routing pipeline — so it does not pick up
+   * `app.setGlobalPrefix(...)`, URI versioning, guards, or interceptors. Use
+   * `endpoint` for a trivial path change on a no-auth server.
+   *
+   * When you bring your own controller, the path comes from your
+   * `@Controller(...)` decorator (and global prefix / versioning apply normally)
+   * — `endpoint` is ignored. The transport logs a warning if you set it anyway.
+   *
+   * @default '/mcp'
+   */
+  endpoint?: string;
+  /**
+   * Enable session management (a long-lived MCP server per session, identified
+   * by the `mcp-session-id` header, with `GET`/`DELETE` support for SSE streams
+   * and session teardown).
+   *
+   * Left off (the default), the transport is **stateless**: every request is
+   * self-contained, a fresh server is created and torn down per request, and
+   * `GET`/`DELETE` return `405`. Stateless is the simplest mode and the right
+   * default for most servers; turn this on only when you need server-initiated
+   * streaming/notifications tied to a session.
+   *
+   * @default false (stateless)
+   */
+  statefulMode?: boolean;
+  /**
+   * Return a single JSON response instead of opening an SSE stream.
+   *
+   * When unset, this **follows the session mode**: `true` in stateless mode (so
+   * a plain POST gets a JSON reply with no stream to manage) and `false` in
+   * stateful mode (SSE, so server-initiated messages can flow). Set it
+   * explicitly to override that pairing.
+   *
+   * @default `!statefulMode` (JSON when stateless, SSE when stateful)
+   */
+  enableJsonResponse?: boolean;
+  /** Custom session id generator (stateful mode). */
+  sessionIdGenerator?: () => string;
+  /**
+   * Whether the transport mounts its own `POST`/`GET`/`DELETE` routes on the
+   * Nest HTTP adapter.
+   *
+   * Leave it unset (the default) for **auto-detection**: the transport
+   * self-mounts UNLESS something has read {@link httpHandlers} — which happens
+   * exactly when you wire a bring-your-own `@Controller` (e.g. via
+   * `{ provide: MCP_HTTP_HANDLER, useValue: transport.httpHandlers }`). So
+   * providing a controller automatically suppresses self-mounting; doing
+   * nothing keeps the zero-config self-mount. This read happens at module
+   * definition time, before the transport starts, so the timing is reliable.
+   *
+   * Set it explicitly to override the heuristic:
+   * - `true`: always self-mount (bypasses the Nest pipeline — no guards).
+   * - `false`: never self-mount (you own the route via a controller).
+   *
+   * @default undefined (auto: self-mount unless `httpHandlers` was accessed)
+   */
+  mount?: boolean;
+}
+
+/**
+ * Streamable-HTTP transport. Mounts `POST`/`GET`/`DELETE` on the Nest HTTP server
+ * and delegates to the MCP SDK `StreamableHTTPServerTransport`. Supports both the
+ * stateless (one server per request) and stateful (session-managed) modes.
+ */
+export class StreamableHttpTransport implements McpTransport {
+  readonly kind = 'streamable-http' as const;
+
+  private readonly endpoint: string;
+  private readonly statefulMode: boolean;
+  private readonly enableJsonResponse: boolean;
+  private readonly sessionIdGenerator: () => string;
+  /** Whether `endpoint` was set explicitly (vs defaulted) — for the ignored-option warning. */
+  private readonly endpointExplicit: boolean;
+  /** Explicit `mount` override; `undefined` means auto-detect. */
+  private readonly mountOption?: boolean;
+  /** Set the first time {@link httpHandlers} is read — implies a BYO controller. */
+  private handlersClaimed = false;
+
+  private readonly transports: Record<string, StreamableHTTPServerTransport> =
+    {};
+  private readonly servers: Record<string, McpServer> = {};
+  private ctx?: McpTransportContext;
+
+  constructor(options: StreamableHttpTransportOptions = {}) {
+    this.endpoint = ensureLeadingSlash(options.endpoint ?? 'mcp');
+    this.endpointExplicit = options.endpoint !== undefined;
+    this.statefulMode = options.statefulMode ?? false;
+    // Default follows the session mode: JSON in stateless, SSE in stateful.
+    this.enableJsonResponse =
+      options.enableJsonResponse ?? !this.statefulMode;
+    this.sessionIdGenerator =
+      options.sessionIdGenerator ?? (() => randomUUID());
+    this.mountOption = options.mount;
+  }
+
+  /**
+   * The HTTP verb handlers, for bring-your-own-controller setups. Provide this
+   * under `MCP_HTTP_HANDLER` and delegate to it from a `@Controller` (see
+   * {@link StreamableHttpController}). The returned functions are bound to this
+   * transport and read their context lazily, so it is safe to grab this getter
+   * at module-construction time — before `start()` has run.
+   *
+   * Reading this getter also marks the route as claimed, so the transport
+   * auto-disables its own self-mount (unless `mount` was set explicitly). That
+   * is how `{ provide: MCP_HTTP_HANDLER, useValue: transport.httpHandlers }`
+   * suppresses self-mounting without any extra flag.
+   */
+  get httpHandlers(): McpHttpHandler {
+    this.handlersClaimed = true;
+    return {
+      handlePost: (req: unknown, res: unknown) => this.handlePost(req, res),
+      handleGet: (req: unknown, res: unknown) => this.handleGet(req, res),
+      handleDelete: (req: unknown, res: unknown) => this.handleDelete(req, res),
+    };
+  }
+
+  start(ctx: McpTransportContext): void {
+    // The context (server factory, request-handler binding, logger) is always
+    // needed — the handlers read it lazily whether we self-mount or a user
+    // controller calls them.
+    this.ctx = ctx;
+
+    // Auto-detect: self-mount unless a controller claimed the route by reading
+    // `httpHandlers`. An explicit `mount` option overrides the heuristic.
+    const shouldMount = this.mountOption ?? !this.handlersClaimed;
+
+    if (!shouldMount) {
+      // The path now comes from the user's @Controller(...), so a self-mount
+      // `endpoint` would be silently ignored. Don't let that pass quietly.
+      if (this.endpointExplicit) {
+        ctx.logger.warn(
+          `StreamableHttpTransport: \`endpoint: '${this.endpoint}'\` is ignored because a controller owns the route. Set the path on your @Controller(...) decorator instead (it also picks up global prefix and versioning).`,
+        );
+      }
+      ctx.logger.log(
+        `MCP streamable-http transport ready (${this.statefulMode ? 'stateful' : 'stateless'}, self-mount disabled — a controller owns the route)`,
+      );
+      return;
+    }
+
+    if (!ctx.httpAdapter) {
+      throw new Error(
+        'StreamableHttpTransport requires an HTTP adapter to self-mount. Pass it via new McpStrategy({ httpAdapter }) or strategy.setHttpAdapter(app.getHttpAdapter()) — or mount your own controller (provide MCP_HTTP_HANDLER with transport.httpHandlers).',
+      );
+    }
+    const adapter = ctx.httpAdapter as unknown as {
+      post(path: string, handler: (req: any, res: any) => unknown): unknown;
+      get(path: string, handler: (req: any, res: any) => unknown): unknown;
+      delete(path: string, handler: (req: any, res: any) => unknown): unknown;
+    };
+
+    adapter.post(this.endpoint, (req, res) => this.handlePost(req, res));
+    adapter.get(this.endpoint, (req, res) => this.handleGet(req, res));
+    adapter.delete(this.endpoint, (req, res) => this.handleDelete(req, res));
+
+    ctx.logger.log(
+      `MCP streamable-http transport mounted at ${this.endpoint} (${this.statefulMode ? 'stateful' : 'stateless'})`,
+    );
+  }
+
+  async close(): Promise<void> {
+    for (const sessionId of Object.keys(this.transports)) {
+      await this.cleanupSession(sessionId);
+    }
+  }
+
+  private async handlePost(req: any, res: any): Promise<void> {
+    const adapter = HttpAdapterFactory.getAdapter(req, res);
+    const adaptedReq = adapter.adaptRequest(req);
+    const adaptedRes = adapter.adaptResponse(res);
+    const body = await readJsonBody(adaptedReq);
+
+    try {
+      if (this.statefulMode) {
+        await this.handleStateful(adaptedReq, adaptedRes, body);
+      } else {
+        await this.handleStateless(adaptedReq, adaptedRes, body);
+      }
+    } catch (error) {
+      this.ctx!.logger.error('Error handling MCP request', error as Error);
+      if (!adaptedRes.headersSent) {
+        adaptedRes.status(500).json({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: 'Internal server error' },
+          id: null,
+        });
+      }
+    }
+  }
+
+  private async handleStateless(
+    req: ReturnType<
+      ReturnType<typeof HttpAdapterFactory.getAdapter>['adaptRequest']
+    >,
+    res: HttpResponse,
+    body: unknown,
+  ): Promise<void> {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: this.enableJsonResponse,
+    });
+    const server = this.ctx!.createServer();
+    await server.connect(transport);
+    this.ctx!.bindRequestHandlers(
+      server,
+      { transport: this.kind, stateless: true },
+      req.raw,
+    );
+
+    res.raw.on('finish', () => {
+      void transport.close();
+      void server.close();
+    });
+
+    await transport.handleRequest(req.raw, res.raw, body);
+  }
+
+  private async handleStateful(
+    req: ReturnType<
+      ReturnType<typeof HttpAdapterFactory.getAdapter>['adaptRequest']
+    >,
+    res: HttpResponse,
+    body: unknown,
+  ): Promise<void> {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+
+    if (!sessionId && isInitializeRequest(body)) {
+      const server = this.ctx!.createServer();
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: this.sessionIdGenerator,
+        enableJsonResponse: this.enableJsonResponse,
+        onsessioninitialized: (sid: string) => {
+          this.transports[sid] = transport;
+          this.servers[sid] = server;
+        },
+        onsessionclosed: (sid: string) => {
+          void this.cleanupSession(sid);
+        },
+      });
+      await server.connect(transport);
+      this.ctx!.bindRequestHandlers(
+        server,
+        { transport: this.kind, stateless: false },
+        req.raw,
+      );
+      await transport.handleRequest(req.raw, res.raw, body);
+      return;
+    }
+
+    if (sessionId) {
+      const transport = this.transports[sessionId];
+      const server = this.servers[sessionId];
+      if (!transport || !server) {
+        res.status(404).json({
+          jsonrpc: '2.0',
+          error: { code: -32001, message: 'Session not found' },
+          id: null,
+        });
+        return;
+      }
+      // Re-bind so the per-request auth context is current.
+      this.ctx!.bindRequestHandlers(
+        server,
+        { transport: this.kind, stateless: false, sessionId },
+        req.raw,
+      );
+      await transport.handleRequest(req.raw, res.raw, body);
+      return;
+    }
+
+    res.status(400).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32000,
+        message: 'Bad Request: Mcp-Session-Id header is required',
+      },
+      id: null,
+    });
+  }
+
+  private async handleGet(req: any, res: any): Promise<void> {
+    const adapter = HttpAdapterFactory.getAdapter(req, res);
+    const adaptedReq = adapter.adaptRequest(req);
+    const adaptedRes = adapter.adaptResponse(res);
+
+    if (!this.statefulMode) {
+      adaptedRes.status(405).json({
+        jsonrpc: '2.0',
+        error: {
+          code: -32000,
+          message: 'Method not allowed in stateless mode',
+        },
+        id: null,
+      });
+      return;
+    }
+    const sessionId = adaptedReq.headers['mcp-session-id'] as
+      | string
+      | undefined;
+    const transport = sessionId ? this.transports[sessionId] : undefined;
+    if (!transport) {
+      adaptedRes.status(404).json({
+        jsonrpc: '2.0',
+        error: { code: -32001, message: 'Session not found' },
+        id: null,
+      });
+      return;
+    }
+    await transport.handleRequest(adaptedReq.raw, adaptedRes.raw);
+  }
+
+  private async handleDelete(req: any, res: any): Promise<void> {
+    const adapter = HttpAdapterFactory.getAdapter(req, res);
+    const adaptedReq = adapter.adaptRequest(req);
+    const adaptedRes = adapter.adaptResponse(res);
+
+    if (!this.statefulMode) {
+      adaptedRes.status(405).json({
+        jsonrpc: '2.0',
+        error: {
+          code: -32000,
+          message: 'Method not allowed in stateless mode',
+        },
+        id: null,
+      });
+      return;
+    }
+    const sessionId = adaptedReq.headers['mcp-session-id'] as
+      | string
+      | undefined;
+    const transport = sessionId ? this.transports[sessionId] : undefined;
+    if (!transport) {
+      adaptedRes.status(404).json({
+        jsonrpc: '2.0',
+        error: { code: -32001, message: 'Session not found' },
+        id: null,
+      });
+      return;
+    }
+    await transport.handleRequest(adaptedReq.raw, adaptedRes.raw);
+  }
+
+  private async cleanupSession(sessionId: string): Promise<void> {
+    const transport = this.transports[sessionId];
+    const server = this.servers[sessionId];
+    delete this.transports[sessionId];
+    delete this.servers[sessionId];
+    try {
+      await transport?.close();
+      await server?.close();
+    } catch {
+      // best-effort cleanup
+    }
+  }
+}
+
+function isInitializeRequest(body: unknown): boolean {
+  const isInit = (msg: unknown): boolean =>
+    typeof msg === 'object' &&
+    msg !== null &&
+    'method' in msg &&
+    (msg as { method?: unknown }).method === 'initialize';
+  return Array.isArray(body) ? body.some(isInit) : isInit(body);
+}
+
+function ensureLeadingSlash(endpoint: string): string {
+  const trimmed = endpoint.trim();
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}