Merge pull request #79 from modelcontextprotocol/drewbent/personas

Break up quickstart into 4 different ones based on personas

clients.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Clients"
+title: "Example Clients"
 description: "A list of applications that support MCP integrations"
 ---
 

examples.mdx

@@ -1,5 +1,5 @@
 ---
-title: Examples 
+title: Example Servers 
 description: 'A list of example servers and implementations'
 ---
 

introduction.mdx

@@ -19,7 +19,7 @@ At its core, MCP follows a client-server architecture where a host application c
 ```mermaid
 flowchart LR
     subgraph "Your Computer"
-        Host["MCP Host\n(Claude, IDEs, Tools)"]
+        Host["Host with MCP Client\n(Claude, IDEs, Tools)"]
         S1["MCP Server A"]
         S2["MCP Server B"]
         S3["MCP Server C"]
@@ -44,23 +44,42 @@ flowchart LR
 
 Choose the path that best fits your needs:
 
+#### Quick Starts
 <CardGroup cols={2}>
   <Card
-    title="Quickstart"
+    title="For Server Developers"
     icon="bolt"
-    href="/quickstart"
+    href="/quickstart/server"
   >
-    Build and connect to your first MCP server
+    Get started building your own server to use in Claude for Desktop and other clients
   </Card>
   <Card
-    title="Examples"
+    title="For Client Developers"
+    icon="bolt"
+    href="/quickstart/client"
+  >
+    Get started building your own client that can integrate with all MCP servers
+  </Card>
+  <Card
+    title="For Claude Desktop Users"
+    icon="bolt"
+    href="/quickstart/user"
+  >
+    Get started using pre-built servers in Claude for Desktop
+  </Card>
+</CardGroup>
+
+#### Examples
+<CardGroup cols={2}>
+  <Card
+    title="Example Servers"
     icon="grid"
     href="/examples"
   >
     Check out our gallery of official MCP servers and implementations
   </Card>
   <Card
-    title="Clients"
+    title="Example Clients"
     icon="cubes"
     href="/clients"
   >
@@ -71,13 +90,6 @@ Choose the path that best fits your needs:
 ## Tutorials
 
 <CardGroup cols={2}>
-  <Card
-    title="Building a MCP client"
-    icon="outlet"
-    href="/tutorials/building-a-client"
-  >
-    Learn how to build your first MCP client
-  </Card>
   <Card
     title="Building MCP with LLMs"
     icon="comments"

mint.json

@@ -47,15 +47,22 @@
       "group": "Get Started",
       "pages": [
         "introduction",
-        "quickstart",
+        {
+          "group": "Quickstart",
+          "pages": [
+            "quickstart/server",
+            "quickstart/client",
+            "quickstart/user"
+          ]
+        },
         "examples",
         "clients"
       ]
     },
+    
     {
       "group": "Tutorials",
       "pages": [
-        "tutorials/building-a-client",
         "tutorials/building-mcp-with-llms",
         "docs/tools/debugging",
         "docs/tools/inspector"
@@ -86,5 +93,15 @@
   },
   "feedback": {
     "thumbsRating": true
-  }
+  },
+  "redirects": [
+    {
+      "source": "/tutorials/building-a-client",
+      "destination": "/quickstart/client"
+    },
+    {
+      "source": "/quickstart",
+      "destination": "/quickstart/server"
+    }
+  ]
 }

quickstart/client.mdx

@@ -0,0 +1,430 @@
+---
+title: "For Client Developers"
+description: "Get started building your own client that can integrate with all MCP servers."
+---
+
+In this tutorial, you'll learn how to build a LLM-powered chatbot client that connects to MCP servers. It helps to have gone through the [Server quickstart](/quickstart/server) that guides you through the basic of building your first server.
+
+<Tabs>
+<Tab title="Python">
+
+[You can find the complete code for this tutorial here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client)
+
+## System Requirements
+
+Before starting, ensure your system meets these requirements:
+- Mac or Windows computer
+- Latest Python version installed
+- Latest version of `uv` installed
+
+## Setting Up Your Environment
+
+First, create a new Python project with `uv`: 
+
+```bash
+# Create project directory
+uv init mcp-client
+cd mcp-client
+
+# Create virtual environment
+uv venv
+
+# Activate virtual environment
+# On Windows:
+.venv\Scripts\activate
+# On Unix or MacOS:
+source .venv/bin/activate
+
+# Install required packages
+uv add mcp anthropic python-dotenv
+
+# Remove boilerplate files
+rm hello.py
+
+# Create our main file
+touch client.py
+```
+
+## Setting Up Your API Key
+
+You'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).
+
+Create a `.env` file to store it:
+
+```bash
+# Create .env file
+touch .env
+```
+
+Add your key to the `.env` file:
+```bash
+ANTHROPIC_API_KEY=<your key here>
+```
+
+Add `.env` to your `.gitignore`:
+```bash
+echo ".env" >> .gitignore
+```
+
+<Warning>
+Make sure you keep your `ANTHROPIC_API_KEY` secure!
+</Warning>
+
+## Creating the Client
+
+### Basic Client Structure
+First, let's set up our imports and create the basic client class:
+
+```python
+import asyncio
+from typing import Optional
+from contextlib import AsyncExitStack
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+from anthropic import Anthropic
+from dotenv import load_dotenv
+
+load_dotenv()  # load environment variables from .env
+
+class MCPClient:
+    def __init__(self):
+        # Initialize session and client objects
+        self.session: Optional[ClientSession] = None
+        self.exit_stack = AsyncExitStack()
+        self.anthropic = Anthropic()
+    # methods will go here
+```
+
+### Server Connection Management
+
+Next, we'll implement the method to connect to an MCP server:
+
+```python
+async def connect_to_server(self, server_script_path: str):
+    """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")
+        
+    command = "python" if is_python else "node"
+    server_params = StdioServerParameters(
+        command=command,
+        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])
+```
+
+### Query Processing Logic
+
+Now let's add the core functionality for processing queries and handling tool calls:
+
+```python
+async def process_query(self, query: str) -> str:
+    """Process a query using Claude and available tools"""
+    messages = [
+        {
+            "role": "user",
+            "content": query
+        }
+    ]
+
+    response = await self.session.list_tools()
+    available_tools = [{ 
+        "name": tool.name,
+        "description": tool.description,
+        "input_schema": tool.inputSchema
+    } for tool in response.tools]
+
+    # Initial Claude API call
+    response = self.anthropic.messages.create(
+        model="claude-3-5-sonnet-20241022",
+        max_tokens=1000,
+        messages=messages,
+        tools=available_tools
+    )
+
+    # Process response and handle tool calls
+    tool_results = []
+    final_text = []
+
+    for content in response.content:
+        if content.type == 'text':
+            final_text.append(content.text)
+        elif content.type == 'tool_use':
+            tool_name = content.name
+            tool_args = content.input
+            
+            # Execute tool call
+            result = await self.session.call_tool(tool_name, tool_args)
+            tool_results.append({"call": tool_name, "result": result})
+            final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")
+
+            # Continue conversation with tool results
+            if hasattr(content, 'text') and content.text:
+                messages.append({
+                  "role": "assistant",
+                  "content": content.text
+                })
+            messages.append({
+                "role": "user", 
+                "content": result.content
+            })
+
+            # Get next response from Claude
+            response = self.anthropic.messages.create(
+                model="claude-3-5-sonnet-20241022",
+                max_tokens=1000,
+                messages=messages,
+            )
+
+            final_text.append(response.content[0].text)
+
+    return "\n".join(final_text)
+```
+
+### Interactive Chat Interface
+Now we'll add the chat loop and cleanup functionality:
+
+```python
+async def chat_loop(self):
+    """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):
+    """Clean up resources"""
+    await self.exit_stack.aclose()
+```
+
+### Main Entry Point
+
+Finally, we'll add the main execution logic:
+
+```python
+async def main():
+    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])
+        await client.chat_loop()
+    finally:
+        await client.cleanup()
+
+if __name__ == "__main__":
+    import sys
+    asyncio.run(main())
+```
+
+You can find the complete `client.py` file [here.](https://gist.github.com/zckly/f3f28ea731e096e53b39b47bf0a2d4b1)
+
+## Key Components Explained
+
+### 1. Client Initialization
+- The `MCPClient` class initializes with session management and API clients
+- Uses `AsyncExitStack` for proper resource management
+- Configures the Anthropic client for Claude interactions
+
+### 2. Server Connection
+- Supports both Python and Node.js servers
+- Validates server script type
+- Sets up proper communication channels
+- Initializes the session and lists available tools
+
+### 3. Query Processing
+- Maintains conversation context
+- Handles Claude's responses and tool calls
+- Manages the message flow between Claude and tools
+- Combines results into a coherent response
+
+### 4. Interactive Interface
+- Provides a simple command-line interface
+- Handles user input and displays responses
+- Includes basic error handling
+- Allows graceful exit
+
+### 5. Resource Management
+- Proper cleanup of resources
+- Error handling for connection issues
+- Graceful shutdown procedures
+
+## Common Customization Points
+
+1. **Tool Handling**
+   - Modify `process_query()` to handle specific tool types
+   - Add custom error handling for tool calls
+   - Implement tool-specific response formatting
+
+2. **Response Processing**
+   - Customize how tool results are formatted
+   - Add response filtering or transformation
+   - Implement custom logging
+
+3. **User Interface**
+   - Add a GUI or web interface
+   - Implement rich console output
+   - Add command history or auto-completion
+
+## Running the Client
+
+To run your client with any MCP server:
+
+```bash
+uv run client.py path/to/server.py # python server
+uv run client.py path/to/build/index.js # node server
+```
+
+<Note>
+If you're continuing the weather tutorial from the server quickstart, your command might look something like this: `python client.py .../weather/src/weather/server.py`
+</Note>
+
+The client will:
+1. Connect to the specified server
+2. List available tools
+3. Start an interactive chat session where you can:
+   - Enter queries
+   - See tool executions
+   - Get responses from Claude
+
+Here's an example of what it should look like if connected to the weather server from the server quickstart:
+
+<Frame>
+  <img src="/images/client-claude-cli-python.png" />
+</Frame>
+
+## How It Works
+
+When you submit a query:
+
+1. The client gets the list of available tools from the server
+2. Your query is sent to Claude along with tool descriptions
+3. Claude decides which tools (if any) to use
+4. The client executes any requested tool calls through the server
+5. Results are sent back to Claude
+6. Claude provides a natural language response
+7. The response is displayed to you
+
+## Best practices
+
+1. **Error Handling**
+   - Always wrap tool calls in try-catch blocks
+   - Provide meaningful error messages
+   - Gracefully handle connection issues
+
+2. **Resource Management**
+   - Use `AsyncExitStack` for proper cleanup
+   - Close connections when done
+   - Handle server disconnections
+
+3. **Security**
+   - Store API keys securely in `.env`
+   - Validate server responses
+   - Be cautious with tool permissions
+
+## Troubleshooting
+
+### Server Path Issues
+- Double-check the path to your server script is correct
+- Use the absolute path if the relative path isn't working
+- For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\) in the path
+- Verify the server file has the correct extension (.py for Python or .js for Node.js)
+
+Example of correct path usage:
+```bash
+# Relative path
+uv run client.py ./server/weather.py
+
+# Absolute path
+uv run client.py /Users/username/projects/mcp-server/weather.py
+
+# Windows path (either format works)
+uv run client.py C:/projects/mcp-server/weather.py
+uv run client.py C:\\projects\\mcp-server\\weather.py
+```
+
+### Response Timing
+- The first response might take up to 30 seconds to return
+- This is normal and happens while:
+  - The server initializes
+  - Claude processes the query
+  - Tools are being executed
+- Subsequent responses are typically faster
+- Don't interrupt the process during this initial waiting period
+
+### Common Error Messages
+
+If you see:
+- `FileNotFoundError`: Check your server path
+- `Connection refused`: Ensure the server is running and the path is correct
+- `Tool execution failed`: Verify the tool's required environment variables are set
+- `Timeout error`: Consider increasing the timeout in your client configuration
+
+</Tab>
+
+</Tabs>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card
+    title="Example servers"
+    icon="grid"
+    href="/examples"
+  >
+    Check out our gallery of official MCP servers and implementations
+  </Card>
+  <Card
+    title="Clients"
+    icon="cubes"
+    href="/clients"
+  >
+    View the list of clients that support MCP integrations
+  </Card>
+  <Card
+    title="Building MCP with LLMs"
+    icon="comments"
+    href="/building-mcp-with-llms"
+  >
+    Learn how to use LLMs like Claude to speed up your MCP development
+  </Card>
+   <Card
+    title="Core architecture"
+    icon="sitemap"
+    href="/docs/concepts/architecture"
+  >
+    Understand how MCP connects clients, servers, and LLMs
+  </Card>
+</CardGroup>

quickstart/user.mdx

@@ -0,0 +1,209 @@
+---
+title: "For Claude Desktop Users"
+description: "Get started using pre-built servers in Claude for Desktop."
+---
+
+In this tutorial, you will extend [Claude for Desktop](https://claude.ai/download) so that it can read from your computer's file system, write new files, move files, and even search files.
+
+<Frame>
+  <img src="/images/quickstart-filesystem.png" />
+</Frame>
+
+Don't worry — it will ask you for your permission before executing these actions!
+
+## 1. Download Claude for Desktop
+
+Start by downloading [Claude for Desktop](https://claude.ai/download), choosing either macOS or Windows. (Linux is not yet supported for Claude for Desktop.)
+
+Follow the installation instructions.
+
+If you already have Claude for Desktop, make sure it's on the latest version by clicking on the Claude menu on your computer and selecting "Check for Updates..."
+
+<Accordion title="Why Claude for Desktop and not Claude.ai?">
+  Because servers are locally run, MCP currently only supports desktop hosts. Remote hosts are in active development.
+</Accordion>
+
+## 2. Add the Filesystem MCP Server
+
+To add this filesystem functionality, we will be installing a pre-built [Filesystem MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) to Claude for Desktop. This is one of dozens of [servers](https://github.com/modelcontextprotocol/servers/tree/main) created by Anthropic and the community.
+
+Get started by opening up the Claude menu on your computer and select "Settings..." Please note that these are not the Claude Account Settings found in the app window itself.
+
+This is what it should look like on a Mac:
+<Frame style={{ textAlign: 'center' }}>
+  <img src="/images/quickstart-menu.png" width="400" />
+</Frame>
+
+Click on "Developer" in the lefthand bar of the Settings pane, and then click on "Edit Config":
+<Frame>
+  <img src="/images/quickstart-developer.png" />
+</Frame>
+
+This will create a configuration file at:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+if you don't already have one, and will display the file in your file system.
+
+Open up the configuration file in any text editor. Replace the file contents with this:
+<Tabs>
+<Tab title="MacOS/Linux">
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/username/Desktop",
+        "/Users/username/Downloads"
+      ]
+    }
+  }
+}
+```
+</Tab>
+<Tab title="Windows">
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "C:\\Users\\username\\Desktop",
+        "C:\\Users\\username\\Downloads"
+      ]
+    }
+  }
+}
+```
+</Tab>
+</Tabs>
+
+Make sure to replace `username` with your computer's username. The paths should point to valid directories that you want Claude to be able to access and modify. It's set up to work for Desktop and Downloads, but you can add more paths as well.
+
+You will also need [Node.js](https://nodejs.org) on your computer for this to run properly. To verify you have Node installed, open the command line on your computer.
+- On macOS, open the Terminal from your Applications folder
+- On Windows, press Windows + R, type "cmd", and press Enter
+
+Once in the command line, verify you have Node installed by entering in the following command:
+```bash
+node --version
+```
+If you get an error saying "command not found" or "node is not recognized", download Node from [nodejs.org](https://nodejs.org/).
+
+<Tip>
+**How does the configuration file work?**
+
+This configuration file tells Claude for Dekstop which MCP servers to start up every time you start the application. In this case, we have added one server called "filesystem" that will use the Node `npx` command to install and run `@modelcontextprotocol/server-filesystem`. This server, described [here](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem), will let you access your file system in Claude for Desktop.
+</Tip>
+
+## 3. Restart Claude
+
+After updating your configuration file, you need to restart Claude for Desktop.
+
+Upon restarting, you should see a hammer <img src="/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon in the bottom right corner of the input box:
+
+<Frame>
+  <img src="/images/quickstart-hammer.png" />
+</Frame>
+
+After clicking on the hammer icon, you should see the tools that come with the Filesystem MCP Server:
+
+<Frame style={{ textAlign: 'center' }}>
+  <img src="/images/quickstart-tools.png" width="400" />
+</Frame>
+
+If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips.
+
+## 4. Try it out!
+
+You can now talk to Claude and ask it about your filesystem. It should know when to call the relevant tools.
+
+Things you might try asking Claude:
+- Can you write a poem and save it to my desktop?
+- What are some work-related files in my downloads folder?
+- Can you take all the images on my desktop and move them to a new folder called "Images"?
+
+As needed, Claude will call the relevant tools and seek your approval before taking an action:
+<Frame style={{ textAlign: 'center' }}>
+  <img src="/images/quickstart-approve.png" width="500" />
+</Frame>
+
+## Troubleshooting
+
+<AccordionGroup>
+<Accordion title="Server not showing up in Claude / hammer icon missing">
+  1. Restart Claude for Desktop completely
+  2. Check your `claude_desktop_config.json` file syntax
+  3. Make sure the file paths included in `claude_desktop_config.json` are valid and that they are absolute and not relative
+  4. Look at [logs](#getting-logs-from-claude-for-desktop) to see why the server is not connecting
+  5. In your command line, try manually running the server (replacing `username` as you did in `claude_desktop_config.json`) to see if you get any errors:
+<Tabs>
+<Tab title="MacOS/Linux">
+```bash
+npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads`
+```
+</Tab>
+<Tab title="Windows">
+```bash
+npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads
+```
+</Tab>
+</Tabs>
+</Accordion>
+<Accordion title="Getting logs from Claude for Desktop">
+  Claude.app logging related to MCP is written to log files in:
+  - macOS: `~/Library/Logs/Claude`
+  - Windows: `%APPDATA%\Claude\logs`
+
+  - `mcp.log` will contain general logging about MCP connections and connection failures.
+  - Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.
+
+  You can run the following command to list recent logs and follow along with any new ones (on Windows, it will only show recent logs):
+<Tabs>
+<Tab title="MacOS/Linux">
+```bash
+# Check Claude's logs for errors
+tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
+```
+</Tab>
+<Tab title="Windows">
+```bash
+type "%APPDATA%\Claude\logs\mcp*.log"
+```
+</Tab>
+</Tabs>
+</Accordion>
+<Accordion title="Tool calls failing silently">
+  If Claude attempts to use the tools but they fail:
+
+  1. Check Claude's logs for errors
+  2. Verify your server builds and runs without errors
+  3. Try restarting Claude for Desktop
+</Accordion>
+<Accordion title="None of this is working. What do I do?">
+  Please refer to our [debugging guide](/docs/tools/debugging) for better debugging tools and more detailed guidance.
+</Accordion>
+</AccordionGroup>
+
+## Next steps
+<CardGroup cols={2}>
+  <Card
+    title="Explore other servers"
+    icon="grid"
+    href="/examples"
+  >
+    Check out our gallery of official MCP servers and implementations
+  </Card>
+  <Card
+    title="Build your own server"
+    icon="code"
+    href="/quickstart/server"
+  >
+    Now build your own custom server to use in Claude for Desktop and other clients
+  </Card>
+</CardGroup>