From 2b85d8e0dc5be06376ae31b85b283516a3465cb0 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 23 Jan 2025 14:01:13 +0000 Subject: [PATCH] Revert "Update TypeScript examples to use simplified API" --- docs/concepts/architecture.mdx | 53 +++++++------ docs/concepts/prompts.mdx | 138 ++++++++++++++++++++++----------- docs/concepts/resources.mdx | 51 +++++++----- docs/concepts/tools.mdx | 69 +++++++++++------ quickstart/server.mdx | 87 +++++++++++++-------- 5 files changed, 254 insertions(+), 144 deletions(-) diff --git a/docs/concepts/architecture.mdx b/docs/concepts/architecture.mdx index f841d59..164628a 100644 --- a/docs/concepts/architecture.mdx +++ b/docs/concepts/architecture.mdx @@ -210,30 +210,35 @@ Here's a basic example of implementing an MCP server: - ```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); - ``` + ```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); + ``` ```python diff --git a/docs/concepts/prompts.mdx b/docs/concepts/prompts.mdx index 3848cd2..ed8b473 100644 --- a/docs/concepts/prompts.mdx +++ b/docs/concepts/prompts.mdx @@ -197,52 +197,98 @@ Here's a complete example of implementing prompts in an MCP server: - ```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}` - } - }] - }) - ); - ``` + ```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"); + }); + ``` ```python diff --git a/docs/concepts/resources.mdx b/docs/concepts/resources.mdx index 31aba5e..50eb8eb 100644 --- a/docs/concepts/resources.mdx +++ b/docs/concepts/resources.mdx @@ -145,32 +145,47 @@ Here's a simple example of implementing resource support in an MCP server: ```typescript - import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; - - const server = new McpServer({ + const server = new Server({ name: "example-server", version: "1.0.0" + }, { + capabilities: { + resources: {} + } }); - // Add static resource - server.resource( - "logs", - "file:///logs/app.log", - { - mimeType: "text/plain", - description: "Application log file" - }, - async (uri) => { + // 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") { const logContents = await readLogFile(); return { - contents: [{ - uri: uri.href, - mimeType: "text/plain", - text: logContents - }] + contents: [ + { + uri, + mimeType: "text/plain", + text: logContents + } + ] }; } - ); + + throw new Error("Resource not found"); + }); ``` diff --git a/docs/concepts/tools.mdx b/docs/concepts/tools.mdx index 1b0e160..45eb4ec 100644 --- a/docs/concepts/tools.mdx +++ b/docs/concepts/tools.mdx @@ -40,31 +40,50 @@ Here's an example of implementing a basic tool in an MCP server: - ```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) - }] - }) - ); - ``` + ```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"); + }); + ``` ```python diff --git a/quickstart/server.mdx b/quickstart/server.mdx index a95a563..1a12e2a 100644 --- a/quickstart/server.mdx +++ b/quickstart/server.mdx @@ -450,39 +450,64 @@ const ForecastArgumentsSchema = z.object({ longitude: z.number().min(-180).max(180), }); +// Create server instance +const server = new Server( + { + name: "weather", + version: "1.0.0", + }, + { + capabilities: { + tools: {}, + }, + } +); +``` + +### Implementing tool listing + +We need to tell clients what tools are available. This `server.setRequestHandler` call will register this list for us: + ```typescript -import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; -import { z } from "zod"; - -const server = new McpServer({ - name: "weather", - version: "1.0.0" +// 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 weather alert tool -server.tool( - "get-alerts", - "Get weather alerts for a state", - { - state: z.string().length(2).describe("Two-letter state code (e.g. CA, NY)") - }, - async ({ state }) => { - // Tool implementation - } -); - -// 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`.