feat: Add Typescript cat-facts example that can be the base for a streamable HTTP example

clareliguori · clareliguori · commit 4b0de8978ca6 · 2025-06-24T17:09:06.000-07:00
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -100,6 +100,16 @@ updates:
       prefix: "chore(deps)"
     rebase-strategy: "disabled"
 
+  - package-ecosystem: npm
+    directory: "/examples/servers/cat-facts"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 10
+    versioning-strategy: increase
+    commit-message:
+      prefix: "chore(deps)"
+    rebase-strategy: "disabled"
+
   - package-ecosystem: npm
     directory: "/e2e_tests/typescript"
     schedule:
diff --git a/.github/workflows/cdk-checks.yml b/.github/workflows/cdk-checks.yml
@@ -117,3 +117,45 @@ jobs:
         working-directory: ./examples/servers/weather-alerts
         env:
           CDK_DEFAULT_ACCOUNT: "000000000000"
+
+  check_cat_facts_server:
+    name: Check Typescript-based Cat Facts 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: Install CDK CLI
+        run: npm install -g aws-cdk
+
+      - name: Build and link local package
+        run: |
+          npm ci
+          npm audit --audit-level critical
+          npm run build
+          npm link
+        working-directory: ./src/typescript
+
+      - name: Install dependencies
+        run: |
+          npm ci
+          npm audit --audit-level critical
+          npm link @aws/run-mcp-servers-with-aws-lambda
+        working-directory: ./examples/servers/cat-facts
+
+      - name: Build
+        run: npm run build
+        working-directory: ./examples/servers/cat-facts
+
+      - name: Synthesize CDK stack
+        run: cdk synth --app 'node lib/cat-facts-mcp-server.js'
+        working-directory: ./examples/servers/cat-facts
+        env:
+          CDK_DEFAULT_ACCOUNT: "000000000000"
diff --git a/.mergify.yml b/.mergify.yml
@@ -17,6 +17,7 @@ queue_rules:
       - 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-based Cat Facts 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
@@ -20,3 +20,6 @@ cdk destroy --force --app 'python3 cdk_stack.py'
 
 cd ../weather-alerts/
 cdk destroy --force --app 'node lib/weather-alerts-mcp-server.js'
+
+cd ../cat-facts/
+cdk destroy --force --app 'node lib/cat-facts-mcp-server.js'
diff --git a/e2e_tests/python/main.py b/e2e_tests/python/main.py
@@ -80,6 +80,7 @@ async def main() -> None:
         "What is the current time in Seattle?",
         "Are there any weather alerts right now?",
         "What documentation sources can you use to answer questions?",
+        "Tell me a cat fact.",
         "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
@@ -34,6 +34,13 @@ npm link @aws/run-mcp-servers-with-aws-lambda
 npm run build
 cdk deploy --app 'node lib/weather-alerts-mcp-server.js'
 
+# Deploy Typescript-based cat-facts MCP server
+cd ../cat-facts/
+npm ci
+npm link @aws/run-mcp-servers-with-aws-lambda
+npm run build
+cdk deploy --app 'node lib/cat-facts-mcp-server.js'
+
 # Configure integ tests
 cd ../../../e2e_tests/
 sed "s/INTEG_TEST_ID/$INTEG_TEST_ID/g" servers_config.integ.json > python/servers_config.json
diff --git a/e2e_tests/servers_config.integ.json b/e2e_tests/servers_config.integ.json
@@ -17,6 +17,10 @@
     "mcpdoc": {
       "functionName": "mcp-server-mcpdoc-INTEG_TEST_ID",
       "region": "us-east-2"
+    },
+    "catFacts": {
+      "functionName": "mcp-server-cat-facts-INTEG_TEST_ID",
+      "region": "us-east-2"
     }
   }
 }
diff --git a/e2e_tests/typescript/src/main.ts b/e2e_tests/typescript/src/main.ts
@@ -34,6 +34,7 @@ async function main(): Promise<void> {
     "What is the current time in Seattle?",
     "Are there any weather alerts right now?",
     "What documentation sources can you use to answer questions?",
+    "Tell me a cat fact.",
     "Who is Tom Cruise?",
   ];
 
diff --git a/examples/chatbots/python/servers_config.json b/examples/chatbots/python/servers_config.json
@@ -17,6 +17,10 @@
     "mcpdoc": {
       "functionName": "mcp-server-mcpdoc",
       "region": "us-east-2"
+    },
+    "catFacts": {
+      "functionName": "mcp-server-cat-facts",
+      "region": "us-east-2"
     }
   }
 }
diff --git a/examples/chatbots/typescript/servers_config.json b/examples/chatbots/typescript/servers_config.json
@@ -17,6 +17,10 @@
     "mcpdoc": {
       "functionName": "mcp-server-mcpdoc",
       "region": "us-east-2"
+    },
+    "catFacts": {
+      "functionName": "mcp-server-cat-facts",
+      "region": "us-east-2"
     }
   }
 }
