feat: Add Python mcpdoc example that can be the base for a streamable HTTP example

clareliguori · clareliguori · commit 4943cf384bd6 · 2025-06-24T16:53:02.000-07:00
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -50,6 +50,26 @@ updates:
       prefix: "chore(deps)"
     rebase-strategy: "disabled"
 
+  - package-ecosystem: pip
+    directory: "/examples/servers/mcpdoc"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 10
+    versioning-strategy: increase
+    commit-message:
+      prefix: "chore(deps)"
+    rebase-strategy: "disabled"
+
+  - package-ecosystem: pip
+    directory: "/examples/servers/mcpdoc/function"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 10
+    versioning-strategy: increase
+    commit-message:
+      prefix: "chore(deps)"
+    rebase-strategy: "disabled"
+
   - package-ecosystem: npm
     directory: "/src/typescript"
     schedule:
diff --git a/.github/workflows/cdk-checks.yml b/.github/workflows/cdk-checks.yml
@@ -40,6 +40,42 @@ jobs:
         env:
           CDK_DEFAULT_ACCOUNT: "000000000000"
 
+  check_mcpdoc_server:
+    name: Check Python-based MCP Doc Server
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "Set up Typescript"
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "src/python/.python-version"
+
+      - name: Install CDK CLI
+        run: npm install -g aws-cdk
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+        working-directory: ./examples/servers/mcpdoc
+
+      - uses: pypa/gh-action-pip-audit@v1.1.0
+        with:
+          inputs: ./examples/servers/mcpdoc/requirements.txt
+
+      - name: Synthesize CDK stack
+        run: cdk synth --app 'python3 cdk_stack.py'
+        working-directory: ./examples/servers/mcpdoc
+        env:
+          CDK_DEFAULT_ACCOUNT: "000000000000"
+
   check_weather_alerts_server:
     name: Check Typescript-based Weather Alerts Server
     runs-on: ubuntu-latest
diff --git a/.mergify.yml b/.mergify.yml
@@ -15,6 +15,7 @@ queue_rules:
       - status-success=Check Python library
       - status-success=Check Typescript library
       - status-success=Check Python-based Time Server
+      - status-success=Check Python-based MCP Doc Server
       - status-success=Check Typescript-based Weather Alerts Server
       - status-success=Check Typescript chatbot
     merge_method: squash
diff --git a/e2e_tests/clean_up_integ_test.sh b/e2e_tests/clean_up_integ_test.sh
@@ -15,5 +15,8 @@ export INTEG_TEST_ID=$(cat e2e_tests/integ-test-id)
 cd examples/servers/time
 cdk destroy --force --app 'python3 cdk_stack.py'
 
+cd ../mcpdoc
+cdk destroy --force --app 'python3 cdk_stack.py'
+
 cd ../weather-alerts/
 cdk destroy --force --app 'node lib/weather-alerts-mcp-server.js'
diff --git a/e2e_tests/python/main.py b/e2e_tests/python/main.py
@@ -79,6 +79,7 @@ async def main() -> None:
         "Hello!",
         "What is the current time in Seattle?",
         "Are there any weather alerts right now?",
+        "What documentation sources can you use to answer questions?",
         "Who is Tom Cruise?",
     ]
     chat_session = ChatSession(servers, llm_client, user_utterances)
diff --git a/e2e_tests/run_integ_test.sh b/e2e_tests/run_integ_test.sh
@@ -17,6 +17,11 @@ cd ../../examples/servers/time
 uv pip install -r requirements.txt
 cdk deploy --app 'python3 cdk_stack.py'
 
+# Deploy Python-based mcpdoc MCP server
+cd ../mcpdoc
+uv pip install -r requirements.txt
+cdk deploy --app 'python3 cdk_stack.py'
+
 # Deploy Typescript-based example MCP server
 cd ../../../src/typescript/
 npm ci
diff --git a/e2e_tests/servers_config.integ.json b/e2e_tests/servers_config.integ.json
@@ -13,6 +13,10 @@
     "weatherAlerts": {
       "functionName": "mcp-server-weather-alerts-INTEG_TEST_ID",
       "region": "us-east-2"
+    },
+    "mcpdoc": {
+      "functionName": "mcp-server-mcpdoc-INTEG_TEST_ID",
+      "region": "us-east-2"
     }
   }
 }
