@aws/run-mcp-servers-with-aws-lambda 0.2.1 → 0.2.3

package/dist/handlers/lambda_function_url_event_handler.js

@@ -0,0 +1,42 @@
+import { StreamableHttpHandler, } from "./streamable_http_handler.js";
+/**
+ * Handler for Lambda Function URL requests
+ *
+ * This handler processes APIGatewayProxyEventV2 events and returns APIGatewayProxyResultV2 responses.
+ *
+ * This class handles all the generic JSON-RPC protocol aspects of the MCP Streamable HTTP transport:
+ * - HTTP method validation (POST, OPTIONS, GET)
+ * - Content-Type and Accept header validation
+ * - JSON parsing and validation
+ * - Batch request handling
+ * - CORS headers
+ * - Error response formatting
+ * This class does not implement session management.
+ *
+ * The specific business logic is delegated to a provided RequestHandler implementation.
+ */
+export class LambdaFunctionURLEventHandler extends StreamableHttpHandler {
+    constructor(requestHandler) {
+        super(requestHandler);
+    }
+    /**
+     * Parse Lambda Function URL event (APIGatewayProxyEventV2) into common HTTP request format
+     */
+    parseEvent(event) {
+        return {
+            method: event.requestContext.http.method,
+            headers: event.headers || {},
+            body: event.body || null,
+        };
+    }
+    /**
+     * Format HTTP response as APIGatewayProxyResultV2
+     */
+    formatResponse(response) {
+        return {
+            statusCode: response.statusCode,
+            headers: response.headers,
+            body: response.body,
+        };
+    }
+}

package/dist/handlers/request_handler.d.ts

@@ -0,0 +1,43 @@
+import { Context } from "aws-lambda";
+import { JSONRPCRequest, JSONRPCResponse, JSONRPCError } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Interface for handling individual JSON-RPC requests
+ *
+ * This interface defines the contract for processing MCP (Model Context Protocol) requests
+ * in AWS Lambda functions. Implementations should contain the business logic for handling
+ * specific JSON-RPC methods.
+ */
+export interface RequestHandler {
+    /**
+     * Process a single JSON-RPC request and return a response or error
+     *
+     * @param request The JSON-RPC request to process
+     * @param context The AWS Lambda context providing runtime information
+     * @returns A Promise that resolves to either a JSON-RPC response (for successful requests)
+     *          or a JSON-RPC error (for failed requests)
+     *
+     * @example
+     * ```typescript
+     * async handleRequest(request: JSONRPCRequest, context: Context): Promise<JSONRPCResponse | JSONRPCError> {
+     *   switch (request.method) {
+     *     case "ping":
+     *       return {
+     *         jsonrpc: "2.0",
+     *         result: { message: "pong" },
+     *         id: request.id,
+     *       };
+     *     default:
+     *       return {
+     *         jsonrpc: "2.0",
+     *         error: {
+     *           code: -32601,
+     *           message: "Method not found",
+     *         },
+     *         id: request.id,
+     *       };
+     *   }
+     * }
+     * ```
+     */
+    handleRequest(request: JSONRPCRequest, context: Context): Promise<JSONRPCResponse | JSONRPCError>;
+}

package/dist/handlers/request_handler.js

@@ -0,0 +1 @@
+export {};

package/dist/handlers/streamable_http_handler.d.ts

