@aws/run-mcp-servers-with-aws-lambda 0.4.0 → 0.4.2

package/README.md

@@ -1,5 +1,8 @@
 # Run Model Context Protocol (MCP) servers with AWS Lambda
 
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/run-mcp-servers-with-aws-lambda?style=for-the-badge&label=PyPi%20Downloads&color=blue)](https://pypi.org/project/run-mcp-servers-with-aws-lambda/)
+[![NPM Downloads](https://img.shields.io/npm/dm/%40aws%2Frun-mcp-servers-with-aws-lambda?style=for-the-badge&label=NPM%20Downloads&color=blue)](https://www.npmjs.com/package/@aws/run-mcp-servers-with-aws-lambda)
+
 This project enables you to run [Model Context Protocol](https://modelcontextprotocol.io) stdio-based servers in AWS Lambda functions.
 
 Currently, most implementations of MCP servers and clients are entirely local on a single machine.
@@ -156,7 +159,7 @@ from mcp.client.streamable_http import streamablehttp_client
 # Create OAuth client provider here
 
 async with streamablehttp_client(
-    url="https://abc123.execute-api.us-east-2.amazonaws.com/prod/mcp",
+    url="https://abc123.execute-api.us-west-2.amazonaws.com/prod/mcp",
     auth=oauth_client_provider,
 ) as (
     read_stream,
@@ -195,7 +198,7 @@ const client = new Client(
 // Create OAuth client provider here
 
 const transport = new StreamableHTTPClientTransport(
-  "https://abc123.execute-api.us-east-2.amazonaws.com/prod/mcp",
+  "https://abc123.execute-api.us-west-2.amazonaws.com/prod/mcp",
   {
     authProvider: oauthProvider,
   }
@@ -229,40 +232,16 @@ such as Amazon Cognito, Okta, or Auth0.
 
 Using Bedrock AgentCore Gateway in front of your stdio-based MCP server requires that
 you retrieve the MCP server's tool schema, and provide it in the
-[AgentCore Gateway Lambda target configuration](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-add-target-lambda.html#gateway-lambda-schema).
+[AgentCore Gateway Lambda target configuration](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-add-target-lambda.html#gateway-building-lambda-multiple-tools).
 AgentCore Gateway can then advertise the schema to HTTP clients and validate request inputs and outputs.
 
-To retrieve your stdio-based MCP server's tool schema:
-
-1. Start the MCP inspector: `npx @modelcontextprotocol/inspector`
-2. Open the inspector tool in your web browser using the localhost link shown.
-3. In the left-hand column, select STDIO transport type, and fill in your server's command and arguments. For example, command `uvx` and arguments `mcp-server-time`.
-4. Click Connect.
-5. In the main panel, select Tools and click "List Tools".
-6. In the bottom "History" panel, select the `tools/list` request.
-7. In the Response box, click the Copy clipboard icon in the upper-right corner of the box.
-8. Paste the JSON into a new file. It should begin with `{ tools:[...`
-9. Add a new key "arn" to your JSON file with the value of your Lambda function's ARN.
-
-Your Lambda function schema should now look something like this:
-
-```json
-{
-  "arn": "arn:aws:lambda:us-west-2:123456789012:function:MyFunction",
-  "tools": [
-    {
-      "name": "process_data",
-      "description": "Process input data",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "input": { "type": "string" }
-        },
-        "required": ["input"]
-      }
-    }
-  ]
-}
+To retrieve and save your stdio-based MCP server's tool schema to a file, run:
+
+```bash
+npx @modelcontextprotocol/inspector --cli --method tools/list <your MCP server command and arguments> > tool-schema.json
+
+# For example:
+npx @modelcontextprotocol/inspector --cli --method tools/list uvx mcp-server-time > tool-schema.json
 ```
 
 <details>
@@ -293,6 +272,8 @@ def handler(event, context):
     return event_handler.handle(event, context)
 ```
 
+See a full, deployable example [here](examples/servers/book-search/).
+
 </details>
 
 <details>
@@ -321,13 +302,15 @@ const requestHandler = new BedrockAgentCoreGatewayTargetHandler(
 );
 
 export const handler: Handler = async (
-  event: event: Record<string, unknown>,
+  event: Record<string, unknown>,
   context: Context
-): Promise<event: Record<string, unknown>> => {
+): Promise<Record<string, unknown>> => {
   return requestHandler.handle(event, context);
 };
 ```
 
+See a full, deployable example [here](examples/servers/dictionary/).
+
 </details>
 
 <details>
@@ -493,9 +476,9 @@ from mcp import ClientSession
 from mcp_lambda.client.streamable_http_sigv4 import streamablehttp_client_with_sigv4
 
 async with streamablehttp_client_with_sigv4(
-    url="https://url-id-12345.lambda-url.us-east-2.on.aws",
+    url="https://url-id-12345.lambda-url.us-west-2.on.aws",
     service="lambda",
-    region="us-east-2",
+    region="us-west-2",
 ) as (
     read_stream,
     write_stream,
@@ -531,10 +514,10 @@ const client = new Client(
 );
 
 const transport = new StreamableHTTPClientWithSigV4Transport(
-  new URL("https://url-id-12345.lambda-url.us-east-2.on.aws"),
+  new URL("https://url-id-12345.lambda-url.us-west-2.on.aws"),
   {
     service: "lambda",
-    region: "us-east-2",
+    region: "us-west-2",
   }
 );
 await client.connect(transport);
@@ -627,7 +610,7 @@ from mcp_lambda import LambdaFunctionParameters, lambda_function_client
 
 server_params = LambdaFunctionParameters(
     function_name="my-mcp-server-function",
-    region_name="us-east-2",
+    region_name="us-west-2",
 )
 
 async with lambda_function_client(server_params) as (
@@ -656,7 +639,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 
 const serverParams: LambdaFunctionParameters = {
   functionName: "my-mcp-server-function",
-  regionName: "us-east-2",
+  regionName: "us-west-2",
 };
 
 const client = new Client(

package/dist/handlers/bedrockAgentCoreGatewayTargetHandler.d.ts

@@ -13,5 +13,5 @@ export declare class BedrockAgentCoreGatewayTargetHandler {
     /**
      * Handle Lambda invocation from Bedrock AgentCore Gateway
      */
-    handleEvent(event: Record<string, unknown>, context: Context): Promise<unknown>;
+    handle(event: Record<string, unknown>, context: Context): Promise<unknown>;
 }

package/dist/handlers/bedrockAgentCoreGatewayTargetHandler.js

@@ -14,12 +14,21 @@ export class BedrockAgentCoreGatewayTargetHandler {
     /**
      * Handle Lambda invocation from Bedrock AgentCore Gateway
      */
-    async handleEvent(event, context) {
+    async handle(event, context) {
         // Extract tool metadata from context
-        const toolName = context.clientContext?.Custom?.["bedrockagentcoreToolName"];
-        if (!toolName) {
-            throw new Error("Missing bedrockagentcoreToolName in context");
+        const clientContext = context.clientContext;
+        const custom = clientContext?.["custom"];
+        const gatewayToolName = custom?.["bedrockAgentCoreToolName"];
+        if (!gatewayToolName) {
+            throw new Error("Missing bedrockAgentCoreToolName in context");
         }
+        // Gateway names the tools like <target name>___<tool name>
+        const delimiter = "___";
+        const delimiterIndex = gatewayToolName.indexOf(delimiter);
+        if (delimiterIndex === -1) {
+            throw new Error(`Invalid gateway tool name format: ${gatewayToolName}`);
+        }
+        const toolName = gatewayToolName.substring(delimiterIndex + delimiter.length);
         // Create JSON-RPC request from gateway event
         const jsonRpcRequest = {
             jsonrpc: "2.0",

package/dist/handlers/handlers.test.js

@@ -4,13 +4,18 @@ import { APIGatewayProxyEventHandler, APIGatewayProxyEventV2Handler, LambdaFunct
 class MockRequestHandler {
     responses = new Map();
     shouldThrow = false;
+    lastCall = null;
     setResponse(method, response) {
         this.responses.set(method, response);
     }
     setShouldThrow(shouldThrow) {
         this.shouldThrow = shouldThrow;
     }
+    getLastCall() {
+        return this.lastCall;
+    }
     async handleRequest(request, _context) {
+        this.lastCall = request;
         if (this.shouldThrow) {
             throw new Error("Mock handler error");
         }
@@ -636,8 +641,8 @@ describe("BedrockAgentCoreGatewayTargetHandler", () => {
         handler = new BedrockAgentCoreGatewayTargetHandler(mockRequestHandler);
         mockContext = {
             clientContext: {
-                Custom: {
-                    bedrockagentcoreToolName: "test_tool",
+                custom: {
+                    bedrockAgentCoreToolName: "target___test_tool",
                 },
             },
         };
@@ -650,13 +655,48 @@ describe("BedrockAgentCoreGatewayTargetHandler", () => {
         };
         mockRequestHandler.setResponse("tools/call", expectedResponse);
         const event = { param1: "value1", param2: "value2" };
-        const result = await handler.handleEvent(event, mockContext);
+        const result = await handler.handle(event, mockContext);
         expect(result).toEqual({ message: "Tool executed successfully" });
+        // Verify the extracted tool name is everything after the first delimiter
+        const lastCall = mockRequestHandler.getLastCall();
+        expect(lastCall?.params?.name).toBe("test_tool");
     });
     it("should throw error when tool name is missing", async () => {
-        const contextWithoutTool = { clientContext: { Custom: {} } };
+        const contextWithoutTool = { clientContext: { custom: {} } };
+        const event = { param1: "value1" };
+        await expect(handler.handle(event, contextWithoutTool)).rejects.toThrow("Missing bedrockAgentCoreToolName in context");
+    });
+    it("should throw error when tool name format is invalid", async () => {
+        const contextWithInvalidFormat = {
+            clientContext: {
+                custom: {
+                    bedrockAgentCoreToolName: "invalid_format",
+                },
+            },
+        };
+        const event = { param1: "value1" };
+        await expect(handler.handle(event, contextWithInvalidFormat)).rejects.toThrow("Invalid gateway tool name format: invalid_format");
+    });
+    it("should handle tool name with multiple delimiters", async () => {
+        const contextWithMultipleDelimiters = {
+            clientContext: {
+                custom: {
+                    bedrockAgentCoreToolName: "target___test___tool",
+                },
+            },
+        };
+        const expectedResponse = {
+            jsonrpc: "2.0",
+            result: { message: "Tool executed successfully" },
+            id: 1,
+        };
+        mockRequestHandler.setResponse("tools/call", expectedResponse);
         const event = { param1: "value1" };
-        await expect(handler.handleEvent(event, contextWithoutTool)).rejects.toThrow("Missing bedrockagentcoreToolName in context");
+        const result = await handler.handle(event, contextWithMultipleDelimiters);
+        expect(result).toEqual({ message: "Tool executed successfully" });
+        // Verify the extracted tool name is everything after the first delimiter
+        const lastCall = mockRequestHandler.getLastCall();
+        expect(lastCall?.params?.name).toBe("test___tool");
     });
     it("should throw error when request handler returns error", async () => {
         const errorResponse = {
@@ -666,6 +706,6 @@ describe("BedrockAgentCoreGatewayTargetHandler", () => {
         };
         mockRequestHandler.setResponse("tools/call", errorResponse);
         const event = { param1: "value1" };
-        await expect(handler.handleEvent(event, mockContext)).rejects.toThrow("Method not found");
+        await expect(handler.handle(event, mockContext)).rejects.toThrow("Method not found");
     });
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aws/run-mcp-servers-with-aws-lambda",
   "description": "Run Model Context Protocol (MCP) servers with AWS Lambda",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "license": "Apache-2.0",
   "author": {
@@ -39,29 +39,29 @@
     "dist"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.32.0",
+    "@eslint/js": "^9.33.0",
     "@tsconfig/recommended": "^1.0.10",
     "@types/aws-lambda": "^8.10.152",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.1.0",
+    "@types/node": "^24.3.0",
     "aws-sdk-client-mock": "^4.1.0",
     "aws-sdk-client-mock-jest": "^4.1.0",
-    "eslint": "^9.30.1",
+    "eslint": "^9.33.0",
     "eslint-plugin-check-file": "^3.3.0",
     "jest": "^30.0.5",
-    "ts-jest": "^29.4.0",
-    "tsx": "^4.20.3",
+    "ts-jest": "^29.4.1",
+    "tsx": "^4.20.4",
     "typescript": "^5.9.2",
-    "typescript-eslint": "^8.39.0"
+    "typescript-eslint": "^8.40.0"
   },
   "dependencies": {
     "@aws-crypto/sha256-js": "^5.2.0",
-    "@aws-sdk/client-lambda": "^3.859.0",
+    "@aws-sdk/client-lambda": "^3.873.0",
     "@aws-sdk/credential-provider-node": "^3.859.0",
     "@aws-sdk/protocol-http": "^3.374.0",
     "@aws-sdk/types": "^3.840.0",
-    "@modelcontextprotocol/sdk": "^1.17.1",
-    "@smithy/signature-v4": "^5.1.2",
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "@smithy/signature-v4": "^5.1.3",
     "winston": "^3.17.0"
   }
 }