From e0d0f4418aa11e6111c2adcc6d8f1f2ddab580fe Mon Sep 17 00:00:00 2001 From: Zachary Lee Date: Fri, 6 Dec 2024 15:35:38 -0800 Subject: [PATCH] almost done with phase 1 of revamp --- introduction.mdx | 101 ++++++--- mint.json | 6 +- servers.mdx | 22 ++ tutorials/claude-desktop.mdx | 394 +++++++++++++++++++++++++++++++++++ 4 files changed, 490 insertions(+), 33 deletions(-) create mode 100644 servers.mdx create mode 100644 tutorials/claude-desktop.mdx diff --git a/introduction.mdx b/introduction.mdx index 571602e..be461d3 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -3,7 +3,45 @@ title: Introduction description: 'Get started with the Model Context Protocol (MCP)' --- -The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need. +Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. + +## Why MCP + +MCP is a great choice for anyone building agents or complex integrations on top of LLMs. LLMs frequently need to integrate with data and tools, and MCP provides: +- A growing list of pre-built integrations that your LLM can directly plug into. + - Check out our official [servers repo](https://github.com/modelcontextprotocol/servers) for a focused list and [MCP Get](https://mcp-get.com/) for a more complete directory +- The flexibility to switch between LLM providers and vendors +- Best practices for securing your data within your infrastructure + +### General architecture + +At its core, MCP follows a client-server architecture where a client application can connect to multiple servers: + +```mermaid +flowchart LR + subgraph "Your Computer" + Client["MCP Client\n(Claude, IDEs, Tools)"] + S1["MCP Server A"] + S2["MCP Server B"] + S3["MCP Server C"] + + Client <-->|"MCP Protocol"| S1 + Client <-->|"MCP Protocol"| S2 + Client <-->|"MCP Protocol"| S3 + + S1 <--> R1[("Local\nResource A")] + S2 <--> R2[("Local\nResource B")] + end + + subgraph "Internet" + S3 <-->|"Web APIs"| R3[("Remote\nResource C")] + end +``` + +- **MCP Client**: Programs like Claude Desktop, IDEs, or AI tools that want to access resources through MCP +- **MCP Servers**: Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol +- **Local Resources**: Your computer's resources (databases, files, services) that MCP servers can securely access +- **Remote Resources**: Resources available over the internet (e.g., through APIs) that MCP servers can connect to ## Get started with MCP @@ -15,41 +53,28 @@ Choose the path that best fits your needs: icon="bolt" href="/quickstart" > - The fastest way to see MCP in action—connect example servers to Claude Desktop + Build your first MCP client and server in less than 5 minutes - Create a simple MCP server in Python to understand the basics + Give Claude Desktop the ability to query SQLite data using MCP - Create a simple MCP server in TypeScript to understand the basics - - - -## Development tools - -Essential tools for building and debugging MCP servers: - - - - Learn how to effectively debug MCP servers and integrations + See a detailed list of MCP clients - Test and inspect your MCP servers with our interactive debugging tool + See a detailed list of MCP servers @@ -102,6 +127,26 @@ Dive deeper into MCP's core concepts and capabilities: +## Development tools + +Essential tools for building and debugging MCP servers: + + + + Learn how to effectively debug MCP servers and integrations + + + Test and inspect your MCP servers with our interactive debugging tool + + + ## Contributing -Want to contribute? Check out [@modelcontextprotocol](https://github.com/modelcontextprotocol) on GitHub to join our growing community of developers building with MCP. +Want to contribute? Check out [@modelcontextprotocol](https://github.com/modelcontextprotocol) on GitHub to join our growing community of developers building with MCP. \ No newline at end of file diff --git a/mint.json b/mint.json index 1f47020..98c1d15 100644 --- a/mint.json +++ b/mint.json @@ -40,11 +40,7 @@ "navigation": [ { "group": "Get Started", - "pages": ["introduction", "quickstart", "clients"] - }, - { - "group": "Your First MCP Server", - "pages": ["docs/first-server/python", "docs/first-server/typescript"] + "pages": ["introduction", "quickstart", "clients", "servers"] }, { "group": "Development Tools", diff --git a/servers.mdx b/servers.mdx new file mode 100644 index 0000000..89b0173 --- /dev/null +++ b/servers.mdx @@ -0,0 +1,22 @@ +--- +title: "Servers" +description: "A list of featured servers and directories" +--- + +This page provides a continuously updated list of featured MCP servers and directories made by the community. + +## Featured servers + +[Cloudflare]: https://github.com/cloudflare/mcp-server-cloudflare +[Firebase Genkit]: https://github.com/firebase/genkit/tree/main/js/plugins/mcp +[Neon Database]: https://github.com/neondatabase/mcp-server-neon + +## Server directories + +### MCP servers repository + +For a list of servers built and maintained by the MCP team, check out our official [servers repository on Github](https://github.com/modelcontextprotocol/servers). + +### MCP Get + +MCP Get is the largest community-led directory of MCP servers. You can find it here: https://mcp-get.com/ \ No newline at end of file diff --git a/tutorials/claude-desktop.mdx b/tutorials/claude-desktop.mdx new file mode 100644 index 0000000..76be6a2 --- /dev/null +++ b/tutorials/claude-desktop.mdx @@ -0,0 +1,394 @@ +--- +title: "Set up MCP on Claude Desktop" +description: "How to set up MCP servers on Claude Desktop" +--- + +MCP is a protocol that enables secure connections between host applications, such as [Claude Desktop](https://claude.ai/download), and local services. In this quickstart guide, you'll learn how to: + + +While this tutorial focuses on using Claude Desktop as an example MCP client, the protocol is open and can be integrated by any application. IDEs, AI tools, and other software can all use MCP to connect to local integrations in a standardized way. + + + +Claude Desktop's MCP support is currently in developer preview and only supports connecting to local MCP servers running on your machine. Remote MCP connections are not yet supported. This integration is only available in the Claude Desktop app, not the Claude web interface (claude.ai). + + +### In This Guide + +For this tutorial, we'll implement a focused example using SQLite: + +```mermaid +flowchart LR + subgraph "Your Computer" + direction LR + Claude["Claude Desktop"] + MCP["SQLite MCP Server"] + DB[(SQLite Database\n~/test.db)] + + Claude <-->|"MCP Protocol\n(Queries & Results)"| MCP + MCP <-->|"Local Access\n(SQL Operations)"| DB + end +``` + +1. Claude Desktop acts as our MCP client +2. A SQLite MCP Server provides secure database access +3. Your local SQLite database stores the actual data + +The communication between the SQLite MCP server and your local SQLite database happens entirely on your machine—your SQLite database is not exposed to the internet. The Model Context Protocol ensures that Claude Desktop can only perform approved database operations through well-defined interfaces. This gives you a secure way to let Claude analyze and interact with your local data while maintaining complete control over what it can access. + +## Prerequisites + +- macOS or Windows +- The latest version of [Claude Desktop](https://claude.ai/download) installed +- [uv](https://docs.astral.sh/uv/) 0.4.18 or higher (`uv --version` to check) +- Git (`git --version` to check) +- SQLite (`sqlite3 --version` to check) + + + + ```bash + # Using Homebrew + brew install uv git sqlite3 + + # Or download directly: + # uv: https://docs.astral.sh/uv/ + # Git: https://git-scm.com + # SQLite: https://www.sqlite.org/download.html + ``` + + + ```powershell + # Using winget + winget install --id=astral-sh.uv -e + winget install git.git sqlite.sqlite + + # Or download directly: + # uv: https://docs.astral.sh/uv/ + # Git: https://git-scm.com + # SQLite: https://www.sqlite.org/download.html + ``` + + + +## Installation + + + + + + Let's create a simple SQLite database for testing: + + ```bash + # Create a new SQLite database + sqlite3 ~/test.db < + + + Open your Claude Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor. + + For example, if you have [VS Code](https://code.visualstudio.com/) installed: + + ```bash + code ~/Library/Application\ Support/Claude/claude_desktop_config.json + ``` + + Add this configuration (replace YOUR_USERNAME with your actual username): + + ```json + { + "mcpServers": { + "sqlite": { + "command": "uvx", + "args": ["mcp-server-sqlite", "--db-path", "/Users/YOUR_USERNAME/test.db"] + } + } + } + ``` + + This tells Claude Desktop: + 1. There's an MCP server named "sqlite" + 2. Launch it by running `uvx mcp-server-sqlite` + 3. Connect it to your test database + + Save the file, and restart **Claude Desktop**. + + + + + + + Let's create a simple SQLite database for testing: + + ```powershell + # Create a new SQLite database + $sql = @' + CREATE TABLE products ( + id INTEGER PRIMARY KEY, + name TEXT, + price REAL + ); + + INSERT INTO products (name, price) VALUES + ('Widget', 19.99), + ('Gadget', 29.99), + ('Gizmo', 39.99), + ('Smart Watch', 199.99), + ('Wireless Earbuds', 89.99), + ('Portable Charger', 24.99), + ('Bluetooth Speaker', 79.99), + ('Phone Stand', 15.99), + ('Laptop Sleeve', 34.99), + ('Mini Drone', 299.99), + ('LED Desk Lamp', 45.99), + ('Keyboard', 129.99), + ('Mouse Pad', 12.99), + ('USB Hub', 49.99), + ('Webcam', 69.99), + ('Screen Protector', 9.99), + ('Travel Adapter', 27.99), + ('Gaming Headset', 159.99), + ('Fitness Tracker', 119.99), + ('Portable SSD', 179.99); + '@ + + cd ~ + & sqlite3 test.db $sql + ``` + + + + Open your Claude Desktop App configuration at `%APPDATA%\Claude\claude_desktop_config.json` in a text editor. + + For example, if you have [VS Code](https://code.visualstudio.com/) installed: + + ```powershell + code $env:AppData\Claude\claude_desktop_config.json + ``` + + Add this configuration (replace YOUR_USERNAME with your actual username): + + ```json + { + "mcpServers": { + "sqlite": { + "command": "uvx", + "args": [ + "mcp-server-sqlite", + "--db-path", + "C:\\Users\\YOUR_USERNAME\\test.db" + ] + } + } + } + ``` + + This tells Claude Desktop: + 1. There's an MCP server named "sqlite" + 2. Launch it by running `uvx mcp-server-sqlite` + 3. Connect it to your test database + + Save the file, and restart **Claude Desktop**. + + + + + +## Test it out + +Let's verify everything is working. Try sending this prompt to Claude Desktop: + +``` +Can you connect to my SQLite database and tell me what products are available, and their prices? +``` + +Claude Desktop will: +1. Connect to the SQLite MCP server +2. Query your local database +3. Format and present the results + + + Example Claude Desktop conversation showing database query results + + +## What's happening under the hood? + +When you interact with Claude Desktop using MCP: + +1. **Server Discovery**: Claude Desktop connects to your configured MCP servers on startup +2. **Protocol Handshake**: When you ask about data, Claude Desktop: + - Identifies which MCP server can help (sqlite in this case) + - Negotiates capabilities through the protocol + - Requests data or actions from the MCP server + +3. **Interaction Flow**: + ```mermaid + sequenceDiagram + participant C as Claude Desktop + participant M as MCP Server + participant D as SQLite DB + + C->>M: Initialize connection + M-->>C: Available capabilities + + C->>M: Query request + M->>D: SQL query + D-->>M: Results + M-->>C: Formatted results + ``` + +4. **Security**: + - MCP servers only expose specific, controlled capabilities + - MCP servers run locally on your machine, and the resources they access are not exposed to the internet + - Claude Desktop requires user confirmation for sensitive operations + +## Try these examples + +Now that MCP is working, try these increasingly powerful examples: + + + + ``` + What's the average price of all products in the database? + ``` + + + ``` + Can you analyze the price distribution and suggest any pricing optimizations? + ``` + + + ``` + Could you help me design and create a new table for storing customer orders? + ``` + + + +## Add more capabilities + +Want to give Claude Desktop more local integration capabilities? Add these servers to your configuration: + + + Note that these MCP servers will require [Node.js](https://nodejs.org/en) to be installed on your machine. + + + + + Add this to your config to let Claude Desktop read and analyze files: + ```json + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/YOUR_USERNAME/Desktop"] + } + ``` + + + + Connect Claude Desktop to your PostgreSQL database: + ```json + "postgres": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"] + } + ``` + + + +## More MCP Clients + +While this guide demonstrates MCP using Claude Desktop as a client, several other applications support MCP integration: + + + + A high-performance, multiplayer code editor with built-in MCP support for AI-powered coding assistance + + + + Code intelligence platform featuring MCP integration for enhanced code search and analysis capabilities + + + +Each host application may implement MCP features differently or support different capabilities. Check out our [clients](/clients) documentation for more information. + +## Troubleshooting + + + + 1. Check if MCP is enabled: + - Click the 🔌 icon in Claude Desktop, next to the chat box + - Expand "Installed MCP Servers" + - You should see your configured servers + + 2. Verify your config: + - From Claude Desktop, go to Claude > Settings… + - Open the "Developer" tab to see your configuration + + 3. Restart Claude Desktop completely: + - Quit the app (not just close the window) + - Start it again + + + + 1. Check Claude Desktop's logs: + ```bash + tail -n 20 -f ~/Library/Logs/Claude/mcp*.log + ``` + + 2. Verify database access: + ```bash + # Test database connection + sqlite3 ~/test.db ".tables" + ``` + + 3. Common fixes: + - Check file paths in your config + - Verify database file permissions + - Ensure SQLite is installed properly + + + +## Next steps + + + + Build your first MCP client and server from scratch in less than 5 minutes. + + + + Browse our collection of example servers to see what's possible. + + \ No newline at end of file