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

docs_src/completions/tutorial002.py

@@ -0,0 +1,30 @@
+from mcp_types import Completion, CompletionArgument, CompletionContext, PromptReference, ResourceTemplateReference
+
+from mcp.server import MCPServer
+
+mcp = MCPServer("GitHub Explorer")
+
+LANGUAGES = ["go", "javascript", "python", "rust", "typescript"]
+
+
+@mcp.resource("github://repos/{owner}/{repo}")
+def github_repo(owner: str, repo: str) -> str:
+    """A GitHub repository."""
+    return f"Repository: {owner}/{repo}"
+
+
+@mcp.prompt()
+def review_code(language: str, code: str) -> str:
+    """Review a snippet of code."""
+    return f"Review this {language} code:\n{code}"
+
+
+@mcp.completion()
+async def handle_completion(
+    ref: PromptReference | ResourceTemplateReference,
+    argument: CompletionArgument,
+    context: CompletionContext | None,
+) -> Completion | None:
+    if isinstance(ref, PromptReference) and argument.name == "language":
+        return Completion(values=[lang for lang in LANGUAGES if lang.startswith(argument.value)])
+    return None