Add story-style examples suite (27 stories + harness + CI) (#2957)

examples/stories/schema_validators/server.py

@@ -0,0 +1,59 @@
+"""Four ways to type a tool parameter so MCPServer derives and enforces inputSchema."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import BaseModel
+
+# pydantic requires typing_extensions.TypedDict (not typing.TypedDict) on Python < 3.12
+# when a TypedDict is used as a field/parameter type.
+from typing_extensions import TypedDict
+
+from mcp.server.mcpserver import MCPServer
+from stories._hosting import run_server_from_args
+
+
+class PersonModel(BaseModel):
+    name: str
+    title: str = "friend"
+
+
+class PersonTD(TypedDict):
+    name: str
+    title: str
+
+
+@dataclass
+class PersonDC:
+    name: str
+    title: str = "friend"
+
+
+def build_server() -> MCPServer:
+    mcp = MCPServer("schema-validators-example")
+
+    @mcp.tool()
+    def greet_pydantic(who: PersonModel) -> str:
+        """`who` arrives as a validated PersonModel instance."""
+        return f"Hello {who.name}, my {who.title}"
+
+    @mcp.tool()
+    def greet_typeddict(who: PersonTD) -> str:
+        """`who` arrives as a plain dict; TypedDict drives the schema and editor hints."""
+        return f"Hello {who['name']}, my {who['title']}"
+
+    @mcp.tool()
+    def greet_dataclass(who: PersonDC) -> str:
+        """`who` arrives as a PersonDC instance (pydantic coerces the wire dict)."""
+        return f"Hello {who.name}, my {who.title}"
+
+    @mcp.tool()
+    def greet_dict(who: dict[str, Any]) -> str:
+        """`who` is a free-form object — any dict passes; the handler must check it."""
+        return f"Hello {who['name']}, my {who.get('title', 'friend')}"
+
+    return mcp
+
+
+if __name__ == "__main__":
+    run_server_from_args(build_server)