docs: cover the remaining Tier 1 audit items (#3325)

docs_src/lowlevel/tutorial007.py

@@ -0,0 +1,30 @@
+from mcp.server import Server, ServerRequestContext
+from mcp.types import CallToolRequestParams, CallToolResult, ListToolsResult, PaginatedRequestParams, TextContent, Tool
+
+FIND_BOOK = Tool(
+    name="find_book",
+    description="Find one book by ISBN, or by title and author.",
+    input_schema={
+        "type": "object",
+        "properties": {
+            "isbn": {"type": "string", "pattern": "^[0-9]{13}$"},
+            "title": {"type": "string"},
+            "author": {"type": "string"},
+        },
+        "oneOf": [{"required": ["isbn"]}, {"required": ["title", "author"]}],
+        "additionalProperties": False,
+    },
+)
+
+
+async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+    return ListToolsResult(tools=[FIND_BOOK])
+
+
+async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+    args = params.arguments or {}
+    found = f"ISBN {args['isbn']}" if "isbn" in args else f"{args['title']!r} by {args['author']}"
+    return CallToolResult(content=[TextContent(type="text", text=f"Found {found} on shelf C-3.")])
+
+
+server = Server("Bookshop", on_list_tools=list_tools, on_call_tool=call_tool)

docs_src/media/tutorial005.py

@@ -0,0 +1,18 @@
+from mcp.server import MCPServer
+from mcp.types import EmbeddedResource, TextResourceContents
+
+mcp = MCPServer("Brand kit")
+
+
+@mcp.resource("brand://guidelines", mime_type="text/markdown")
+def guidelines() -> str:
+    """How to use the brand assets."""
+    return "# Brand guidelines\n\nUse the primary colour for calls to action.\n"
+
+
+@mcp.tool()
+def brand_guidelines() -> EmbeddedResource:
+    """The brand guidelines as a Markdown document."""
+    return EmbeddedResource(
+        resource=TextResourceContents(uri="brand://guidelines", mime_type="text/markdown", text=guidelines())
+    )

docs_src/prompts/tutorial004.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Message, UserMessage
+from mcp.types import EmbeddedResource, TextResourceContents
+
+mcp = MCPServer("Code Helper")
+
+STYLE_GUIDE_FILE = Path(__file__).parent / "style-guide.md"  # or the path to your file on disk
+
+
+@mcp.resource("style://python", mime_type="text/markdown")
+def style_guide() -> str:
+    """The team's Python style guide."""
+    return STYLE_GUIDE_FILE.read_text(encoding="utf-8")
+
+
+@mcp.prompt()
+def review_code(code: str) -> list[Message]:
+    """Review a piece of code against the team style guide."""
+    guide = TextResourceContents(uri="style://python", mime_type="text/markdown", text=style_guide())
+    return [
+        UserMessage(EmbeddedResource(resource=guide)),
+        UserMessage(f"Review this code against the style guide above:\n\n{code}"),
+    ]

docs_src/prompts/tutorial005.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Image, Message, UserMessage
+
+mcp = MCPServer("Code Helper")
+
+DIAGRAM_FILE = Path(__file__).parent / "architecture.png"  # or the path to your file on disk
+
+
+@mcp.prompt()
+def explain_component(component: str) -> list[Message]:
+    """Explain one component using the architecture diagram."""
+    return [
+        UserMessage(Image(path=DIAGRAM_FILE)),
+        UserMessage(f"Where does {component} sit in this architecture, and what does it talk to?"),
+    ]

docs_src/prompts/tutorial006.py

@@ -0,0 +1,28 @@
+from contextlib import suppress
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+from mcp.server.mcpserver.prompts import Prompt
+
+mcp = MCPServer("Code Helper")
+
+
+@mcp.prompt()
+def review_code(code: str) -> str:
+    """Review a piece of code."""
+    return f"Please review this code:\n\n{code}"
+
+
+@mcp.tool()
+async def save_template(name: str, instruction: str, ctx: Context) -> str:
+    """Save an instruction as a prompt the user can pick from the menu."""
+
+    def template(code: str) -> str:
+        return f"{instruction}\n\n{code}"
+
+    with suppress(ValueError):  # replace an existing entry of the same name
+        mcp.remove_prompt(name)
+    mcp.add_prompt(Prompt.from_function(template, name=name, description=instruction))
+    await ctx.notify_prompts_changed()
+    await ctx.session.send_prompt_list_changed()
+    return f"Saved '{name}' to the prompt menu."