Add beginner-friendly documentation to api.py and weather_mcp_server.py

Explains FastAPI, MCP, async/await, HuggingFace, and the overall architecture
for readers unfamiliar with these technologies.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

api.py

@@ -1,14 +1,47 @@
 """
-api.py  —  FastAPI server (port 7860, required by HuggingFace Spaces)
-
-Exposes:
-  POST /ask   { "question": "What's the temp in Tokyo?" }
-              → { "answer": "..." }
-
-  GET  /health → { "status": "ok" }
-
-The MCP server (weather_mcp_server.py) runs as a separate process on port 8000
-managed by supervisord. This app connects to it via SSE URL.
+api.py  —  The main web server for this weather assistant app.
+
+HOW THIS APP WORKS:
+    When someone sends a question like "What's the weather in Tokyo?", this file
+    handles it end-to-end:
+
+      1. Receives the question via HTTP (like a web form submission)
+      2. Passes it to an AI language model (Qwen2.5) running on HuggingFace
+      3. The AI decides it needs real weather data, so it asks for the
+         get_current_temperature tool to be called
+      4. This server calls that tool (defined in weather_mcp_server.py)
+      5. The tool fetches live weather from the internet
+      6. The result is sent back to the AI, which writes a natural response
+      7. That response is returned to whoever asked the question
+
+WHAT IS FastAPI?
+    FastAPI is a Python library for building web servers. It lets you define
+    "endpoints" — URLs that accept requests and return responses. Think of it
+    like building a simple API that other apps or curl commands can talk to.
+
+WHAT IS MCP (Model Context Protocol)?
+    MCP is a standard way for AI models to use external tools. Instead of the
+    AI just generating text, it can say "I need to call this tool with these
+    arguments." This server listens for those requests and executes the tools.
+    weather_mcp_server.py defines the tools; this file calls them.
+
+WHAT IS HuggingFace?
+    HuggingFace is a platform that hosts AI models and lets you run them via
+    their API. This app uses their "Inference API" to run the Qwen2.5 language
+    model without needing to host it ourselves.
+
+ENDPOINTS (URLs this server responds to):
+    POST /ask    Send a question, get an answer
+                 Request:  { "question": "What's the temp in Tokyo?" }
+                 Response: { "answer": "It's currently 72°F and sunny in Tokyo..." }
+
+    GET  /health Just checks that the server is running
+                 Response: { "status": "ok" }
+
+ENVIRONMENT VARIABLES (settings loaded from the environment, not hardcoded):
+    HF_TOKEN        Your HuggingFace API token — needed to use the AI model
+    MCP_SERVER_URL  Where the weather tool server is running
+                    (defaults to http://localhost:8000/sse)
 """
 
 import asyncio
@@ -24,13 +57,23 @@ from mcp.client.sse import sse_client
 from huggingface_hub import InferenceClient
 
 # ---------------------------------------------------------------------------
-# Config
+# Configuration
 # ---------------------------------------------------------------------------
 
+# The AI model we're using. Qwen2.5 is an open-source language model made by
+# Alibaba, hosted for free on HuggingFace.
 MODEL = "Qwen/Qwen2.5-7B-Instruct"
+
+# Your HuggingFace token, loaded from an environment variable (not hardcoded
+# here for security reasons).
 HF_TOKEN = os.environ.get("HF_TOKEN")
+
+# The URL of the weather tool server (weather_mcp_server.py). SSE (Server-Sent
+# Events) is the communication protocol they use to talk to each other.
 MCP_SERVER_URL = os.environ.get("MCP_SERVER_URL", "http://localhost:8000/sse")
 
