@aws/run-mcp-servers-with-aws-lambda 0.5.12 → 0.5.14

package/README.md

@@ -150,6 +150,158 @@ node /var/task/node_modules/@ivotoby/openapi-mcp-server/bin/mcp-server.js
 
 </details>
 
+### Passing credentials and other secrets to the MCP server
+
+This library does not provide out-of-the-box mechanisms for managing any secrets needed by the wrapped
+MCP server. For example, the [GitHub MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/github)
+and the [Brave search MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search)
+require API keys to make requests to third-party APIs.
+You may configure these API keys as
+[encrypted environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars-encryption.html)
+in the Lambda function's configuration or retrieve them from Secrets Manager in the Lambda function code (examples below).
+However, note that anyone with access to invoke the Lambda function
+will then have access to use your API key to call the third-party APIs by invoking the function.
+We recommend limiting access to the Lambda function using
+[least-privilege IAM policies](https://docs.aws.amazon.com/lambda/latest/dg/security-iam.html).
+If you use an identity-based authentication mechanism such as OAuth, you could also store and retrieve API keys per user but there are no implementation examples in this repository.
+
+<details>
+
+<summary><b>Python server example retrieving an API key from Secrets Manager</b></summary>
+
+```python
+import sys
+
+import boto3
+from mcp.client.stdio import StdioServerParameters
+
+# Retrieve API key from Secrets Manager
+secrets_client = boto3.client("secretsmanager")
+api_key = secrets_client.get_secret_value(SecretId="my-api-key-secret")["SecretString"]
+
+server_params = StdioServerParameters(
+    command=sys.executable,
+    args=["-m", "my_mcp_server"],
+    env={
+        "API_KEY": api_key,
+    },
+)
+```
+
+</details>
+
+<details>
+
+<summary><b>Typescript server example retrieving an API key from Secrets Manager</b></summary>
+
+```typescript
+import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
+
+const secretsClient = new SecretsManagerClient({});
+const secret = await secretsClient.send(
+  new GetSecretValueCommand({ SecretId: "my-api-key-secret" })
+);
+const apiKey = secret.SecretString;
+
+const serverParams = {
+  command: "npx",
+  args: ["--offline", "my-mcp-server"],
+  env: {
+    API_KEY: apiKey,
+  },
+};
+```
+
+</details>
+<br/>
+
+If your MCP server needs to call AWS APIs (such as the [MCP servers for AWS](https://github.com/awslabs/mcp)),
+you can pass the Lambda function's AWS credentials to the wrapped MCP server via environment variables.
+The wrapped MCP server's child process does not automatically inherit the Lambda execution role's credentials.
+Again, note that anyone with access to invoke the Lambda function
+will then have access to use the function's AWS credentials to call AWS APIs by invoking the function.
+We recommend limiting access to the Lambda function using
+[least-privilege IAM policies](https://docs.aws.amazon.com/lambda/latest/dg/security-iam.html).
+
+<details>
+
+<summary><b>Python server example using AWS credentials via environment variables</b></summary>
+
+```python
+import os
+import sys
+
+import boto3
+from mcp.client.stdio import StdioServerParameters
+
+# Get AWS credentials from Lambda execution role to pass to subprocess
+session = boto3.Session()
+credentials = session.get_credentials()
+if credentials is None:
+    raise RuntimeError("Unable to retrieve AWS credentials from the execution environment")
+resolved = credentials.get_frozen_credentials()
+
+server_params = StdioServerParameters(
+    command=sys.executable,
+    args=["-m", "my_mcp_server"],
+    env={
+        "AWS_REGION": os.environ.get("AWS_REGION", "us-west-2"),
+        "AWS_DEFAULT_REGION": os.environ.get("AWS_REGION", "us-west-2"),
+        "AWS_ACCESS_KEY_ID": resolved.access_key,
+        "AWS_SECRET_ACCESS_KEY": resolved.secret_key,
+        "AWS_SESSION_TOKEN": resolved.token or "",
+    },
+)
+```
+
+</details>
+
+<details>
+
+<summary><b>Python server example using AWS credentials via credentials file</b></summary>
+
+Some MCP servers require an AWS profile and do not support credentials passed via environment variables.
+In this case, you can write the credentials to a file and point the MCP server to it.
+
+```python
+import os
+import sys
+
+import boto3
+from mcp.client.stdio import StdioServerParameters
+
+# Get AWS credentials from Lambda execution role to pass to subprocess
+session = boto3.Session()
+credentials = session.get_credentials()
+if credentials is None:
+    raise RuntimeError("Unable to retrieve AWS credentials from the execution environment")
+resolved = credentials.get_frozen_credentials()
+
+# Write credentials to disk as default profile
+aws_dir = "/tmp/.aws"
+os.makedirs(aws_dir, exist_ok=True)
+with open(f"{aws_dir}/credentials", "w") as f:
+    f.write("[default]\n")
+    f.write(f"aws_access_key_id = {resolved.access_key}\n")
+    f.write(f"aws_secret_access_key = {resolved.secret_key}\n")
+    if resolved.token:
+        f.write(f"aws_session_token = {resolved.token}\n")
+
+server_params = StdioServerParameters(
+    command=sys.executable,
+    args=["-m", "my_mcp_server"],
+    env={
+        "AWS_REGION": os.environ.get("AWS_REGION", "us-west-2"),
+        "AWS_DEFAULT_REGION": os.environ.get("AWS_REGION", "us-west-2"),
+        "AWS_SHARED_CREDENTIALS_FILE": f"{aws_dir}/credentials",
+    },
+)
+```
+
+See a full, deployable example [here](examples/servers/sns-sqs/).
+
+</details>
+
 ## Use API Gateway
 
 ```mermaid
@@ -341,6 +493,14 @@ npx @modelcontextprotocol/inspector --cli --method tools/list <your MCP server c
 npx @modelcontextprotocol/inspector --cli --method tools/list uvx mcp-server-time > tool-schema.json
 ```
 
+Some MCP servers generate tool schemas that AgentCore Gateway rejects with strict validation,
+such as `"items": {}`, `"default": null`, or `anyOf` with `{"type": "null"}`.
+You may need to clean up the schema before using it:
+
+```bash
+python3 scripts/clean-tool-schema.py tool-schema.json
+```
+
 <details>
 
 <summary><b>Python server example</b></summary>
@@ -780,17 +940,6 @@ See a full example as part of the sample chatbot [here](examples/chatbots/typesc
   the [sqlite MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite),
   the [filesystem MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem),
   and the [git MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/git).
-- This library does not provide mechanisms for managing any secrets needed by the wrapped
-  MCP server. For example, the [GitHub MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/github)
-  and the [Brave search MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search)
-  require API keys to make requests to third-party APIs.
-  You may configure these API keys as
-  [encrypted environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars-encryption.html)
-  in the Lambda function's configuration. However, note that anyone with access to invoke the Lambda function
-  will then have access to use your API key to call the third-party APIs by invoking the function.
-  We recommend limiting access to the Lambda function using
-  [least-privilege IAM policies](https://docs.aws.amazon.com/lambda/latest/dg/security-iam.html).
-  If you use an identity-based authentication mechanism such as OAuth, you could also store and retrieve API keys per user but there are no implementation examples in this repository.
 
 ## Deploy and run the examples
 

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.5.12",
+  "version": "0.5.14",
   "type": "module",
   "license": "Apache-2.0",
   "author": {
@@ -44,24 +44,24 @@
     "@tsconfig/recommended": "^1.0.13",
     "@types/aws-lambda": "^8.10.161",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.2.0",
+    "@types/node": "^25.5.0",
     "aws-sdk-client-mock": "^4.1.0",
     "aws-sdk-client-mock-jest": "^4.1.0",
-    "eslint": "^10.0.2",
+    "eslint": "^10.2.0",
     "eslint-plugin-check-file": "^3.3.1",
-    "jest": "^30.2.0",
-    "ts-jest": "^29.4.6",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.9",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1"
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1"
   },
   "dependencies": {
     "@aws-crypto/sha256-js": "^5.2.0",
-    "@aws-sdk/client-lambda": "^3.1000.0",
-    "@aws-sdk/credential-provider-node": "^3.958.0",
+    "@aws-sdk/client-lambda": "^3.1027.0",
+    "@aws-sdk/credential-provider-node": "^3.972.30",
     "@aws-sdk/protocol-http": "^3.374.0",
     "@aws-sdk/types": "^3.910.0",
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@smithy/signature-v4": "^5.3.3",
     "winston": "^3.19.0"
   }

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

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

package/dist/client/lambdaFunction.test.js

@@ -1,191 +0,0 @@
-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/client/streamableHttpWithSigV4.test.d.ts

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