open-mcp-app 0.0.14 → 0.0.15

package/dist/server/index.d.ts

@@ -321,6 +321,35 @@ interface TransportSessionInfo {
     /** The transport type for this session */
     transport: TransportType;
 }
+type ServerlessTransportMode = "stateful" | "stateless";
+interface StateAdapter {
+    get: (instanceId: string) => Promise<unknown | undefined>;
+    set: (instanceId: string, state: unknown) => Promise<void>;
+    delete: (instanceId: string) => Promise<void>;
+}
+interface ServerlessAdapterOptions {
+    /**
+     * Controls whether MCP transport sessions are persisted between requests.
+     *
+     * - `"stateful"` keeps normal MCP session semantics and expects sticky routing.
+     * - `"stateless"` disables MCP transport session IDs so each request stands alone.
+     *
+     * For AWS Lambda and other serverless deployments, `"stateless"` is usually the
+     * safest default because requests may land on different warm instances.
+     */
+    transportMode?: ServerlessTransportMode;
+    /**
+     * Enables JSON POST responses for stateless streamable-http mode.
+     * This avoids relying on SSE session continuity in serverless environments.
+     */
+    enableJsonResponse?: boolean;
+    /**
+     * Optional backing store for `context.getState()` / `context.setState()`.
+     * This is only needed for tools that rely on server-side state across requests.
+     */
+    stateAdapter?: StateAdapter;
+}
+type AwsLambdaHandler = (...args: unknown[]) => Promise<unknown>;
 /**
  * App configuration.
  */
@@ -619,13 +648,22 @@ declare class App {
      * Get the Express application for serverless wrapping (e.g. Lambda).
      * Does NOT start listening on a port.
      */
-    toExpressApp(): express__default.Express;
+    toExpressApp(options?: ServerlessAdapterOptions): express__default.Express;
+    toAwsLambda(options?: ServerlessAdapterOptions): AwsLambdaHandler;
     /**
      * Close a specific transport session.
      */
     closeTransportSession(sessionId: string): boolean;
     private getPort;
     private getCallerDir;
+    private lambdaEventToRequest;
+    private handleLambdaHttpRequest;
+    private writeLambdaResponse;
+    private isStatelessTransport;
+    private getStateAdapter;
+    private loadInstanceState;
+    private persistInstanceState;
+    private deleteInstanceState;
     /**
      * Handle an MCP JSON-RPC request directly.
      * Used for testing without starting a server.
@@ -1478,4 +1516,4 @@ declare const exp: {
     sampleMessage: typeof experimental_sampleMessage;
 };
 
-export { App, type AppConfig, type DisplayMode, type IconConfig, type InstanceDestroyContext, type KvSearchResult, MIME_TYPES, type ResourceConfig, type ServerLogLevel, type ServerLogger, type ToolAnnotations, type ToolCallInfo, type ToolCallResultInfo, type ToolConfig, type ToolContext, type ToolHandler, type ToolResult, type ToolVisibility, type TransportSessionInfo, type TransportType, type VectorSearchResult, type WebSocketConnection, createApp, exp, experimental_blobDelete, experimental_blobDeleteSync, experimental_blobGet, experimental_blobGetSync, experimental_blobIsAvailable, experimental_blobList, experimental_blobListSync, experimental_blobPut, experimental_blobPutSync, experimental_deleteFile, experimental_deleteFileSync, experimental_exists, experimental_existsSync, experimental_getProjectId, experimental_getServerName, experimental_getWritableDirectory, experimental_kvDelete, experimental_kvDeleteSync, experimental_kvGet, experimental_kvGetSync, experimental_kvIsAvailable, experimental_kvList, experimental_kvListSync, experimental_kvSearch, experimental_kvSet, experimental_kvSetSync, experimental_mkdir, experimental_mkdirSync, experimental_readFile, experimental_readFileSync, experimental_readdir, experimental_readdirSync, experimental_rmdir, experimental_rmdirSync, experimental_sampleMessage, experimental_vectorDelete, experimental_vectorIsAvailable, experimental_vectorSearch, experimental_vectorUpsert, experimental_writeFile, experimental_writeFileSync, htmlLoader, isHtmlContent, loadHtml, svgToDataUri, wrapServer };
+export { App, type AppConfig, type AwsLambdaHandler, type DisplayMode, type IconConfig, type InstanceDestroyContext, type KvSearchResult, MIME_TYPES, type ResourceConfig, type ServerLogLevel, type ServerLogger, type ServerlessAdapterOptions, type ServerlessTransportMode, type StateAdapter, type ToolAnnotations, type ToolCallInfo, type ToolCallResultInfo, type ToolConfig, type ToolContext, type ToolHandler, type ToolResult, type ToolVisibility, type TransportSessionInfo, type TransportType, type VectorSearchResult, type WebSocketConnection, createApp, exp, experimental_blobDelete, experimental_blobDeleteSync, experimental_blobGet, experimental_blobGetSync, experimental_blobIsAvailable, experimental_blobList, experimental_blobListSync, experimental_blobPut, experimental_blobPutSync, experimental_deleteFile, experimental_deleteFileSync, experimental_exists, experimental_existsSync, experimental_getProjectId, experimental_getServerName, experimental_getWritableDirectory, experimental_kvDelete, experimental_kvDeleteSync, experimental_kvGet, experimental_kvGetSync, experimental_kvIsAvailable, experimental_kvList, experimental_kvListSync, experimental_kvSearch, experimental_kvSet, experimental_kvSetSync, experimental_mkdir, experimental_mkdirSync, experimental_readFile, experimental_readFileSync, experimental_readdir, experimental_readdirSync, experimental_rmdir, experimental_rmdirSync, experimental_sampleMessage, experimental_vectorDelete, experimental_vectorIsAvailable, experimental_vectorSearch, experimental_vectorUpsert, experimental_writeFile, experimental_writeFileSync, htmlLoader, isHtmlContent, loadHtml, svgToDataUri, wrapServer };

package/dist/server/index.js

@@ -6796,6 +6796,8 @@ var require_dist = __commonJS({
 // src/server/app.ts
 import { randomUUID } from "crypto";
 import path2 from "path";
+import { Readable as Readable2 } from "stream";
+import { pipeline } from "stream/promises";
 import { fileURLToPath } from "url";
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
@@ -12342,7 +12344,7 @@ var toRequestError = (e) => {
   return new RequestError(e.message, { cause: e });
 };
 var GlobalRequest = global.Request;
-var Request = class extends GlobalRequest {
+var Request2 = class extends GlobalRequest {
   constructor(input, options) {
     if (typeof input === "object" && getRequestCache in input) {
       input = input[getRequestCache]();
@@ -12375,7 +12377,7 @@ var newRequestFromIncoming = (method, url, headers, incoming, abortController) =
   };
   if (method === "TRACE") {
     init.method = "GET";
-    const req = new Request(url, init);
+    const req = new Request2(url, init);
     Object.defineProperty(req, "method", {
       get() {
         return "TRACE";
@@ -12412,7 +12414,7 @@ var newRequestFromIncoming = (method, url, headers, incoming, abortController) =
       init.body = Readable.toWeb(incoming);
     }
   }
-  return new Request(url, init);
+  return new Request2(url, init);
 };
 var getRequestCache = /* @__PURE__ */ Symbol("getRequestCache");
 var requestCache = /* @__PURE__ */ Symbol("requestCache");
@@ -12473,7 +12475,7 @@ var requestPrototype = {
     }
   });
 });