diff --git a/e2e_tests/typescript/src/main.ts b/e2e_tests/typescript/src/main.ts
@@ -33,6 +33,7 @@ async function main(): Promise<void> {
     "Hello!",
     "What is the current time in Seattle?",
     "Are there any weather alerts right now?",
+    "What documentation sources can you use to answer questions?",
     "Who is Tom Cruise?",
   ];
 
diff --git a/examples/chatbots/python/servers_config.json b/examples/chatbots/python/servers_config.json
@@ -13,6 +13,10 @@
     "weatherAlerts": {
       "functionName": "mcp-server-weather-alerts",
       "region": "us-east-2"
+    },
+    "mcpdoc": {
+      "functionName": "mcp-server-mcpdoc",
+      "region": "us-east-2"
     }
   }
 }
diff --git a/examples/chatbots/typescript/servers_config.json b/examples/chatbots/typescript/servers_config.json
@@ -13,6 +13,10 @@
     "weatherAlerts": {
       "functionName": "mcp-server-weather-alerts",
       "region": "us-east-2"
+    },
+    "mcpdoc": {
+      "functionName": "mcp-server-mcpdoc",
+      "region": "us-east-2"
     }
   }
 }
diff --git a/examples/servers/mcpdoc/README.md b/examples/servers/mcpdoc/README.md
@@ -0,0 +1,31 @@
+# mcpdoc MCP Server Lambda Example
+
+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.
+
+## Sample inputs
+
+```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}, ""))'
+
+# 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}, ""))'
+
+# 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}, ""))'
+```
+
+## 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/mcpdoc/cdk_stack.py b/examples/servers/mcpdoc/cdk_stack.py
@@ -0,0 +1,100 @@
+from aws_cdk import (
+    App,
+    Aspects,
+    DockerVolume,
+    Environment,
+    RemovalPolicy,
+    Stack,
+    aws_iam as iam,
+    aws_lambda as lambda_,
+    aws_lambda_python_alpha as lambda_python,
+    aws_logs as logs,
+)
+from cdk_nag import AwsSolutionsChecks
+from constructs import Construct
+import jsii
+import os
+
+
+# For testing, the run-mcp-servers-with-aws-lambda module is built and bundled
+# from local files. Remove these command hooks if using the
+# run-mcp-servers-with-aws-lambda from PyPi.
+@jsii.implements(lambda_python.ICommandHooks)
+class CommandHooks:
+    @jsii.member(jsii_name="afterBundling")
+    def after_bundling(self, input_dir: str, output_dir: str) -> list[str]:
+        return [
+            f"cd {output_dir}",
+            f"curl -LsSf https://astral.sh/uv/install.sh | env UV_UNMANAGED_INSTALL='{output_dir}' sh",
+            f"mkdir {output_dir}/mcp_lambda_build",
+            f"cp /mcp_lambda_src/README.md {output_dir}/mcp_lambda_build/README.md",
+            f"cp /mcp_lambda_src/pyproject.toml {output_dir}/mcp_lambda_build/pyproject.toml",
+            f"cp /mcp_lambda_src/uv.lock {output_dir}/mcp_lambda_build/uv.lock",
+            f"cp -r /mcp_lambda_src/src {output_dir}/mcp_lambda_build/src",
+            f"UV_CACHE_DIR={output_dir}/.cache UV_DYNAMIC_VERSIONING_BYPASS=0.0.1 {output_dir}/uv build --wheel --directory {output_dir}/mcp_lambda_build",
+            f"python -m pip install {output_dir}/mcp_lambda_build/dist/*.whl -t {output_dir}",
+            f"rm -r {output_dir}/mcp_lambda_build {output_dir}/.cache uv",
+        ]
+
+    @jsii.member(jsii_name="beforeBundling")
+    def before_bundling(self, input_dir: str, output_dir: str) -> list[str]:
+        return []
+
+
+class LambdaMcpdocMcpServer(Stack):
+    def __init__(
+        self, scope: Construct, construct_id: str, stack_name_suffix: str, **kwargs
+    ) -> None:
+        super().__init__(scope, construct_id, **kwargs)
+
+        log_group = logs.LogGroup(
+            self,
+            "ServerFunctionLogGroup",
+            log_group_name=f"mcp-server-mcpdoc{stack_name_suffix}",
+            retention=logs.RetentionDays.ONE_DAY,
+            removal_policy=RemovalPolicy.DESTROY,
+        )
+
+        lambda_python.PythonFunction(
+            self,
+            "ServerFunction",
+            function_name="mcp-server-mcpdoc" + stack_name_suffix,
+            role=iam.Role.from_role_name(self, "Role", "mcp-lambda-example-servers"),
+            log_group=log_group,
+            runtime=lambda_.Runtime.PYTHON_3_13,
+            entry="function",
+            memory_size=2048,
+            environment={
+                "LOG_LEVEL": "DEBUG",
+            },
+            # For testing, the run-mcp-servers-with-aws-lambda module is built and bundled
+            # from local files. Remove the bundling configuration if using the
+            # run-mcp-servers-with-aws-lambda from PyPi.
+            bundling=lambda_python.BundlingOptions(
+                # asset_excludes=[".venv", ".mypy_cache", "__pycache__"],
+                volumes=[
+                    DockerVolume(
+                        container_path="/mcp_lambda_src",
+                        # Assume we're in examples/servers/mcpdoc dir
+                        host_path=os.path.join(os.getcwd(), "../../../src/python"),
+                    )
+                ],
+                command_hooks=CommandHooks(),
+            ),
+        )
+
+
+app = App()
+env = Environment(account=os.environ["CDK_DEFAULT_ACCOUNT"], region="us-east-2")
+stack_name_suffix = (
+    f'-{os.environ["INTEG_TEST_ID"]}' if "INTEG_TEST_ID" in os.environ else ""
+)
+stack = LambdaMcpdocMcpServer(
+    app,
+    "LambdaMcpServer-Mcpdoc",
+    stack_name_suffix,
+    stack_name="LambdaMcpServer-Mcpdoc" + stack_name_suffix,
+    env=env,
+)
+Aspects.of(stack).add(AwsSolutionsChecks(verbose=True))
+app.synth()
diff --git a/examples/servers/mcpdoc/function/__init__.py b/examples/servers/mcpdoc/function/__init__.py
@@ -0,0 +1 @@
+
diff --git a/examples/servers/mcpdoc/function/index.py b/examples/servers/mcpdoc/function/index.py
@@ -0,0 +1,17 @@
+import sys
+from mcp.client.stdio import StdioServerParameters
+from mcp_lambda import stdio_server_adapter
+
+server_params = StdioServerParameters(
+    command=sys.executable,
+    args=[
+        "-m",
+        "mcpdoc",
+        "--urls", "Strands:https://strandsagents.com/latest/llms.txt",
+        "--allowed-domains", "strandsagents.com",
+    ],
+)
+
+
+def handler(event, context):
+    return stdio_server_adapter(server_params, event, context)
diff --git a/examples/servers/mcpdoc/function/requirements.txt b/examples/servers/mcpdoc/function/requirements.txt
@@ -0,0 +1,5 @@
+mcpdoc
+
+# For testing, this module is installed from local files.
+# Uncomment this line to build using the module from PyPi
+# run-mcp-servers-with-aws-lambda >= 0.0.1
diff --git a/examples/servers/mcpdoc/requirements.txt b/examples/servers/mcpdoc/requirements.txt
@@ -0,0 +1,4 @@
+aws-cdk-lib==2.199.0
+aws-cdk.aws-lambda-python-alpha==2.199.0a0
+constructs>=10.0.0,<11.0.0
+cdk-nag==2.36.2

Original file line number	Diff line number	Diff line change
`@@ -79,6 +79,7 @@ async def main() -> None:`
`79`	`79`	`"Hello!",`
`80`	`80`	`"What is the current time in Seattle?",`
`81`	`81`	`"Are there any weather alerts right now?",`
	`82`	`+ "What documentation sources can you use to answer questions?",`
`82`	`83`	`"Who is Tom Cruise?",`
`83`	`84`	`]`
`84`	`85`	`chat_session = ChatSession(servers, llm_client, user_utterances)`
Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,10 @@`
`13`	`13`	`"weatherAlerts": {`
`14`	`14`	`"functionName": "mcp-server-weather-alerts-INTEG_TEST_ID",`
`15`	`15`	`"region": "us-east-2"`
	`16`	`+ },`
	`17`	`+ "mcpdoc": {`
	`18`	`+ "functionName": "mcp-server-mcpdoc-INTEG_TEST_ID",`
	`19`	`+ "region": "us-east-2"`
`16`	`20`	`}`
`17`	`21`	`}`
`18`	`22`	`}`