feat: Typescript-based cat-facts MCP server accessible behind Lambda function URL using streamable HTTP transport and Sigv4

Author: clareliguori

examples/servers/cat-facts/README.md

@@ -1,15 +1,3 @@
-Sample inputs:
+# Cat Facts MCP Server
 
-```bash
-$ npm run build
-$ export LOG_LEVEL=debug
-
-# Initialize
-$ node -e 'require("./lib/cat-facts-mcp-server.function.js").handler({"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"roots":{"listChanged":true}},"clientInfo":{"name":"mcp","version":"0.1.0"}},"jsonrpc":"2.0","id":0}, "")'
-
-# List tools
-$ node -e 'require("./lib/cat-facts-mcp-server.function.js").handler({"method":"tools/list","params":{"clientInfo":{"name":"mcp","version":"0.1.0"}},"jsonrpc":"2.0","id":0}, "")'
-
-# Get a random cat fact
-$ node -e 'require("./lib/cat-facts-mcp-server.function.js").handler({"method":"tools/call","params":{"name":"getRandomFact","arguments":{}},"jsonrpc":"2.0","id":0}, "")'
-```
+This example demonstrates an MCP server that provides cat facts through a Lambda Function URL and IAM authentication.

examples/servers/cat-facts/lib/cat-facts-mcp-server.function.ts

@@ -1,4 +1,13 @@
-import { Handler, Context } from "aws-lambda";
+import {
+  Handler,
+  Context,
+  APIGatewayProxyEventV2WithIAMAuthorizer,
+  APIGatewayProxyResultV2,
+} from "aws-lambda";
+import {
+  LambdaFunctionURLEventHandler,
+  StdioServerAdapterRequestHandler,
+} from "@aws/run-mcp-servers-with-aws-lambda";
 
 const serverParams = {
   command: "node",
@@ -11,11 +20,16 @@ const serverParams = {
   ],
 };
 
-export const handler: Handler = async (event, context: Context) => {
-  // Dynamically import ES module into CommonJS Lambda function
-  const { stdioServerAdapter } = await import(
-    "@aws/run-mcp-servers-with-aws-lambda"
-  );
+const requestHandler = new LambdaFunctionURLEventHandler(
+  new StdioServerAdapterRequestHandler(serverParams)
+);
 
-  return await stdioServerAdapter(serverParams, event, context);
+export const handler: Handler = async (
+  event: APIGatewayProxyEventV2WithIAMAuthorizer,
+  context: Context
+): Promise<APIGatewayProxyResultV2> => {
+  // To customize the handler based on the caller's identity, you can use:
+  // event.requestContext.authorizer.iam
+
+  return requestHandler.handle(event, context);
 };

examples/servers/cat-facts/lib/cat-facts-mcp-server.ts

@@ -1,6 +1,6 @@
 import * as cdk from "aws-cdk-lib";
 import { Construct } from "constructs";
-import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
+import { NodejsFunction, OutputFormat } from "aws-cdk-lib/aws-lambda-nodejs";
 import {
   Code,
   LayerVersion,
@@ -59,6 +59,8 @@ export class CatFactsMcpServer extends cdk.Stack {
       },
       layers: [mcpLambdaLayer],
       bundling: {
+        format: OutputFormat.ESM,
+        mainFields: ["module", "main"],
         nodeModules: ["@ivotoby/openapi-mcp-server"],
         // For testing, the @aws/run-mcp-servers-with-aws-lambda package is bundled from local files using the Lambda layer above.
         // Remove the layer and this externalModules configuration if using the @aws/run-mcp-servers-with-aws-lambda package from npm.