chore: import upstream snapshot with attribution

docs_src/uri_templates/tutorial001.py

@@ -0,0 +1,43 @@
+from mcp.server import MCPServer
+
+mcp = MCPServer("Bookshop")
+
+BOOKS = {
+    "978-0441172719": {"title": "Dune", "author": "Frank Herbert"},
+    "978-0553293357": {"title": "Foundation", "author": "Isaac Asimov"},
+}
+
+MANUALS = {
+    "printing/setup.md": "# Printer setup\n\nLoad paper, then power on.",
+    "returns.md": "# Returns policy\n\nThirty days with a receipt.",
+}
+
+
+@mcp.resource("books://{isbn}")
+def get_book(isbn: str) -> dict[str, str]:
+    """A single book by ISBN."""
+    return BOOKS[isbn]
+
+
+@mcp.resource("orders://{order_id}")
+def get_order(order_id: int) -> dict[str, object]:
+    """An order by its numeric id."""
+    return {"order_id": order_id, "next_order": order_id + 1, "status": "shipped"}
+
+
+@mcp.resource("manuals://{+path}")
+def read_manual(path: str) -> str:
+    """A staff manual page. The path keeps its slashes."""
+    return MANUALS[path]
+
+
+@mcp.resource("reviews://{isbn}{?limit,sort}")
+def list_reviews(isbn: str, limit: int = 10, sort: str = "newest") -> str:
+    """Reviews of a book, optionally limited and sorted."""
+    return f"{limit} {sort} reviews of {BOOKS[isbn]['title']}"
+
+
+@mcp.resource("shelves://browse{/path*}")
+def browse_shelf(path: list[str]) -> str:
+    """A shelf in the category tree, addressed by segments."""
+    return " > ".join(["catalog", *path])

docs_src/uri_templates/tutorial002.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+
+from mcp.server import MCPServer
+from mcp.shared.path_security import safe_join
+
+mcp = MCPServer("Bookshop")
+
+DOCS_ROOT = Path("./manuals")
+
+
+@mcp.resource("manuals://{+path}")
+def read_manual(path: str) -> str:
+    """A staff manual page, served from a directory on disk."""
+    return safe_join(DOCS_ROOT, path).read_text()

docs_src/uri_templates/tutorial003.py

@@ -0,0 +1,25 @@
+from mcp.server import MCPServer
+from mcp.server.mcpserver import ResourceSecurity
+
+mcp = MCPServer("Bookshop")
+
+
+@mcp.resource(
+    "imports://preview/{+source}",
+    security=ResourceSecurity(exempt_params={"source"}),
+)
+def preview_import(source: str) -> str:
+    """Preview a catalog import. `source` may be an absolute path."""
+    return f"Would import from {source}"
+
+
+relaxed = MCPServer(
+    "Bookshop",
+    resource_security=ResourceSecurity(reject_path_traversal=False),
+)
+
+
+@relaxed.resource("imports://preview/{+source}")
+def preview_import_relaxed(source: str) -> str:
+    """The server-wide flag exempts every resource on `relaxed`."""
+    return f"Would import from {source}"

docs_src/uri_templates/tutorial004.py

@@ -0,0 +1,28 @@
+from mcp_types import (
+    ListResourcesResult,
+    PaginatedRequestParams,
+    ReadResourceRequestParams,
+    ReadResourceResult,
+    Resource,
+    TextResourceContents,
+)
+
+from mcp.server import Server, ServerRequestContext
+
+RESOURCES = {
+    "config://shop": '{"currency": "USD", "tax_rate": 0.08}',
+    "status://health": "ok",
+}
+
+
+async def list_resources(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListResourcesResult:
+    return ListResourcesResult(resources=[Resource(name=uri, uri=uri) for uri in RESOURCES])
+
+
+async def read_resource(ctx: ServerRequestContext, params: ReadResourceRequestParams) -> ReadResourceResult:
+    if (text := RESOURCES.get(params.uri)) is not None:
+        return ReadResourceResult(contents=[TextResourceContents(uri=params.uri, text=text)])
+    raise ValueError(f"Unknown resource: {params.uri}")
+
+
+server = Server("Bookshop", on_list_resources=list_resources, on_read_resource=read_resource)

docs_src/uri_templates/tutorial005.py

@@ -0,0 +1,55 @@
+from mcp_types import (
+    ListResourceTemplatesResult,
+    PaginatedRequestParams,
+    ReadResourceRequestParams,
+    ReadResourceResult,
+    ResourceTemplate,
+    TextResourceContents,
+)
+
+from mcp.server import Server, ServerRequestContext
+from mcp.shared.path_security import contains_path_traversal, is_absolute_path
+from mcp.shared.uri_template import UriTemplate
+
+TEMPLATES = {
+    "manuals": UriTemplate.parse("manuals://{+path}"),
+    "books": UriTemplate.parse("books://{isbn}"),
+}
+
+MANUALS = {"printing/setup.md": "# Printer setup", "returns.md": "# Returns policy"}
+BOOKS = {"978-0441172719": "Dune by Frank Herbert"}
+
+
+def read_manual_safely(path: str) -> str:
+    if contains_path_traversal(path) or is_absolute_path(path):
+        raise ValueError("rejected")
+    return MANUALS[path]
+
+
+async def read_resource(ctx: ServerRequestContext, params: ReadResourceRequestParams) -> ReadResourceResult:
+    if (matched := TEMPLATES["manuals"].match(params.uri)) is not None:
+        text = read_manual_safely(str(matched["path"]))
+        return ReadResourceResult(contents=[TextResourceContents(uri=params.uri, text=text)])
+
+    if (matched := TEMPLATES["books"].match(params.uri)) is not None:
+        text = BOOKS[str(matched["isbn"])]
+        return ReadResourceResult(contents=[TextResourceContents(uri=params.uri, text=text)])
+
+    raise ValueError(f"Unknown resource: {params.uri}")
+
+
+async def list_resource_templates(
+    ctx: ServerRequestContext, params: PaginatedRequestParams | None
+) -> ListResourceTemplatesResult:
+    return ListResourceTemplatesResult(
+        resource_templates=[
+            ResourceTemplate(name=name, uri_template=str(template)) for name, template in TEMPLATES.items()
+        ]
+    )
+
+
+server = Server(
+    "Bookshop",
+    on_read_resource=read_resource,
+    on_list_resource_templates=list_resource_templates,
+)