weather tol

Author: frogkris

.github/workflows/mcp.yml

@@ -17,7 +17,7 @@ env:
   DEFAULT_WORKSPACE: "${{github.workspace}}/LLM/MCP"  # 
 jobs:
   helloWorldDockerPackage:
-    name: "Hello World Docker package"
+    name: "MCP Hello World - Docker image build"
     runs-on: ubuntu-latest # https://github.com/actions/runner-images
     outputs:
       image_todays_tag: ${{ steps.set_var.outputs.TODAYS_DATE }}
@@ -161,7 +161,7 @@ jobs:
             echo " " >> $GITHUB_STEP_SUMMARY
 
   helloWorldDockerPackageImageTest:
-    name: "Hello World Docker image test"
+    name: "MCP Hello World - Docker image test"
     runs-on: ubuntu-latest
     needs: helloWorldDockerPackage
     env:

LLM/MCP/1-hello-world/mcp.sh

@@ -10,7 +10,7 @@ prereq(){
 }
 start(){
     printf "\n ----------------------------------------------------------------  "
-    printf "\n Starting Hello World MCP Application ... "
+    printf "\n Starting MCP: Hello World service using SSE transport ... "
     printf "\n ----------------------------------------------------------------  \n "
     uv run src/main.py & 
     sleep 5
@@ -24,12 +24,16 @@ build(){
 }
 stop(){
     printf "\n ----------------------------------------------------------------  "
-    printf "\n Stopping Hello World MCP Application ... "
+    printf "\n Stopping MCP: Hello World service using SSE transport ... "
     printf "\n ----------------------------------------------------------------  \n "
 
     # uv stop
-    kill -9 $(lsof -ti tcp:8000)
-    exit 0
+    # kill -9 $(lsof -ti tcp:8000) &
+    # Kill process on port 8000, skip if error (no process running)
+    pid=$(lsof -ti tcp:8000 2>/dev/null)
+    if [ -n "$pid" ]; then
+        kill -9 "$pid" 2>/dev/null || true
+    fi
 }
 test(){
     test-web
@@ -87,6 +91,7 @@ if [[ -n $arg ]] ; then
             ;;
         STOP)
             stop
+            exit 0
             ;;
         *)
             echo "Invalid argument: $arg"

LLM/MCP/3-weather/Dockerfile

@@ -0,0 +1,31 @@
+# https://hub.docker.com/_/python
+FROM python:3.12-slim
+
+# Copy the uv binary from the astral-sh/uv image
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+RUN apt-get update && apt-get install -y  curl git gnupg && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt-get install -y nodejs && npm install -g npm@latest && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Copy the project into the image
+COPY ./ /app/
+
+# Disable development dependencies
+ENV UV_NO_DEV=1
+
+# Sync the project into a new environment, asserting the lockfile is up to date
+WORKDIR /app
+RUN uv lock && uv sync --frozen && uv pip install -e ".[dev]" 
+
+# # RUN tests
+# RUN uv run pytest tests/maintests.py -v
+
+# Expose the port
+EXPOSE 8000
+
+# # Health check
+# HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+#     CMD python -c "import requests; requests.get('http://localhost:8000/health')" || exit 1
+
+# Run the application
+# uv run src/main.py
+CMD ["uv", "run", "src/main.py"]

LLM/MCP/3-weather/README.md

@@ -0,0 +1,142 @@
+# Hello World MCP Example
+
+## Pre-requisites
+
+- [uv](https://github.com/astral-sh/uv) (Fast Python package installer and resolver)
+
+## Setup
+
+Install dependencies:
+- ruff install info at https://docs.astral.sh/ruff/installation/
+```bash
+uv pip install -e ".[dev]" && uv sync
+```
+
+## Running the Server
+
+Run the MCP server (configured to use SSE transport):
+
+```bash
+uv run src/main.py
+```
+
+- The server will start on `http://127.0.0.1:8000`
+
+## Testing
+
+### In Browser: Validating the Server
+
+- [http://127.0.0.1:8000](http://127.0.0.1:8000)
+![Inde Page](./images/indexPage.png)
+
+- [http://127.0.0.1:8000?name=krishna](http://127.0.0.1:8000?name=krishna)
+![Inde Page with parms](./images/indexPageWithParms.png)
+
+### Unit Testing
+
+```bash
+uv run pytest tests/maintests.py -v
+```
+![Unit Tests](./images/unittests.png)
+
+### Manual Testing via Curl (MCP Protocol)
+
+To test the MCP protocol fully via `curl`, you need to simulate an MCP client. This involves two steps:
+
+**1. Connect to SSE Stream**
+
+Open a terminal and listen to the event stream:
+
+```bash
+curl -N http://127.0.0.1:8000/sse
+```
+![SSE Stream](./images/sseStream.png)
+
+*Keep this running.* You will see an `endpoint` event containing a URL (e.g., `/messages/?session_id=...`). Copy this URL.
+
+**2. Send JSON-RPC Requests**
+
+In a **new terminal**, use the URL you copied to send requests.
+
+**Initialize:**
+
+```bash
+curl -X POST "http://127.0.0.1:8000/messages/?session_id=123456" \
+     -H "Content-Type: application/json" \
+     -d '{
+           "jsonrpc": "2.0",
+           "id": 1,
+           "method": "initialize",
+           "params": {
+             "protocolVersion": "2024-11-05",
+             "capabilities": {},
+             "clientInfo": { "name": "curl-client", "version": "1.0" }
+           }
+         }'
+```
+![Messages Curl](./images/messages-curl.png)
+
+![Messages Stream](./images/messages-stream.png)
+
+
+**List Tools:**
+
+```bash
+curl -X POST "http://127.0.0.1:8000/messages/?session_id=123456" \
+     -H "Content-Type: application/json" \
+     -d '{
+           "jsonrpc": "2.0",
+           "id": 2,
+           "method": "tools/list"
+         }'
+```
+![Tools list curl](./images/tools-list-curl.png)
+![Tools list resp](./images/tools-list-resp.png)
+
+**Call Tool (index):**
+
+```bash
+curl -X POST "http://127.0.0.1:8000/messages/?session_id=123456" \
+     -H "Content-Type: application/json" \
+     -d '{
+           "jsonrpc": "2.0",
+           "id": 3,
+           "method": "tools/call",
+           "params": {
+             "name": "index",
+             "arguments": {}
+           }
+         }'
+```
+
+![Tools call curl](./images/tools-call-index-req.png)
+![Tools call resp](./images/tools-call-index-resp.png)
+
+**Call Tool (greeting):**
+
+```bash
+curl -X POST "http://127.0.0.1:8000/messages/?session_id=123456" \
+     -H "Content-Type: application/json" \
+     -d '{
+           "jsonrpc": "2.0",
+           "id": 4,
+           "method": "tools/call",
+           "params": {
+             "name": "greeting",
+             "arguments": { "name": "Krishna" }
+           }
+         }'
+```
+
+![Tools call greeting curl](./images/tools-call-greeting-req.png)
+![Tools call greeting resp](./images/tools-call-greeting-resp.png)
+
+### MCP Inspector
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a developer tool for testing and debugging MCP servers.
+
+Run the inspector (this uses `npx` to run the inspector, which then runs your server in `stdio` mode):
+
+```bash
+npx @modelcontextprotocol/inspector uv run src/main.py --transport stdio
+```