Add quickstart-client example for the "Building MCP clients" tutorial

Import the quickstart MCP client from
`modelcontextprotocol/quickstart-resources` into
`examples/clients/quickstart-client/`. This is the companion code for
the "Building MCP clients" tutorial at modelcontextprotocol.io.

The client connects to any MCP server via stdio, discovers its tools,
and runs an interactive chat loop where user queries are sent to Claude
with the server's tools available for use.

Changes from the upstream source:

- Moved `import sys` to top-level imports
- Added return type annotations (`-> None`) to all methods
- Added `assert self.session is not None` guards for type narrowing
- Changed `tool.inputSchema` to `tool.input_schema` (SDK Python name)
- Added proper Anthropic type annotations (`MessageParam`, `ToolParam`,
  `TextBlock`, `ToolUseBlock`, `ToolResultBlockParam`, `TextBlockParam`)
- Fixed tool result handling to use proper `ToolResultBlockParam` with
  `tool_use_id` linkage and explicit MCP `TextContent` to Anthropic
  `TextBlockParam` conversion, replacing the original code which passed
  raw MCP content objects to the Anthropic API

Root `pyproject.toml` adds `mcp-quickstart-client` as a dev dependency
with a workspace source mapping. This is necessary because `anthropic`
is a new external dependency not already in the root package's
transitive dependency tree, and without this, `uv sync --all-extras`
(used by CI) would not install it, causing `pyright` to fail.

Author: jonathanhefner

examples/clients/quickstart-client/.env.example

@@ -0,0 +1 @@
+ANTHROPIC_API_KEY=

examples/clients/quickstart-client/README.md

