chore(docs): Add individual docs for each example server

clareliguori · clareliguori · commit 0ca317ba3140 · 2025-07-09T16:32:14.000-07:00
diff --git a/DEVELOP.md b/DEVELOP.md
@@ -8,23 +8,23 @@ and using an example chatbot client to communicate with those Lambda-based MCP s
 
 The example chatbot client will communicate with seven servers:
 
-1. **time**: Ask "What is the current time?".
-2. **weather-alerts**: Ask "Are there any weather alerts right now?".
+1. **dad-jokes**: Ask "Tell me a good dad joke."
+2. **dog-facts**: Ask "Tell me something about dogs".
 3. **mcpdoc**: Ask "What is Strands Agents?".
 4. **cat-facts**: Ask "Tell me something about cats".
-5. **dad-jokes**: Ask "Tell me a good dad joke."
-6. **dog-facts**: Ask "Tell me something about dogs".
+5. **time**: Ask "What is the current time?".
+6. **weather-alerts**: Ask "Are there any weather alerts right now?".
 7. **fetch**: Ask "Who is Tom Cruise?".
 
-| MCP server     | Language   | Runtime       | MCP transport                                       | Authentication | Endpoint            |
-| -------------- | ---------- | ------------- | --------------------------------------------------- | -------------- | ------------------- |
-| time           | Python     | Lambda        | Custom Lambda Invoke transport                      | AWS IAM        | Lambda Invoke API   |
-| weather-alerts | Typescript | Lambda        | Custom Lambda Invoke transport                      | AWS IAM        | Lambda Invoke API   |
-| mcpdoc         | Python     | Lambda        | Custom Streamable HTTP transport with SigV4 support | AWS IAM        | Lambda Function URL |
-| cat-facts      | Typescript | Lambda        | Custom Streamable HTTP transport with SigV4 support | AWS IAM        | Lambda Function URL |
-| dad-jokes      | Python     | Lambda        | Streamable HTTP transport                           | OAuth          | API Gateway         |
-| dog-facts      | Typescript | Lambda        | Streamable HTTP transport                           | OAuth          | API Gateway         |
-| fetch          | Python     | Local process | stdio                                               | N/A            | N/A                 |
+| MCP server                                          | Language   | Runtime       | MCP transport                                       | Authentication | Endpoint            |
+| --------------------------------------------------- | ---------- | ------------- | --------------------------------------------------- | -------------- | ------------------- |
+| [dad-jokes](/examples/servers/dad-jokes/)           | Python     | Lambda        | Streamable HTTP transport                           | OAuth          | API Gateway         |
+| [dog-facts](/examples/servers/dog-facts/)           | Typescript | Lambda        | Streamable HTTP transport                           | OAuth          | API Gateway         |
+| [mcpdoc ](/examples/servers/mcpdoc/)                | Python     | Lambda        | Custom Streamable HTTP transport with SigV4 support | AWS IAM        | Lambda Function URL |
+| [cat-facts](/examples/servers/cat-facts/)           | Typescript | Lambda        | Custom Streamable HTTP transport with SigV4 support | AWS IAM        | Lambda Function URL |
+| [time](/examples/servers/time/)                     | Python     | Lambda        | Custom Lambda Invoke transport                      | AWS IAM        | Lambda Invoke API   |
+| [weather-alerts](/examples/servers/weather-alerts/) | Typescript | Lambda        | Custom Lambda Invoke transport                      | AWS IAM        | Lambda Invoke API   |
+| [fetch](https://pypi.org/project/mcp-server-fetch/) | Python     | Local process | stdio                                               | N/A            | N/A                 |
 
 ### Setup
 
@@ -74,7 +74,9 @@ Test the OAuth configuration with [oauth2c](https://github.com/cloudentity/oauth
 ./test-automated-oauth.sh
 ```
 
-### Build the Python module
+### Build the run-mcp-servers-with-aws-lambda library
+
+#### Build the Python module
 
 Install the run-mcp-servers-with-aws-lambda Python module from source:
 
@@ -92,7 +94,7 @@ uv run pyright
 uv run pytest # coverage report will be in htmlcov/index.html
 ```
 
-### Build the Typescript package
+#### Build the Typescript package
 
 Build the @aws/run-mcp-servers-with-aws-lambda Typescript module:
 
@@ -110,83 +112,95 @@ npm test # coverage report will be in coverage/index.html
 npm run lint
 ```
 
-### Deploy the example Python servers
+### Deploy the example remote MCP servers
 
-Deploy the Lambda 'time' function - the deployed function will be named "mcp-server-time".
+#### Deploy dad-jokes MCP server
+
+Deploy the Lambda 'dad-jokes' function - the deployed function will be named "mcp-server-dad-jokes".
 
 ```bash
-cd examples/servers/time/
+cd examples/servers/dad-jokes/
 
 uv pip install -r requirements.txt
 
 cdk deploy --app 'python3 cdk_stack.py'
 ```
 
-Deploy the Lambda 'mcpdoc' function - the deployed function will be named "mcp-server-mcpdoc".
+#### Deploy dog-facts MCP server
+
+Deploy the Lambda 'dog-facts' function - the deployed function will be named "mcp-server-dog-facts".
 
 ```bash
-cd examples/servers/mcpdoc/
+cd examples/servers/dog-facts/
 
-uv pip install -r requirements.txt
+npm install
 
-cdk deploy --app 'python3 cdk_stack.py'
+npm link @aws/run-mcp-servers-with-aws-lambda
+
+npm run build
+
+cdk deploy --app 'node lib/dog-facts-mcp-server.js'
 ```
 
-Deploy the Lambda 'dad-jokes' function - the deployed function will be named "mcp-server-dad-jokes".
+#### Deploy the mcpdoc MCP server
+
+Deploy the Lambda 'mcpdoc' function - the deployed function will be named "mcp-server-mcpdoc".
 
 ```bash
-cd examples/servers/dad-jokes/
+cd examples/servers/mcpdoc/
 
 uv pip install -r requirements.txt
 
 cdk deploy --app 'python3 cdk_stack.py'
 ```
 
-### Deploy the example Typescript servers
+#### Deploy the cat-facts MCP server
 
-Deploy the Lambda 'weather-alerts' function - the deployed function will be named "mcp-server-weather-alerts".
+Deploy the Lambda 'cat-facts' function - the deployed function will be named "mcp-server-cat-facts".
 
 ```bash
-cd examples/servers/weather-alerts/
+cd examples/servers/cat-facts/
 
 npm install
 
 npm link @aws/run-mcp-servers-with-aws-lambda
 
 npm run build
 
-cdk deploy --app 'node lib/weather-alerts-mcp-server.js'
+cdk deploy --app 'node lib/cat-facts-mcp-server.js'
 ```
 
-Deploy the Lambda 'cat-facts' function - the deployed function will be named "mcp-server-cat-facts".
+#### Deploy the time MCP server
 
-```bash
-cd examples/servers/cat-facts/
-
-npm install
+Deploy the Lambda 'time' function - the deployed function will be named "mcp-server-time".
 
-npm link @aws/run-mcp-servers-with-aws-lambda
+```bash
+cd examples/servers/time/
 
-npm run build
+uv pip install -r requirements.txt
 
-cdk deploy --app 'node lib/cat-facts-mcp-server.js'
+cdk deploy --app 'python3 cdk_stack.py'
 ```
 
-Deploy the Lambda 'dog-facts' function - the deployed function will be named "mcp-server-dog-facts".
+#### Deploy the weather-alerts MCP server
+
+Deploy the Lambda 'weather-alerts' function - the deployed function will be named "mcp-server-weather-alerts".
 
 ```bash
-cd examples/servers/dog-facts/
+cd examples/servers/weather-alerts/
 
 npm install
 
 npm link @aws/run-mcp-servers-with-aws-lambda
 
 npm run build
 
-cdk deploy --app 'node lib/dog-facts-mcp-server.js'
+cdk deploy --app 'node lib/weather-alerts-mcp-server.js'
 ```
 
-### Run the example Python client
+### Run the chatbot
+
+#### Run the example Python chatbot
 
 Run the Python-based chatbot client:
 
@@ -198,7 +212,7 @@ uv pip install -r requirements.txt
 python main.py
 ```
 
-### Run the example Typescript client
+#### Run the example Typescript chatbot
 
 Run the Typescript-based chatbot client:
 
diff --git a/examples/servers/cat-facts/README.md b/examples/servers/cat-facts/README.md
@@ -1,3 +1,22 @@
-# Cat Facts MCP Server
+# Cat Facts Remote MCP Server
 
-This example demonstrates an MCP server that provides cat facts through a Lambda Function URL and IAM authentication.
+This remote MCP server wraps the [@ivotoby/openapi-mcp-server](https://www.npmjs.com/package/@ivotoby/openapi-mcp-server)
+stdio-based MCP server in a Lambda function. The server is configured with a simplified OpenAPI specification for the
+[catfact.ninja](https://catfact.ninja/) API.
+
+- Language: Typescript
+- Transport: Custom Streamable HTTP transport with SigV4 support
+- Authentication: AWS IAM
+- Endpoint: Lambda Function URL
+
+### Deploy
+
+```bash
+npm install
+
+npm link @aws/run-mcp-servers-with-aws-lambda
+
+npm run build
+
+cdk deploy --app 'node lib/cat-facts-mcp-server.js'
+```
diff --git a/examples/servers/dad-jokes/README.md b/examples/servers/dad-jokes/README.md
@@ -1,3 +1,18 @@
-# Dad Jokes MCP Server
+# Dad Jokes Remote MCP Server
 
-This is an MCP (Model Context Protocol) server that provides access to dad jokes via the icanhazdadjoke.com API. It uses the mcp-openapi-proxy package to expose the API as MCP tools.
+This remote MCP server wraps the [mcp-openapi-proxy](https://pypi.org/project/mcp-openapi-proxy/)
+stdio-based MCP server in a Lambda function. The server is configured with a simplified OpenAPI specification for the
+[icanhazdadjoke](https://icanhazdadjoke.com/api) API.
+
+- Language: Python
+- Transport: Streamable HTTP transport
+- Authentication: AWS IAM
+- Endpoint: API Gateway
+
+### Deploy
+
+```bash
+uv pip install -r requirements.txt
+
+cdk deploy --app 'python3 cdk_stack.py'
+```
diff --git a/examples/servers/dog-facts/README.md b/examples/servers/dog-facts/README.md
@@ -1,3 +1,22 @@
-# Dog Facts MCP Server
+# Dog Facts Remote MCP Server
 
-This example demonstrates an MCP server that provides dog facts through an API Gateway and OAuth authentication.
+This remote MCP server wraps the [@ivotoby/openapi-mcp-server](https://www.npmjs.com/package/@ivotoby/openapi-mcp-server)
+stdio-based MCP server in a Lambda function. The server is configured with a simplified OpenAPI specification for the
+[dogapi.dog](https://dogapi.dog/) API.
+
+- Language: Typescript
+- Transport: Streamable HTTP transport
+- Authentication: AWS IAM
+- Endpoint: API Gateway
+
+### Deploy
+
+```bash
+npm install
+
+npm link @aws/run-mcp-servers-with-aws-lambda
+
+npm run build
+
+cdk deploy --app 'node lib/dog-facts-mcp-server.js'
+```
diff --git a/examples/servers/mcpdoc/README.md b/examples/servers/mcpdoc/README.md
@@ -1,31 +1,17 @@
-# mcpdoc MCP Server Lambda Example
+# mcpdoc Remote MCP Server
 
-This example demonstrates running the [mcpdoc MCP server](https://github.com/langchain-ai/mcpdoc) in AWS Lambda.
-The mcpdoc server provides access to documentation via llms.txt files.
+This remote MCP server wraps the [mcpdoc](https://pypi.org/project/mcpdoc/) stdio-based MCP server in a Lambda function.
+The server is configured to fetch llms.txt documentation for the [Strands Agents SDK](https://strandsagents.com/).
 
-## Sample inputs
+- Language: Python
+- Transport: Custom Streamable HTTP transport with SigV4 support
+- Authentication: AWS IAM
+- Endpoint: Lambda Function URL
 
-```bash
-uv pip install -r function/requirements.txt
-
-# Initialize
-$ python -c 'from function import index; print(index.handler({"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"roots":{"listChanged":True}},"clientInfo":{"name":"mcp","version":"0.1.0"}},"jsonrpc":"2.0","id":0}, ""))'
+### Deploy
 
-# List tools
-$ python -c 'from function import index; print(index.handler({"method":"tools/list","params":{"clientInfo":{"name":"mcp","version":"0.1.0"}},"jsonrpc":"2.0","id":0}, ""))'
-
-# List documentation sources
-$ python -c 'from function import index; print(index.handler({"method":"tools/invoke","params":{"name":"list_doc_sources","parameters":{}},"jsonrpc":"2.0","id":0}, ""))'
+```bash
+uv pip install -r requirements.txt
 
-# Fetch documentation
-$ python -c 'from function import index; print(index.handler({"method":"tools/invoke","params":{"name":"fetch_docs","parameters":{"url":"https://strandsagents.com/latest/llms.txt"}},"jsonrpc":"2.0","id":0}, ""))'
+cdk deploy --app 'python3 cdk_stack.py'
 ```
-
-## Configuration
-
-The mcpdoc server is configured with the following options:
-
-- `--urls`: Specifies the llms.txt files to use, in the format `Name:URL`. In this example, we use `Strands:https://strandsagents.com/latest/llms.txt`.
-- `--allowed-domains`: Specifies which domains the server is allowed to fetch documentation from. In this example, we allow `strandsagents.com`.
-
-For more configuration options, see the [mcpdoc GitHub repository](https://github.com/langchain-ai/mcpdoc).
diff --git a/examples/servers/time/README.md b/examples/servers/time/README.md
@@ -1,3 +1,22 @@
+# Time Remote MCP server
+
+This remote MCP server wraps the [time](https://pypi.org/project/mcp-server-time/) stdio-based MCP server in a Lambda function.
+
+- Language: Python
+- Transport: Custom Lambda Invoke transport
+- Authentication: AWS IAM
+- Endpoint: Lambda Invoke API
+
+### Deploy
+
+```bash
+uv pip install -r requirements.txt
+
+cdk deploy --app 'python3 cdk_stack.py'
+```
+
+### Testing
+
 Sample inputs:
 
 ```bash
diff --git a/examples/servers/weather-alerts/README.md b/examples/servers/weather-alerts/README.md
@@ -1,3 +1,28 @@
+# Weather Alerts Remote MCP server
+
+This remote MCP server wraps the [@ivotoby/openapi-mcp-server](https://www.npmjs.com/package/@ivotoby/openapi-mcp-server)
+stdio-based MCP server in a Lambda function. The server is configured with a simplified OpenAPI specification for the
+[National Weather Service API](https://www.weather.gov/documentation/services-web-api).
+
+- Language: Typescript
+- Transport: Custom Lambda Invoke transport
+- Authentication: AWS IAM
+- Endpoint: Lambda Invoke API
+
+### Deploy
+
+```bash
+npm install
+
+npm link @aws/run-mcp-servers-with-aws-lambda
+
+npm run build
+
+cdk deploy --app 'node lib/weather-alerts-mcp-server.js'
+```
+
+### Testing
+
 Sample inputs:
 
 ```bash
