chore: import upstream snapshot with attribution

docs_src/extensions/tutorial001.py

@@ -0,0 +1,4 @@
+from mcp.server.apps import Apps
+from mcp.server.mcpserver import MCPServer
+
+mcp = MCPServer("demo", extensions=[Apps()])

docs_src/extensions/tutorial002.py

@@ -0,0 +1,5 @@
+from mcp.server.extension import Extension
+
+
+class Stamps(Extension):
+    identifier = "com.example/stamps"

docs_src/extensions/tutorial003.py

@@ -0,0 +1,35 @@
+from collections.abc import Sequence
+from typing import Any
+
+from mcp import Client
+from mcp.server.extension import Extension, ToolBinding
+from mcp.server.mcpserver import MCPServer
+
+
+def stamp(text: str) -> str:
+    """Stamp a message with the office seal."""
+    return f"[stamped] {text}"
+
+
+class Stamps(Extension):
+    """A purely additive extension: one tool, one capability entry."""
+
+    identifier = "com.example/stamps"
+
+    def settings(self) -> dict[str, Any]:
+        return {"sealed": True}
+
+    def tools(self) -> Sequence[ToolBinding]:
+        return [ToolBinding(fn=stamp)]
+
+
+mcp = MCPServer("post-office", extensions=[Stamps()])
+
+
+async def main() -> None:
+    async with Client(mcp) as client:
+        print(client.server_capabilities.extensions)
+        # {'com.example/stamps': {'sealed': True}}
+        result = await client.call_tool("stamp", {"text": "hello"})
+        print(result.content)
+        # [TextContent(text='[stamped] hello')]

docs_src/extensions/tutorial004.py

@@ -0,0 +1,59 @@
+from collections.abc import Sequence
+from typing import Any, Literal
+
+import mcp_types as types
+from pydantic import Field
+
+from mcp import Client
+from mcp.client import advertise
+from mcp.server.context import ServerRequestContext
+from mcp.server.extension import Extension, MethodBinding
+from mcp.server.mcpserver import MCPServer, require_client_extension
+
+EXTENSION_ID = "com.example/search"
+
+
+class SearchParams(types.RequestParams):
+    query: str
+    limit: int = Field(default=10, ge=1, le=100)
+
+
+class SearchResult(types.Result):
+    items: list[str]
+
+
+class SearchRequest(types.Request[SearchParams, Literal["com.example/search"]]):
+    method: Literal["com.example/search"] = "com.example/search"
+    params: SearchParams
+
+
+async def search(ctx: ServerRequestContext[Any, Any], params: SearchParams) -> SearchResult:
+    require_client_extension(ctx, EXTENSION_ID)
+    return SearchResult(items=[f"{params.query}-{n}" for n in range(params.limit)])
+
+
+class Search(Extension):
+    """An extension that serves its own request method."""
+
+    identifier = EXTENSION_ID
+
+    def methods(self) -> Sequence[MethodBinding]:
+        return [
+            MethodBinding(
+                "com.example/search",
+                SearchParams,
+                search,
+                protocol_versions=frozenset({"2026-07-28"}),
+            )
+        ]
+
+
+mcp = MCPServer("catalog", extensions=[Search()])
+
+
+async def main() -> None:
+    async with Client(mcp, extensions=[advertise(EXTENSION_ID)]) as client:
+        request = SearchRequest(params=SearchParams(query="mcp", limit=3))
+        result = await client.session.send_request(request, SearchResult)
+        print(result.items)
+        # ['mcp-0', 'mcp-1', 'mcp-2']

docs_src/extensions/tutorial005.py

@@ -0,0 +1,34 @@
+import logging
+from typing import Any
+
+from mcp_types import CallToolRequestParams
+
+from mcp.server.context import CallNext, HandlerResult, ServerRequestContext
+from mcp.server.extension import Extension
+from mcp.server.mcpserver import MCPServer
+
+logger = logging.getLogger(__name__)
+
+
+class AuditLog(Extension):
+    """Observe every tools/call without touching its result."""
+
+    identifier = "com.example/audit"
+
+    async def intercept_tool_call(
+        self,
+        params: CallToolRequestParams,
+        ctx: ServerRequestContext[Any, Any],
+        call_next: CallNext,
+    ) -> HandlerResult:
+        logger.info("tool %r called", params.name)
+        return await call_next(ctx)
+
+
+mcp = MCPServer("audited", extensions=[AuditLog()])
+
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b

