modelcontextprotocol/docs
Watch
1
0
Fork
You've already forked docs
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update typescript.mdx

Browse source
This commit is contained in:
Justin Spahr-Summers 2024-11-21 13:51:57 +00:00
commit 9a27539dc1
No known key found for this signature in database
1 changed files with 58 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

117
docs/first-server/typescript.mdx
View file

@ -48,7 +48,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
<Steps> <Steps>
<Step title="Define types"> <Step title="Define types">
Create a file `types.ts`, and add the following: Create a file `src/types.ts`, and add the following:
```typescript ```typescript
export interface OpenWeatherResponse { 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 // Type guard for forecast arguments
export function isValidForecastArgs(args: unknown): args is GetForecastArgs { export function isValidForecastArgs(args: any): args is GetForecastArgs {
return ( return (
typeof args === "object" && typeof args === "object" &&
args !== null && args !== null &&
@ -98,9 +98,10 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
</Step> </Step>
<Step title="Add the base code"> <Step title="Add the base code">
Replace `index.ts` with the following: Replace `src/index.ts` with the following:
```typescript ```typescript
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { import {
@ -116,7 +117,6 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
import { import {
WeatherData, WeatherData,
ForecastDay, ForecastDay,
GetForecastArgs,
OpenWeatherResponse, OpenWeatherResponse,
isValidForecastArgs isValidForecastArgs
} from "./types.js"; } 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({ this.server = new Server({
name: "example-weather-server", name: "example-weather-server",
version: "0.1.0" version: "0.1.0"
}, {
capabilities: {
resources: {},
tools: {}
}
}); });
// Configure axios with defaults // Configure axios with defaults
@ -197,7 +202,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
</Step> </Step>
<Step title="Add resource handlers"> <Step title="Add resource handlers">
Add this to the `setupHandlers` method: Add this to the `setupResourceHandlers` method:
```typescript ```typescript
private setupResourceHandlers(): void { private setupResourceHandlers(): void {
@ -263,7 +268,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
</Step> </Step>
<Step title="Add tool handlers"> <Step title="Add tool handlers">
Add these handlers to the `setupHandlers` method: Add these handlers to the `setupToolHandlers` method:
```typescript ```typescript
private setupToolHandlers(): void { 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) { } catch (error) {
if (axios.isAxiosError(error)) { if (axios.isAxiosError(error)) {
throw new McpError( return {
ErrorCode.InternalError, content: {
`Weather API error: ${error.response?.data.message ?? error.message}` mimeType: "text/plain",
); text: `Weather API error: ${error.response?.data.message ?? error.message}`
},
isError: true,
}
} }
throw error; throw error;
} }
@ -361,7 +374,7 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
<Steps> <Steps>
<Step title="Update Claude config"> <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 ```json
{ {
@ -466,6 +479,27 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
title="Error Handling" title="Error Handling"
icon="shield" 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 ```typescript
try { try {
const response = await this.axiosInstance.get(...); 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)) { if (axios.isAxiosError(error)) {
throw new McpError( throw new McpError(
ErrorCode.InternalError, ErrorCode.InternalError,
`API error: ${error.response?.data.message}` `Weather API error: ${error.response?.data.message}`
); );
} }
throw error; throw error;
@ -482,11 +516,11 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
</Card> </Card>
<Card <Card
title="Type Guards" title="Type Validation"
icon="check" icon="check"
> >
```typescript ```typescript
function isValidForecastArgs(args: unknown): args is GetForecastArgs { function isValidForecastArgs(args: any): args is GetForecastArgs {
return ( return (
typeof args === "object" && typeof args === "object" &&
args !== null && args !== null &&
@ -495,71 +529,36 @@ This guide uses the OpenWeatherMap API. You'll need a free API key from [OpenWea
); );
} }
``` ```
</Card>
<Card <Tip>You can also use libraries like [Zod](https://zod.dev/) to perform this validation automatically.</Tip>
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;
```
</Card> </Card>
</CardGroup> </CardGroup>
## Available transports ## Available transports
While this guide uses stdio transport, MCP supports multiple transport options: While this guide uses stdio to run the MCP server as a local process, MCP supports other [transports](/docs/concepts/transports) as well.
### 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);
```
## Troubleshooting ## Troubleshooting
<Info>
The following troubleshooting tips are for macOS. Guides for other platforms are coming soon.
</Info>
### Build errors ### Build errors
```bash ```bash
# Check TypeScript version # Check TypeScript version
npx tsc --version npx tsc --version
# Clean and rebuild # Clean and rebuild
rm -rf dist/ rm -rf build/
npm run build npm run build
``` ```
### Runtime errors ### Runtime errors
Look for detailed error messages in the Claude app logs: Look for detailed error messages in the Claude Desktop logs:
```bash ```bash
# Launch Claude with logging
open /Applications/Claude.app --stdout ~/Claude.log --stderr ~/Claude.log
# Monitor logs # Monitor logs
tail -f ~/Claude.log tail -n 20 -f ~/Library/Application\ Support/Claude/mcp*.log
``` ```
### Type errors ### Type errors