docs: stop presenting the in-memory client as the way to connect (#3443)

docs_src/client/tutorial001.py

@@ -1,18 +1,56 @@
-from mcp import Client
+from pydantic import BaseModel
+
 from mcp.server import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import Completion, CompletionArgument, CompletionContext, PromptReference, ResourceTemplateReference
 
 mcp = MCPServer("Bookshop", instructions="Search the catalog before recommending a book.")
 
+GENRES = ["fiction", "non-fiction", "poetry"]
+
+
+class Book(BaseModel):
+    title: str
+    author: str
+    year: int
+
+
+@mcp.tool(title="Search the catalog")
+def search_books(query: str, limit: int = 10) -> str:
+    """Search the catalog by title or author."""
+    return f"Found 3 books matching {query!r} (showing up to {limit})."
+
 
 @mcp.tool()
-def search_books(query: str) -> str:
-    """Search the catalog by title or author."""
-    return f"Found 3 books matching {query!r}."
+def lookup_book(title: str) -> Book:
+    """Look up a book by its exact title."""
+    if title != "Dune":
+        raise ToolError(f"No book titled {title!r} in the catalog.")
+    return Book(title="Dune", author="Frank Herbert", year=1965)
 
 
-async def main() -> None:
-    async with Client(mcp) as client:
-        print(client.server_info)
-        print(client.server_capabilities)
-        print(client.protocol_version)
-        print(client.instructions)
+@mcp.resource("catalog://genres")
+def genres() -> list[str]:
+    """The genres the catalog is organised by."""
+    return GENRES
+
+
+@mcp.resource("catalog://genres/{genre}")
+def books_in_genre(genre: str) -> str:
+    """Every title we stock in one genre."""
+    return f"3 books filed under {genre}."
+
+
+@mcp.prompt(title="Recommend a book")
+def recommend(genre: str) -> str:
+    """Ask for a recommendation in a genre."""
+    return f"Recommend one {genre} book from the catalog and say why."
+
+
+@mcp.completion()
+async def complete_genre(
+    ref: PromptReference | ResourceTemplateReference,
+    argument: CompletionArgument,
+    context: CompletionContext | None,
+) -> Completion | None:
+    return Completion(values=[genre for genre in GENRES if genre.startswith(argument.value)])

docs_src/client/tutorial001_client.py

@@ -0,0 +1,15 @@
+import anyio
+
+from mcp import Client
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp") as client:
+        print(client.server_info)
+        print(client.server_capabilities)
+        print(client.protocol_version)
+        print(client.instructions)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial002.py

@@ -1,20 +1,17 @@
+import anyio
+
 from mcp import Client
-from mcp.server import MCPServer
-
-mcp = MCPServer("Bookshop")
-
-
-@mcp.tool(title="Search the catalog")
-def search_books(query: str, limit: int = 10) -> str:
-    """Search the catalog by title or author."""
-    return f"Found 3 books matching {query!r} (showing up to {limit})."
 
 
 async def main() -> None:
-    async with Client(mcp) as client:
+    async with Client("http://localhost:8000/mcp") as client:
         result = await client.list_tools()
         for tool in result.tools:
             print(tool.name)
             print(tool.title)
             print(tool.description)
             print(tool.input_schema)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial003.py

@@ -1,29 +1,11 @@
-from pydantic import BaseModel
+import anyio
 
 from mcp import Client
-from mcp.server import MCPServer
-from mcp.server.mcpserver.exceptions import ToolError
 from mcp.types import TextContent
 
-mcp = MCPServer("Bookshop")
-
-
-class Book(BaseModel):
-    title: str
-    author: str
-    year: int
-
-
-@mcp.tool()
-def lookup_book(title: str) -> Book:
-    """Look up a book by its exact title."""
-    if title != "Dune":
-        raise ToolError(f"No book titled {title!r} in the catalog.")
-    return Book(title="Dune", author="Frank Herbert", year=1965)
-
 
 async def main() -> None:
-    async with Client(mcp) as client:
+    async with Client("http://localhost:8000/mcp") as client:
         result = await client.call_tool("lookup_book", {"title": "Dune"})
 
         for block in result.content:
@@ -32,3 +14,7 @@ async def main() -> None:
 
         print(result.structured_content)
         print(result.is_error)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial004.py

@@ -1,24 +1,11 @@
+import anyio
+
 from mcp import Client
-from mcp.server import MCPServer
 from mcp.types import TextResourceContents
 
-mcp = MCPServer("Bookshop")
-
-
-@mcp.resource("catalog://genres")
-def genres() -> list[str]:
-    """The genres the catalog is organised by."""
-    return ["fiction", "non-fiction", "poetry"]
-
-
-@mcp.resource("catalog://genres/{genre}")
-def books_in_genre(genre: str) -> str:
-    """Every title we stock in one genre."""
-    return f"3 books filed under {genre}."
-
 
 async def main() -> None:
-    async with Client(mcp) as client:
+    async with Client("http://localhost:8000/mcp") as client:
         listed = await client.list_resources()
         print([resource.uri for resource in listed.resources])
 
@@ -29,3 +16,7 @@ async def main() -> None:
         for contents in result.contents:
             if isinstance(contents, TextResourceContents):
                 print(contents.text)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial005.py

@@ -1,20 +1,17 @@
+import anyio
+
 from mcp import Client
-from mcp.server import MCPServer
-
-mcp = MCPServer("Bookshop")
-
-
-@mcp.prompt(title="Recommend a book")
-def recommend(genre: str) -> str:
-    """Ask for a recommendation in a genre."""
-    return f"Recommend one {genre} book from the catalog and say why."
 
 
 async def main() -> None:
-    async with Client(mcp) as client:
+    async with Client("http://localhost:8000/mcp") as client:
         listed = await client.list_prompts()
         print(listed.prompts)
 
         result = await client.get_prompt("recommend", {"genre": "poetry"})
         for message in result.messages:
             print(message.role, message.content)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial006.py

@@ -1,31 +1,17 @@
+import anyio
+
 from mcp import Client
-from mcp.server import MCPServer
-from mcp.types import Completion, CompletionArgument, CompletionContext, PromptReference, ResourceTemplateReference
-
-mcp = MCPServer("Bookshop")
-
-GENRES = ["fiction", "non-fiction", "poetry"]
-
-
-@mcp.prompt()
-def recommend(genre: str) -> str:
-    """Ask for a recommendation in a genre."""
-    return f"Recommend one {genre} book from the catalog and say why."
-
-
-@mcp.completion()
-async def complete_genre(
-    ref: PromptReference | ResourceTemplateReference,
-    argument: CompletionArgument,
-    context: CompletionContext | None,
-) -> Completion | None:
-    return Completion(values=[genre for genre in GENRES if genre.startswith(argument.value)])
+from mcp.types import PromptReference
 
 
 async def main() -> None:
-    async with Client(mcp) as client:
+    async with Client("http://localhost:8000/mcp") as client:
         result = await client.complete(
             ref=PromptReference(type="ref/prompt", name="recommend"),
             argument={"name": "genre", "value": "p"},
         )
         print(result.completion.values)
+
+
+if __name__ == "__main__":
+    anyio.run(main)

docs_src/client/tutorial007.py

@@ -1,30 +1,25 @@
+import anyio
+
 from mcp import Client
-from mcp.server import MCPServer
 from mcp.types import Tool
 
-mcp = MCPServer("Bookshop")
 
-
-@mcp.tool()
-def search_books(query: str) -> str:
-    """Search the catalog by title or author."""
-    return f"Found 3 books matching {query!r}."
-
-
-@mcp.tool()
-def reserve_book(title: str) -> str:
-    """Put a book on hold."""
-    return f"Reserved {title!r}."
+async def list_all_tools(client: Client) -> list[Tool]:
+    tools: list[Tool] = []
+    cursor: str | None = None
+    while True:
+        page = await client.list_tools(cursor=cursor)
+        tools.extend(page.tools)
+        if page.next_cursor is None:
+            return tools
+        cursor = page.next_cursor
 
 
 async def main() -> None:
-    async with Client(mcp) as client:
-        tools: list[Tool] = []
-        cursor: str | None = None
-        while True:
-            page = await client.list_tools(cursor=cursor)
-            tools.extend(page.tools)
-            if page.next_cursor is None:
-                break
-            cursor = page.next_cursor
+    async with Client("http://localhost:8000/mcp") as client:
+        tools = await list_all_tools(client)
         print([tool.name for tool in tools])
+
+
+if __name__ == "__main__":
+    anyio.run(main)