From 16b0cc8cccc3eeb1129a4bebe985bfd4eebb3783 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Tue, 21 Jan 2025 14:13:21 +0000 Subject: [PATCH 1/2] Update TypeScript examples to use simplified API --- docs/concepts/architecture.mdx | 53 ++++++------- docs/concepts/prompts.mdx | 138 +++++++++++---------------------- docs/concepts/tools.mdx | 69 ++++++----------- quickstart/server.mdx | 81 +++++++------------ 4 files changed, 123 insertions(+), 218 deletions(-) diff --git a/docs/concepts/architecture.mdx b/docs/concepts/architecture.mdx index 164628a..f841d59 100644 --- a/docs/concepts/architecture.mdx +++ b/docs/concepts/architecture.mdx @@ -210,35 +210,30 @@ Here's a basic example of implementing an MCP server: - ```typescript - import { Server } from "@modelcontextprotocol/sdk/server/index.js"; - import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; - - const server = new Server({ - name: "example-server", - version: "1.0.0" - }, { - capabilities: { - resources: {} - } - }); - - // Handle requests - server.setRequestHandler(ListResourcesRequestSchema, async () => { - return { - resources: [ - { - uri: "example://resource", - name: "Example Resource" - } - ] - }; - }); - - // Connect transport - const transport = new StdioServerTransport(); - await server.connect(transport); - ``` + ```typescript + import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; + + const server = new McpServer({ + name: "example-server", + version: "1.0.0" + }); + + // Register a resource + server.resource( + "example", + "example://resource", + async (uri) => ({ + contents: [{ + uri: uri.href, + text: "Example resource content" + }] + }) + ); + + // Connect transport + const transport = new StdioServerTransport(); + await server.connect(transport); + ``` ```python diff --git a/docs/concepts/prompts.mdx b/docs/concepts/prompts.mdx index ed8b473..3848cd2 100644 --- a/docs/concepts/prompts.mdx +++ b/docs/concepts/prompts.mdx @@ -197,98 +197,52 @@ Here's a complete example of implementing prompts in an MCP server: - ```typescript - import { Server } from "@modelcontextprotocol/sdk/server"; - import { - ListPromptsRequestSchema, - GetPromptRequestSchema - } from "@modelcontextprotocol/sdk/types"; - - const PROMPTS = { - "git-commit": { - name: "git-commit", - description: "Generate a Git commit message", - arguments: [ - { - name: "changes", - description: "Git diff or description of changes", - required: true - } - ] - }, - "explain-code": { - name: "explain-code", - description: "Explain how code works", - arguments: [ - { - name: "code", - description: "Code to explain", - required: true - }, - { - name: "language", - description: "Programming language", - required: false - } - ] - } - }; - - const server = new Server({ - name: "example-prompts-server", - version: "1.0.0" - }, { - capabilities: { - prompts: {} - } - }); - - // List available prompts - server.setRequestHandler(ListPromptsRequestSchema, async () => { - return { - prompts: Object.values(PROMPTS) - }; - }); - - // Get specific prompt - server.setRequestHandler(GetPromptRequestSchema, async (request) => { - const prompt = PROMPTS[request.params.name]; - if (!prompt) { - throw new Error(`Prompt not found: ${request.params.name}`); - } - - if (request.params.name === "git-commit") { - return { - messages: [ - { - role: "user", - content: { - type: "text", - text: `Generate a concise but descriptive commit message for these changes:\n\n${request.params.arguments?.changes}` - } - } - ] - }; - } - - if (request.params.name === "explain-code") { - const language = request.params.arguments?.language || "Unknown"; - return { - messages: [ - { - role: "user", - content: { - type: "text", - text: `Explain how this ${language} code works:\n\n${request.params.arguments?.code}` - } - } - ] - }; - } - - throw new Error("Prompt implementation not found"); - }); - ``` + ```typescript + import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; + import { z } from "zod"; + + const server = new McpServer({ + name: "example-prompts-server", + version: "1.0.0" + }); + + // Register git commit prompt + server.prompt( + "git-commit", + "Generate a Git commit message", + { + changes: z.string().describe("Git diff or description of changes") + }, + ({ changes }) => ({ + messages: [{ + role: "user", + content: { + type: "text", + text: `Generate a concise but descriptive commit message for these changes:\n\n${changes}` + } + }] + }) + ); + + // Register code explanation prompt + server.prompt( + "explain-code", + "Explain how code works", + { + code: z.string().describe("Code to explain"), + language: z.string().optional().describe("Programming language") + }, + ({ code, language }) => ({ + messages: [{ + role: "user", + content: { + type: "text", + text: `Explain how this ${language || "Unknown"} code works:\n\n${code}` + } + }] + }) + ); + ``` ```python diff --git a/docs/concepts/tools.mdx b/docs/concepts/tools.mdx index 45eb4ec..1b0e160 100644 --- a/docs/concepts/tools.mdx +++ b/docs/concepts/tools.mdx @@ -40,50 +40,31 @@ Here's an example of implementing a basic tool in an MCP server: - ```typescript - const server = new Server({ - name: "example-server", - version: "1.0.0" - }, { - capabilities: { - tools: {} - } - }); - - // Define available tools - server.setRequestHandler(ListToolsRequestSchema, async () => { - return { - tools: [{ - name: "calculate_sum", - description: "Add two numbers together", - inputSchema: { - type: "object", - properties: { - a: { type: "number" }, - b: { type: "number" } - }, - required: ["a", "b"] - } - }] - }; - }); - - // Handle tool execution - server.setRequestHandler(CallToolRequestSchema, async (request) => { - if (request.params.name === "calculate_sum") { - const { a, b } = request.params.arguments; - return { - content: [ - { - type: "text", - text: String(a + b) - } - ] - }; - } - throw new Error("Tool not found"); - }); - ``` + ```typescript + import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; + import { z } from "zod"; + + const server = new McpServer({ + name: "example-server", + version: "1.0.0" + }); + + // Register a tool + server.tool( + "calculate_sum", + "Add two numbers together", + { + a: z.number(), + b: z.number() + }, + async ({ a, b }) => ({ + content: [{ + type: "text", + text: String(a + b) + }] + }) + ); + ``` ```python diff --git a/quickstart/server.mdx b/quickstart/server.mdx index 1a12e2a..a95a563 100644 --- a/quickstart/server.mdx +++ b/quickstart/server.mdx @@ -450,64 +450,39 @@ const ForecastArgumentsSchema = z.object({ longitude: z.number().min(-180).max(180), }); -// Create server instance -const server = new Server( +```typescript +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { z } from "zod"; + +const server = new McpServer({ + name: "weather", + version: "1.0.0" +}); + +// Register weather alert tool +server.tool( + "get-alerts", + "Get weather alerts for a state", { - name: "weather", - version: "1.0.0", + state: z.string().length(2).describe("Two-letter state code (e.g. CA, NY)") }, - { - capabilities: { - tools: {}, - }, + async ({ state }) => { + // Tool implementation } ); -``` -### Implementing tool listing - -We need to tell clients what tools are available. This `server.setRequestHandler` call will register this list for us: - -```typescript -// List available tools -server.setRequestHandler(ListToolsRequestSchema, async () => { - return { - tools: [ - { - name: "get-alerts", - description: "Get weather alerts for a state", - inputSchema: { - type: "object", - properties: { - state: { - type: "string", - description: "Two-letter state code (e.g. CA, NY)", - }, - }, - required: ["state"], - }, - }, - { - name: "get-forecast", - description: "Get weather forecast for a location", - inputSchema: { - type: "object", - properties: { - latitude: { - type: "number", - description: "Latitude of the location", - }, - longitude: { - type: "number", - description: "Longitude of the location", - }, - }, - required: ["latitude", "longitude"], - }, - }, - ], - }; -}); +// Register forecast tool +server.tool( + "get-forecast", + "Get weather forecast for a location", + { + latitude: z.number().min(-90).max(90).describe("Latitude of the location"), + longitude: z.number().min(-180).max(180).describe("Longitude of the location") + }, + async ({ latitude, longitude }) => { + // Tool implementation + } +); ``` This defines our two tools: `get-alerts` and `get-forecast`. From 335db056fc648e8fc0b97caab188b43b78f3139c Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Tue, 21 Jan 2025 14:17:10 +0000 Subject: [PATCH 2/2] Missed one --- docs/concepts/resources.mdx | 51 +++++++++++++------------------------ 1 file changed, 18 insertions(+), 33 deletions(-) diff --git a/docs/concepts/resources.mdx b/docs/concepts/resources.mdx index 50eb8eb..31aba5e 100644 --- a/docs/concepts/resources.mdx +++ b/docs/concepts/resources.mdx @@ -145,47 +145,32 @@ Here's a simple example of implementing resource support in an MCP server: ```typescript - const server = new Server({ + import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; + + const server = new McpServer({ name: "example-server", version: "1.0.0" - }, { - capabilities: { - resources: {} - } }); - // List available resources - server.setRequestHandler(ListResourcesRequestSchema, async () => { - return { - resources: [ - { - uri: "file:///logs/app.log", - name: "Application Logs", - mimeType: "text/plain" - } - ] - }; - }); - - // Read resource contents - server.setRequestHandler(ReadResourceRequestSchema, async (request) => { - const uri = request.params.uri; - - if (uri === "file:///logs/app.log") { + // Add static resource + server.resource( + "logs", + "file:///logs/app.log", + { + mimeType: "text/plain", + description: "Application log file" + }, + async (uri) => { const logContents = await readLogFile(); return { - contents: [ - { - uri, - mimeType: "text/plain", - text: logContents - } - ] + contents: [{ + uri: uri.href, + mimeType: "text/plain", + text: logContents + }] }; } - - throw new Error("Resource not found"); - }); + ); ```