From 3113c1a09cbb897c47fb589792f97d24fc4a26a3 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 11:52:50 +0000 Subject: [PATCH 01/10] Rename "transport" to "transports" --- docs/concepts/{transport.mdx => transports.mdx} | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename docs/concepts/{transport.mdx => transports.mdx} (92%) diff --git a/docs/concepts/transport.mdx b/docs/concepts/transports.mdx similarity index 92% rename from docs/concepts/transport.mdx rename to docs/concepts/transports.mdx index bc50202..cf3bb9e 100644 --- a/docs/concepts/transport.mdx +++ b/docs/concepts/transports.mdx @@ -1,13 +1,13 @@ --- -title: "Transport" +title: "Transports" description: "Learn about MCP's communication mechanisms" --- -Transport in the Model Context Protocol (MCP) provides the foundation for communication between clients and servers. It handles the underlying mechanics of how messages are sent and received. +Transports in the Model Context Protocol (MCP) provide the foundation for communication between clients and servers. A transport handles the underlying mechanics of how messages are sent and received. -## How transport works +## How transports work -MCP transport is built on a simple message-passing architecture where both clients and servers can send messages to each other. The transport layer is responsible for: +An MCP transport is built on a simple message-passing architecture where both clients and servers can send messages to each other. The transport layer is responsible for: - Establishing connections - Sending messages @@ -275,4 +275,4 @@ Choose the appropriate transport based on your needs: - Only server-to-client streaming is needed - WebSocket support is limited - Working with restricted networks -- Implementing simple updates \ No newline at end of file +- Implementing simple updates From cb5d4c72e275feb32527263fe93e29650a700e88 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 11:53:00 +0000 Subject: [PATCH 02/10] Update introduction.mdx --- introduction.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/introduction.mdx b/introduction.mdx index 374247c..fb35f6a 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -26,7 +26,7 @@ Choose the path that best fits your needs: Create a simple MCP server in TypeScript to understand the basics @@ -94,14 +94,14 @@ Dive deeper into MCP's core concepts and capabilities: Let your servers request completions from LLMs - Learn about MCP's communication mechanisms + Learn about MCP's communication mechanism ## Contributing -Want to contribute? Check out our [GitHub repository](https://github.com/modelcontextprotocol) or join our growing community of developers building with MCP. \ No newline at end of file +Want to contribute? Check out [@modelcontextprotocol](https://github.com/modelcontextprotocol) on GitHub to join our growing community of developers building with MCP. From 3066ca201316376f8a231c89425126e8202771bc Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 12:19:28 +0000 Subject: [PATCH 03/10] Fix link to "transport" --- mint.json | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/mint.json b/mint.json index 33e32a5..fb4384b 100644 --- a/mint.json +++ b/mint.json @@ -43,15 +43,24 @@ "navigation": [ { "group": "Get Started", - "pages": ["introduction", "quickstart"] + "pages": [ + "introduction", + "quickstart" + ] }, { "group": "Your First MCP Server", - "pages": ["docs/first-server/python", "docs/first-server/typescript"] + "pages": [ + "docs/first-server/python", + "docs/first-server/typescript" + ] }, { "group": "Development Tools", - "pages": ["docs/tools/debugging", "docs/tools/inspector"] + "pages": [ + "docs/tools/debugging", + "docs/tools/inspector" + ] }, { "group": "Concepts", @@ -61,7 +70,7 @@ "docs/concepts/prompts", "docs/concepts/tools", "docs/concepts/sampling", - "docs/concepts/transport" + "docs/concepts/transports" ] }, { From 342c8c26f69ce545cfe993a9b48bf651d585008f Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 12:39:47 +0000 Subject: [PATCH 04/10] Update quickstart.mdx --- quickstart.mdx | 74 +++++++++++++++++++++----------------------------- 1 file changed, 31 insertions(+), 43 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index 1dba7c9..312b137 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -10,16 +10,16 @@ MCP is a protocol that enables secure connections between clients, such as the C - Query and analyze your data securely -While this guide focuses on using Claude Desktop as an example MCP client, the protocol is open and can be implemented by any application. IDEs, AI tools, and other software can all act as MCP clients to access local services in a standardized way. +While this guide focuses on using Claude Desktop as an example MCP client, the protocol is open and can be implemented by any application. IDEs, AI tools, and other software can all act as MCP clients to access local integrations in a standardized way. -Claude Desktop's MCP support is currently in developer preview and only supports connecting to local servers running on your machine. Remote connections are not yet supported. MCP integration is only available in the Claude Desktop app, not the Claude web interface (claude.ai). +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). ## How MCP works -MCP (Model Context Protocol) is an open protocol that enables secure, controlled interactions between AI applications and local resources on your computer. Let's break down how it works, then look at how we'll use it in this guide. +MCP (Model Context Protocol) is an open protocol that enables secure, controlled interactions between AI applications and local or remote resources. Let's break down how it works, then look at how we'll use it in this guide. ### General Architecture At its core, MCP follows a client-server architecture where multiple services can connect to any compatible client: @@ -38,13 +38,17 @@ flowchart LR S1 <--> R1[("Local\nResource A")] S2 <--> R2[("Local\nResource B")] - S3 <--> R3[("Local\nResource C")] + end + + subgraph "Internet" + S3 <-->|"Web APIs"| R3[("Remote\nResource C")] end ``` -- **MCP Clients**: Applications like Claude Desktop, IDEs, or AI tools that want to access local resources -- **MCP Servers**: Lightweight programs that each expose specific capabilities through the standardized MCP protocol +- **MCP Clients**: Applications like Claude Desktop, IDEs, or AI tools that want to access resources +- **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 ### In This Guide @@ -67,15 +71,15 @@ flowchart LR 2. A SQLite MCP Server provides secure database access 3. Your local SQLite database stores the actual data -All communication happens entirely on your machine - no data leaves your computer. The MCP protocol ensures that Claude Desktop can only perform approved database operations through well-defined interfaces. +All communication happens entirely on your machine—no data leaves your computer. The MCP 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 (Windows/Linux guides coming soon) +- [Claude Desktop](https://claude.ai/download) v0.7.0 or newer installed (Claude > About Claude to check) - Node.js v18 or higher (`node --version` to check) - Git (`git --version` to check) -- [Claude Desktop app](https://claude.ai/download) installed - SQLite (`sqlite3 --version` to check) @@ -97,16 +101,7 @@ brew install node git sqlite3 Let's start by getting the pre-built MCP servers: ```bash - # Clone the example servers - git clone https://github.com/modelcontextprotocol/servers - cd servers - - # Install dependencies and build - npm install - npm run build - - # Make servers available globally - npm install -g + npm install -g @modelcontextprotocol/servers ``` This makes the MCP servers available as command-line tools that Claude Desktop can launch. @@ -133,14 +128,14 @@ brew install node git sqlite3 - Open your Claude Desktop App configuration: + 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 - # Requires VSCode to be installed to use the 'code' command code ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` - Add this configuration (replace YOUR_USERNAME with your actual username): ```json @@ -158,9 +153,8 @@ brew install node git sqlite3 1. There's an MCP server named "sqlite" 2. Launch it using the `mcp-server-sqlite` command 3. Connect it to your test database - 4. Provide necessary environment variables - Save and **restart Claude Desktop App**. + Save the file, and restart **Claude Desktop**. @@ -169,7 +163,7 @@ brew install node git sqlite3 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? +Can you connect to my SQLite database and tell me what products are available, and their prices? ``` Claude Desktop will: @@ -185,11 +179,11 @@ Claude Desktop will: When you interact with Claude Desktop using MCP: -1. **Server Discovery**: Claude Desktop loads your configured MCP servers on startup +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 MCP protocol - - Establishes a secure local connection + - Negotiates capabilities through the protocol + - Requests data or actions from the MCP server 3. **Interaction Flow**: ```mermaid @@ -242,12 +236,9 @@ Want to give Claude Desktop more local integration capabilities? Add these serve Add this to your config to let Claude Desktop read and analyze files: ```json - "tee": { - "command": "mcp-server-tee", - "args": ["tail", "-f", "/var/log/system.log"], - "env": { - "HOME": "/Users/YOUR_USERNAME" - } + "filesystem": { + "command": "mcp-server-filesystem", + "args": ["/Users/YOUR_USERNAME/Desktop"] } ``` @@ -257,10 +248,7 @@ Want to give Claude Desktop more local integration capabilities? Add these serve ```json "postgres": { "command": "mcp-server-postgres", - "args": ["postgresql://localhost/mydb"], - "env": { - "HOME": "/Users/YOUR_USERNAME" - } + "args": ["postgresql://localhost/mydb"] } ``` @@ -293,23 +281,23 @@ Each client may implement MCP features differently or support different capabili 1. Check if MCP is enabled: - - Click the 🔌 icon in Claude Desktop + - 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: - ```bash - cat ~/Library/Application\ Support/Claude/claude_desktop_config.json - ``` + - 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 -f ~/Library/Logs/Claude/mcp.log + tail -n 20 -f ~/Library/Logs/Claude/mcp*.log ``` 2. Verify database access: From d51617a40a722f5c9ecaa80a98f7c3e0239992a3 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 12:52:38 +0000 Subject: [PATCH 05/10] Add Windows installation steps --- quickstart.mdx | 171 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 120 insertions(+), 51 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index 312b137..ea1c5ac 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -76,8 +76,8 @@ This gives you a secure way to let Claude analyze and interact with your local d ## Prerequisites -- macOS (Windows/Linux guides coming soon) -- [Claude Desktop](https://claude.ai/download) v0.7.0 or newer installed (Claude > About Claude to check) +- macOS or Windows +- The latest version of [Claude Desktop](https://claude.ai/download) installed - Node.js v18 or higher (`node --version` to check) - Git (`git --version` to check) - SQLite (`sqlite3 --version` to check) @@ -96,67 +96,136 @@ brew install node git sqlite3 ## Installation - - - Let's start by getting the pre-built MCP servers: + + + + + Let's start by getting the pre-built MCP servers: - ```bash - npm install -g @modelcontextprotocol/servers - ``` + ```bash + npm install -g @modelcontextprotocol/servers + ``` - This makes the MCP servers available as command-line tools that Claude Desktop can launch. - + This makes the MCP servers available as command-line tools that Claude Desktop can launch. + - - Let's create a simple SQLite database for testing: + + Let's create a simple SQLite database for testing: - ```bash - # Create a new SQLite database - sqlite3 ~/test.db < + ```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. + + 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: + For example, if you have [VS Code](https://code.visualstudio.com/) installed: - ```bash - code ~/Library/Application\ Support/Claude/claude_desktop_config.json - ``` + ```bash + code ~/Library/Application\ Support/Claude/claude_desktop_config.json + ``` - Add this configuration (replace YOUR_USERNAME with your actual username): + Add this configuration (replace YOUR_USERNAME with your actual username): - ```json - { - "mcpServers": { - "sqlite": { - "command": "mcp-server-sqlite", - "args": ["/Users/YOUR_USERNAME/test.db"] + ```json + { + "mcpServers": { + "sqlite": { + "command": "mcp-server-sqlite", + "args": ["/Users/YOUR_USERNAME/test.db"] + } + } } - } - } - ``` + ``` - This tells Claude Desktop: - 1. There's an MCP server named "sqlite" - 2. Launch it using the `mcp-server-sqlite` command - 3. Connect it to your test database + This tells Claude Desktop: + 1. There's an MCP server named "sqlite" + 2. Launch it using the `mcp-server-sqlite` command + 3. Connect it to your test database - Save the file, and restart **Claude Desktop**. - - + Save the file, and restart **Claude Desktop**. + + + + + + + Let's start by getting the pre-built MCP servers: + + ```bash + npm install -g @modelcontextprotocol/servers + ``` + + This makes the MCP servers available as command-line tools that Claude Desktop can launch. + + + + 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); + '@ + + & 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: + + ```bash + $env:AppData\Claude\claude_desktop_config.json + ``` + + Add this configuration (replace YOUR_USERNAME with your actual username): + + ```json + { + "mcpServers": { + "sqlite": { + "command": "mcp-server-sqlite", + "args": ["/Users/YOUR_USERNAME/test.db"] + } + } + } + ``` + + This tells Claude Desktop: + 1. There's an MCP server named "sqlite" + 2. Launch it using the `mcp-server-sqlite` command + 3. Connect it to your test database + + Save the file, and restart **Claude Desktop**. + + + + ## Test it out From 17cc8bc42ada5e26b27adc23e8a3f5b105833510 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 12:57:52 +0000 Subject: [PATCH 06/10] Fix Windows steps --- quickstart.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index ea1c5ac..b93194c 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -199,8 +199,8 @@ brew install node git sqlite3 For example, if you have [VS Code](https://code.visualstudio.com/) installed: - ```bash - $env:AppData\Claude\claude_desktop_config.json + ```powershell + code $env:AppData\Claude\claude_desktop_config.json ``` Add this configuration (replace YOUR_USERNAME with your actual username): @@ -210,7 +210,7 @@ brew install node git sqlite3 "mcpServers": { "sqlite": { "command": "mcp-server-sqlite", - "args": ["/Users/YOUR_USERNAME/test.db"] + "args": ["C:\\Users\\YOUR_USERNAME\\test.db"] } } } From bf595f70a5c1c7186874da7e27121dffd317045e Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 13:13:49 +0000 Subject: [PATCH 07/10] Ensure users create SQLite DB in Windows home folder --- quickstart.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/quickstart.mdx b/quickstart.mdx index b93194c..d386722 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -190,6 +190,7 @@ brew install node git sqlite3 ('Gizmo', 39.99); '@ + cd ~ & sqlite3 test.db $sql ``` From 30018f6ef5d6241791c4dd2b28c21609bca17688 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 13:14:33 +0000 Subject: [PATCH 08/10] Minor tweaks to Python "first server" intro --- docs/first-server/python.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/first-server/python.mdx b/docs/first-server/python.mdx index 73ac3b8..5d38acb 100644 --- a/docs/first-server/python.mdx +++ b/docs/first-server/python.mdx @@ -11,6 +11,10 @@ Let's build your first MCP server in Python! We'll create a weather server that ## Prerequisites + + The following steps are for macOS. Guides for other platforms are coming soon. + + You'll need Python 3.10 or higher: @@ -21,7 +25,9 @@ Let's build your first MCP server in Python! We'll create a weather server that ``` - + + See https://docs.astral.sh/uv/ for more information. + ```bash brew install uv uv --version # Should be 0.4.18 or higher @@ -54,14 +60,8 @@ Let's build your first MCP server in Python! We'll create a weather server that ## Create your server - - ```bash - touch weather_server.py - ``` - - - In `weather_server.py`: + Create a file `weather_server.py` and add the following: ```python import os From 1e5dc3398e5ed914846ce2d9227a6de7a12f16ea Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 13:22:16 +0000 Subject: [PATCH 09/10] Use `@modelcontextprotocol/create-server` --- docs/first-server/typescript.mdx | 54 +++++--------------------------- 1 file changed, 8 insertions(+), 46 deletions(-) diff --git a/docs/first-server/typescript.mdx b/docs/first-server/typescript.mdx index 0047394..d46c882 100644 --- a/docs/first-server/typescript.mdx +++ b/docs/first-server/typescript.mdx @@ -22,35 +22,17 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea + You can use our [create-typescript-server](https://github.com/modelcontextprotocol/create-typescript-server) tool to bootstrap a new project: + ```bash - mkdir weather-server + npx @modelcontextprotocol/create-server weather-server cd weather-server - npm init -y ``` ```bash - npm install @modelcontextprotocol/sdk axios dotenv typescript @types/node - npm install --save-dev ts-node - ``` - - - - Create `tsconfig.json`: - ```json - { - "compilerOptions": { - "target": "ES2020", - "module": "ES2020", - "moduleResolution": "node", - "esModuleInterop": true, - "outDir": "./dist", - "rootDir": "./src", - "strict": true - }, - "include": ["src/**/*"] - } + npm install --save axios dotenv ``` @@ -65,16 +47,8 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea ## Create your server - - ```bash - mkdir src - touch src/index.ts - touch src/types.ts - ``` - - - In `src/types.ts`: + Create a file `types.ts`, and add the following: ```typescript export interface OpenWeatherResponse { @@ -124,7 +98,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea - In `src/index.ts`: + Replace `index.ts` with the following: ```typescript import { Server } from "@modelcontextprotocol/sdk/server/index.js"; @@ -376,21 +350,9 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea - Add these scripts to `package.json`: - ```json - { - "scripts": { - "build": "tsc", - "start": "node dist/index.js", - "dev": "ts-node src/index.ts" - } - } - ``` - - Then run: ```bash npm run build - npm install -g . + npm link ``` @@ -628,4 +590,4 @@ npx tsc --noEmit Need help? Ask Claude! Since it has access to the MCP SDK documentation, it can help you debug issues and suggest improvements to your server. - \ No newline at end of file + From 9a27539dc161a7d23191a60e7ee112f6c3caa072 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 13:51:57 +0000 Subject: [PATCH 10/10] Update typescript.mdx --- docs/first-server/typescript.mdx | 117 +++++++++++++++---------------- 1 file changed, 58 insertions(+), 59 deletions(-) diff --git a/docs/first-server/typescript.mdx b/docs/first-server/typescript.mdx index d46c882..9a24b2a 100644 --- a/docs/first-server/typescript.mdx +++ b/docs/first-server/typescript.mdx @@ -48,7 +48,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea - Create a file `types.ts`, and add the following: + Create a file `src/types.ts`, and add the following: ```typescript export interface OpenWeatherResponse { @@ -85,7 +85,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea } // Type guard for forecast arguments - export function isValidForecastArgs(args: unknown): args is GetForecastArgs { + export function isValidForecastArgs(args: any): args is GetForecastArgs { return ( typeof args === "object" && args !== null && @@ -98,9 +98,10 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea - Replace `index.ts` with the following: + Replace `src/index.ts` with the following: ```typescript + #!/usr/bin/env node import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { @@ -116,7 +117,6 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea import { WeatherData, ForecastDay, - GetForecastArgs, OpenWeatherResponse, isValidForecastArgs } from "./types.js"; @@ -145,6 +145,11 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea this.server = new Server({ name: "example-weather-server", version: "0.1.0" + }, { + capabilities: { + resources: {}, + tools: {} + } }); // Configure axios with defaults @@ -197,7 +202,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea - Add this to the `setupHandlers` method: + Add this to the `setupResourceHandlers` method: ```typescript private setupResourceHandlers(): void { @@ -263,7 +268,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea - Add these handlers to the `setupHandlers` method: + Add these handlers to the `setupToolHandlers` method: ```typescript private setupToolHandlers(): void { @@ -333,13 +338,21 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea }); } - return { toolResult: forecasts }; + return { + content: { + mimeType: "application/json", + text: JSON.stringify(forecasts, null, 2) + } + }; } catch (error) { if (axios.isAxiosError(error)) { - throw new McpError( - ErrorCode.InternalError, - `Weather API error: ${error.response?.data.message ?? error.message}` - ); + return { + content: { + mimeType: "text/plain", + text: `Weather API error: ${error.response?.data.message ?? error.message}` + }, + isError: true, + } } throw error; } @@ -361,7 +374,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea - Add to `claude_desktop_config.json`: + If you didn't already connect to Claude Desktop during project setup, add to `claude_desktop_config.json`: ```json { @@ -466,6 +479,27 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea title="Error Handling" icon="shield" > + When a tool encounters an error, return the error message with `isError: true`, so the model can self-correct: + + ```typescript + try { + const response = await axiosInstance.get(...); + } catch (error) { + if (axios.isAxiosError(error)) { + return { + content: { + mimeType: "text/plain", + text: `Weather API error: ${error.response?.data.message ?? error.message}` + }, + isError: true, + } + } + throw error; + } + ``` + + For other handlers, throw an error, so the application can notify the user: + ```typescript try { const response = await this.axiosInstance.get(...); @@ -473,7 +507,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea if (axios.isAxiosError(error)) { throw new McpError( ErrorCode.InternalError, - `API error: ${error.response?.data.message}` + `Weather API error: ${error.response?.data.message}` ); } throw error; @@ -482,11 +516,11 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea ```typescript - function isValidForecastArgs(args: unknown): args is GetForecastArgs { + function isValidForecastArgs(args: any): args is GetForecastArgs { return ( typeof args === "object" && args !== null && @@ -495,71 +529,36 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea ); } ``` - - - ```typescript - if (!process.env.OPENWEATHER_API_KEY) { - throw new Error("OPENWEATHER_API_KEY is required"); - } - ``` - - - - ```typescript - const API_CONFIG = { - BASE_URL: '...', - ENDPOINTS: { - CURRENT: 'weather', - FORECAST: 'forecast' - } - } as const; - ``` + You can also use libraries like [Zod](https://zod.dev/) to perform this validation automatically. ## Available transports -While this guide uses stdio transport, MCP supports multiple transport options: - -### WebSocket -```typescript -import { WebSocketServerTransport } from "@modelcontextprotocol/sdk/server/websocket.js"; -const transport = new WebSocketServerTransport(); -``` - -### SSE (Server-Sent Events) -```typescript -import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js"; -const transport = new SSEServerTransport("/events", response); -``` +While this guide uses stdio to run the MCP server as a local process, MCP supports other [transports](/docs/concepts/transports) as well. ## Troubleshooting + + The following troubleshooting tips are for macOS. Guides for other platforms are coming soon. + + ### Build errors ```bash # Check TypeScript version npx tsc --version # Clean and rebuild -rm -rf dist/ +rm -rf build/ npm run build ``` ### Runtime errors -Look for detailed error messages in the Claude app logs: +Look for detailed error messages in the Claude Desktop logs: ```bash -# Launch Claude with logging -open /Applications/Claude.app --stdout ~/Claude.log --stderr ~/Claude.log - # Monitor logs -tail -f ~/Claude.log +tail -n 20 -f ~/Library/Application\ Support/Claude/mcp*.log ``` ### Type errors