@@ -0,0 +1,3 @@
+# An LLM-Powered Chatbot MCP Client written in Python
+
+See the [Building MCP clients](https://modelcontextprotocol.io/tutorials/building-a-client) tutorial for more information.

examples/clients/quickstart-client/client.py

@@ -0,0 +1,167 @@
+import asyncio
+import os
+import sys
+from contextlib import AsyncExitStack
+from pathlib import Path
+
+from anthropic import Anthropic
+from anthropic.types import MessageParam, TextBlock, TextBlockParam, ToolParam, ToolResultBlockParam, ToolUseBlock
+from dotenv import load_dotenv
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from mcp.types import TextContent
+
+load_dotenv()  # load environment variables from .env
+
+# Claude model constant
+ANTHROPIC_MODEL = "claude-sonnet-4-5"
+
+
+class MCPClient:
+    def __init__(self) -> None:
+        # Initialize session and client objects
+        self.session: ClientSession | None = None
+        self.exit_stack = AsyncExitStack()
+        self._anthropic: Anthropic | None = None
+
+    @property
+    def anthropic(self) -> Anthropic:
+        """Lazy-initialize Anthropic client when needed"""
+        if self._anthropic is None:
+            self._anthropic = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+        return self._anthropic
+
+    async def connect_to_server(self, server_script_path: str) -> None:
+        """Connect to an MCP server
+
+        Args:
+            server_script_path: Path to the server script (.py or .js)
+        """
+        is_python = server_script_path.endswith(".py")
+        is_js = server_script_path.endswith(".js")
+        if not (is_python or is_js):
+            raise ValueError("Server script must be a .py or .js file")
+
+        if is_python:
+            path = Path(server_script_path).resolve()
+            server_params = StdioServerParameters(
+                command="uv",
+                args=["--directory", str(path.parent), "run", path.name],
+                env=None,
+            )
+        else:
+            server_params = StdioServerParameters(command="node", args=[server_script_path], env=None)
+
+        stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
+        self.stdio, self.write = stdio_transport
+        self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))
+
+        await self.session.initialize()
+
+        # List available tools
+        response = await self.session.list_tools()
+        tools = response.tools
+        print("\nConnected to server with tools:", [tool.name for tool in tools])
+
+    async def process_query(self, query: str) -> str:
+        """Process a query using Claude and available tools"""
+        assert self.session is not None
+        messages: list[MessageParam] = [{"role": "user", "content": query}]
+
+        response = await self.session.list_tools()
+        available_tools: list[ToolParam] = [
+            {"name": tool.name, "description": tool.description or "", "input_schema": tool.input_schema or {}}
+            for tool in response.tools
+        ]
+
+        # Initial Claude API call
+        response = self.anthropic.messages.create(
+            model=ANTHROPIC_MODEL, max_tokens=1000, messages=messages, tools=available_tools
+        )
+
+        # Process response and handle tool calls
+        final_text: list[str] = []
+
+        for content in response.content:
+            if isinstance(content, TextBlock):
+                final_text.append(content.text)
+            elif isinstance(content, ToolUseBlock):
+                tool_name = content.name
+                tool_args = content.input
+
+                # Execute tool call
+                assert self.session is not None
+                result = await self.session.call_tool(tool_name, tool_args)
+                final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")
+
+                # Continue conversation with tool results
+                messages.append({"role": "assistant", "content": response.content})
+                tool_result_content: list[TextBlockParam] = [
+                    {"type": "text", "text": block.text} for block in result.content if isinstance(block, TextContent)
+                ]
+                tool_result: ToolResultBlockParam = {
+                    "type": "tool_result",
+                    "tool_use_id": content.id,
+                    "content": tool_result_content,
+                }
+                messages.append({"role": "user", "content": [tool_result]})
+
+                # Get next response from Claude
+                response = self.anthropic.messages.create(
+                    model=ANTHROPIC_MODEL,
+                    max_tokens=1000,
+                    messages=messages,
+                )
+
+                response_text = response.content[0]
+                if isinstance(response_text, TextBlock):
+                    final_text.append(response_text.text)
+
+        return "\n".join(final_text)
+
+    async def chat_loop(self) -> None:
+        """Run an interactive chat loop"""
+        print("\nMCP Client Started!")
+        print("Type your queries or 'quit' to exit.")
+
+        while True:
+            try:
+                query = input("\nQuery: ").strip()
+
+                if query.lower() == "quit":
+                    break
+
+                response = await self.process_query(query)
+                print("\n" + response)
+
+            except Exception as e:
+                print(f"\nError: {str(e)}")
+
+    async def cleanup(self) -> None:
+        """Clean up resources"""
+        await self.exit_stack.aclose()
+
+
+async def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python client.py <path_to_server_script>")
+        sys.exit(1)
+
+    client = MCPClient()
+    try:
+        await client.connect_to_server(sys.argv[1])
+
+        # Check if we have a valid API key to continue
+        api_key = os.getenv("ANTHROPIC_API_KEY")
+        if not api_key:
+            print("\nNo ANTHROPIC_API_KEY found. To query these tools with Claude, set your API key:")
+            print("  export ANTHROPIC_API_KEY=your-api-key-here")
+            return
+
+        await client.chat_loop()
+    finally:
+        await client.cleanup()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/clients/quickstart-client/mcp_quickstart_client/__init__.py

@@ -0,0 +1,25 @@
+[project]
+name = "mcp-quickstart-client"
+version = "0.1.0"
+description = "Tutorial companion: an LLM-powered chatbot MCP client"
+requires-python = ">=3.10"
+dependencies = [
+    "anthropic>=0.72.0",
+    "mcp",
+    "python-dotenv>=1.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["mcp_quickstart_client"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = []

examples/clients/quickstart-client/pyproject.toml

@@ -58,6 +58,8 @@ required-version = ">=0.9.5"
 dev = [
     # We add mcp[cli,ws] so `uv sync` considers the extras.
     "mcp[cli,ws]",
+    # Pull in workspace members whose deps aren't already covered by the root package.
+    "mcp-quickstart-client",
     "pyright>=1.1.400",
     "pytest>=8.3.4",
     "ruff>=0.8.5",
@@ -167,6 +169,7 @@ members = ["examples/clients/*", "examples/servers/*", "examples/snippets"]
 
 [tool.uv.sources]
 mcp = { workspace = true }
+mcp-quickstart-client = { workspace = true }
 strict-no-cover = { git = "https://github.com/pydantic/strict-no-cover" }
 
 [tool.pytest.ini_options]