docs_src/extensions/tutorial006.py

@@ -0,0 +1,70 @@
+from collections.abc import Sequence
+from typing import Any, Literal
+
+import mcp_types as types
+
+from mcp import Client
+from mcp.client import ClaimContext, ClientExtension, ResultClaim
+from mcp.server.context import CallNext, HandlerResult, ServerRequestContext
+from mcp.server.extension import Extension
+from mcp.server.mcpserver import MCPServer, require_client_extension
+
+EXTENSION_ID = "com.example/receipts"
+
+
+class ReceiptResult(types.Result):
+    """The claimed result shape; `result_type` pins the wire tag."""
+
+    result_type: Literal["receipt"] = "receipt"
+    receipt_token: str
+
+
+class ReceiptIssuer(Extension):
+    """Server half: answers `buy` with a receipt instead of a final result."""
+
+    identifier = EXTENSION_ID
+
+    async def intercept_tool_call(
+        self,
+        params: types.CallToolRequestParams,
+        ctx: ServerRequestContext[Any, Any],
+        call_next: CallNext,
+    ) -> HandlerResult:
+        if params.name != "buy":
+            return await call_next(ctx)
+        require_client_extension(ctx, EXTENSION_ID)
+        return {"resultType": "receipt", "receiptToken": "r-117"}
+
+
+class Receipts(ClientExtension):
+    """Client half: claims the `receipt` shape and supplies the code that finishes it."""
+
+    identifier = EXTENSION_ID
+
+    def claims(self) -> Sequence[ResultClaim[Any]]:
+        return [ResultClaim(result_type="receipt", model=ReceiptResult, resolve=self._redeem)]
+
+    async def _redeem(self, claimed: ReceiptResult, ctx: ClaimContext) -> types.CallToolResult:
+        return await ctx.session.call_tool("redeem", {"token": claimed.receipt_token})
+
+
+mcp = MCPServer("shop", extensions=[ReceiptIssuer()])
+
+
+@mcp.tool()
+def buy(item: str) -> types.CallToolResult:
+    """Buy an item."""
+    raise NotImplementedError  # ReceiptIssuer answers `buy` before the tool runs
+
+
+@mcp.tool()
+def redeem(token: str) -> str:
+    """Exchange a receipt token for the goods."""
+    return f"goods for {token}"
+
+
+async def main() -> None:
+    async with Client(mcp, extensions=[Receipts()]) as client:
+        result = await client.call_tool("buy", {"item": "lamp"})
+        print(result.content)
+        # [TextContent(text='goods for r-117')]

docs_src/extensions/tutorial007.py

@@ -0,0 +1,50 @@
+from collections.abc import Sequence
+from typing import Any, Literal
+
+import mcp_types as types
+
+from mcp import Client
+from mcp.client import advertise
+from mcp.server.context import ServerRequestContext
+from mcp.server.extension import Extension, MethodBinding
+from mcp.server.mcpserver import MCPServer
+
+EXTENSION_ID = "com.example/jobs"
+
+
+class JobParams(types.RequestParams):
+    job_id: str
+
+
+class JobStatus(types.Result):
+    status: str
+
+
+class JobStatusRequest(types.Request[JobParams, Literal["com.example/jobs.status"]]):
+    method: Literal["com.example/jobs.status"] = "com.example/jobs.status"
+    params: JobParams
+    name_param = "jobId"  # params["jobId"] rides the Mcp-Name header
+
+
+async def job_status(ctx: ServerRequestContext[Any, Any], params: JobParams) -> JobStatus:
+    return JobStatus(status=f"{params.job_id} is running")
+
+
+class Jobs(Extension):
+    """An extension whose verb names its subject, so the header can route on it."""
+
+    identifier = EXTENSION_ID
+
+    def methods(self) -> Sequence[MethodBinding]:
+        return [MethodBinding("com.example/jobs.status", JobParams, job_status)]
+
+
+mcp = MCPServer("worker", extensions=[Jobs()])
+
+
+async def main() -> None:
+    async with Client(mcp, extensions=[advertise(EXTENSION_ID)]) as client:
+        request = JobStatusRequest(params=JobParams(job_id="job-7"))
+        result = await client.session.send_request(request, JobStatus)
+        print(result.status)
+        # job-7 is running