docs: make all code examples self-contained and runnable

Every Python code block in docs pages is now both linted and executed
by pytest-examples.

- Make all concepts.md examples self-contained with proper imports
- Add test_docs_examples_run that executes every doc code block
- Use __name__ override to prevent `if __name__ == "__main__"` blocks
  from starting servers during tests
- Support skip-run/skip-lint prefix tags for future use
- Drop snippet-source from quickstart.md so the example is
  self-contained

Author: Kludex

docs/concepts.md

@@ -21,41 +21,51 @@ Host (e.g. Claude Desktop)
 
 ## Primitives
 
-MCP servers expose three core primitives:
+MCP servers expose three core primitives: **resources**, **tools**, and **prompts**.
 
 ### Resources
 
 Resources provide data to LLMs — similar to GET endpoints in a REST API. They load information into the
 LLM's context without performing computation or causing side effects.
 
+Resources can be static (fixed URI) or use URI templates for dynamic content:
+
 ```python
+import json
+
+from mcp.server.mcpserver import MCPServer
+
+mcp = MCPServer("Demo")
+
+
 @mcp.resource("config://app")
 def get_config() -> str:
     """Expose application configuration."""
     return json.dumps({"theme": "dark", "version": "2.0"})
-```
 
-Resources can be static (fixed URI) or use URI templates for dynamic content:
 
-```python
 @mcp.resource("users://{user_id}/profile")
 def get_profile(user_id: str) -> str:
     """Get a user profile by ID."""
-    return json.dumps(load_profile(user_id))
+    return json.dumps({"user_id": user_id, "name": "Alice"})
 ```
 
 <!-- TODO: See [Resources](server/resources.md) for full documentation. -->
 
 ### Tools
 
 Tools let LLMs take actions — similar to POST endpoints. They perform computation, call external APIs,
-or produce side effects.
+or produce side effects:
 
 ```python
+from mcp.server.mcpserver import MCPServer
+
+mcp = MCPServer("Demo")
+
+
 @mcp.tool()
 def send_email(to: str, subject: str, body: str) -> str:
     """Send an email to the given recipient."""
-    # ... send email logic ...
     return f"Email sent to {to}"
 ```
 
@@ -67,6 +77,11 @@ Tools support structured output, progress reporting, and more.
 Prompts are reusable templates for LLM interactions. They help standardize common workflows:
 
 ```python
+from mcp.server.mcpserver import MCPServer
+
+mcp = MCPServer("Demo")
+
+
 @mcp.prompt()
 def review_code(code: str, language: str = "python") -> str:
     """Generate a code review prompt."""
@@ -93,7 +108,10 @@ When handling requests, your functions can access a **context object** that prov
 like logging, progress reporting, and access to the current session:
 
 ```python
-from mcp.server.mcpserver import Context
+from mcp.server.mcpserver import Context, MCPServer
+
+mcp = MCPServer("Demo")
+
 
 @mcp.tool()
 async def long_task(ctx: Context) -> str:
@@ -113,15 +131,28 @@ Servers support a **lifespan** pattern for managing startup and shutdown logic 
 initializing a database connection pool on startup and closing it on shutdown:
 
 ```python
+from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from mcp.server.mcpserver import MCPServer
+
+
+@dataclass
+class AppContext:
+    db_url: str
+
 
 @asynccontextmanager
-async def app_lifespan(server):
-    db = await Database.connect()
+async def app_lifespan(server: MCPServer) -> AsyncIterator[AppContext]:
+    # Initialize on startup
+    ctx = AppContext(db_url="postgresql://localhost/mydb")
     try:
-        yield {"db": db}
+        yield ctx
     finally:
-        await db.disconnect()
+        # Cleanup on shutdown
+        pass
+
 
 mcp = MCPServer("My App", lifespan=app_lifespan)
 ```

docs/quickstart.md

@@ -10,14 +10,7 @@ You'll need Python 3.10+ and [uv](https://docs.astral.sh/uv/) (recommended) or p
 
 Create a file called `server.py` with a tool, a resource, and a prompt:
 
