Rebuild the docs around tested examples; shrink README.v2.md to a pitch (#2978)

docs_src/structured_output/tutorial001.py

@@ -0,0 +1,11 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Weather")
+
+READINGS = {"London": 17, "Cairo": 34, "Reykjavik": 4}
+
+
+@mcp.tool()
+def get_temperature(city: str) -> int:
+    """Current temperature in a city, in whole degrees Celsius."""
+    return READINGS[city]

docs_src/structured_output/tutorial002.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel, Field
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Weather")
+
+
+class WeatherData(BaseModel):
+    temperature: float = Field(description="Degrees Celsius.")
+    humidity: float = Field(description="Relative humidity, 0 to 1.")
+    conditions: str
+
+
+@mcp.tool()
+def get_weather(city: str) -> WeatherData:
+    """Current weather for a city."""
+    return WeatherData(temperature=16.2, humidity=0.83, conditions="Overcast")

docs_src/structured_output/tutorial003.py

@@ -0,0 +1,17 @@
+from typing import TypedDict
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Weather")
+
+
+class WeatherData(TypedDict):
+    temperature: float
+    humidity: float
+    conditions: str
+
+
+@mcp.tool()
+def get_weather(city: str) -> WeatherData:
+    """Current weather for a city."""
+    return WeatherData(temperature=16.2, humidity=0.83, conditions="Overcast")

docs_src/structured_output/tutorial004.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Weather")
+
+
+@dataclass
+class WeatherData:
+    temperature: float
+    humidity: float
+    conditions: str
+
+
+@mcp.tool()
+def get_weather(city: str) -> WeatherData:
+    """Current weather for a city."""
+    return WeatherData(temperature=16.2, humidity=0.83, conditions="Overcast")

docs_src/structured_output/tutorial005.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Weather")
+
+
+class WeatherData(BaseModel):
+    temperature: float
+    humidity: float
+    conditions: str
+
+
+@mcp.tool()
+def get_forecast(city: str, days: int) -> list[WeatherData]:
+    """Daily forecast for a city."""
+    return [WeatherData(temperature=16.2 + day, humidity=0.83, conditions="Overcast") for day in range(days)]

docs_src/structured_output/tutorial006.py

@@ -0,0 +1,11 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Weather")
+
+READINGS = {"London": 16.2, "Cairo": 34.1, "Reykjavik": 4.4}
+
+
+@mcp.tool()
+def get_temperatures(cities: list[str]) -> dict[str, float]:
+    """Current temperature for each city, in degrees Celsius."""
+    return {city: READINGS[city] for city in cities}

docs_src/structured_output/tutorial007.py

@@ -0,0 +1,21 @@
+import json
+
+from pydantic import BaseModel
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("Weather")
+
+UPSTREAM = {"London": '{"temperature": 16.2, "conditions": "Overcast"}'}
+
+
+class WeatherData(BaseModel):
+    temperature: float
+    humidity: float
+    conditions: str
+
+
+@mcp.tool()
+def get_weather(city: str) -> WeatherData:
+    """Current weather for a city."""
+    return json.loads(UPSTREAM[city])

docs_src/structured_output/tutorial008.py

@@ -0,0 +1,9 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Weather")
+
+
+@mcp.tool(structured_output=False)
+def weather_report(city: str) -> str:
+    """A human-readable weather report for a city."""
+    return f"{city}: 17 degrees, overcast, light rain easing by evening."

docs_src/structured_output/tutorial009.py

@@ -0,0 +1,15 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Weather")
+
+
+class Station:
+    def __init__(self, name: str, online: bool):
+        self.name = name
+        self.online = online
+
+
+@mcp.tool()
+def get_station(name: str) -> Station:
+    """Look up a weather station by name."""
+    return Station(name=name, online=True)