Add consideration about existing MCP clients, move build/deploy instructions out into a separate guide

Author: clareliguori

DEVELOP.md

@@ -0,0 +1,126 @@
+## Deploy and run the examples
+
+This guide will walk you through building the source code in this repository,
+deploying example MCP servers in Lambda functions,
+and using an example chatbot client to communicate with those Lambda-based MCP servers.
+
+The example chatbot client will communicate with three servers:
+
+1. a Lambda function-based 'time' MCP server (Python)
+2. a Lambda function-based 'weather-alerts' MCP server (Typescript)
+3. a [local 'fetch' MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch)
+
+To use the remote 'time' server, you can ask the chatbot questions like "What is the current time?".
+
+To use the remote 'weather-alerts' server, you can ask the chatbot questions like "Are there any weather alerts right now?".
+
+To use the local 'fetch' server, you can ask questions like "Who is Tom Cruise?".
+
+### Setup
+
+First, install the [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_install).
+
+Request [Bedrock model access](https://us-west-2.console.aws.amazon.com/bedrock/home?region=us-west-2#/modelaccess)
+to Anthropic Claude 3.5 Sonnet v2 in region us-west-2.
+
+Create an IAM role for the example Lambda functions and bootstrap the account for CDK:
+
+```bash
+aws iam create-role \
+  --role-name mcp-lambda-example-servers \
+  --assume-role-policy-document file://examples/servers/lambda-assume-role-policy.json
+
+aws iam attach-role-policy \
+  --role-name mcp-lambda-example-servers \
+  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
+
+cdk bootstrap aws://<aws account id>/us-east-2
+```
+
+### Build the Python module
+
+Install the mcp-lambda Python module from source:
+
+```bash
+cd src/python/
+
+uv venv
+source .venv/bin/activate
+
+uv sync --all-extras --dev
+
+# For development
+uv run ruff check .
+uv run pyright
+uv run pytest
+```
+
+### Build the Typescript package
+
+Build the mcp-lambda Typescript module:
+
+```bash
+cd src/typescript/
+
+npm install
+
+npm run build
+
+npm link
+```
+
+### Deploy the example Python server
+
+Deploy the Lambda 'time' function - the deployed function will be named "mcp-server-time".
+
+```bash
+cd examples/servers/time/
+
+uv pip install -r requirements.txt
+
+cdk deploy --app 'python3 cdk_stack.py'
+```
+
+### Deploy the example Typescript server
+
+Deploy the Lambda 'weather-alerts' function - the deployed function will be named "mcp-server-weather-alerts".
+
+```bash
+cd examples/servers/weather-alerts/
+
+npm install
+
+npm link mcp-lambda
+
+npm run build
+
+cdk deploy --app 'node lib/weather-alerts-mcp-server.js'
+```
+
+### Run the example Python client
+
+Run the Python-based chatbot client:
+
+```bash
+cd examples/chatbots/python/
+
+uv pip install -r requirements.txt
+
+python main.py
+```
+
+### Run the example Typescript client
+
+Run the Typescript-based chatbot client:
+
+```bash
+cd examples/chatbots/typescript/
+
+npm install
+
+npm link mcp-lambda
+
+npm run build
+
+npm run start
+```

README.md

@@ -1,6 +1,6 @@
-# Utilities for Model Context Protocol (MCP) with AWS Lambda
+# Run Model Context Protocol (MCP) servers in AWS Lambda
 
-This project enables you to run [Model Context Protocol](https://modelcontextprotocol.io) servers in AWS Lambda functions.
+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.
 A desktop application such as an IDE or Claude Desktop initiates MCP servers locally as child processes
@@ -22,7 +22,8 @@ You can invoke these function-based MCP servers from your application using the
 over short-lived connections.
 Your application can then be a desktop-based app, a distributed system running in the cloud,
 or any other architecture.
-The only requirement is that your application has access to invoke your Lambda functions.
+Your application must have access to invoke your Lambda functions,
+and use the custom MCP client transport that invokes the Lambda functions.
 
 ```mermaid
 flowchart LR
@@ -37,6 +38,12 @@ flowchart LR
 
 ## Considerations
 
+- This package currently requires using a custom MCP client transport to communicate with the MCP
+  server by invoking the Lambda function. Existing applications with MCP support such as
+  Amazon Q Developer CLI, Cline, etc do not have this custom transport, and cannot communicate with
+  MCP servers adapted into Lambda functions.
+  Note: with [upcoming changes to the MCP protocol](https://github.com/modelcontextprotocol/specification/pull/206),
+  we expect that this limitation will be removed in the future.
 - 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.
@@ -176,112 +183,7 @@ await this.client.connect(transport);
 
 ### Deploy and run the examples
 
-First, install the [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_install).
-
-Request [Bedrock model access](https://us-west-2.console.aws.amazon.com/bedrock/home?region=us-west-2#/modelaccess)
-to Anthropic Claude 3.5 Sonnet v2 in region us-west-2.
-
-Install the mcp-lambda Python module from source:
-
-```bash
-cd src/python/
-
-uv venv
-source .venv/bin/activate
-
-uv sync --all-extras --dev
-
-# For development
-uv run ruff check .
-uv run pyright
-uv run pytest
-```
-
-Create an IAM role for the example Lambda functions and bootstrap the account for CDK:
-
-```bash
-aws iam create-role \
-  --role-name mcp-lambda-example-servers \
-  --assume-role-policy-document file://examples/servers/lambda-assume-role-policy.json
-
-aws iam attach-role-policy \
-  --role-name mcp-lambda-example-servers \
-  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
-
-cdk bootstrap aws://<aws account id>/us-east-2
-```
-
-Deploy the Lambda 'time' function - the deployed function will be named "mcp-server-time".
-
-```bash
-cd examples/servers/time/
-
-uv pip install -r requirements.txt
-
-cdk deploy --app 'python3 cdk_stack.py'
-```
-
-Build the mcp-lambda Typescript module:
-
-```bash
-cd src/typescript/
-
-npm install
-
-npm run build
-
-npm link
-```
-
-Deploy the Lambda 'weather-alerts' function - the deployed function will be named "mcp-server-weather-alerts".
-
-```bash
-cd examples/servers/weather-alerts/
-
-npm install
-
-npm link mcp-lambda
-
-npm run build
-
-cdk deploy --app 'node lib/weather-alerts-mcp-server.js'
-```
-
-Run the Python-based chatbot client:
-
-```bash
-cd examples/chatbots/python/
-
-uv pip install -r requirements.txt
-
-python main.py
-```
-
-Alternatively, run the Typescript-based chatbot client:
-
-```bash
-cd examples/chatbots/typescript/
-
-npm install
-
-npm link mcp-lambda
-
-npm run build
-
-npm run start
-```
-
-The chatbot client will communicate with three servers:
-
-1. the Lambda function-based 'time' MCP server
-2. the Lambda function-based 'weather-alerts' MCP server
-3. a [local 'fetch' MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch)
-
-To use the remote 'time' server, you can ask the chatbot questions like "What is the current time?".
-
-To use the remote 'weather-alerts' server, you can ask the chatbot questions like "Are there any weather alerts right now?".
-
-To use the local 'fetch' server, you can ask questions like "Who is Tom Cruise?".
+See the [development guide](DEVELOP.md) for instructions to deploy and run the examples in this repository.
 
 ## Security