-<!-- snippet-source examples/snippets/servers/mcpserver_quickstart.py -->
 ```python
-"""MCPServer quickstart example.
-
-Run from the repository root:
-    uv run examples/snippets/servers/mcpserver_quickstart.py
-"""
-
 from mcp.server.mcpserver import MCPServer
 
 # Create an MCP server
@@ -27,21 +20,21 @@ mcp = MCPServer("Demo")
 # Add an addition tool
 @mcp.tool()
 def add(a: int, b: int) -> int:
-    """Add two numbers"""
+    """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"""
+    """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"""
+    """Generate a greeting prompt."""
     styles = {
         "friendly": "Please write a warm, friendly greeting",
         "formal": "Please write a formal, professional greeting",
@@ -51,14 +44,10 @@ def greet_user(name: str, style: str = "friendly") -> str:
     return f"{styles.get(style, styles['friendly'])} for someone named {name}."
 
 
-# Run with streamable HTTP transport
 if __name__ == "__main__":
-    mcp.run(transport="streamable-http", json_response=True)
+    mcp.run(transport="streamable-http")
 ```
 
-_Full example: [examples/snippets/servers/mcpserver_quickstart.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/mcpserver_quickstart.py)_
-<!-- /snippet-source -->
-
 ## Run the server
 
 ```bash

tests/test_examples.py

@@ -7,6 +7,7 @@
 
 import sys
 from pathlib import Path
+from typing import Any
 
 import pytest
 from inline_snapshot import snapshot
@@ -96,20 +97,52 @@ async def test_desktop(monkeypatch: pytest.MonkeyPatch):
             assert "/fake/path/file2.txt" in content.text
 
 
+SKIP_RUN_TAGS = ["skip", "skip-run"]
+SKIP_LINT_TAGS = ["skip", "skip-lint"]
+
+# Files with code examples that are both linted and run
+DOCS_FILES = ["docs/quickstart.md", "docs/concepts.md"]
+
+
+def _set_eval_config(eval_example: EvalExample) -> None:
+    eval_example.set_config(
+        ruff_ignore=["F841", "I001", "F821"],
+        target_version="py310",
+        line_length=120,
+    )
+
+
 # TODO(v2): Change back to README.md when v2 is released
 @pytest.mark.parametrize(
     "example",
-    find_examples("README.v2.md", "docs/quickstart.md", "docs/concepts.md"),
+    find_examples("README.v2.md", *DOCS_FILES),
     ids=str,
 )
 def test_docs_examples(example: CodeExample, eval_example: EvalExample):
-    ruff_ignore: list[str] = ["F841", "I001", "F821"]  # F821: undefined names (snippets lack imports)
+    if any(example.prefix_settings().get(key) == "true" for key in SKIP_LINT_TAGS):
+        pytest.skip("skip-lint")
 
-    # Use project's actual line length of 120
-    eval_example.set_config(ruff_ignore=ruff_ignore, target_version="py310", line_length=120)
+    _set_eval_config(eval_example)
 
-    # Use Ruff for both formatting and linting (skip Black)
     if eval_example.update_examples:  # pragma: no cover
         eval_example.format_ruff(example)
     else:
         eval_example.lint_ruff(example)
+
+
+def _get_runnable_docs_examples() -> list[CodeExample]:
+    examples = find_examples(*DOCS_FILES)
+    return [ex for ex in examples if not any(ex.prefix_settings().get(key) == "true" for key in SKIP_RUN_TAGS)]
+
+
+@pytest.mark.parametrize("example", _get_runnable_docs_examples(), ids=str)
+def test_docs_examples_run(example: CodeExample, eval_example: EvalExample):
+    _set_eval_config(eval_example)
+
+    # Prevent `if __name__ == "__main__"` blocks from starting servers
+    globals: dict[str, Any] = {"__name__": "__docs_test__"}
+
+    if eval_example.update_examples:  # pragma: no cover
+        eval_example.run_print_update(example, module_globals=globals)
+    else:
+        eval_example.run_print_check(example, module_globals=globals)