feat: Add Streamable HTTP Transport for MCP with AWS Lambda

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.3.0](https://github.com/awslabs/run-model-context-protocol-servers-with-aws-lambda/compare/v0.2.1...v0.3.0) (2025-06-24)
+
+### Features
+
+* **Streamable HTTP Transport**: Added new HTTP transport implementation for MCP with AWS Lambda
+  - Native HTTP communication without stdio bridging
+  - Built-in AWS SigV4 authentication
+  - Real-time streaming support with Server-Sent Events (SSE)
+  - Context passing mechanism for Lambda event data
+  - Comprehensive error handling and retry logic
+  - Support for both stateful and stateless modes
+  - Complete examples and documentation
+
 ## [0.2.1](https://github.com/awslabs/run-model-context-protocol-servers-with-aws-lambda/compare/v0.2.0...v0.2.1) (2025-06-03)
 
 ## [0.2.0](https://github.com/awslabs/run-model-context-protocol-servers-with-aws-lambda/compare/v0.1.6...v0.2.0) (2025-05-30)

README.md

@@ -49,6 +49,8 @@ flowchart LR
 - This package currently supports MCP servers and clients written in Python and Typescript.
   Other languages such as Kotlin are not supported.
 - The server adapters only adapt stdio MCP servers, not servers written for other protocols such as SSE.
+- **NEW**: This package now includes a Streamable HTTP transport for MCP that supports real-time streaming
+  with Server-Sent Events (SSE) for stateless applications that need streaming notifications during request processing.
 - The server adapters do not maintain any MCP server state across Lambda function invocations.
   Only stateless MCP servers are a good fit for using this adapter. For example, MCP servers
   that invoke stateless tools like the [time MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/time)
@@ -200,6 +202,61 @@ const transport = new LambdaFunctionClientTransport(serverParams);
 await client.connect(transport);
 ```
 
+### Streamable HTTP Transport Example
+
+This project now includes a Streamable HTTP transport implementation that supports real-time streaming with Server-Sent Events (SSE). This is useful for applications that need to receive streaming notifications during MCP tool execution.
+
+The [streamable HTTP example](examples/streamable-http/) demonstrates:
+
+- **Server**: Express.js server with MCP streaming support
+- **Client**: TypeScript client that handles real-time notifications
+- **Tools**: Calculator tool and streaming counter tool with live notifications
+
+#### Quick Start
+
+```bash
+cd examples/streamable-http
+npm install
+npm run dev:server  # Start server on http://localhost:8080
+npm run dev:client  # Run client demo in another terminal
+```
+
+#### Server Usage
+
+```typescript
+import { createMCPServer } from './server/mcp-server-factory.js';
+import { StreamableHTTPServerTransport } from '@aws/mcp-streamable-http-transport';
+
+const mcpServer = createMCPServer();
+const transport = new StreamableHTTPServerTransport({
+  sessionIdGenerator: () => undefined,
+  enableJsonResponse: false
+});
+
+await mcpServer.connect(transport);
+```
+
+#### Client Usage
+
+```typescript
+import { MCPStreamingClient } from './client/mcp-streaming-client.js';
+
+const client = new MCPStreamingClient({
+  serverName: 'mcp-streaming-server',
+  serverVersion: '1.0.0',
+  endpoint: 'http://localhost:8080/mcp'
+});
+
+await client.connect();
+
+// Execute streaming tool with real-time notifications
+const result = await client.executeStreamingTool('count-with-notifications', {
+  maxCount: 5
+});
+```
+
+The streaming client automatically handles real-time notifications and displays them as they arrive from the server.
+
 ### Deploy and run the examples
 
 See the [development guide](DEVELOP.md) for instructions to deploy and run the examples in this repository.

STREAMABLE_HTTP_TRANSPORT.md

@@ -0,0 +1,164 @@
+# Streamable HTTP Transport for MCP
+
+This repository now includes a **Streamable HTTP Transport** implementation that provides an alternative to the stdio-based approach for running MCP servers in AWS Lambda.
+
+## Why Streamable HTTP Transport?
+
+The original stdio-based approach requires creating child processes inside Lambda functions and bridging stdio communication. The Streamable HTTP transport eliminates this complexity by implementing native HTTP communication.
+
+### Architecture Comparison
+
+#### Original Stdio Approach
+```
+[MCP Client] → [Lambda Invoke API] → [Lambda Function]
+    → [stdio bridge] → [Child Process MCP Server]
+    → [stdio response] → [Lambda Response] → [MCP Client]
+```
+
+#### New Streamable HTTP Approach
+```
+[MCP Client] → [HTTP POST with SigV4] → [Lambda Function URL]
+    → [StreamableHTTPServerTransport] → [MCP Tools with Context]
+    → [SSE/JSON Response] → [MCP Client]
+```
+
+## Key Advantages
+
+- Better performance: No child process overhead, faster cold starts
+- Native AWS security: Built-in SigV4 authentication
+- Real-time streaming: Server-Sent Events for notifications
+- Context passing: Clean mechanism to pass Lambda event data to tools
+- Cost effective: Direct Lambda Function URLs, no API Gateway needed
+- Comprehensive error handling, retry logic, session management
+
+## Quick Start
+
+### 1. Install the Transport
+
+```bash
+cd src/typescript-streamable-http
+npm install
+npm run build
+```
+
+### 2. Run the Examples
+
+```bash
+cd examples/streamable-http
+npm install
+
+# Start server
+npm run dev:server
+
+# In another terminal, start client
+npm run dev:client
+```
+
+### 3. Deploy to AWS Lambda
+
+The examples include complete deployment instructions for AWS Lambda with Function URLs.
+
+## Implementation Highlights
+
+### Server Side
+```typescript
+import { StreamableHTTPServerTransport, extractContextFiled } from './src/typescript-streamable-http';
+
+const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => undefined, // Stateless for Lambda
+    enableJsonResponse: false // Use SSE streaming
+});
+
+// Extract context in MCP tools
+const context = extractContextFiled<UserContext>(mcpServer, 'context');
+```
+
+### Client Side
+```typescript
+import { StreamableHTTPClientTransport } from './src/typescript-streamable-http';
+
+const transport = new StreamableHTTPClientTransport(
+    new URL('https://your-function-url.lambda-url.us-west-2.on.aws/mcp'),
+    { context: { userId: '123', role: 'admin' } }, // Pass context
+    'us-west-2',
+    'lambda'
+);
+```
+
+## Documentation
+
+- **[Transport Library README](src/typescript-streamable-http/README.md)** - Complete API documentation
+- **[Examples README](examples/streamable-http/README.md)** - Step-by-step examples
+- **[Server Example](examples/streamable-http/server-example.ts)** - Complete server implementation
+- **[Client Example](examples/streamable-http/client-example.ts)** - Client with streaming support
+
+## Comparison with Existing Approach
+
+| Feature | Stdio Transport | Streamable HTTP Transport |
+|---------|----------------|---------------------------|
+| **Architecture** | Child process + stdio bridge | Native HTTP communication |
+| **Cold Start** | Slower (process spawning) | Faster (direct HTTP) |
+| **Memory Usage** | Higher (multiple processes) | Lower (single process) |
+| **Context Passing** | Complex (environment variables) | Clean (HTTP headers) |
+| **Streaming** | Limited | Full SSE support |
+| **Error Handling** | Basic | Comprehensive with retry |
+| **AWS Integration** | Manual invoke API | Native SigV4 + Function URLs |
+| **Scalability** | Limited by process limits | HTTP connection pooling |
+| **Cost** | Higher (API Gateway often needed) | Lower (direct Function URLs) |
+
+## Migration Guide
+
+### From Stdio to Streamable HTTP
+
+1. **Replace transport imports**:
+   ```typescript
+   // Old
+   import { stdioServerAdapter } from '@aws/run-mcp-servers-with-aws-lambda';
+
+   // New  
+   import { StreamableHTTPServerTransport } from './src/typescript-streamable-http';
+   ```
+
+2. **Update server initialization**:
+   ```typescript
+   // Old - stdio adapter in Lambda handler
+   export const handler = (event, context) => {
+       return stdioServerAdapter(serverParams, event, context);
+   };
+
+   // New - Express app with HTTP transport
+   const app = express();
+   const transport = new StreamableHTTPServerTransport({...});
+   app.all('/mcp', (req, res) => transport.handleRequest(req, res));
+   ```
+
+3. **Update client connection**:
+   ```typescript
+   // Old - Lambda invoke transport
+   const transport = new LambdaFunctionClientTransport({...});
+
+   // New - HTTP transport
+   const transport = new StreamableHTTPClientTransport(url, options, region, service);
+   ```
+
+## Production Deployments
+
+The Streamable HTTP transport is already being used in production environments with:
+- **Multi-stage deployments** (alpha, beta, gamma, prod)
+- **Multiple MCP servers** running as separate Lambda functions
+- **Real-time streaming** for long-running operations
+- **Context-aware tools** that access user and request data
+- **Automatic retry and reconnection** for reliability
+
+## Contributing
+
+This transport implementation represents a significant improvement over the stdio approach and is ready for community adoption. The code is production-tested and includes comprehensive examples and documentation.
+
+## Next Steps
+
+1. **Test the examples** locally
+2. **Deploy to AWS Lambda** using the provided instructions  
+3. **Integrate into your MCP applications**
+4. **Contribute improvements** back to the community
+
+The Streamable HTTP transport makes MCP with AWS Lambda more performant, scalable, and developer-friendly while maintaining full protocol compatibility.

VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0