+# This is the instruction we give the AI at the start of every conversation.
+# It tells the AI what its job is and how to behave.
 SYSTEM_PROMPT = (
     "You are a helpful assistant with access to real-time weather data. "
     "When the user asks about temperature or weather, always use the "
@@ -39,12 +82,18 @@ SYSTEM_PROMPT = (
 )
 
 # ---------------------------------------------------------------------------
-# Startup: wait for MCP server to be ready
+# Startup: wait for the weather tool server to be ready
 # ---------------------------------------------------------------------------
 
+# This function runs when the web server first starts up. FastAPI calls it
+# automatically before accepting any requests.
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     print("Waiting for MCP server to be ready...", flush=True)
+
+    # Try up to 20 times (once per second) to connect to the weather tool
+    # server. Both servers start at the same time, so this gives the tool
+    # server time to finish booting before we start accepting requests.
     for _ in range(20):
         try:
             async with sse_client(MCP_SERVER_URL) as (read, write):
@@ -54,23 +103,32 @@ async def lifespan(app: FastAPI):
                     print(f"MCP ready — {len(tools.tools)} tool(s) available", flush=True)
                     break
         except Exception:
-            await asyncio.sleep(1)
+            await asyncio.sleep(1)  # Wait 1 second before trying again
     else:
         print("WARNING: MCP server did not become ready in time", flush=True)
-    yield
 
+    yield  # Hand control back to FastAPI — start accepting requests
 
+
+# Create the FastAPI web server instance.
 app = FastAPI(title="Weather via MCP + Qwen2.5", lifespan=lifespan)
 
 # ---------------------------------------------------------------------------
-# MCP helpers (SSE transport)
+# Functions for talking to the weather tool server (MCP)
 # ---------------------------------------------------------------------------
 
 async def fetch_mcp_tools() -> list[dict]:
+    """
+    Ask the weather tool server what tools it has available.
+
+    Returns a list of tool definitions formatted the way the AI model expects
+    them — including the tool's name, what it does, and what arguments it takes.
+    """
     async with sse_client(MCP_SERVER_URL) as (read, write):
         async with ClientSession(read, write) as session:
             await session.initialize()
             tools_result = await session.list_tools()
+            # Reformat each tool into the structure the AI model expects
             return [
                 {
                     "type": "function",
@@ -85,39 +143,70 @@ async def fetch_mcp_tools() -> list[dict]:
 
 
 async def call_mcp_tool(tool_name: str, tool_args: dict) -> str:
+    """
+    Call a specific tool on the weather tool server and return its result.
+
+    For example: call_mcp_tool("get_current_temperature", {"location": "Tokyo"})
+    connects to weather_mcp_server.py, runs that function, and returns the
+    weather data as a string.
+    """
     async with sse_client(MCP_SERVER_URL) as (read, write):
         async with ClientSession(read, write) as session:
             await session.initialize()
             result = await session.call_tool(tool_name, tool_args)
+            # The result may contain multiple content blocks; join them into one string
             return "\n".join(
                 block.text for block in result.content if hasattr(block, "text")
             )
 
 # ---------------------------------------------------------------------------
-# Agentic loop
+# The agentic loop — the core logic of this app
 # ---------------------------------------------------------------------------
 
 async def run(user_message: str) -> str:
+    """
+    Send a user's question to the AI and return its final answer.
+
+    This is called an "agentic loop" because the AI can go back and forth
+    multiple times — asking for tool results, getting them, then deciding
+    whether to ask for more or give a final answer.
+
+    Typical flow:
+      1. We send: [system prompt] + [user question] + [available tools]
+      2. AI responds: "I need to call get_current_temperature for Tokyo"
+      3. We call that tool and get the weather data
+      4. We send the weather data back to the AI
+      5. AI responds with a natural language answer — we return that
+    """
+    # Create a client that can talk to HuggingFace's AI inference API
     client = InferenceClient(model=MODEL, token=HF_TOKEN)
+
+    # Get the list of available tools from the weather server
     tools = await fetch_mcp_tools()
 
+    # Build the conversation history. The AI sees this as a back-and-forth chat.
+    # "system" sets the AI's behavior; "user" is the human's message.
     messages = [
         {"role": "system", "content": SYSTEM_PROMPT},
         {"role": "user",   "content": user_message},
     ]
 
+    # Send the conversation to the AI model and get its first response
     response = client.chat.completions.create(
         messages=messages,
-        tools=tools,
-        tool_choice="auto",
-        max_tokens=512,
-        temperature=0.2,
+        tools=tools,         # Tell the AI what tools it can use
+        tool_choice="auto",  # Let the AI decide whether to use a tool
+        max_tokens=512,      # Maximum length of the AI's response
+        temperature=0.2,     # Low temperature = more focused, less random responses
     )
 
     choice = response.choices[0]
     assistant_msg = choice.message
 
+    # If the AI wants to call a tool, handle it and loop back
     while choice.finish_reason == "tool_calls" and assistant_msg.tool_calls:
+
+        # Add the AI's tool request to the conversation history
         messages.append({
             "role": "assistant",
             "content": assistant_msg.content or "",
@@ -134,16 +223,18 @@ async def run(user_message: str) -> str:
             ],
         })
 
+        # Execute each tool the AI requested and add results to the conversation
         for tc in assistant_msg.tool_calls:
             fn_name = tc.function.name
-            fn_args = json.loads(tc.function.arguments)
+            fn_args = json.loads(tc.function.arguments)  # Parse the JSON arguments string
             tool_result = await call_mcp_tool(fn_name, fn_args)
             messages.append({
                 "role": "tool",
-                "tool_call_id": tc.id,
+                "tool_call_id": tc.id,   # Links this result to the specific tool call
                 "content": tool_result,
             })
 
+        # Send the updated conversation (now including tool results) back to the AI
         response = client.chat.completions.create(
             messages=messages,
             tools=tools,
@@ -154,26 +245,44 @@ async def run(user_message: str) -> str:
         choice = response.choices[0]
         assistant_msg = choice.message
 
+    # The AI has finished — return its final text response
     return assistant_msg.content or "(no response)"
 
 # ---------------------------------------------------------------------------
-# Routes
+# Request/response shapes
 # ---------------------------------------------------------------------------
 
+# These classes define the exact structure of data that goes in and out of
+# the /ask endpoint. FastAPI uses them to validate requests and format responses.
+
 class AskRequest(BaseModel):
-    question: str
+    question: str   # The user's weather question
 
 class AskResponse(BaseModel):
-    answer: str
+    answer: str     # The AI's response
 
+# ---------------------------------------------------------------------------
+# Endpoints (URLs the server responds to)
+# ---------------------------------------------------------------------------
 
 @app.get("/health")
 async def health():
+    """Simple health check — returns OK if the server is running."""
     return {"status": "ok"}
 
 
 @app.post("/ask", response_model=AskResponse)
 async def ask(req: AskRequest):
+    """
+    Main endpoint — accepts a weather question and returns an AI-generated answer.
+
+    Example request:
+        POST /ask
+        { "question": "What's the temperature in Paris?" }
+
+    Example response:
+        { "answer": "It's currently 58°F and partly cloudy in Paris, France." }
+    """
     if not req.question.strip():
         raise HTTPException(status_code=400, detail="question must not be empty")
     answer = await run(req.question)
@@ -181,9 +290,11 @@ async def ask(req: AskRequest):
 
 
 # ---------------------------------------------------------------------------
-# Entry point
+# Entry point (only used when running locally, not in Docker)
 # ---------------------------------------------------------------------------
 
+# This block only runs if you start the file directly: `python api.py`
+# In Docker/HuggingFace Spaces, supervisord starts uvicorn directly instead.
 if __name__ == "__main__":
     import uvicorn
     uvicorn.run(app, host="0.0.0.0", port=7860)

weather_mcp_server.py

@@ -1,37 +1,95 @@
 """
-weather_mcp_server.py
-
-A simple MCP server exposing a get_current_temperature tool.
-Uses Open-Meteo (free, no API key required).
-Run with: python weather_mcp_server.py
-Transport: stdio (default for local use) or SSE for remote.
+weather_mcp_server.py  —  The weather tool server for this app.
+
+WHAT THIS FILE DOES:
+    This file is a "tool server" — it doesn't talk to users directly. Instead,
+    it waits for api.py to ask it to do things, like "fetch the current
+    temperature in Tokyo." It does the work and sends the result back.
+
+WHAT IS MCP (Model Context Protocol)?
+    MCP is a standard developed by Anthropic that defines how AI models can use
+    external tools. The problem it solves: AI models only know what they were
+    trained on — they can't look things up in real time. MCP lets you plug in
+    tools that the AI can call to get live data.
+
+    There are two sides to MCP:
+      - MCP Server (this file): defines and runs the tools
+      - MCP Client (api.py): connects to this server and calls the tools
+                             on behalf of the AI
+
+    Think of it like a power outlet and a plug — MCP is the standard that
+    makes them compatible.
+
+WHAT IS FastMCP?
+    FastMCP is a Python library that makes it easy to build MCP servers. Without
+    it, you'd have to implement the MCP protocol by hand. With it, you just write
+    normal Python functions and add a @mcp.tool() decorator, and FastMCP handles
+    all the communication details automatically.
+
+HOW THE WEATHER DATA WORKS:
+    This app uses Open-Meteo (open-meteo.com), a free weather API that doesn't
+    require an account or API key. Getting weather for a city takes two steps:
+      1. Geocoding: convert the city name ("Tokyo") into coordinates (lat/lon)
+      2. Weather fetch: use those coordinates to get current conditions
+
+HOW THIS SERVER COMMUNICATES:
+    This server uses SSE (Server-Sent Events) — a way for one server to talk to
+    another over HTTP. It runs on port 8000 and api.py connects to it there.
+    SSE is used instead of stdio (standard input/output) because both servers
+    run as separate processes inside Docker and need to communicate over the
+    network, not through a shared terminal.
 """
 
 import httpx
 from mcp.server.fastmcp import FastMCP
 
+# Create the MCP server instance.
+# "weather-server" is just a name that identifies this server.
+# host/port tell it to listen on all network interfaces on port 8000.
 mcp = FastMCP("weather-server", host="0.0.0.0", port=8000)
 
 
 def _geocode(location: str) -> tuple[float, float, str]:
-    """Resolve a place name to (lat, lon, resolved_name) via Open-Meteo geocoding."""
+    """
+    Convert a city name into GPS coordinates (latitude and longitude).
+
+    AI models work with place names like "Tokyo" or "Paris", but weather APIs
+    need exact coordinates. This function bridges that gap by calling Open-Meteo's
+    free geocoding API.
+
+    Returns a tuple of (latitude, longitude, full_place_name).
+    For example: "Tokyo" → (35.6895, 139.6917, "Tokyo, Tokyo, Japan")
+
+    Raises ValueError if the location isn't found.
+    """
     resp = httpx.get(
         "https://geocoding-api.open-meteo.com/v1/search",
         params={"name": location, "count": 1, "language": "en", "format": "json"},
         timeout=10,
     )
-    resp.raise_for_status()
+    resp.raise_for_status()  # Raises an error if the HTTP request failed
     data = resp.json()
     results = data.get("results")
     if not results:
         raise ValueError(f"Location not found: {location!r}")
     r = results[0]
+    # Build a full place name like "Chicago, Illinois, United States"
     name = f"{r['name']}, {r.get('admin1', '')}, {r.get('country', '')}".strip(", ")
     return r["latitude"], r["longitude"], name
 
 
 def _fetch_temperature(lat: float, lon: float, unit: str) -> dict:
-    """Fetch current temperature from Open-Meteo."""
+    """
+    Fetch current weather conditions from Open-Meteo using GPS coordinates.
+
+    Requests three pieces of data:
+      - temperature_2m:    air temperature measured 2 meters above ground
+      - weathercode:       a WMO standard code representing current conditions
+                           (e.g. 0 = clear sky, 61 = slight rain)
+      - wind_speed_10m:    wind speed measured 10 meters above ground
+
+    Returns the raw JSON response from Open-Meteo.
+    """
     unit_param = "fahrenheit" if unit == "fahrenheit" else "celsius"
     resp = httpx.get(
         "https://api.open-meteo.com/v1/forecast",
@@ -41,7 +99,7 @@ def _fetch_temperature(lat: float, lon: float, unit: str) -> dict:
             "current": "temperature_2m,weathercode,wind_speed_10m",
             "temperature_unit": unit_param,
             "wind_speed_unit": "mph",
-            "timezone": "auto",
+            "timezone": "auto",   # Automatically detect the timezone for this location
         },
         timeout=10,
     )
@@ -49,7 +107,10 @@ def _fetch_temperature(lat: float, lon: float, unit: str) -> dict:
     return resp.json()
 
 
-# WMO weather code descriptions (subset)
+# WMO (World Meteorological Organization) weather codes.
+# Open-Meteo returns a numeric code for current conditions — this table
+# translates those numbers into human-readable descriptions.
+# This is a subset of the full WMO code table (codes go up to 99).
 WMO_CODES = {
     0: "Clear sky", 1: "Mainly clear", 2: "Partly cloudy", 3: "Overcast",
     45: "Fog", 48: "Icy fog",
@@ -61,22 +122,39 @@ WMO_CODES = {
 }
 
 
+# ---------------------------------------------------------------------------
+# The MCP tool — this is what the AI model can call
+# ---------------------------------------------------------------------------
+
+# @mcp.tool() is a "decorator" — it registers this function with the MCP server
+# so that api.py can discover it and offer it to the AI model. Without this
+# decorator, the function would just be a regular Python function that nothing
+# outside this file knows about.
 @mcp.tool()
 def get_current_temperature(location: str, unit: str = "fahrenheit") -> str:
     """
     Get the current temperature for any city or location.
 
+    This is the function the AI model calls when it needs weather data.
+    The AI passes in the location name and preferred unit, and gets back
+    a plain-text summary it can include in its response to the user.
+
     Args:
         location: City name or place (e.g. "Chicago", "Paris", "Tokyo").
         unit: Temperature unit — "fahrenheit" or "celsius". Defaults to fahrenheit.
 
     Returns:
-        A plain-text summary of current conditions.
+        A plain-text summary of current conditions, for example:
+            Current conditions in Tokyo, Tokyo, Japan:
+              Temperature: 68°F
+              Conditions:  Partly cloudy
+              Wind speed:  12 mph
     """
     unit = unit.lower()
     if unit not in ("fahrenheit", "celsius"):
         return f"Invalid unit {unit!r}. Use 'fahrenheit' or 'celsius'."
 
+    # Step 1: Convert the city name to GPS coordinates
     try:
         lat, lon, resolved = _geocode(location)
     except ValueError as e:
@@ -84,16 +162,18 @@ def get_current_temperature(location: str, unit: str = "fahrenheit") -> str:
     except httpx.HTTPError as e:
         return f"Geocoding request failed: {e}"
 
+    # Step 2: Fetch the current weather for those coordinates
     try:
         data = _fetch_temperature(lat, lon, unit)
     except httpx.HTTPError as e:
         return f"Weather request failed: {e}"
 
+    # Step 3: Extract the relevant fields from the response and format them
     current = data["current"]
     temp = current["temperature_2m"]
     wind = current["wind_speed_10m"]
     code = current.get("weathercode", 0)
-    condition = WMO_CODES.get(code, f"Weather code {code}")
+    condition = WMO_CODES.get(code, f"Weather code {code}")  # Fall back to the raw code if unknown
     symbol = "°F" if unit == "fahrenheit" else "°C"
 
     return (
@@ -104,11 +184,18 @@ def get_current_temperature(location: str, unit: str = "fahrenheit") -> str:
     )
 
 
+# ---------------------------------------------------------------------------
+# Entry point — how this server starts up
+# ---------------------------------------------------------------------------
+
 if __name__ == "__main__":
     import os
+    # MCP_TRANSPORT can be set to "stdio" for local testing (communicates via
+    # terminal input/output). In Docker/HuggingFace Spaces it defaults to "sse"
+    # so api.py can connect to it over the network.
     transport = os.environ.get("MCP_TRANSPORT", "sse")
     if transport == "stdio":
         mcp.run(transport="stdio")
     else:
-        # SSE — persistent server, used in Docker
+        # SSE (Server-Sent Events) — runs as a persistent HTTP server on port 8000
         mcp.run(transport="sse")