docs: extract uri-templates examples to tested docs_src/ files

Converts docs/advanced/uri-templates.md to the docs_src/ pattern used
by the rest of the docs: runnable example files under
docs_src/uri_templates/ included via --8<--, with
tests/docs_src/test_uri_templates.py proving each claim the page makes.

Author: maxisbey

docs/advanced/uri-templates.md

@@ -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/__init__.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/tutorial001.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/tutorial002.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/tutorial003.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,
+)

docs_src/uri_templates/tutorial004.py

@@ -0,0 +1,170 @@
+"""`docs/advanced/uri-templates.md`: every claim the page makes, proved against the real SDK."""
+
+from pathlib import Path
+
+import pytest
+from inline_snapshot import snapshot
+from mcp_types import INVALID_PARAMS, ErrorData, ResourceTemplate, TextResourceContents
+
+from docs_src.uri_templates import tutorial001, tutorial002, tutorial003, tutorial004, tutorial005
+from mcp import Client, MCPError
+from mcp.shared.path_security import PathEscapeError, contains_path_traversal, safe_join
+
+# See test_index.py for why this is a per-module mark and not a conftest hook.
+pytestmark = [pytest.mark.anyio, pytest.mark.filterwarnings("error::mcp.MCPDeprecationWarning")]
+
+
+async def test_simple_expansion_maps_the_segment_to_the_argument() -> None:
+    """tutorial001: `books://{isbn}` reads `books://978-...` and the matched string is the argument."""
+    async with Client(tutorial001.mcp) as client:
+        (content,) = (await client.read_resource("books://978-0441172719")).contents
+        assert isinstance(content, TextResourceContents)
+        assert content.text == snapshot('{\n  "title": "Dune",\n  "author": "Frank Herbert"\n}')
+
+
+async def test_an_int_parameter_is_converted_from_the_uri_string() -> None:
+    """tutorial001: `order_id: int` receives `12345`, not `"12345"`, so `order_id + 1` is `12346`."""
+    async with Client(tutorial001.mcp) as client:
+        (content,) = (await client.read_resource("orders://12345")).contents
+        assert isinstance(content, TextResourceContents)
+        assert content.text == snapshot('{\n  "order_id": 12345,\n  "next_order": 12346,\n  "status": "shipped"\n}')
+
+
+async def test_plus_keeps_the_slashes_in_the_captured_value() -> None:
+    """tutorial001: `{+path}` matches `printing/setup.md` as one value; a plain `{path}` would not."""
+    async with Client(tutorial001.mcp) as client:
+        (content,) = (await client.read_resource("manuals://printing/setup.md")).contents
+        assert isinstance(content, TextResourceContents)
+        assert content.text == "# Printer setup\n\nLoad paper, then power on."
+
+
+async def test_omitted_query_params_fall_through_to_function_defaults() -> None:
+    """tutorial001: `{?limit,sort}` is lenient. No query string means `limit=10, sort="newest"`."""
+    async with Client(tutorial001.mcp) as client:
+        (content,) = (await client.read_resource("reviews://978-0441172719")).contents
+        assert isinstance(content, TextResourceContents)
+        assert content.text == "10 newest reviews of Dune"
+
+
+async def test_a_query_param_overrides_only_the_default_it_names() -> None:
+    """tutorial001: `?sort=top` sets `sort` and leaves `limit` at its default."""
+    async with Client(tutorial001.mcp) as client:
+        (content,) = (await client.read_resource("reviews://978-0441172719?sort=top")).contents
+        assert isinstance(content, TextResourceContents)
+        assert content.text == "10 top reviews of Dune"
+
+
+async def test_exploded_path_arrives_as_a_list_of_segments() -> None:
+    """tutorial001: `{/path*}` splits `/fiction/sci-fi` into `["fiction", "sci-fi"]`."""
+    async with Client(tutorial001.mcp) as client:
+        (content,) = (await client.read_resource("shelves://browse/fiction/sci-fi")).contents
+        assert isinstance(content, TextResourceContents)
+        assert content.text == "catalog > fiction > sci-fi"
+
+
+async def test_traversal_is_rejected_before_the_handler_runs() -> None:
+    """The `!!! check`: `../` triggers `-32602` "Unknown resource" and `read_manual` is never called."""
+    async with Client(tutorial001.mcp) as client:
+        with pytest.raises(MCPError) as exc_info:
+            await client.read_resource("manuals://../etc/passwd")
+    assert exc_info.value.error == snapshot(
+        ErrorData(
+            code=INVALID_PARAMS,
+            message="Unknown resource: manuals://../etc/passwd",
+            data={"uri": "manuals://../etc/passwd"},
+        )
+    )
+
+
+def test_dotdot_is_a_component_check_not_a_substring_scan() -> None:
+    """The page's prose: `v1.0..v2.0` passes because `..` is not a standalone path segment."""
+    assert contains_path_traversal("../etc") is True
+    assert contains_path_traversal("v1.0..v2.0") is False
+
+
+async def test_safe_join_serves_a_file_inside_the_base_directory(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """tutorial002: `safe_join(DOCS_ROOT, path).read_text()` returns the file under the base."""
+    (tmp_path / "printing").mkdir()
+    (tmp_path / "printing" / "setup.md").write_text("# Printer setup")
+    monkeypatch.setattr(tutorial002, "DOCS_ROOT", tmp_path)
+    async with Client(tutorial002.mcp) as client:
+        (content,) = (await client.read_resource("manuals://printing/setup.md")).contents
+        assert isinstance(content, TextResourceContents)
+        assert content.text == "# Printer setup"
+
+
+def test_safe_join_raises_when_the_resolved_path_escapes_the_base(tmp_path: Path) -> None:
+    """tutorial002: a path that climbs out of `DOCS_ROOT` raises `PathEscapeError`."""
+    with pytest.raises(PathEscapeError):
+        safe_join(tmp_path, "../etc/passwd")
+
+
+async def test_exempt_params_lets_an_absolute_path_through() -> None:
+    """tutorial003: `exempt_params={"source"}` skips the checks for that one parameter."""
+    async with Client(tutorial003.mcp) as client:
+        (content,) = (await client.read_resource("imports://preview//srv/incoming/catalog.csv")).contents
+        assert isinstance(content, TextResourceContents)
+        assert content.text == "Would import from /srv/incoming/catalog.csv"
+
+
+async def test_server_wide_resource_security_relaxes_every_resource() -> None:
+    """tutorial003: `resource_security=ResourceSecurity(reject_path_traversal=False)` exempts the whole server."""
+    async with Client(tutorial003.relaxed) as client:
+        (content,) = (await client.read_resource("imports://preview/../sibling/catalog.csv")).contents
+        assert isinstance(content, TextResourceContents)
+        assert content.text == "Would import from ../sibling/catalog.csv"
+
+
+async def test_lowlevel_static_dispatch_lists_and_reads_by_exact_uri() -> None:
+    """tutorial004: the registry is the listing, and a known URI returns its text."""
+    async with Client(tutorial004.server) as client:
+        listed = (await client.list_resources()).resources
+        assert [r.uri for r in listed] == ["config://shop", "status://health"]
+        (content,) = (await client.read_resource("status://health")).contents
+        assert content == TextResourceContents(uri="status://health", text="ok")
+
+
+async def test_lowlevel_unknown_uri_raises() -> None:
+    """tutorial004: a URI outside the registry raises and surfaces as a protocol error."""
+    async with Client(tutorial004.server) as client:
+        with pytest.raises(MCPError):
+            await client.read_resource("config://missing")
+
+
+def test_uritemplate_match_returns_a_dict_or_none() -> None:
+    """tutorial005: `match()` extracts decoded variables, or `None` when the URI doesn't fit."""
+    assert tutorial005.TEMPLATES["manuals"].match("manuals://printing/setup.md") == {"path": "printing/setup.md"}
+    assert tutorial005.TEMPLATES["books"].match("manuals://nope") is None
+
+
+async def test_lowlevel_match_routes_the_request_to_the_right_template() -> None:
+    """tutorial005: two templates, one handler. Each concrete URI lands in its own branch."""
+    async with Client(tutorial005.server) as client:
+        (manual,) = (await client.read_resource("manuals://printing/setup.md")).contents
+        assert manual == TextResourceContents(uri="manuals://printing/setup.md", text="# Printer setup")
+        (book,) = (await client.read_resource("books://978-0441172719")).contents
+        assert book == TextResourceContents(uri="books://978-0441172719", text="Dune by Frank Herbert")
+
+
+async def test_lowlevel_handler_applies_the_safety_checks_itself() -> None:
+    """tutorial005: there is no default policy down here; `read_manual_safely` is the gate."""
+    async with Client(tutorial005.server) as client:
+        with pytest.raises(MCPError):
+            await client.read_resource("manuals://../etc/passwd")
+        with pytest.raises(MCPError):
+            await client.read_resource("nothing://matches")
+
+
+async def test_str_of_a_template_round_trips_to_the_original_string() -> None:
+    """tutorial005: `str(template)` is the source string, so the listing reuses the parsed templates."""
+    assert str(tutorial005.TEMPLATES["manuals"]) == "manuals://{+path}"
+    async with Client(tutorial005.server) as client:
+        result = await client.list_resource_templates()
+        assert result.resource_templates == snapshot(
+            [
+                ResourceTemplate(name="manuals", uri_template="manuals://{+path}"),
+                ResourceTemplate(name="books", uri_template="books://{isbn}"),
+            ]
+        )