diff --git a/examples/servers/cat-facts/.npmignore b/examples/servers/cat-facts/.npmignore
@@ -0,0 +1,6 @@
+*.ts
+!*.d.ts
+
+# CDK asset staging directory
+.cdk.staging
+cdk.out
diff --git a/examples/servers/cat-facts/README.md b/examples/servers/cat-facts/README.md
@@ -0,0 +1,21 @@
+Sample inputs:
+
+```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}, "")'
+
+# Get cat breeds
+$ node -e 'require("./lib/cat-facts-mcp-server.function.js").handler({"method":"tools/call","params":{"name":"getBreeds","arguments":{"limit":5}},"jsonrpc":"2.0","id":0}, "")'
+
+# Get multiple cat facts
+$ node -e 'require("./lib/cat-facts-mcp-server.function.js").handler({"method":"tools/call","params":{"name":"getFacts","arguments":{"limit":3,"max_length":100}},"jsonrpc":"2.0","id":0}, "")'
+```
diff --git a/examples/servers/cat-facts/cat-facts-openapi.json b/examples/servers/cat-facts/cat-facts-openapi.json
@@ -0,0 +1,212 @@
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "Cat Fact API",
+        "description": "An API for facts about cats",
+        "contact": {
+            "email": "contact@catfact.ninja"
+        },
+        "version": "1.0.0"
+    },
+    "servers": [
+        {
+            "url": "https://catfact.ninja"
+        }
+    ],
+    "paths": {
+        "/breeds": {
+            "get": {
+                "tags": [
+                    "Breeds"
+                ],
+                "summary": "Get a list of breeds",
+                "description": "Returns a a list of breeds",
+                "operationId": "getBreeds",
+                "parameters": [
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "description": "limit the amount of results returned",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "successful operation",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/Breed"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/fact": {
+            "get": {
+                "tags": [
+                    "Facts"
+                ],
+                "summary": "Get Random Fact",
+                "description": "Returns a random fact",
+                "operationId": "getRandomFact",
+                "parameters": [
+                    {
+                        "name": "max_length",
+                        "in": "query",
+                        "description": "maximum length of returned fact",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "successful operation",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/CatFact"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Fact not found"
+                    }
+                }
+            }
+        },
+        "/facts": {
+            "get": {
+                "tags": [
+                    "Facts"
+                ],
+                "summary": "Get a list of facts",
+                "description": "Returns a a list of facts",
+                "operationId": "getFacts",
+                "parameters": [
+                    {
+                        "name": "max_length",
+                        "in": "query",
+                        "description": "maximum length of returned fact",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64"
+                        }
+                    },
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "description": "limit the amount of results returned",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "successful operation",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/CatFact"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "Breed": {
+                "title": "Breed model",
+                "description": "Breed",
+                "properties": {
+                    "breed": {
+                        "title": "Breed",
+                        "description": "Breed",
+                        "type": "string",
+                        "format": "string"
+                    },
+                    "country": {
+                        "title": "Country",
+                        "description": "Country",
+                        "type": "string",
+                        "format": "string"
+                    },
+                    "origin": {
+                        "title": "Origin",
+                        "description": "Origin",
+                        "type": "string",
+                        "format": "string"
+                    },
+                    "coat": {
+                        "title": "Coat",
+                        "description": "Coat",
+                        "type": "string",
+                        "format": "string"
+                    },
+                    "pattern": {
+                        "title": "Pattern",
+                        "description": "Pattern",
+                        "type": "string",
+                        "format": "string"
+                    }
+                },
+                "type": "object"
+            },
+            "CatFact": {
+                "title": "CatFact model",
+                "description": "CatFact",
+                "properties": {
+                    "fact": {
+                        "title": "Fact",
+                        "description": "Fact",
+                        "type": "string",
+                        "format": "string"
+                    },
+                    "length": {
+                        "title": "Length",
+                        "description": "Length",
+                        "type": "integer",
+                        "format": "int32"
+                    }
+                },
+                "type": "object"
+            }
+        }
+    },
+    "tags": [
+        {
+            "name": "Facts",
+            "description": "Cat Facts"
+        },
+        {
+            "name": "Breeds",
+            "description": "Breeds"
+        }
+    ],
+    "security": [
+        []
+    ]
+}
diff --git a/examples/servers/cat-facts/lib/cat-facts-mcp-server.function.ts b/examples/servers/cat-facts/lib/cat-facts-mcp-server.function.ts
@@ -0,0 +1,15 @@
+import { Handler, Context } from "aws-lambda";
+
+const serverParams = {
+  command: "npx",
+  args: ["--offline", "openapi-mcp-server", "./cat-facts-openapi.json"],
+};
+
+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"
+  );
+
+  return await stdioServerAdapter(serverParams, event, context);
+};
diff --git a/examples/servers/cat-facts/lib/cat-facts-mcp-server.ts b/examples/servers/cat-facts/lib/cat-facts-mcp-server.ts
diff --git a/examples/servers/cat-facts/package-lock.json b/examples/servers/cat-facts/package-lock.json
diff --git a/examples/servers/cat-facts/package.json b/examples/servers/cat-facts/package.json
diff --git a/examples/servers/cat-facts/tsconfig.json b/examples/servers/cat-facts/tsconfig.json

Original file line number	Diff line number	Diff line change
`@@ -80,6 +80,7 @@ async def main() -> None:`
`80`	`80`	`"What is the current time in Seattle?",`
`81`	`81`	`"Are there any weather alerts right now?",`
`82`	`82`	`"What documentation sources can you use to answer questions?",`
	`83`	`+ "Tell me a cat fact.",`
`83`	`84`	`"Who is Tom Cruise?",`
`84`	`85`	`]`
`85`	`86`	`chat_session = ChatSession(servers, llm_client, user_utterances)`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,10 @@`
`17`	`17`	`"mcpdoc": {`
`18`	`18`	`"functionName": "mcp-server-mcpdoc-INTEG_TEST_ID",`
`19`	`19`	`"region": "us-east-2"`
	`20`	`+ },`
	`21`	`+ "catFacts": {`
	`22`	`+ "functionName": "mcp-server-cat-facts-INTEG_TEST_ID",`
	`23`	`+ "region": "us-east-2"`
`20`	`24`	`}`
`21`	`25`	`}`
`22`	`26`	`}`