Merge pull request modelcontextprotocol#15 from modelcontextprotocol/justin/fixes

Tweaks to "Get started" and "Your first server"

Author: jspahrsummers

docs/concepts/transport.mdx renamed to 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
+- Implementing simple updates

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
 
+<Info>
+  The following steps are for macOS. Guides for other platforms are coming soon.
+</Info>
+
 <Steps>
   <Step title="Install Python">
     You'll need Python 3.10 or higher:
@@ -20,7 +24,9 @@ Let's build your first MCP server in Python! We'll create a weather server that
     ```
   </Step>
 
-  <Step title="Install uv (https://docs.astral.sh/uv/) via homebrew">
+  <Step title="Install uv via homebrew">
+    See https://docs.astral.sh/uv/ for more information.
+
     ```bash
     brew install uv
     uv --version # Should be 0.4.18 or higher

docs/first-server/typescript.mdx

@@ -22,35 +22,17 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
   </Step>
 
   <Step title="Create a new project">
+    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
     ```
   </Step>
 
   <Step title="Install dependencies">
     ```bash
-    npm install @modelcontextprotocol/sdk axios dotenv typescript @types/node
-    npm install --save-dev ts-node
-    ```
-  </Step>
-
-  <Step title="Configure TypeScript">
-    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
     ```
   </Step>
 
@@ -65,16 +47,8 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
 ## Create your server
 
 <Steps>
-  <Step title="Create project structure">
-    ```bash
-    mkdir src
-    touch src/index.ts
-    touch src/types.ts
-    ```
-  </Step>
-
   <Step title="Define types">
-    In `src/types.ts`:
+    Create a file `src/types.ts`, and add the following:
 
     ```typescript
     export interface OpenWeatherResponse {
@@ -111,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 && 
@@ -124,9 +98,10 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
   </Step>
 
   <Step title="Add the base code">
-    In `src/index.ts`:
+    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 {
@@ -142,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";
@@ -171,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
@@ -223,7 +202,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
   </Step>
 
   <Step title="Add resource handlers">
-    Add this to the `setupHandlers` method:
+    Add this to the `setupResourceHandlers` method:
 
     ```typescript
     private setupResourceHandlers(): void {
@@ -289,7 +268,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
   </Step>
 
   <Step title="Add tool handlers">
-    Add these handlers to the `setupHandlers` method:
+    Add these handlers to the `setupToolHandlers` method:
 
     ```typescript
    private setupToolHandlers(): void {
@@ -359,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;
           }
@@ -376,21 +363,9 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
   </Step>
 
   <Step title="Build and test">
-    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
     ```
   </Step>
 </Steps>
@@ -399,7 +374,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
 
 <Steps>
   <Step title="Update Claude config">
-    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
     {
@@ -504,14 +479,35 @@ 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(...);
     } catch (error) {
       if (axios.isAxiosError(error)) {
         throw new McpError(
           ErrorCode.InternalError,
-          `API error: ${error.response?.data.message}`
+          `Weather API error: ${error.response?.data.message}`
         );
       }
       throw error;
@@ -520,11 +516,11 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
   </Card>
 
   <Card
-    title="Type Guards"
+    title="Type Validation"
     icon="check"
   >
     ```typescript
-    function isValidForecastArgs(args: unknown): args is GetForecastArgs {
+    function isValidForecastArgs(args: any): args is GetForecastArgs {
       return (
         typeof args === "object" && 
         args !== null && 
@@ -533,71 +529,36 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
       );
     }
     ```
-  </Card>
-
-  <Card
-    title="Environment Variables"
-    icon="gear"
-  >
-    ```typescript
-    if (!process.env.OPENWEATHER_API_KEY) {
-      throw new Error("OPENWEATHER_API_KEY is required");
-    }
-    ```
-  </Card>
 
-  <Card
-    title="Constants"
-    icon="box"
-  >
-    ```typescript
-    const API_CONFIG = {
-      BASE_URL: '...',
-      ENDPOINTS: {
-        CURRENT: 'weather',
-        FORECAST: 'forecast'
-      }
-    } as const;
-    ```
+    <Tip>You can also use libraries like [Zod](https://zod.dev/) to perform this validation automatically.</Tip>
   </Card>
 </CardGroup>
 
 ## 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
 
+<Info>
+  The following troubleshooting tips are for macOS. Guides for other platforms are coming soon.
+</Info>
+
 ### 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
@@ -628,4 +589,4 @@ npx tsc --noEmit
 
 <Note>
 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.
-</Note>
+</Note>

introduction.mdx

@@ -26,7 +26,7 @@ Choose the path that best fits your needs:
   </Card>
   <Card
     title="Build your first server (TypeScript)"
-    icon="code"
+    icon="square-js"
     href="/docs/first-server/typescript"
   >
     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
   </Card>
   <Card
-    title="Transport"
+    title="Transports"
     icon="network-wired"
-    href="/docs/concepts/transport"
+    href="/docs/concepts/transports"
   >
-    Learn about MCP's communication mechanisms
+    Learn about MCP's communication mechanism
   </Card>
 </CardGroup>
 
 ## Contributing
 
-Want to contribute? Check out our [GitHub repository](https://github.com/modelcontextprotocol) or 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.