@@ -0,0 +1,81 @@
+import { Context } from "aws-lambda";
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { RequestHandler } from "./request_handler.js";
+/**
+ * Parsed HTTP request data extracted from various Lambda event types
+ */
+export interface ParsedHttpRequest {
+    method: string;
+    headers: Record<string, string | undefined>;
+    body: string | null;
+}
+/**
+ * HTTP response data that can be formatted for different Lambda event types
+ */
+export interface HttpResponse {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * Abstract base class for MCP Streamable HTTP protocol handlers in Lambda functions
+ *
+ * This class handles all the generic JSON-RPC protocol aspects:
+ * - HTTP method validation (POST, OPTIONS, GET)
+ * - Content-Type and Accept header validation
+ * - JSON parsing and validation
+ * - Batch request handling
+ * - CORS headers
+ * - Error response formatting
+ * This class does not implement session management.
+ *
+ * The specific business logic is delegated to a RequestHandler implementation.
+ * Event-specific parsing and response formatting is handled by concrete subclasses.
+ */
+export declare abstract class StreamableHttpHandler<TEvent, TResult> {
+    protected requestHandler: RequestHandler;
+    constructor(requestHandler: RequestHandler);
+    /**
+     * Main handler method that processes Lambda events.
+     * Concrete implementations should call this after parsing the event.
+     */
+    handle(event: TEvent, context: Context): Promise<TResult>;
+    /**
+     * Parse the Lambda event into a common HTTP request format
+     * Must be implemented by concrete subclasses
+     */
+    protected abstract parseEvent(event: TEvent): ParsedHttpRequest;
+    /**
+     * Format the HTTP response for the specific Lambda event type
+     * Must be implemented by concrete subclasses
+     */
+    protected abstract formatResponse(response: HttpResponse): TResult;
+    /**
+     * Process the HTTP request using shared MCP Streamable HTTP logic
+     */
+    protected processHttpRequest(httpRequest: ParsedHttpRequest, context: Context): Promise<HttpResponse>;
+    /**
+     * Get header value in a case-insensitive way
+     */
+    protected getHeaderValue(headers: Record<string, string | undefined>, headerName: string): string | undefined;
+    /**
+     * Create a CORS preflight HTTP response
+     */
+    protected createCorsHttpResponse(): HttpResponse;
+    /**
+     * Create an error HTTP response with proper CORS headers
+     */
+    protected createErrorHttpResponse(statusCode: number, errorCode: ErrorCode, message: string, additionalHeaders?: Record<string, string>, data?: unknown): HttpResponse;
+    /**
+     * Helper function to create JSON-RPC error responses with no ID
+     */
+    protected createJSONRPCErrorResponse(code: ErrorCode, message: string, data?: unknown): {
+        jsonrpc: "2.0";
+        error: {
+            data?: {} | null | undefined;
+            code: ErrorCode;
+            message: string;
+        };
+        id: null;
+    };
+}

package/dist/handlers/streamable_http_handler.js

@@ -0,0 +1,234 @@
+import { isJSONRPCRequest, isJSONRPCResponse, isJSONRPCError, isJSONRPCNotification, ErrorCode, } from "@modelcontextprotocol/sdk/types.js";
+import { createLogger, format, transports } from 'winston';
+const logger = createLogger({
+    level: process.env.LOG_LEVEL?.toLowerCase() || 'info',
+    format: format.simple(),
+    transports: [new transports.Console()],
+});
+/**
+ * Abstract base class for MCP Streamable HTTP protocol handlers in Lambda functions
+ *
+ * This class handles all the generic JSON-RPC protocol aspects:
+ * - HTTP method validation (POST, OPTIONS, GET)
+ * - Content-Type and Accept header validation
+ * - JSON parsing and validation
+ * - Batch request handling
+ * - CORS headers
+ * - Error response formatting
+ * This class does not implement session management.
+ *
+ * The specific business logic is delegated to a RequestHandler implementation.
+ * Event-specific parsing and response formatting is handled by concrete subclasses.
+ */
+export class StreamableHttpHandler {
+    requestHandler;
+    constructor(requestHandler) {
+        this.requestHandler = requestHandler;
+    }
+    /**
+     * Main handler method that processes Lambda events.
+     * Concrete implementations should call this after parsing the event.
+     */
+    async handle(event, context) {
+        try {
+            logger.debug("Incoming event:", JSON.stringify(event, null, 2));
+            // Parse the event into a common HTTP request format
+            const httpRequest = this.parseEvent(event);
+            // Process the HTTP request using shared logic
+            const httpResponse = await this.processHttpRequest(httpRequest, context);
+            // Format the response for the specific event type
+            return this.formatResponse(httpResponse);
+        }
+        catch (error) {
+            logger.error("Error processing MCP Streamable HTTP request:", error);
+            return this.formatResponse(this.createErrorHttpResponse(500, ErrorCode.InternalError, "Internal error", {}, error instanceof Error ? error.message : "Unknown error"));
+        }
+    }
+    /**
+     * Process the HTTP request using shared MCP Streamable HTTP logic
+     */
+    async processHttpRequest(httpRequest, context) {
+        // Handle different HTTP methods according to MCP Streamable HTTP spec
+        logger.debug("Detected HTTP method:", httpRequest.method);
+        if (httpRequest.method === "OPTIONS") {
+            // Handle CORS preflight
+            return this.createCorsHttpResponse();
+        }
+        if (httpRequest.method === "GET") {
+            // No support for SSE streaming in Lambda functions
+            // Return 405 Method Not Allowed as per spec
+            return this.createErrorHttpResponse(405, ErrorCode.ConnectionClosed, "Method Not Allowed: SSE streaming not supported", { Allow: "POST, OPTIONS" });
+        }
+        if (httpRequest.method !== "POST") {
+            return this.createErrorHttpResponse(405, ErrorCode.ConnectionClosed, "Method Not Allowed", { Allow: "POST, OPTIONS" });
+        }
+        // Validate Accept header for POST requests
+        const acceptHeader = this.getHeaderValue(httpRequest.headers, "accept");
+        if (!acceptHeader?.includes("application/json")) {
+            return this.createErrorHttpResponse(406, ErrorCode.ConnectionClosed, "Not Acceptable: Client must accept application/json");
+        }
+        // Validate Content-Type header
+        const contentType = this.getHeaderValue(httpRequest.headers, "content-type");
+        if (!contentType?.includes("application/json")) {
+            return this.createErrorHttpResponse(415, ErrorCode.ConnectionClosed, "Unsupported Media Type: Content-Type must be application/json");
+        }
+        // Parse the request body according to MCP Streamable HTTP spec
+        if (!httpRequest.body) {
+            return this.createErrorHttpResponse(400, ErrorCode.ParseError, "Parse error: Empty request body");
+        }
+        let parsedBody;
+        try {
+            parsedBody = JSON.parse(httpRequest.body);
+        }
+        catch {
+            return this.createErrorHttpResponse(400, ErrorCode.ParseError, "Parse error: Invalid JSON");
+        }
+        // Handle both single messages and batches according to MCP spec
+        let messages;
+        if (Array.isArray(parsedBody)) {
+            messages = parsedBody;
+        }
+        else {
+            messages = [parsedBody];
+        }
+        // Validate that all messages are valid JSON-RPC using schema validation
+        const validatedMessages = [];
+        for (const message of messages) {
+            if (isJSONRPCRequest(message) ||
+                isJSONRPCResponse(message) ||
+                isJSONRPCError(message) ||
+                isJSONRPCNotification(message)) {
+                validatedMessages.push(message);
+            }
+            else {
+                return this.createErrorHttpResponse(400, ErrorCode.InvalidRequest, "Invalid Request: All messages must be valid JSON-RPC 2.0");
+            }
+        }
+        // Check if any message is a request (vs notification/response)
+        const hasRequests = validatedMessages.some(isJSONRPCRequest);
+        if (!hasRequests) {
+            // If it only contains notifications or responses, return 202 Accepted
+            return {
+                statusCode: 202,
+                headers: {
+                    "Access-Control-Allow-Origin": "*",
+                },
+                body: "",
+            };
+        }
+        // Process requests - for Lambda, we'll process them sequentially and return JSON
+        const responses = [];
+        for (const message of validatedMessages) {
+            if (isJSONRPCRequest(message)) {
+                try {
+                    // Delegate to the specific request handler
+                    const response = await this.requestHandler.handleRequest(message, context);
+                    // The handler should return JSONRPCResponse or JSONRPCError for requests
+                    if (isJSONRPCResponse(response) || isJSONRPCError(response)) {
+                        responses.push(response);
+                    }
+                    else {
+                        // Unexpected response format - return internal server error
+                        logger.error("Unexpected response format from request handler:", response);
+                        const errorResponse = {
+                            jsonrpc: "2.0",
+                            error: {
+                                code: ErrorCode.InternalError,
+                                message: "Internal error: Unexpected response format from request handler",
+                                data: "Expected JSONRPCResponse or JSONRPCError",
+                            },
+                            id: message.id,
+                        };
+                        responses.push(errorResponse);
+                    }
+                }
+                catch (error) {
+                    // Return JSON-RPC error response
+                    const errorResponse = {
+                        jsonrpc: "2.0",
+                        error: {
+                            code: ErrorCode.InternalError,
+                            message: "Internal error",
+                            data: error instanceof Error ? error.message : "Unknown error",
+                        },
+                        id: message.id,
+                    };
+                    responses.push(errorResponse);
+                }
+            }
+        }
+        // Prepare response headers
+        const responseHeaders = {
+            "Content-Type": "application/json",
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "POST, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type, Accept, Mcp-Session-Id, Mcp-Protocol-Version",
+        };
+        // Return the response(s)
+        const responseBody = responses.length === 1 ? responses[0] : responses;
+        return {
+            statusCode: 200,
+            headers: responseHeaders,
+            body: JSON.stringify(responseBody),
+        };
+    }
+    /**
+     * Get header value in a case-insensitive way
+     */
+    getHeaderValue(headers, headerName) {
+        // Try exact match first
+        if (headers[headerName] !== undefined) {
+            return headers[headerName];
+        }
+        // Try case-insensitive match
+        const lowerHeaderName = headerName.toLowerCase();
+        for (const [key, value] of Object.entries(headers)) {
+            if (key.toLowerCase() === lowerHeaderName) {
+                return value;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Create a CORS preflight HTTP response
+     */
+    createCorsHttpResponse() {
+        return {
+            statusCode: 200,
+            headers: {
+                "Access-Control-Allow-Origin": "*",
+                "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
+                "Access-Control-Allow-Headers": "Content-Type, Accept, Mcp-Session-Id, Mcp-Protocol-Version",
+            },
+            body: "",
+        };
+    }
+    /**
+     * Create an error HTTP response with proper CORS headers
+     */
+    createErrorHttpResponse(statusCode, errorCode, message, additionalHeaders = {}, data) {
+        return {
+            statusCode,
+            headers: {
+                "Content-Type": "application/json",
+                "Access-Control-Allow-Origin": "*",
+                ...additionalHeaders,
+            },
+            body: JSON.stringify(this.createJSONRPCErrorResponse(errorCode, message, data)),
+        };
+    }
+    /**
+     * Helper function to create JSON-RPC error responses with no ID
+     */
+    createJSONRPCErrorResponse(code, message, data) {
+        return {
+            jsonrpc: "2.0",
+            error: {
+                code,
+                message,
+                ...(data !== undefined && { data }),
+            },
+            id: null,
+        };
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export * from './client/index.js';
-export * from './server-adapter/index.js';
+export * from "./client/index.js";
+export * from "./server-adapter/index.js";
+export * from "./handlers/index.js";

package/dist/index.js

@@ -1,2 +1,3 @@
-export * from './client/index.js';
-export * from './server-adapter/index.js';
+export * from "./client/index.js";
+export * from "./server-adapter/index.js";
+export * from "./handlers/index.js";

package/dist/server-adapter/index.d.ts

@@ -1,4 +1,2 @@
-import { Context } from 'aws-lambda';
-import { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
-export declare function stdioServerAdapter(serverParams: StdioServerParameters, event: JSONRPCMessage, context: Context): Promise<{}>;
+export { stdioServerAdapter } from "./stdio_server_adapter.js";
+export { StdioServerAdapterRequestHandler } from "./stdio_server_adapter_request_handler.js";

package/dist/server-adapter/index.js

@@ -1,110 +1,2 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport, } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { JSONRPCNotificationSchema, JSONRPCRequestSchema, McpError, ResultSchema, ErrorCode, } from '@modelcontextprotocol/sdk/types.js';
-import { z } from 'zod';
-import { createLogger, format, transports } from 'winston';
-const logger = createLogger({
-    level: process.env.LOG_LEVEL?.toLowerCase() || 'info',
-    format: format.simple(),
-    transports: [new transports.Console()],
-});
-export async function stdioServerAdapter(serverParams, event, context) {
-    logger.debug(`Request: ${JSON.stringify(event)}`);
-    const response = await handleMessage(serverParams, event, context);
-    logger.debug(`Response: ${JSON.stringify(response)}`);
-    return response;
-}
-async function handleMessage(serverParams, event, context) {
-    // Determine the type of the message
-    try {
-        const request = JSONRPCRequestSchema.parse(event);
-        return await handleRequest(serverParams, request, context);
-    }
-    catch (error) {
-        if (error instanceof z.ZodError) {
-            try {
-                const notification = JSONRPCNotificationSchema.parse(event);
-                return await handleNotification(serverParams, notification, context);
-            }
-            catch (notificationError) {
-                if (notificationError instanceof z.ZodError) {
-                    return {
-                        jsonrpc: event.jsonrpc,
-                        id: 0,
-                        error: {
-                            code: ErrorCode.InvalidRequest,
-                            message: 'Request is neither a valid JSON-RPC request nor a valid JSON-RPC notification',
-                        },
-                    };
-                }
-                else {
-                    throw notificationError;
-                }
-            }
-        }
-        else {
-            throw error;
-        }
-    }
-}
-async function handleNotification(_serverParams, _event, _context) {
-    // Ignore notifications
-    logger.debug('Ignoring notification');
-    return {};
-}
-async function handleRequest(serverParams, event, _context) {
-    logger.debug('Handling request');
-    const { jsonrpc, id, ...request } = event;
-    const client = new Client({
-        name: 'mcp-client',
-        version: '1.0.0',
-    }, {
-        capabilities: {
-            prompts: {},
-            resources: {},
-            tools: {},
-        },
-    });
-    try {
-        const transport = new StdioClientTransport(serverParams);
-        await client.connect(transport);
-        const result = await client.request(request, ResultSchema);
-        return {
-            jsonrpc: jsonrpc,
-            id: id,
-            result: result,
-        };
-    }
-    catch (error) {
-        if (error instanceof McpError) {
-            logger.error(`MCP error: ${error}`);
-            return {
-                jsonrpc: jsonrpc,
-                id: id,
-                error: {
-                    code: error.code,
-                    message: error.message,
-                },
-            };
-        }
-        else {
-            logger.error(`General exception: ${error}`);
-            return {
-                jsonrpc: jsonrpc,
-                id: id,
-                error: {
-                    code: 500,
-                    message: 'Internal failure, please check Lambda function logs',
-                },
-            };
-        }
-    }
-    finally {
-        try {
-            await client.close();
-        }
-        catch (error) {
-            logger.error(`Did not cleanly close client ${error}`);
-        }
-    }
-}
+export { stdioServerAdapter } from "./stdio_server_adapter.js";
+export { StdioServerAdapterRequestHandler } from "./stdio_server_adapter_request_handler.js";

package/dist/server-adapter/stdio_server_adapter.d.ts

@@ -0,0 +1,17 @@
+import { Context } from "aws-lambda";
+import { StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Lambda function adapter for MCP stdio-based server
+ *
+ * This function provides a bridge between a JSON-RPC message in a Lambda function payload
+ * and an MCP stdio server. It runs the MCP server as a child process of the function invocation,
+ * proxies the message to the MCP server, and returns the server's response.
+ * The MCP server is started and shut down on each function invocation.
+ *
+ * @param serverParams - Configuration for the stdio server (command, args, etc.)
+ * @param event - The JSON-RPC message to process
+ * @param context - AWS Lambda context
+ * @returns Promise resolving to a JSON-RPC response, error, or empty object for notifications
+ */
+export declare function stdioServerAdapter(serverParams: StdioServerParameters, event: JSONRPCMessage, context: Context): Promise<{}>;

package/dist/server-adapter/stdio_server_adapter.js

@@ -0,0 +1,118 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { McpError, ResultSchema, ErrorCode, isJSONRPCRequest, isJSONRPCNotification, } from "@modelcontextprotocol/sdk/types.js";
+import { createLogger, format, transports } from "winston";
+const logger = createLogger({
+    level: process.env.LOG_LEVEL?.toLowerCase() || "info",
+    format: format.simple(),
+    transports: [new transports.Console()],
+});
+/**
+ * Lambda function adapter for MCP stdio-based server
+ *
+ * This function provides a bridge between a JSON-RPC message in a Lambda function payload
+ * and an MCP stdio server. It runs the MCP server as a child process of the function invocation,
+ * proxies the message to the MCP server, and returns the server's response.
+ * The MCP server is started and shut down on each function invocation.
+ *
+ * @param serverParams - Configuration for the stdio server (command, args, etc.)
+ * @param event - The JSON-RPC message to process
+ * @param context - AWS Lambda context
+ * @returns Promise resolving to a JSON-RPC response, error, or empty object for notifications
+ */
+export async function stdioServerAdapter(serverParams, event, context) {
+    logger.debug(`Request: ${JSON.stringify(event)}`);
+    const response = await handleMessage(serverParams, event, context);
+    logger.debug(`Response: ${JSON.stringify(response)}`);
+    return response;
+}
+/**
+ * Handles incoming JSON-RPC messages by determining their type and routing appropriately
+ */
+async function handleMessage(serverParams, event, context) {
+    // Determine the type of the message
+    if (isJSONRPCRequest(event)) {
+        return await handleRequest(serverParams, event, context);
+    }
+    else if (isJSONRPCNotification(event)) {
+        return await handleNotification(serverParams, event, context);
+    }
+    else {
+        // Invalid message format
+        return {
+            jsonrpc: event.jsonrpc,
+            id: 0,
+            error: {
+                code: ErrorCode.InvalidRequest,
+                message: "Request is neither a valid JSON-RPC request nor a valid JSON-RPC notification",
+            },
+        };
+    }
+}
+/**
+ * Handles JSON-RPC notifications (fire-and-forget messages)
+ */
+async function handleNotification(_serverParams, _event, _context) {
+    // Ignore notifications
+    logger.debug("Ignoring notification");
+    return {};
+}
+/**
+ * Handles JSON-RPC requests by starting the MCP server and forwarding the request.
+ */
+async function handleRequest(serverParams, event, _context) {
+    logger.debug("Handling request");
+    const { jsonrpc, id, ...request } = event;
+    const client = new Client({
+        name: "mcp-client",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            prompts: {},
+            resources: {},
+            tools: {},
+        },
+    });
+    try {
+        const transport = new StdioClientTransport(serverParams);
+        await client.connect(transport);
+        const result = await client.request(request, ResultSchema);
+        return {
+            jsonrpc: jsonrpc,
+            id: id,
+            result: result,
+        };
+    }
+    catch (error) {
+        if (error instanceof McpError) {
+            logger.error(`MCP error: ${error}`);
+            return {
+                jsonrpc: jsonrpc,
+                id: id,
+                error: {
+                    code: error.code,
+                    message: error.message,
+                },
+            };
+        }
+        else {
+            logger.error(`General exception: ${error}`);
+            return {
+                jsonrpc: jsonrpc,
+                id: id,
+                error: {
+                    code: 500,
+                    message: "Internal failure, please check Lambda function logs",
+                },
+            };
+        }
+    }
+    finally {
+        try {
+            await client.close();
+        }
+        catch (error) {
+            logger.error(`Did not cleanly close client ${error}`);
+        }
+    }
+}

package/dist/server-adapter/stdio_server_adapter.test.d.ts

@@ -0,0 +1 @@
+export {};