chore: import upstream snapshot with attribution

docs_src/lowlevel/tutorial001.py

@@ -0,0 +1,33 @@
+from mcp_types import (
+    CallToolRequestParams,
+    CallToolResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    TextContent,
+    Tool,
+)
+
+from mcp.server import Server, ServerRequestContext
+
+SEARCH_BOOKS = Tool(
+    name="search_books",
+    description="Search the catalog by title or author.",
+    input_schema={
+        "type": "object",
+        "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}},
+        "required": ["query", "limit"],
+    },
+)
+
+
+async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+    return ListToolsResult(tools=[SEARCH_BOOKS])
+
+
+async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+    args = params.arguments or {}
+    text = f"Found 3 books matching {args['query']!r} (showing up to {args['limit']})."
+    return CallToolResult(content=[TextContent(type="text", text=text)])
+
+
+server = Server("Bookshop", on_list_tools=list_tools, on_call_tool=call_tool)

docs_src/lowlevel/tutorial002.py

@@ -0,0 +1,48 @@
+from mcp_types import (
+    CallToolRequestParams,
+    CallToolResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    TextContent,
+    Tool,
+)
+
+from mcp.server import Server, ServerRequestContext
+
+SEARCH_BOOKS = Tool(
+    name="search_books",
+    description="Search the catalog by title or author.",
+    input_schema={
+        "type": "object",
+        "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}},
+        "required": ["query", "limit"],
+    },
+)
+
+ADD_BOOK = Tool(
+    name="add_book",
+    description="Add a book to the catalog.",
+    input_schema={
+        "type": "object",
+        "properties": {"title": {"type": "string"}, "author": {"type": "string"}, "year": {"type": "integer"}},
+        "required": ["title", "author", "year"],
+    },
+)
+
+
+async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+    return ListToolsResult(tools=[SEARCH_BOOKS, ADD_BOOK])
+
+
+async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+    args = params.arguments or {}
+    if params.name == "search_books":
+        text = f"Found 3 books matching {args['query']!r} (showing up to {args['limit']})."
+    elif params.name == "add_book":
+        text = f"Added {args['title']!r} by {args['author']} ({args['year']})."
+    else:
+        raise ValueError(f"Unknown tool: {params.name}")
+    return CallToolResult(content=[TextContent(type="text", text=text)])
+
+
+server = Server("Bookshop", on_list_tools=list_tools, on_call_tool=call_tool)

docs_src/lowlevel/tutorial003.py

@@ -0,0 +1,41 @@
+from mcp_types import (
+    CallToolRequestParams,
+    CallToolResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    TextContent,
+    Tool,
+)
+
+from mcp.server import Server, ServerRequestContext
+
+SEARCH_BOOKS = Tool(
+    name="search_books",
+    description="Search the catalog by title or author.",
+    input_schema={
+        "type": "object",
+        "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}},
+        "required": ["query", "limit"],
+    },
+    output_schema={
+        "type": "object",
+        "properties": {"matches": {"type": "integer"}, "query": {"type": "string"}},
+        "required": ["matches", "query"],
+    },
+)
+
+
+async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+    return ListToolsResult(tools=[SEARCH_BOOKS])
+
+
+async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+    args = params.arguments or {}
+    data = {"matches": 3, "query": args["query"]}
+    return CallToolResult(
+        content=[TextContent(type="text", text=f"Found 3 books matching {args['query']!r}.")],
+        structured_content=data,
+    )
+
+
+server = Server("Bookshop", on_list_tools=list_tools, on_call_tool=call_tool)

docs_src/lowlevel/tutorial004.py

@@ -0,0 +1,42 @@
+from mcp_types import (
+    CallToolRequestParams,
+    CallToolResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    TextContent,
+    Tool,
+)
+
+from mcp.server import Server, ServerRequestContext
+
+SEARCH_BOOKS = Tool(
+    name="search_books",
+    description="Search the catalog by title or author.",
+    input_schema={
+        "type": "object",
+        "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}},
+        "required": ["query", "limit"],
+    },
+    output_schema={
+        "type": "object",
+        "properties": {"matches": {"type": "integer"}, "query": {"type": "string"}},
+        "required": ["matches", "query"],
+    },
+)
+
+
+async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+    return ListToolsResult(tools=[SEARCH_BOOKS])
+
+
+async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+    args = params.arguments or {}
+    data = {"matches": 3, "query": args["query"]}
+    return CallToolResult(
+        content=[TextContent(type="text", text=f"Found 3 books matching {args['query']!r}.")],
+        structured_content=data,
+        _meta={"bookshop/record_ids": ["bk_17", "bk_42", "bk_99"]},
+    )
+
+
+server = Server("Bookshop", on_list_tools=list_tools, on_call_tool=call_tool)

docs_src/lowlevel/tutorial005.py

@@ -0,0 +1,51 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from mcp_types import (
+    CallToolRequestParams,
+    CallToolResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    TextContent,
+    Tool,
+)
+
+from mcp.server import Server, ServerRequestContext
+
+
+@dataclass
+class Catalog:
+    books: list[str]
+
+    def search(self, query: str) -> list[str]:
+        return [title for title in self.books if query.lower() in title.lower()]
+
+
+@asynccontextmanager
+async def lifespan(server: Server[Catalog]) -> AsyncIterator[Catalog]:
+    yield Catalog(books=["Dune", "Dune Messiah", "Children of Dune"])
+
+
+SEARCH_BOOKS = Tool(
+    name="search_books",
+    description="Search the catalog by title or author.",
+    input_schema={
+        "type": "object",
+        "properties": {"query": {"type": "string"}},
+        "required": ["query"],
+    },
+)
+
+
+async def list_tools(ctx: ServerRequestContext[Catalog], params: PaginatedRequestParams | None) -> ListToolsResult:
+    return ListToolsResult(tools=[SEARCH_BOOKS])
+
+
+async def call_tool(ctx: ServerRequestContext[Catalog], params: CallToolRequestParams) -> CallToolResult:
+    matches = ctx.lifespan_context.search((params.arguments or {})["query"])
+    text = f"Found {len(matches)} books: {', '.join(matches)}."
+    return CallToolResult(content=[TextContent(type="text", text=text)])
+
+
+server = Server("Bookshop", lifespan=lifespan, on_list_tools=list_tools, on_call_tool=call_tool)

docs_src/lowlevel/tutorial006.py

@@ -0,0 +1,48 @@
+from mcp_types import (
+    CallToolRequestParams,
+    CallToolResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    RequestParams,
+    TextContent,
+    Tool,
+)
+from pydantic import BaseModel
+
+from mcp.server import Server, ServerRequestContext
+
+SEARCH_BOOKS = Tool(
+    name="search_books",
+    description="Search the catalog by title or author.",
+    input_schema={
+        "type": "object",
+        "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}},
+        "required": ["query", "limit"],
+    },
+)
+
+
+async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+    return ListToolsResult(tools=[SEARCH_BOOKS])
+
+
+async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+    args = params.arguments or {}
+    text = f"Found 3 books matching {args['query']!r} (showing up to {args['limit']})."
+    return CallToolResult(content=[TextContent(type="text", text=text)])
+
+
+class ReindexParams(RequestParams):
+    full: bool = False
+
+
+class ReindexResult(BaseModel):
+    indexed: int
+
+
+async def reindex(ctx: ServerRequestContext, params: ReindexParams) -> ReindexResult:
+    return ReindexResult(indexed=3)
+
+
+server = Server("Bookshop", on_list_tools=list_tools, on_call_tool=call_tool)
+server.add_request_handler("bookshop/reindex", ReindexParams, reindex)