Embed code snippets for README from executable examples

.github/workflows/shared.yml

@@ -46,3 +46,19 @@
       - name: Run pytest
         run: uv run --frozen --no-sync pytest
     continue-on-error: true
+
+  readme-snippets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          version: 0.7.2
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --python 3.10
+
+      - name: Check README snippets are up to date
+        run: uv run --frozen scripts/update_readme_snippets.py --check

.pre-commit-config.yaml

@@ -36,3 +36,9 @@ repos:
         language: system
         files: ^(pyproject\.toml|uv\.lock)$
         pass_filenames: false
+      - id: readme-snippets
+        name: Check README snippets are up to date
+        entry: uv run scripts/update_readme_snippets.py --check
+        language: system
+        files: ^(README\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
+        pass_filenames: false

README.md

@@ -419,21 +419,27 @@ def create_thumbnail(image_path: str) -> Image:
 
 The Context object gives your tools and resources access to MCP capabilities:
 
+<!-- snippet-source examples/servers/everything/src/everything/server.py#L43-L58 -->
 ```python
-from mcp.server.fastmcp import FastMCP, Context
-
-mcp = FastMCP("My App")
-
+    # Tool with context for logging and progress
+    @mcp.tool(description="A tool that demonstrates logging and progress", title="Progress Tool")
+    async def tool_with_progress(message: str, ctx: Context, steps: int = 3) -> str:
+        await ctx.info(f"Starting processing of '{message}' with {steps} steps")
+
+        # Send progress notifications
+        for i in range(steps):
+            progress_value = (i + 1) / steps
+            await ctx.report_progress(
+                progress=progress_value,
+                total=1.0,
+                message=f"Processing step {i + 1} of {steps}",
+            )
+            await ctx.debug(f"Completed step {i + 1}")
 
-@mcp.tool()
-async def long_task(files: list[str], ctx: Context) -> str:
-    """Process multiple files with progress tracking"""
-    for i, file in enumerate(files):
-        ctx.info(f"Processing {file}")
-        await ctx.report_progress(i, len(files))
-        data, mime_type = await ctx.read_resource(f"file://{file}")
-    return "Processing complete"
+        return f"Processed '{message}' in {steps} steps"
 ```
+_Full example: [examples/servers/everything/src/everything/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/everything/src/everything/server.py#L43-L58)_
+<!-- /snippet-source -->
 
 ### Completions
 

examples/servers/everything/README.md

@@ -0,0 +1,43 @@
+# MCP Everything Server
+
+A comprehensive example MCP server that demonstrates all features of the Model Context Protocol, including:
+
+- Tools with progress reporting, logging, and elicitation
+- Resource handling (static, dynamic, and templated)
+- Prompts with arguments
+- Completion support for resource templates and prompts
+- Request context propagation
+- Notifications and logging
+- Sampling capabilities
+- Structured output
+
+## Usage
+
+### Running the server
+
+```bash
+uv run mcp-server-everything
+```
+
+### Testing with MCP Inspector
+
+```bash
+mcp dev "uv run mcp-server-everything"
+```
+
+### Installing in Claude Desktop
+
+```bash
+mcp install "uv run mcp-server-everything" --name "Everything Server"
+```
+
+## Features
+
+This server demonstrates:
+
+- **Tools**: Echo, progress tracking, sampling, notifications, context access, elicitation
+- **Resources**: Static resources, dynamic resources with parameters, resource templates
+- **Prompts**: Simple and complex prompts with arguments
+- **Completions**: Context-aware completion for prompts and resource templates
+- **Notifications**: Progress updates, logging at different levels, resource/tool list changes
+- **Elicitation**: Interactive user input during tool execution

examples/servers/everything/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "mcp-server-everything"
+version = "0.1.0"
+description = "Comprehensive MCP server demonstrating all protocol features"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp",
+    "pydantic>=2.0",
+    "httpx",
+]
+
+[project.scripts]
+mcp-server-everything = "everything.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

examples/servers/everything/src/everything/__init__.py

@@ -0,0 +1,5 @@
+"""MCP Everything Server - Comprehensive example demonstrating all MCP features."""
+
+from .server import create_everything_server
+
+__all__ = ["create_everything_server"]

examples/servers/everything/src/everything/__main__.py

@@ -0,0 +1,14 @@
+"""Main entry point for the Everything Server."""
+
+from .server import create_everything_server
+
+
+def main():
+    """Run the everything server."""
+    mcp = create_everything_server()
+    # Use FastMCP's built-in run method for better CLI integration
+    mcp.run(transport="sse")
+
+
+if __name__ == "__main__":
+    main()