@aws/run-mcp-servers-with-aws-lambda 0.0.1

package/dist/client/index.d.ts

@@ -0,0 +1,27 @@
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+export type LambdaFunctionParameters = {
+    /**
+     * The name or ARN of the Lambda function, version, or alias.
+     */
+    functionName: string;
+    /**
+     * The AWS region of the Lambda function.
+     */
+    regionName?: string;
+};
+/**
+ * Client transport for Lambda functions:
+ * this will connect to a server by calling the Lambda Invoke API.
+ */
+export declare class LambdaFunctionClientTransport implements Transport {
+    private _serverParams;
+    private _lambdaClient;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(server: LambdaFunctionParameters);
+    start(): Promise<void>;
+    close(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+}

package/dist/client/index.js

@@ -0,0 +1,51 @@
+import { LambdaClient, InvokeCommand } from "@aws-sdk/client-lambda";
+/**
+ * Client transport for Lambda functions:
+ * this will connect to a server by calling the Lambda Invoke API.
+ */
+export class LambdaFunctionClientTransport {
+    _serverParams;
+    _lambdaClient;
+    onclose;
+    onerror;
+    onmessage;
+    constructor(server) {
+        this._serverParams = server;
+        this._lambdaClient = new LambdaClient({
+            region: this._serverParams.regionName,
+        });
+    }
+    async start() {
+        // no-op
+    }
+    async close() {
+        // no-op
+    }
+    async send(message) {
+        try {
+            const invokeCommand = new InvokeCommand({
+                FunctionName: this._serverParams.functionName,
+                InvocationType: "RequestResponse",
+                Payload: JSON.stringify(message),
+            });
+            const invokeCommandOutput = await this._lambdaClient.send(invokeCommand);
+            if (invokeCommandOutput.Payload) {
+                const responseMessage = Buffer.from(invokeCommandOutput.Payload).toString("utf-8");
+                if (invokeCommandOutput.FunctionError) {
+                    throw new Error(`${invokeCommandOutput.FunctionError} ${responseMessage}`);
+                }
+                if (responseMessage === "{}") {
+                    // Assume we sent a notification and do not expect a response
+                    return;
+                }
+                this.onmessage?.(JSON.parse(responseMessage));
+            }
+            else {
+                throw new Error("No payload returned from Lambda function");
+            }
+        }
+        catch (error) {
+            this.onerror?.(error);
+        }
+    }
+}

package/dist/client/index.test.d.ts

@@ -0,0 +1 @@
+import "aws-sdk-client-mock-jest";

package/dist/client/index.test.js

@@ -0,0 +1,191 @@
+import "aws-sdk-client-mock-jest";
+import { LambdaClient, InvokeCommand } from "@aws-sdk/client-lambda";
+import { LambdaFunctionClientTransport, } from "./index.js";
+import { Uint8ArrayBlobAdapter } from "@smithy/util-stream";
+import { mockClient } from "aws-sdk-client-mock";
+describe("LambdaFunctionClientTransport", () => {
+    // Mock implementation of LambdaClient
+    const lambdaMock = mockClient(LambdaClient);
+    // Reset mocks before each test
+    beforeEach(() => {
+        jest.clearAllMocks();
+        lambdaMock.reset();
+    });
+    describe("constructor", () => {
+        test("should initialize client with provided region", async () => {
+            const params = {
+                functionName: "test-function",
+                regionName: "not-a-region",
+            };
+            const message = {
+                jsonrpc: "2.0",
+                id: 1,
+                method: "test-method",
+            };
+            const transport = new LambdaFunctionClientTransport(params);
+            lambdaMock.on(InvokeCommand).resolvesOnce({
+                Payload: Uint8ArrayBlobAdapter.fromString(JSON.stringify({ result: "success" })),
+            });
+            await transport.send(message);
+            expect(await lambdaMock.call(0).thisValue.config.region()).toBe("not-a-region");
+        });
+        test("should use the default region", async () => {
+            const originalRegion = process.env.AWS_REGION;
+            process.env.AWS_REGION = "default-region";
+            try {
+                const params = {
+                    functionName: "test-function",
+                };
+                const message = {
+                    jsonrpc: "2.0",
+                    id: 1,
+                    method: "test-method",
+                };
+                const transport = new LambdaFunctionClientTransport(params);
+                lambdaMock.on(InvokeCommand).resolvesOnce({
+                    Payload: Uint8ArrayBlobAdapter.fromString(JSON.stringify({ result: "success" })),
+                });
+                await transport.send(message);
+                expect(await lambdaMock.call(0).thisValue.config.region()).toBe("default-region");
+            }
+            finally {
+                process.env.AWS_REGION = originalRegion;
+            }
+        });
+    });
+    describe("start and close methods", () => {
+        test("start method should be a no-op", async () => {
+            const params = {
+                functionName: "test-function",
+            };
+            const transport = new LambdaFunctionClientTransport(params);
+            await expect(transport.start()).resolves.toBeUndefined();
+        });
+        test("close method should be a no-op", async () => {
+            const params = {
+                functionName: "test-function",
+            };
+            const transport = new LambdaFunctionClientTransport(params);
+            await expect(transport.close()).resolves.toBeUndefined();
+        });
+    });
+    describe("send method", () => {
+        test("should invoke Lambda function with correct parameters", async () => {
+            const params = {
+                functionName: "test-function",
+            };
+            const message = {
+                jsonrpc: "2.0",
+                id: 1,
+                method: "test-method",
+            };
+            const transport = new LambdaFunctionClientTransport(params);
+            lambdaMock.on(InvokeCommand).resolvesOnce({
+                Payload: Uint8ArrayBlobAdapter.fromString(JSON.stringify({ result: "success" })),
+            });
+            await transport.send(message);
+            expect(lambdaMock).toHaveReceivedCommandTimes(InvokeCommand, 1);
+            expect(lambdaMock).toHaveReceivedCommandWith(InvokeCommand, {
+                FunctionName: "test-function",
+                InvocationType: "RequestResponse",
+                Payload: JSON.stringify(message),
+            });
+        });
+        test("should call onmessage with parsed response", async () => {
+            const params = {
+                functionName: "test-function",
+            };
+            const message = {
+                jsonrpc: "2.0",
+                id: 1,
+                method: "test-method",
+            };
+            const responsePayload = {
+                jsonrpc: "2.0",
+                id: 1,
+                result: { data: "test-data" },
+            };
+            const transport = new LambdaFunctionClientTransport(params);
+            const onMessageMock = jest.fn();
+            transport.onmessage = onMessageMock;
+            lambdaMock.on(InvokeCommand).resolvesOnce({
+                Payload: Uint8ArrayBlobAdapter.fromString(JSON.stringify(responsePayload)),
+            });
+            await transport.send(message);
+            expect(onMessageMock).toHaveBeenCalledTimes(1);
+            expect(onMessageMock).toHaveBeenCalledWith(responsePayload);
+        });
+        test("should not call onmessage for empty response", async () => {
+            const params = {
+                functionName: "test-function",
+            };
+            const message = {
+                jsonrpc: "2.0",
+                method: "notification",
+            };
+            const transport = new LambdaFunctionClientTransport(params);
+            const onMessageMock = jest.fn();
+            transport.onmessage = onMessageMock;
+            lambdaMock.on(InvokeCommand).resolvesOnce({
+                Payload: Uint8ArrayBlobAdapter.fromString("{}"),
+            });
+            await transport.send(message);
+            expect(onMessageMock).not.toHaveBeenCalled();
+        });
+        test("should throw error when Lambda function returns an error", async () => {
+            const params = {
+                functionName: "test-function",
+            };
+            const message = {
+                jsonrpc: "2.0",
+                id: 1,
+                method: "test-method",
+            };
+            const transport = new LambdaFunctionClientTransport(params);
+            const onErrorMock = jest.fn();
+            transport.onerror = onErrorMock;
+            lambdaMock.on(InvokeCommand).resolvesOnce({
+                FunctionError: "Unhandled",
+                Payload: Uint8ArrayBlobAdapter.fromString("Error executing function"),
+            });
+            await transport.send(message);
+            expect(onErrorMock).toHaveBeenCalledTimes(1);
+            expect(onErrorMock.mock.calls[0][0].message).toBe("Unhandled Error executing function");
+        });
+        test("should call onerror when Lambda client throws an error", async () => {
+            const params = {
+                functionName: "test-function",
+            };
+            const message = {
+                jsonrpc: "2.0",
+                id: 1,
+                method: "test-method",
+            };
+            const transport = new LambdaFunctionClientTransport(params);
+            const onErrorMock = jest.fn();
+            transport.onerror = onErrorMock;
+            const error = new Error("Network error");
+            lambdaMock.rejects(error);
+            await transport.send(message);
+            expect(onErrorMock).toHaveBeenCalledTimes(1);
+            expect(onErrorMock).toHaveBeenCalledWith(error);
+        });
+        test("should handle case when no Payload is returned", async () => {
+            const params = {
+                functionName: "test-function",
+            };
+            const message = {
+                jsonrpc: "2.0",
+                id: 1,
+                method: "test-method",
+            };
+            const transport = new LambdaFunctionClientTransport(params);
+            const onErrorMock = jest.fn();
+            transport.onerror = onErrorMock;
+            lambdaMock.on(InvokeCommand).resolvesOnce({});
+            await transport.send(message);
+            expect(onErrorMock).toHaveBeenCalledTimes(1);
+            expect(onErrorMock).toHaveBeenCalledWith(new Error("No payload returned from Lambda function"));
+        });
+    });
+});

package/dist/index.d.ts

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

package/dist/index.js

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

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

@@ -0,0 +1,4 @@
+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<{}>;

package/dist/server-adapter/index.js

@@ -0,0 +1,110 @@
+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}`);
+        }
+    }
+}

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

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

package/dist/server-adapter/index.test.js

@@ -0,0 +1,189 @@
+import { ErrorCode, } from '@modelcontextprotocol/sdk/types.js';
+import { stdioServerAdapter } from './index.js';
+const serverParameters = {
+    command: 'npx',
+    args: ['tsx', 'test-stdio-server/echo_server.ts'],
+};
+const mockContext = {
+    callbackWaitsForEmptyEventLoop: true,
+    functionName: 'test-function',
+    functionVersion: '1',
+    invokedFunctionArn: 'test-arn',
+    memoryLimitInMB: '128',
+    awsRequestId: 'test-id',
+    logGroupName: 'test-group',
+    logStreamName: 'test-stream',
+    getRemainingTimeInMillis: () => 1000,
+    done: () => { },
+    fail: () => { },
+    succeed: () => { },
+};
+test('should respond to pings', async () => {
+    const pingMessage = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'ping',
+    };
+    const expectedResponse = {
+        jsonrpc: '2.0',
+        id: 1,
+        result: {},
+    };
+    const response = (await stdioServerAdapter(serverParameters, pingMessage, mockContext));
+    expect(response).toEqual(expectedResponse);
+});
+test('should respond to initialize', async () => {
+    const initializeMessage = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            clientInfo: { name: 'mcp', version: '0.1.0' },
+        },
+    };
+    const response = (await stdioServerAdapter(serverParameters, initializeMessage, mockContext));
+    expect(response.jsonrpc).toEqual('2.0');
+    expect(response.id).toEqual(1);
+    expect(response).toHaveProperty('result');
+});
+test('should list tools', async () => {
+    const listToolsMessage = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/list',
+    };
+    const expectedResponse = {
+        jsonrpc: '2.0',
+        id: 1,
+        result: {
+            tools: [
+                {
+                    name: 'echo',
+                    inputSchema: {
+                        $schema: 'http://json-schema.org/draft-07/schema#',
+                        additionalProperties: false,
+                        properties: {
+                            message: { type: 'string' },
+                        },
+                        required: ['message'],
+                        type: 'object',
+                    },
+                },
+            ],
+        },
+    };
+    const response = (await stdioServerAdapter(serverParameters, listToolsMessage, mockContext));
+    expect(response).toEqual(expectedResponse);
+});
+test('should call a tool', async () => {
+    const callToolsMessage = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: {
+            name: 'echo',
+            arguments: {
+                message: 'Hello world',
+            },
+        },
+    };
+    const expectedResponse = {
+        jsonrpc: '2.0',
+        id: 1,
+        result: {
+            content: [{ type: 'text', text: 'Echo: Hello world' }],
+        },
+    };
+    const response = (await stdioServerAdapter(serverParameters, callToolsMessage, mockContext));
+    expect(response).toEqual(expectedResponse);
+});
+test('accepts a notification', async () => {
+    const notification = {
+        jsonrpc: '2.0',
+        method: 'notifications/initialized',
+    };
+    const response = (await stdioServerAdapter(serverParameters, notification, mockContext));
+    expect(response).toEqual({});
+});
+test('return error for invalid request', async () => {
+    const invalidRequest = {
+        jsonrpc: '2.0',
+        id: 1,
+        error: {
+            code: 400,
+            message: 'Invalid request',
+        },
+    };
+    const expectedResponse = {
+        jsonrpc: '2.0',
+        id: 0,
+        error: {
+            code: ErrorCode.InvalidRequest,
+            message: 'Request is neither a valid JSON-RPC request nor a valid JSON-RPC notification',
+        },
+    };
+    const response = (await stdioServerAdapter(serverParameters, invalidRequest, mockContext));
+    expect(response).toEqual(expectedResponse);
+});
+test('return internal failure for invalid server params', async () => {
+    const invalidServerParams = {
+        command: 'does-not-exist',
+    };
+    const pingMessage = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'ping',
+    };
+    const expectedResponse = {
+        jsonrpc: '2.0',
+        id: 1,
+        error: {
+            code: 500,
+            message: 'Internal failure, please check Lambda function logs',
+        },
+    };
+    const response = (await stdioServerAdapter(invalidServerParams, pingMessage, mockContext));
+    expect(response).toEqual(expectedResponse);
+});
+test('return error for unknown method', async () => {
+    const invalidMessage = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'does-not-exist',
+    };
+    const expectedResponse = {
+        jsonrpc: '2.0',
+        id: 1,
+        error: {
+            code: ErrorCode.MethodNotFound,
+            message: 'MCP error -32601: Method not found',
+        },
+    };
+    const response = (await stdioServerAdapter(serverParameters, invalidMessage, mockContext));
+    expect(response).toEqual(expectedResponse);
+});
+test('return error for unknown tool call', async () => {
+    const callToolsMessage = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: {
+            name: 'does-not-exist',
+            arguments: {
+                message: 'Hello world',
+            },
+        },
+    };
+    const expectedResponse = {
+        jsonrpc: '2.0',
+        id: 1,
+        error: {
+            code: ErrorCode.InvalidParams,
+            message: 'MCP error -32602: MCP error -32602: Tool does-not-exist not found',
+        },
+    };
+    const response = (await stdioServerAdapter(serverParameters, callToolsMessage, mockContext));
+    expect(response).toEqual(expectedResponse);
+});

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@aws/run-mcp-servers-with-aws-lambda",
+  "description": "Run Model Context Protocol (MCP) servers with AWS Lambda",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Amazon Web Services",
+    "url": "http://aws.amazon.com"
+  },
+  "homepage": "https://github.com/awslabs/run-model-context-protocol-servers-with-aws-lambda",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awslabs/run-model-context-protocol-servers-with-aws-lambda.git"
+  },
+  "bugs": {
+    "url": "https://github.com/awslabs/run-model-context-protocol-servers-with-aws-lambda/issues"
+  },
+  "keywords": [
+    "aws",
+    "lambda",
+    "mcp",
+    "modelcontextprotocol"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "tsc",
+    "clean": "rm -rf dist/",
+    "lint": "eslint src/",
+    "test": "jest",
+    "test-server": "tsx test-stdio-server/echo_server.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.8.0",
+    "@tsconfig/recommended": "^1.0.2",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.14.0",
+    "aws-sdk-client-mock": "^4.1.0",
+    "aws-sdk-client-mock-jest": "^4.1.0",
+    "eslint": "^9.8.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.3.1",
+    "tsx": "^4.16.5",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.29.0"
+  },
+  "dependencies": {
+    "@aws-sdk/client-lambda": "^3.777.0",
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "@types/aws-lambda": "^8.10.148",
+    "winston": "^3.17.0"
+  }
+}