-Object.setPrototypeOf(requestPrototype, Request.prototype);
+Object.setPrototypeOf(requestPrototype, Request2.prototype);
 var newRequest = (incoming, defaultHostname) => {
   const req = Object.create(requestPrototype);
   req[incomingKey] = incoming;
@@ -12539,15 +12541,17 @@ var Response2 = class _Response {
       this.#init = init;
     }
     if (typeof body === "string" || typeof body?.getReader !== "undefined" || body instanceof Blob || body instanceof Uint8Array) {
-      headers ||= init?.headers || { "content-type": "text/plain; charset=UTF-8" };
-      this[cacheKey] = [init?.status || 200, body, headers];
+      ;
+      this[cacheKey] = [init?.status || 200, body, headers || init?.headers];
     }
   }
   get headers() {
     const cache = this[cacheKey];
     if (cache) {
       if (!(cache[2] instanceof Headers)) {
-        cache[2] = new Headers(cache[2]);
+        cache[2] = new Headers(
+          cache[2] || { "content-type": "text/plain; charset=UTF-8" }
+        );
       }
       return cache[2];
     }
@@ -12672,15 +12676,32 @@ var flushHeaders = (outgoing) => {
 };
 var responseViaCache = async (res, outgoing) => {
   let [status, body, header] = res[cacheKey];
-  if (header instanceof Headers) {
+  let hasContentLength = false;
+  if (!header) {
+    header = { "content-type": "text/plain; charset=UTF-8" };
+  } else if (header instanceof Headers) {
+    hasContentLength = header.has("content-length");
     header = buildOutgoingHttpHeaders(header);
+  } else if (Array.isArray(header)) {
+    const headerObj = new Headers(header);
+    hasContentLength = headerObj.has("content-length");
+    header = buildOutgoingHttpHeaders(headerObj);
+  } else {
+    for (const key in header) {
+      if (key.length === 14 && key.toLowerCase() === "content-length") {
+        hasContentLength = true;
+        break;
+      }
+    }
   }
-  if (typeof body === "string") {
-    header["Content-Length"] = Buffer.byteLength(body);
-  } else if (body instanceof Uint8Array) {
-    header["Content-Length"] = body.byteLength;
-  } else if (body instanceof Blob) {
-    header["Content-Length"] = body.size;
+  if (!hasContentLength) {
+    if (typeof body === "string") {
+      header["Content-Length"] = Buffer.byteLength(body);
+    } else if (body instanceof Uint8Array) {
+      header["Content-Length"] = body.byteLength;
+    } else if (body instanceof Blob) {
+      header["Content-Length"] = body.size;
+    }
   }
   outgoing.writeHead(status, header);
   if (typeof body === "string" || body instanceof Uint8Array) {
@@ -12774,9 +12795,9 @@ var responseViaResponseObject = async (res, outgoing, options = {}) => {
 };
 var getRequestListener = (fetchCallback, options = {}) => {
   const autoCleanupIncoming = options.autoCleanupIncoming ?? true;
-  if (options.overrideGlobalObjects !== false && global.Request !== Request) {
+  if (options.overrideGlobalObjects !== false && global.Request !== Request2) {
     Object.defineProperty(global, "Request", {
-      value: Request
+      value: Request2
     });
     Object.defineProperty(global, "Response", {
       value: Response2
@@ -14173,7 +14194,7 @@ var App = class {
         ws.close();
         this.instanceWebSockets.delete(instanceId);
       }
-      this.instanceState.delete(instanceId);
+      this.deleteInstanceState(instanceId);
       console.log(`[MCP] Instance destroyed: ${instanceId}`);
       return true;
     }
@@ -14258,8 +14279,30 @@ var App = class {
    * Get the Express application for serverless wrapping (e.g. Lambda).
    * Does NOT start listening on a port.
    */
-  toExpressApp() {
-    return this.createExpressApp();
+  toExpressApp(options) {
+    return this.createExpressApp({ serverless: options });
+  }
+  toAwsLambda(options) {
+    const serverlessOptions = {
+      transportMode: "stateless",
+      ...options
+    };
+    if (serverlessOptions.transportMode !== "stateless") {
+      throw new Error("app.toAwsLambda() currently requires transportMode: 'stateless'");
+    }
+    const lambdaRuntime = globalThis.awslambda;
+    if (!lambdaRuntime) {
+      throw new Error("app.toAwsLambda() is only available inside the AWS Lambda runtime");
+    }
+    return lambdaRuntime.streamifyResponse(async (event, responseStream) => {
+      const request = this.lambdaEventToRequest(event);
+      const { response, cleanup } = await this.handleLambdaHttpRequest(request, serverlessOptions);
+      try {
+        await this.writeLambdaResponse(response, responseStream);
+      } finally {
+        await cleanup();
+      }
+    });
   }
   /**
    * Close a specific transport session.
@@ -14285,6 +14328,97 @@ var App = class {
   getCallerDir() {
     return this.callerDir;
   }
+  lambdaEventToRequest(event) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(event.headers ?? {})) {
+      if (value !== void 0) {
+        headers.set(key, value);
+      }
+    }
+    if (event.cookies?.length) {
+      headers.set("cookie", event.cookies.join("; "));
+    }
+    const method = event.requestContext?.http?.method || "GET";
+    const scheme = headers.get("x-forwarded-proto") || "https";
+    const host = headers.get("host") || event.requestContext?.domainName || "localhost";
+    const rawPath = event.rawPath || "/mcp";
+    const query = event.rawQueryString ? `?${event.rawQueryString}` : "";
+    const url = `${scheme}://${host}${rawPath}${query}`;
+    const hasBody = event.body !== void 0 && event.body !== null && method !== "GET" && method !== "HEAD";
+    const body = hasBody ? Buffer.from(event.body, event.isBase64Encoded ? "base64" : "utf8") : void 0;
+    return new Request(url, {
+      method,
+      headers,
+      body
+    });
+  }
+  async handleLambdaHttpRequest(request, options) {
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      enableJsonResponse: options.enableJsonResponse ?? false
+    });
+    const server = this.createMcpServer({ serverless: options });
+    await server.connect(transport);
+    setCurrentServer(server);
+    return {
+      response: await transport.handleRequest(request),
+      cleanup: async () => {
+        await server.close().catch(() => {
+        });
+      }
+    };
+  }
+  async writeLambdaResponse(response, responseStream) {
+    const headers = {};
+    response.headers.forEach((value, key) => {
+      if (key.toLowerCase() !== "set-cookie") {
+        headers[key] = value;
+      }
+    });
+    const getSetCookie = response.headers.getSetCookie;
+    const cookies = typeof getSetCookie === "function" ? getSetCookie.call(response.headers) : void 0;
+    const writable = awslambda.HttpResponseStream.from(responseStream, {
+      statusCode: response.status,
+      headers,
+      ...cookies && cookies.length > 0 ? { cookies } : {}
+    });
+    if (!response.body) {
+      writable.end();
+      return;
+    }
+    await pipeline(Readable2.fromWeb(response.body), writable);
+  }
+  isStatelessTransport(options) {
+    return options?.serverless?.transportMode === "stateless";
+  }
+  getStateAdapter(options) {
+    return options?.serverless?.stateAdapter;
+  }
+  async loadInstanceState(instanceId, options) {
+    const adapter = this.getStateAdapter(options);
+    if (adapter) {
+      return adapter.get(instanceId);
+    }
+    return this.instanceState.get(instanceId);
+  }
+  async persistInstanceState(instanceId, state, options) {
+    const adapter = this.getStateAdapter(options);
+    if (adapter) {
+      await adapter.set(instanceId, state);
+      return;
+    }
+    this.instanceState.set(instanceId, state);
+  }
+  deleteInstanceState(instanceId, options) {
+    const adapter = this.getStateAdapter(options);
+    if (adapter) {
+      void adapter.delete(instanceId).catch((error) => {
+        console.error(`[MCP] Failed to delete state for ${instanceId}:`, error);
+      });
+      return;
+    }
+    this.instanceState.delete(instanceId);
+  }
   // ==========================================================================
   // Public API: MCP Request Handling (for testing)
   // ==========================================================================
@@ -14503,7 +14637,7 @@ var App = class {
   // ==========================================================================
   // Private: Express Server
   // ==========================================================================
-  createExpressApp() {
+  createExpressApp(options) {
     const app = express();
     app.use(express.json({ limit: "50mb" }));
     if (this.config.cors !== false) {
@@ -14531,12 +14665,12 @@ var App = class {
         websockets: this.instanceWebSockets.size
       });
     });
-    app.post("/mcp", (req, res) => this.handleMcpPost(req, res));
-    app.get("/mcp", (req, res) => this.handleMcpGet(req, res));
-    app.delete("/mcp", (req, res) => this.handleMcpDelete(req, res));
+    app.post("/mcp", (req, res) => this.handleMcpPost(req, res, options));
+    app.get("/mcp", (req, res) => this.handleMcpGet(req, res, options));
+    app.delete("/mcp", (req, res) => this.handleMcpDelete(req, res, options));
     return app;
   }
-  async handleMcpPost(req, res) {
+  async handleMcpPost(req, res, options) {
     const transportSessionId = req.headers["mcp-session-id"];
     try {
       if (req.body?.method === "tools/list" && this.tools.size === 0) {
@@ -14548,6 +14682,14 @@ var App = class {
         return;
       }
       let transport;
+      if (this.isStatelessTransport(options)) {
+        transport = this.createTransport(options);
+        const server = this.createMcpServer(options);
+        await server.connect(transport);
+        setCurrentServer(server);
+        await transport.handleRequest(req, res, req.body);
+        return;
+      }
       if (transportSessionId && this.transports.has(transportSessionId)) {
         transport = this.transports.get(transportSessionId);
       } else if (!transportSessionId && isInitializeRequest2(req.body)) {
@@ -14562,8 +14704,8 @@ var App = class {
           this.clientType = "unknown";
         }
         console.log(`[MCP] Client: ${clientName}, type: ${this.clientType}`);
-        transport = this.createTransport();
-        const server = this.createMcpServer();
+        transport = this.createTransport(options);
+        const server = this.createMcpServer(options);
         await server.connect(transport);
         this.serverByTransport.set(transport, server);
         setCurrentServer(server);
@@ -14589,8 +14731,16 @@ var App = class {
       }
     }
   }
-  async handleMcpGet(req, res) {
+  async handleMcpGet(req, res, options) {
     const transportSessionId = req.headers["mcp-session-id"];
+    if (this.isStatelessTransport(options)) {
+      const transport2 = this.createTransport(options);
+      const server = this.createMcpServer(options);
+      await server.connect(transport2);
+      setCurrentServer(server);
+      await transport2.handleRequest(req, res);
+      return;
+    }
     if (!transportSessionId || !this.transports.has(transportSessionId)) {
       res.status(400).send("Invalid or missing transport session ID");
       return;
@@ -14598,8 +14748,16 @@ var App = class {
     const transport = this.transports.get(transportSessionId);
     await transport.handleRequest(req, res);
   }
-  async handleMcpDelete(req, res) {
+  async handleMcpDelete(req, res, options) {
     const transportSessionId = req.headers["mcp-session-id"];
+    if (this.isStatelessTransport(options)) {
+      const transport2 = this.createTransport(options);
+      const server = this.createMcpServer(options);
+      await server.connect(transport2);
+      setCurrentServer(server);
+      await transport2.handleRequest(req, res);
+      return;
+    }
     if (!transportSessionId || !this.transports.has(transportSessionId)) {
       res.status(400).send("Invalid or missing transport session ID");
       return;
@@ -14610,10 +14768,12 @@ var App = class {
   // ==========================================================================
   // Private: MCP Server & Transport
   // ==========================================================================
-  createTransport() {
+  createTransport(options) {
+    const stateless = this.isStatelessTransport(options);
     const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: () => randomUUID(),
-      onsessioninitialized: (newSessionId) => {
+      sessionIdGenerator: stateless ? void 0 : (() => randomUUID()),
+      enableJsonResponse: options?.serverless?.enableJsonResponse ?? false,
+      onsessioninitialized: stateless ? void 0 : (newSessionId) => {
         this.transports.set(newSessionId, transport);
         console.log(`[MCP] Transport session created: ${newSessionId}`);
         this.config.onTransportSessionCreated?.({
@@ -14643,7 +14803,7 @@ var App = class {
     };
     return transport;
   }
-  createMcpServer() {
+  createMcpServer(options) {
     const server = new McpServer(
       {
         name: this.config.name,
@@ -14653,7 +14813,7 @@ var App = class {
       { capabilities: { logging: {}, tools: {}, resources: {} } }
     );
     this.registerResources(server);
-    this.registerTools(server);
+    this.registerTools(server, options);
     return server;
   }
   registerResources(server) {
@@ -14739,7 +14899,7 @@ var App = class {
       );
     }
   }
-  registerTools(server) {
+  registerTools(server, options) {
     for (const [name, { config, handler }] of this.tools) {
       const toolMeta = this.buildToolMeta(config);
       const baseSchema = config.input || z3.object({});
@@ -14756,9 +14916,10 @@ var App = class {
         },
         async (args) => {
           let startMs = Date.now();
+          let instanceId;
+          let stateDirty = false;
           try {
             const input = config.input ? config.input.parse(args) : args;
-            let instanceId;
             if (hasUi && config.ui) {
               instanceId = this.resolveInstanceId(args._instanceId);
             }
@@ -14766,15 +14927,21 @@ var App = class {
             const hasWebSocket = resource?.config.experimental?.websocket === true;
             let ws;
             let websocketUrl;
-            if (hasWebSocket && instanceId) {
+            if (hasWebSocket && instanceId && !options?.serverless) {
               ws = this.getOrCreateWebSocket(instanceId);
               websocketUrl = ws?.websocketUrl;
             }
+            let currentState = instanceId ? await this.loadInstanceState(instanceId, options) : void 0;
+            if (instanceId && currentState !== void 0) {
+              this.instanceState.set(instanceId, currentState);
+            }
             const context = {
               instanceId: instanceId || "",
-              getState: () => instanceId ? this.instanceState.get(instanceId) : void 0,
+              getState: () => currentState,
               setState: (state) => {
                 if (instanceId) {
+                  currentState = state;
+                  stateDirty = true;
                   this.instanceState.set(instanceId, state);
                 }
               },
@@ -14805,6 +14972,9 @@ var App = class {
             startMs = Date.now();
             const result = await handler(input, context);
             const durationMs = Date.now() - startMs;
+            if (instanceId && stateDirty) {
+              await this.persistInstanceState(instanceId, currentState, options);
+            }
             try {
               this.config.onAfterToolCall?.({ toolName: name, args, result, durationMs, isError: false });
             } catch {
@@ -14818,6 +14988,9 @@ var App = class {
             const durationMs = Date.now() - startMs;
             console.error(`[MCP] Tool "${name}" failed:`, err.message);
             this.config.onToolError?.(name, err, args);
+            if (instanceId && stateDirty) {
+              await this.persistInstanceState(instanceId, this.instanceState.get(instanceId), options);
+            }
             try {
               this.config.onAfterToolCall?.({ toolName: name, args, durationMs, isError: true, error: err });
             } catch {