README - replace code snippets with examples (#1136)

examples/snippets/servers/__init__.py

@@ -21,7 +21,8 @@ def run_server():
     if len(sys.argv) < 2:
         print("Usage: server <server-name> [transport]")
         print("Available servers: basic_tool, basic_resource, basic_prompt, tool_progress,")
-        print("                   sampling, elicitation, completion, notifications")
+        print("                   sampling, elicitation, completion, notifications,")
+        print("                   fastmcp_quickstart, structured_output, images")
         print("Available transports: stdio (default), sse, streamable-http")
         sys.exit(1)
 

examples/snippets/servers/fastmcp_quickstart.py

@@ -0,0 +1,38 @@
+"""
+FastMCP quickstart example.
+
+cd to the `examples/snippets/clients` directory and run:
+    uv run server fastmcp_quickstart stdio
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+# Create an MCP server
+mcp = FastMCP("Demo")
+
+
+# Add an addition tool
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+
+# Add a dynamic greeting resource
+@mcp.resource("greeting://{name}")
+def get_greeting(name: str) -> str:
+    """Get a personalized greeting"""
+    return f"Hello, {name}!"
+
+
+# Add a prompt
+@mcp.prompt()
+def greet_user(name: str, style: str = "friendly") -> str:
+    """Generate a greeting prompt"""
+    styles = {
+        "friendly": "Please write a warm, friendly greeting",
+        "formal": "Please write a formal, professional greeting",
+        "casual": "Please write a casual, relaxed greeting",
+    }
+
+    return f"{styles.get(style, styles['friendly'])} for someone named {name}."

examples/snippets/servers/images.py

@@ -0,0 +1,15 @@
+"""Example showing image handling with FastMCP."""
+
+from PIL import Image as PILImage
+
+from mcp.server.fastmcp import FastMCP, Image
+
+mcp = FastMCP("Image Example")
+
+
+@mcp.tool()
+def create_thumbnail(image_path: str) -> Image:
+    """Create a thumbnail from an image"""
+    img = PILImage.open(image_path)
+    img.thumbnail((100, 100))
+    return Image(data=img.tobytes(), format="png")

examples/snippets/servers/lifespan_example.py

@@ -0,0 +1,56 @@
+"""Example showing lifespan support for startup/shutdown with strong typing."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from mcp.server.fastmcp import Context, FastMCP
+
+
+# Mock database class for example
+class Database:
+    """Mock database class for example."""
+
+    @classmethod
+    async def connect(cls) -> "Database":
+        """Connect to database."""
+        return cls()
+
+    async def disconnect(self) -> None:
+        """Disconnect from database."""
+        pass
+
+    def query(self) -> str:
+        """Execute a query."""
+        return "Query result"
+
+
+@dataclass
+class AppContext:
+    """Application context with typed dependencies."""
+
+    db: Database
+
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
+    """Manage application lifecycle with type-safe context."""
+    # Initialize on startup
+    db = await Database.connect()
+    try:
+        yield AppContext(db=db)
+    finally:
+        # Cleanup on shutdown
+        await db.disconnect()
+
+
+# Pass lifespan to server
+mcp = FastMCP("My App", lifespan=app_lifespan)
+
+
+# Access type-safe lifespan context in tools
+@mcp.tool()
+def query_db(ctx: Context) -> str:
+    """Tool that uses initialized resources."""
+    db = ctx.request_context.lifespan_context.db
+    return db.query()

examples/snippets/servers/structured_output.py

@@ -0,0 +1,29 @@
+"""Example showing structured output with tools."""
+
+from pydantic import BaseModel, Field
+
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("Structured Output Example")
+
+
+# Using Pydantic models for rich structured data
+class WeatherData(BaseModel):
+    """Weather information structure."""
+
+    temperature: float = Field(description="Temperature in Celsius")
+    humidity: float = Field(description="Humidity percentage")
+    condition: str
+    wind_speed: float
+
+
+@mcp.tool()
+def get_weather(city: str) -> WeatherData:
+    """Get weather for a city - returns structured data."""
+    # Simulated weather data
+    return WeatherData(
+        temperature=72.5,
+        humidity=45.0,
+        condition="sunny",
+        wind_speed=5.2,
+    )