From 61f6e3483dea0d28f943bf30e7371cb8796eaf91 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 15:07:56 +0000 Subject: [PATCH 1/9] Update architecture.mdx --- docs/concepts/architecture.mdx | 180 ++++++++++++++++----------------- 1 file changed, 88 insertions(+), 92 deletions(-) diff --git a/docs/concepts/architecture.mdx b/docs/concepts/architecture.mdx index 63a15ac..b67e295 100644 --- a/docs/concepts/architecture.mdx +++ b/docs/concepts/architecture.mdx @@ -3,50 +3,61 @@ title: "Core architecture" description: "Understand how MCP connects clients, servers, and LLMs" --- -The Model Context Protocol (MCP) is built on a flexible, extensible architecture that enables seamless communication between LLM applications and external services. This document covers the core architectural components and concepts. +The Model Context Protocol (MCP) is built on a flexible, extensible architecture that enables seamless communication between LLM applications and integrations. This document covers the core architectural components and concepts. ## Overview MCP follows a client-server architecture where: -- **Clients** are LLM applications (like claude.ai or IDEs) that initiate connections +- **Hosts** are LLM applications (like Claude Desktop or IDEs) that initiate connections +- **Clients** maintain 1:1 connections with servers, inside the host application - **Servers** provide context, tools, and prompts to clients -- **Hosts** are processes that run MCP clients ```mermaid flowchart LR - subgraph "Host (e.g., claude.ai)" - client[MCP Client] + subgraph " Host (e.g., Claude Desktop) " + client1[MCP Client] + client2[MCP Client] end subgraph "Server Process" - server[MCP Server] + server1[MCP Server] + end + subgraph "Server Process" + server2[MCP Server] end - client <-->|Transport Layer| server + client1 <-->|Transport Layer| server1 + client2 <-->|Transport Layer| server2 ``` ## Core components ### Protocol layer -The protocol layer handles message framing, request/response linking, and high-level communication patterns. Key classes include: +The protocol layer handles message framing, request/response linking, and high-level communication patterns. ```typescript -class Protocol { +class Protocol { // Handle incoming requests - setRequestHandler(schema: T, handler: (request: T) => Result): void + setRequestHandler(schema: T, handler: (request: T, extra: RequestHandlerExtra) => Promise): void // Handle incoming notifications - setNotificationHandler(schema: T, handler: (notification: T) => void): void + setNotificationHandler(schema: T, handler: (notification: T) => Promise): void // Send requests and await responses - request(request: Request, schema: T): Promise + request(request: Request, schema: T, options?: RequestOptions): Promise // Send one-way notifications notification(notification: Notification): Promise } ``` +Key classes include: + +* `Protocol` +* `Client` +* `Server` + ### Transport layer The transport layer handles the actual communication between clients and servers. MCP supports multiple transport mechanisms: @@ -54,66 +65,48 @@ The transport layer handles the actual communication between clients and servers 1. **Stdio transport** - Uses standard input/output for communication - Ideal for local processes - ```typescript - class StdioTransport implements Transport { - constructor(stdin: Readable, stdout: Writable) - send(message: JSONRPCMessage): Promise - } - ``` -2. **WebSocket transport** - - Enables real-time bidirectional communication - - Supports remote connections - ```typescript - class WebSocketTransport implements Transport { - constructor(url: URL) - send(message: JSONRPCMessage): Promise - } - ``` - -3. **SSE transport** +2. **SSE transport** - Uses Server-Sent Events for server-to-client messages - HTTP POST for client-to-server messages - ```typescript - class SSETransport implements Transport { - constructor(url: URL) - send(message: JSONRPCMessage): Promise - } - ``` + +All transports use [JSON-RPC](https://www.jsonrpc.org/) 2.0 to exchange messages. See the [specification](https://spec.modelcontextprotocol.io) for more information. ### Message types -MCP uses JSON-RPC 2.0 as its message format with three main types: +MCP has these main types of messages: -1. **Requests** - ```typescript - interface Request { - method: string - params?: { - _meta?: { - progressToken?: string | number - } - } - } - ``` +1. **Requests** expect a response from the other side: + ```typescript + interface Request { + method: string; + params?: { ... }; + } + ``` -2. **Notifications** - ```typescript - interface Notification { - method: string - params?: { - _meta?: Record - } - } - ``` +2. **Notifications** are one-way messages that don't expect a response: + ```typescript + interface Notification { + method: string; + params?: { ... }; + } + ``` -3. **Results** - ```typescript - interface Result { - _meta?: Record - [key: string]: unknown - } - ``` +3. **Results** are successful responses to requests: + ```typescript + interface Result { + [key: string]: unknown; + } + ``` + +4. **Errors** indicate that a request failed: + ```typescript + interface Error { + code: number; + message: string; + data?: unknown; + } + ``` ## Connection lifecycle @@ -131,19 +124,17 @@ sequenceDiagram Note over Client,Server: Connection ready for use ``` -1. Client sends `initialize` request with capabilities -2. Server responds with supported features -3. Client sends `initialized` notification +1. Client sends `initialize` request with protocol version and capabilities +2. Server responds with its protocol version and capabilities +3. Client sends `initialized` notification as acknowledgment 4. Normal message exchange begins ### 2. Message exchange After initialization, the following patterns are supported: -- **Request-Response**: Client sends request, server responds +- **Request-Response**: Client or server sends requests, the other responds - **Notifications**: Either party sends one-way messages -- **Progress Updates**: Long-running operations can report progress -- **Resource Updates**: Servers notify about changed resources ### 3. Termination @@ -154,19 +145,21 @@ Either party can terminate the connection: ## Error handling -MCP defines standard error codes and handling: +MCP defines these standard error codes: ```typescript enum ErrorCode { - ConnectionClosed = -1, - ParseError = -32700, - InvalidRequest = -32600, - MethodNotFound = -32601, - InvalidParams = -32602, - InternalError = -32603 + // Standard JSON-RPC error codes + ParseError = -32700, + InvalidRequest = -32600, + MethodNotFound = -32601, + InvalidParams = -32602, + InternalError = -32603 } ``` +SDKs and applications can define their own error codes above -32000. + Errors are propagated through: - Error responses to requests - Error events on transports @@ -177,24 +170,28 @@ Errors are propagated through: Here's a basic example of implementing an MCP server: ```typescript -import { Server } from "@modelcontextprotocol/sdk/server"; -import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio"; +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" + name: "example-server", + version: "1.0.0" +}, { + capabilities: { + resources: {} + } }); // Handle requests server.setRequestHandler(ListResourcesRequestSchema, async () => { - return { - resources: [ - { - uri: "example://resource", - name: "Example Resource" - } - ] - }; + return { + resources: [ + { + uri: "example://resource", + name: "Example Resource" + } + ] + }; }); // Connect transport @@ -212,9 +209,8 @@ await server.connect(transport); - Simple process management 2. **Remote communication** - - WebSocket for full-duplex communication - - SSE for scenarios requiring HTTP compatibility - - Consider security implications + - Use SSE for scenarios requiring HTTP compatibility + - Consider security implications including authentication and authorization ### Message handling @@ -277,4 +273,4 @@ await server.connect(transport); - Test different transports - Verify error handling - Check edge cases - - Load test servers \ No newline at end of file + - Load test servers From a2e6868c40c4385088abcb2558b3a1c05e8f83aa Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 15:10:50 +0000 Subject: [PATCH 2/9] Add Python stubs --- docs/concepts/architecture.mdx | 108 +++++++++++++++++++-------------- 1 file changed, 63 insertions(+), 45 deletions(-) diff --git a/docs/concepts/architecture.mdx b/docs/concepts/architecture.mdx index b67e295..fdd0978 100644 --- a/docs/concepts/architecture.mdx +++ b/docs/concepts/architecture.mdx @@ -25,7 +25,7 @@ flowchart LR subgraph "Server Process" server2[MCP Server] end - + client1 <-->|Transport Layer| server1 client2 <-->|Transport Layer| server2 ``` @@ -34,23 +34,32 @@ flowchart LR ### Protocol layer -The protocol layer handles message framing, request/response linking, and high-level communication patterns. +The protocol layer handles message framing, request/response linking, and high-level communication patterns. -```typescript -class Protocol { - // Handle incoming requests - setRequestHandler(schema: T, handler: (request: T, extra: RequestHandlerExtra) => Promise): void - - // Handle incoming notifications - setNotificationHandler(schema: T, handler: (notification: T) => Promise): void - - // Send requests and await responses - request(request: Request, schema: T, options?: RequestOptions): Promise - - // Send one-way notifications - notification(notification: Notification): Promise -} -``` + + + ```typescript + class Protocol { + // Handle incoming requests + setRequestHandler(schema: T, handler: (request: T, extra: RequestHandlerExtra) => Promise): void + + // Handle incoming notifications + setNotificationHandler(schema: T, handler: (notification: T) => Promise): void + + // Send requests and await responses + request(request: Request, schema: T, options?: RequestOptions): Promise + + // Send one-way notifications + notification(notification: Notification): Promise + } + ``` + + + ```python + # Python implementation coming soon + ``` + + Key classes include: @@ -116,11 +125,11 @@ MCP has these main types of messages: sequenceDiagram participant Client participant Server - + Client->>Server: initialize request Server->>Client: initialize response Client->>Server: initialized notification - + Note over Client,Server: Connection ready for use ``` @@ -169,35 +178,44 @@ Errors are propagated through: 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"; + + + ```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" + const server = new Server({ + name: "example-server", + version: "1.0.0" + }, { + capabilities: { + resources: {} } - ] - }; -}); + }); -// Connect transport -const transport = new StdioServerTransport(); -await server.connect(transport); -``` + // 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 + # Python implementation coming soon + ``` + + ## Best practices From 69212f30b057ed332030261625fbf6b947f05cc8 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 15:19:27 +0000 Subject: [PATCH 3/9] Update resources.mdx --- docs/concepts/resources.mdx | 119 +++++++++++++++++++++--------------- 1 file changed, 69 insertions(+), 50 deletions(-) diff --git a/docs/concepts/resources.mdx b/docs/concepts/resources.mdx index f48f14f..5f91a09 100644 --- a/docs/concepts/resources.mdx +++ b/docs/concepts/resources.mdx @@ -24,7 +24,7 @@ Each resource is identified by a unique URI and can contain either text or binar Resources are identified using URIs that follow this format: ``` -[protocol]://[path] +[protocol]://[host]/[path] ``` For example: @@ -42,7 +42,7 @@ Resources can contain two types of content: Text resources contain UTF-8 encoded text data. These are suitable for: - Source code -- Configuration files +- Configuration files - Log files - JSON/XML data - Plain text @@ -66,37 +66,39 @@ Servers expose a list of concrete resources via the `resources/list` endpoint. E ```typescript { - uri: string; // Unique identifier for the resource - name: string; // Human-readable name + uri: string; // Unique identifier for the resource + name: string; // Human-readable name description?: string; // Optional description - mimeType?: string; // Optional MIME type + mimeType?: string; // Optional MIME type } ``` -### Resource templates +### Resource templates -For dynamic resources, servers can expose URI templates that clients can use to construct valid resource URIs: +For dynamic resources, servers can expose [URI templates](https://datatracker.ietf.org/doc/html/rfc6570) that clients can use to construct valid resource URIs: ```typescript { uriTemplate: string; // URI template following RFC 6570 name: string; // Human-readable name for this type description?: string; // Optional description - mimeType?: string; // Optional MIME type for all matching resources + mimeType?: string; // Optional MIME type for all matching resources } ``` ## Reading resources -To read a resource, clients make a `resources/read` request with the resource URI. The server responds with: +To read a resource, clients make a `resources/read` request with the resource URI. + +The server responds with a list of resource contents: ```typescript { contents: [ { - uri: string; // The requested URI + uri: string; // The URI of the resource mimeType?: string; // Optional MIME type - + // One of: text?: string; // For text resources blob?: string; // For binary resources (base64 encoded) @@ -105,6 +107,10 @@ To read a resource, clients make a `resources/read` request with the resource UR } ``` + + Servers may return multiple resources in response to one `resources/read` request. This could be used, for example, to return a list of files inside a directory when the directory is read. + + ## Resource updates MCP supports real-time updates for resources through two mechanisms: @@ -113,7 +119,7 @@ MCP supports real-time updates for resources through two mechanisms: Servers can notify clients when their list of available resources changes via the `notifications/resources/list_changed` notification. -### Content changes +### Content changes Clients can subscribe to updates for specific resources: @@ -126,45 +132,58 @@ Clients can subscribe to updates for specific resources: Here's a simple example of implementing resource support in an MCP server: -```typescript -const server = new Server({ - name: "example-server", - version: "1.0.0" -}); - -// List available resources -server.setRequestHandler(ListResourcesRequestSchema, async () => { - return { - resources: [ - { - uri: "file:///logs/app.log", - name: "Application Logs", - mimeType: "text/plain" + + + ```typescript + const server = new Server({ + name: "example-server", + version: "1.0.0" + }, { + capabilities: { + resources: {} } - ] - }; -}); + }); -// 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, - mimeType: "text/plain", - text: logContents - } - ] - }; - } - - throw new Error("Resource not found"); -}); -``` + // 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, + mimeType: "text/plain", + text: logContents + } + ] + }; + } + + throw new Error("Resource not found"); + }); + ``` + + + ```python + # Python implementation coming soon + ``` + + ## Best practices @@ -194,4 +213,4 @@ When exposing resources: - Encrypt sensitive data in transit - Validate MIME types - Implement timeouts for long-running reads -- Handle resource cleanup appropriately \ No newline at end of file +- Handle resource cleanup appropriately From f137a03a2e58f88972063524e489f4281e83b787 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 15:21:12 +0000 Subject: [PATCH 4/9] Update architecture.mdx --- docs/concepts/architecture.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/concepts/architecture.mdx b/docs/concepts/architecture.mdx index fdd0978..5e09797 100644 --- a/docs/concepts/architecture.mdx +++ b/docs/concepts/architecture.mdx @@ -75,11 +75,11 @@ The transport layer handles the actual communication between clients and servers - Uses standard input/output for communication - Ideal for local processes -2. **SSE transport** +2. **HTTP with SSE transport** - Uses Server-Sent Events for server-to-client messages - HTTP POST for client-to-server messages -All transports use [JSON-RPC](https://www.jsonrpc.org/) 2.0 to exchange messages. See the [specification](https://spec.modelcontextprotocol.io) for more information. +All transports use [JSON-RPC](https://www.jsonrpc.org/) 2.0 to exchange messages. See the [specification](https://spec.modelcontextprotocol.io) for detailed information about the Model Context Protocol message format. ### Message types From de7ee4337a135dcc8da7a90082877c8c7a34f394 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 15:27:37 +0000 Subject: [PATCH 5/9] Update prompts.mdx --- docs/concepts/prompts.mdx | 362 ++++++++++++++++---------------------- 1 file changed, 156 insertions(+), 206 deletions(-) diff --git a/docs/concepts/prompts.mdx b/docs/concepts/prompts.mdx index d80407a..971bec3 100644 --- a/docs/concepts/prompts.mdx +++ b/docs/concepts/prompts.mdx @@ -3,7 +3,7 @@ title: "Prompts" description: "Create resuable prompt templates and workflows" --- -MCP Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions. +Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions. ## Overview @@ -20,13 +20,13 @@ Each prompt is defined with: ```typescript { - name: string; // Unique identifier for the prompt - description?: string; // Human-readable description - arguments?: [ // Optional list of arguments + name: string; // Unique identifier for the prompt + description?: string; // Human-readable description + arguments?: [ // Optional list of arguments { - name: string; // Argument identifier - description?: string; // Argument description - required?: boolean; // Whether argument is required + name: string; // Argument identifier + description?: string; // Argument description + required?: boolean; // Whether argument is required } ] } @@ -78,15 +78,13 @@ To use a prompt, clients make a `prompts/get` request: // Response { - description?: string, // Optional context about the prompt - messages: [ // Messages to send to the LLM + description: "Analyze Python code for potential improvements", + messages: [ { - role: "user" | "assistant", + role: "user", content: { - type: "text" | "image", - text?: string, - data?: string, // base64 for images - mimeType?: string + type: "text", + text: "Please analyze the following Python code for potential improvements:\n\n```python\ndef calculate_sum(numbers):\n total = 0\n for num in numbers:\n total = total + num\n return total\n\nresult = calculate_sum([1, 2, 3, 4, 5])\nprint(result)\n```" } } ] @@ -97,57 +95,63 @@ To use a prompt, clients make a `prompts/get` request: Prompts can be dynamic and include: -### Context integration +### Embedded resource context -```typescript -const analyzeLogsPrompt = { - name: "analyze-logs", - description: "Analyze recent system logs", - arguments: [ +```json +{ + "name": "analyze-project", + "description": "Analyze project logs and code", + "arguments": [ { - name: "timeframe", - description: "Time period to analyze", - required: true + "name": "timeframe", + "description": "Time period to analyze logs", + "required": true + }, + { + "name": "fileUri", + "description": "URI of code file to review", + "required": true } ] -}; - -server.setRequestHandler(GetPromptRequestSchema, async (request) => { - if (request.params.name === "analyze-logs") { - const logs = await getSystemLogs(request.params.arguments?.timeframe); - return { - messages: [ - { - role: "user", - content: { - type: "text", - text: `Analyze these system logs and identify any issues:\n\n${logs}` - } - } - ] - }; - } -}); +} ``` -### Resource references +When handling the `prompts/get` request: -```typescript -const codeReviewPrompt = { - name: "review-code", - async getMessages(fileUri: string) { - const code = await readResource(fileUri); - return [ - { - role: "user", - content: { - type: "text", - text: `Review this code for best practices:\n\n${code}` +```json +{ + "messages": [ + { + "role": "user", + "content": { + "type": "text", + "text": "Analyze these system logs and the code file for any issues:" + } + }, + { + "role": "user", + "content": { + "type": "resource", + "resource": { + "uri": "logs://recent?timeframe=1h", + "text": "[2024-03-14 15:32:11] ERROR: Connection timeout in network.py:127\n[2024-03-14 15:32:15] WARN: Retrying connection (attempt 2/3)\n[2024-03-14 15:32:20] ERROR: Max retries exceeded", + "mimeType": "text/plain" } } - ]; - } -}; + }, + { + "role": "user", + "content": { + "type": "resource", + "resource": { + "uri": "file:///path/to/code.py", + "text": "def connect_to_service(timeout=30):\n retries = 3\n for attempt in range(retries):\n try:\n return establish_connection(timeout)\n except TimeoutError:\n if attempt == retries - 1:\n raise\n time.sleep(5)\n\ndef establish_connection(timeout):\n # Connection implementation\n pass", + "mimeType": "text/x-python" + } + } + } + ] +} ``` ### Multi-step workflows @@ -187,94 +191,107 @@ const debugWorkflow = { 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"; + + + ```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 + 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 + } + ] }, - { - name: "language", - description: "Programming language", - required: false + "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" -}); - -// 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"); -}); -``` + 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 + # Python implementation coming soon + ``` + + ## Best practices @@ -324,70 +341,3 @@ When implementing prompts: - Implement timeouts - Consider prompt injection risks - Document security requirements - -## Advanced features - -### Prompt chaining - -```typescript -const analyzePRPrompt = { - async getMessages(prId: string) { - // Chain multiple prompts - const diffPrompt = await getPrompt("analyze-diff"); - const testsPrompt = await getPrompt("review-tests"); - const securityPrompt = await getPrompt("security-review"); - - return [ - ...diffPrompt.messages, - ...testsPrompt.messages, - ...securityPrompt.messages - ]; - } -}; -``` - -### Context enrichment - -```typescript -const troubleshootPrompt = { - async getMessages(error: string) { - // Enrich with system context - const systemInfo = await getSystemInfo(); - const recentLogs = await getRecentLogs(); - const stackTrace = await parseError(error); - - return [ - { - role: "user", - content: { - type: "text", - text: `Help troubleshoot this error: -Error: ${error} -System: ${systemInfo} -Logs: ${recentLogs} -Stack: ${stackTrace}` - } - } - ]; - } -}; -``` - -### Interactive workflows - -```typescript -const debugWorkflow = { - async getMessages(stage: string, context: any) { - switch (stage) { - case "initial": - return promptForError(); - case "analysis": - return analyzeError(context.error); - case "solution": - return suggestFixes(context.analysis); - case "verification": - return verifyFix(context.solution); - } - } -}; -``` \ No newline at end of file From 75b32848a22d08557fe0916a747bf4a9b64f0514 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 15:35:18 +0000 Subject: [PATCH 6/9] Differentiate the primitives --- docs/concepts/prompts.mdx | 4 ++++ docs/concepts/resources.mdx | 6 ++++++ docs/concepts/tools.mdx | 22 +++++++++++++--------- 3 files changed, 23 insertions(+), 9 deletions(-) diff --git a/docs/concepts/prompts.mdx b/docs/concepts/prompts.mdx index 971bec3..d247ee8 100644 --- a/docs/concepts/prompts.mdx +++ b/docs/concepts/prompts.mdx @@ -5,6 +5,10 @@ description: "Create resuable prompt templates and workflows" Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions. + + Prompts are designed to be **user-controlled**, meaning they are exposed from servers to clients with the intention of the user being able to explicitly select them for use. + + ## Overview Prompts in MCP are predefined templates that can: diff --git a/docs/concepts/resources.mdx b/docs/concepts/resources.mdx index 5f91a09..00f6436 100644 --- a/docs/concepts/resources.mdx +++ b/docs/concepts/resources.mdx @@ -5,6 +5,12 @@ description: "Expose data and content from your servers to LLMs" Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions. + + Resources are designed to be **application-controlled**, meaning that the client application can decide how and when they should be used. + + For example, one application may require users to explicitly select resources, while another could automatically select them based on heuristics or even at the discretion of the AI model itself. + + ## Overview Resources represent any kind of data that an MCP server wants to make available to clients. This can include: diff --git a/docs/concepts/tools.mdx b/docs/concepts/tools.mdx index 557186f..1d13ca8 100644 --- a/docs/concepts/tools.mdx +++ b/docs/concepts/tools.mdx @@ -5,6 +5,10 @@ description: "Enable LLMs to perform actions through your server" Tools are a powerful primitive in the Model Context Protocol (MCP) that enable servers to expose executable functionality to clients. Through tools, LLMs can interact with external systems, perform computations, and take actions in the real world. + + Tools are designed to be **model-controlled**, meaning that tools are exposed from servers to clients with the intention of the AI model being able to automatically invoke them (with a human in the loop to grant approval). + + ## How tools work Tools in MCP follow a request-response pattern where: @@ -79,10 +83,10 @@ For long-running operations, tools can report progress using the progress notifi server.setRequestHandler(CallToolRequestSchema, async (request) => { if (request.params.name === "long_process") { const progressToken = request.params._meta?.progressToken; - + for (let i = 0; i < total; i++) { await doWork(); - + // Send progress update await server.notification({ method: "notifications/progress", @@ -93,7 +97,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => { } }); } - + return { toolResult: "Complete" }; } }); @@ -121,7 +125,7 @@ Tools that interact with the local system: } ``` -### API integrations +### API integrations Tools that wrap external APIs: @@ -152,10 +156,10 @@ Tools that transform or analyze data: type: "object", properties: { filepath: { type: "string" }, - operations: { - type: "array", - items: { - enum: ["sum", "average", "count"] + operations: { + type: "array", + items: { + enum: ["sum", "average", "count"] } } } @@ -276,4 +280,4 @@ Consider these testing approaches: 7. Test rate limiting 8. Check resource cleanup 9. Test timeout handling -10. Verify security constraints \ No newline at end of file +10. Verify security constraints From 2cace9ad021ec8b36d58697bb3c2c794a75764d7 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 15:41:10 +0000 Subject: [PATCH 7/9] Update tools.mdx --- docs/concepts/tools.mdx | 207 +++++++++++++++++----------------------- 1 file changed, 87 insertions(+), 120 deletions(-) diff --git a/docs/concepts/tools.mdx b/docs/concepts/tools.mdx index 1d13ca8..363b9c1 100644 --- a/docs/concepts/tools.mdx +++ b/docs/concepts/tools.mdx @@ -9,14 +9,15 @@ Tools are a powerful primitive in the Model Context Protocol (MCP) that enable s Tools are designed to be **model-controlled**, meaning that tools are exposed from servers to clients with the intention of the AI model being able to automatically invoke them (with a human in the loop to grant approval). -## How tools work +## Overview -Tools in MCP follow a request-response pattern where: +Tools in MCP allow servers to expose executable functions that can be invoked by clients and used by LLMs to perform actions. Key aspects of tools include: -1. Clients discover available tools through the `tools/list` endpoint -2. Clients can invoke tools using the `tools/call` endpoint -3. Servers execute the requested operation and return results -4. Progress updates can be sent during long-running operations +- **Discovery**: Clients can list available tools through the `tools/list` endpoint +- **Invocation**: Tools are called using the `tools/call` endpoint, where servers perform the requested operation and return results +- **Flexibility**: Tools can range from simple calculations to complex API interactions + +Like [resources](/docs/concepts/resources), tools are identified by unique names and can include descriptions to guide their usage. However, unlike resources, tools represent dynamic operations that can modify state or interact with external systems. ## Tool definition structure @@ -24,13 +25,11 @@ Each tool is defined with the following structure: ```typescript { - name: string; // Unique identifier for the tool + name: string; // Unique identifier for the tool description?: string; // Human-readable description - inputSchema: { // JSON Schema for the tool's parameters + inputSchema: { // JSON Schema for the tool's parameters type: "object", - properties: { - // Tool-specific parameters - } + properties: { ... } // Tool-specific parameters } } ``` @@ -39,73 +38,58 @@ Each tool is defined with the following structure: 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" -}); - -// 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"] + + + ```typescript + const server = new Server({ + name: "example-server", + version: "1.0.0" + }, { + capabilities: { + tools: {} } - }] - }; -}); + }); -// Handle tool execution -server.setRequestHandler(CallToolRequestSchema, async (request) => { - if (request.params.name === "calculate_sum") { - const { a, b } = request.params.arguments; - return { - toolResult: a + b - }; - } - throw new Error("Tool not found"); -}); -``` + // 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"] + } + }] + }; + }); -## Progress reporting + // Handle tool execution + server.setRequestHandler(CallToolRequestSchema, async (request) => { + if (request.params.name === "calculate_sum") { + const { a, b } = request.params.arguments; + return { + toolResult: a + b + }; + } + throw new Error("Tool not found"); + }); + ``` + + + ```python + # Python implementation coming soon + ``` + + -For long-running operations, tools can report progress using the progress notification system: +## Example tool patterns -```typescript -server.setRequestHandler(CallToolRequestSchema, async (request) => { - if (request.params.name === "long_process") { - const progressToken = request.params._meta?.progressToken; - - for (let i = 0; i < total; i++) { - await doWork(); - - // Send progress update - await server.notification({ - method: "notifications/progress", - params: { - progress: i, - total: total, - progressToken - } - }); - } - - return { toolResult: "Complete" }; - } -}); -``` - -## Common tool patterns - -Here are some common patterns for implementing tools: +Here are some examples of types of tools that a server could provide: ### System operations @@ -173,7 +157,7 @@ When implementing tools: 1. Provide clear, descriptive names and descriptions 2. Use detailed JSON Schema definitions for parameters -3. Include examples in tool descriptions when helpful +3. Include examples in tool descriptions to demonstrate how the model should use them 4. Implement proper error handling and validation 5. Use progress reporting for long operations 6. Keep tool operations focused and atomic @@ -219,65 +203,48 @@ MCP supports dynamic tool discovery: 3. Tools can be added or removed during runtime 4. Tool definitions can be updated (though this should be done carefully) -## Common tool categories - -Tools typically fall into these categories: - -### System integration -- File operations -- Process management -- System information -- Network operations - -### External services -- API calls -- Database operations -- Authentication services -- Cloud services - -### Data processing -- Format conversion -- Data analysis -- Content generation -- Media processing - -### Device control -- Hardware interaction -- Device configuration -- Sensor reading -- Output control - ## Error handling -Tools should return clear error information: +Tool errors should be reported within the result object, not as MCP protocol-level errors. This allows the LLM to see and potentially handle the error. When a tool encounters an error: + +1. Set `isError` to `true` in the result +2. Include error details in the `content` array + +Here's an example of proper error handling for tools: ```typescript try { // Tool operation + const result = performOperation(); + return { + content: [ + { + type: "text", + text: `Operation successful: ${result}` + } + ] + }; } catch (error) { return { - toolResult: { - error: { - code: "OPERATION_FAILED", - message: "Failed to process request", - details: error.message + isError: true, + content: [ + { + type: "text", + text: `Error: ${error.message}` } - } + ] }; } ``` +This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention. + ## Testing tools -Consider these testing approaches: +A comprehensive testing strategy for MCP tools should cover: -1. Unit test parameter validation -2. Mock external dependencies -3. Test progress reporting -4. Verify error handling -5. Test concurrent execution -6. Validate return values -7. Test rate limiting -8. Check resource cleanup -9. Test timeout handling -10. Verify security constraints +- **Functional testing**: Verify tools execute correctly with valid inputs and handle invalid inputs appropriately +- **Integration testing**: Test tool interaction with external systems using both real and mocked dependencies +- **Security testing**: Validate authentication, authorization, input sanitization, and rate limiting +- **Performance testing**: Check behavior under load, timeout handling, and resource cleanup +- **Error handling**: Ensure tools properly report errors through the MCP protocol and clean up resources From 6eed214799363359ad93a204d5cc4abf5427912c Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 15:46:20 +0000 Subject: [PATCH 8/9] Update sampling.mdx --- docs/concepts/sampling.mdx | 76 +++++++++++++++++++++++++------------- 1 file changed, 50 insertions(+), 26 deletions(-) diff --git a/docs/concepts/sampling.mdx b/docs/concepts/sampling.mdx index d5aeb78..fd17370 100644 --- a/docs/concepts/sampling.mdx +++ b/docs/concepts/sampling.mdx @@ -5,6 +5,10 @@ description: "Let your servers request completions from LLMs" Sampling is a powerful MCP feature that allows servers to request LLM completions through the client, enabling sophisticated agentic behaviors while maintaining security and privacy. + + This feature of MCP is not yet supported in the Claude Desktop client. + + ## How sampling works The sampling flow follows these steps: @@ -12,7 +16,7 @@ The sampling flow follows these steps: 1. Server sends a `sampling/createMessage` request to the client 2. Client reviews the request and can modify it 3. Client samples from an LLM -4. Client reviews the completion +4. Client reviews the completion 5. Client returns the result to the server This human-in-the-loop design ensures users maintain control over what the LLM sees and generates. @@ -28,14 +32,24 @@ Sampling requests use a standardized message format: role: "user" | "assistant", content: { type: "text" | "image", + // For text: text?: string, + // For images: - data?: string, // base64 encoded + data?: string, // base64 encoded mimeType?: string } } ], + modelPreferences?: { + hints?: [{ + name?: string // Suggested model name/family + }], + costPriority?: number, // 0-1, importance of minimizing cost + speedPriority?: number, // 0-1, importance of low latency + intelligencePriority?: number // 0-1, importance of capabilities + }, systemPrompt?: string, includeContext?: "none" | "thisServer" | "allServers", temperature?: number, @@ -51,11 +65,27 @@ Sampling requests use a standardized message format: The `messages` array contains the conversation history to send to the LLM. Each message has: -- `role`: Either "user" or "assistant" +- `role`: Either "user" or "assistant" - `content`: The message content, which can be: - Text content with a `text` field - Image content with `data` (base64) and `mimeType` fields +### Model preferences + +The `modelPreferences` object allows servers to specify their model selection preferences: + +- `hints`: Array of model name suggestions that clients can use to select an appropriate model: + - `name`: String that can match full or partial model names (e.g. "claude-3", "sonnet") + - Clients may map hints to equivalent models from different providers + - Multiple hints are evaluated in preference order + +- Priority values (0-1 normalized): + - `costPriority`: Importance of minimizing costs + - `speedPriority`: Importance of low latency response + - `intelligencePriority`: Importance of advanced model capabilities + +Clients make the final model selection based on these preferences and their available models. + ### System prompt An optional `systemPrompt` field allows servers to request a specific system prompt. The client may modify or ignore this. @@ -85,8 +115,8 @@ The client returns a completion result: ```typescript { - model: string, // Name of the model used - stopReason: "endTurn" | "stopSequence" | "maxTokens", + model: string, // Name of the model used + stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string, role: "user" | "assistant", content: { type: "text" | "image", @@ -97,33 +127,27 @@ The client returns a completion result: } ``` -## Example implementation +## Example request Here's an example of requesting sampling from a client: - -```typescript -// Server-side code -const response = await server.request({ - method: "sampling/createMessage", - params: { - messages: [ +```json +{ + "method": "sampling/createMessage", + "params": { + "messages": [ { - role: "user", - content: { - type: "text", - text: "What files are in the current directory?" + "role": "user", + "content": { + "type": "text", + "text": "What files are in the current directory?" } } ], - systemPrompt: "You are a helpful file system assistant.", - includeContext: "thisServer", - maxTokens: 100, - temperature: 0.7 + "systemPrompt": "You are a helpful file system assistant.", + "includeContext": "thisServer", + "maxTokens": 100 } -}, CreateMessageResultSchema); - -// Handle the completion -console.log(response.content.text); +} ``` ## Best practices @@ -218,4 +242,4 @@ Be aware of these limitations: - Costs should be considered - Model availability varies - Response times vary -- Not all content types supported \ No newline at end of file +- Not all content types supported From 50ba756cef9363e47570df6ca90e74e00d812c81 Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Thu, 21 Nov 2024 15:52:16 +0000 Subject: [PATCH 9/9] Update transports.mdx --- docs/concepts/transports.mdx | 335 +++++++++++++++++------------------ 1 file changed, 161 insertions(+), 174 deletions(-) diff --git a/docs/concepts/transports.mdx b/docs/concepts/transports.mdx index cf3bb9e..3c0fd89 100644 --- a/docs/concepts/transports.mdx +++ b/docs/concepts/transports.mdx @@ -5,128 +5,13 @@ description: "Learn about MCP's communication mechanisms" 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 transports work +## Message Format -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: +MCP uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 as its wire format. The transport layer is responsible for converting MCP protocol messages into JSON-RPC format for transmission and converting received JSON-RPC messages back into MCP protocol messages. -- Establishing connections -- Sending messages -- Receiving messages -- Handling connection lifecycles -- Managing errors -- Ensuring reliable delivery - -## Available transport types - -MCP supports three main transport types: - -### Standard input/output (stdio) - -The stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools. - -```typescript -// Server implementation -const server = new Server({ - name: "example-server", - version: "1.0.0" -}); - -const transport = new StdioServerTransport(); -await server.connect(transport); - -// Client implementation -const client = new Client({ - name: "example-client", - version: "1.0.0" -}); - -const transport = new StdioClientTransport({ - command: "./server", - args: ["--option", "value"] -}); -await client.connect(transport); -``` - -### WebSocket - -WebSocket transport provides real-time, bidirectional communication over a persistent connection. This is ideal for web-based applications that need low-latency messaging. - -```typescript -// Server implementation -const server = new Server({ - name: "example-server", - version: "1.0.0" -}); - -const transport = new WebSocketServerTransport(); -await server.connect(transport); - -// Client implementation -const client = new Client({ - name: "example-client", - version: "1.0.0" -}); - -const transport = new WebSocketClientTransport( - new URL("ws://localhost:3000") -); -await client.connect(transport); -``` - -### Server-sent events - -SSE transport enables server-to-client streaming with HTTP POST requests for client-to-server communication. This is useful when WebSocket support isn't available. - -```typescript -// Server implementation -const server = new Server({ - name: "example-server", - version: "1.0.0" -}); - -const transport = new SSEServerTransport("/message", response); -await server.connect(transport); - -// Client implementation -const client = new Client({ - name: "example-client", - version: "1.0.0" -}); - -const transport = new SSEClientTransport( - new URL("http://localhost:3000/sse") -); -await client.connect(transport); -``` - -## Transport interface - -All transport implementations must conform to the Transport interface: - -```typescript -interface Transport { - // Start processing messages - start(): Promise; - - // Send a JSON-RPC message - send(message: JSONRPCMessage): Promise; - - // Close the connection - close(): Promise; - - // Callbacks - onclose?: () => void; - onerror?: (error: Error) => void; - onmessage?: (message: JSONRPCMessage) => void; -} -``` - -## Message format - -Messages sent over MCP transport follow the JSON-RPC 2.0 specification. There are three types of messages: +There are three types of JSON-RPC messages used: ### Requests - ```typescript { jsonrpc: "2.0", @@ -137,7 +22,6 @@ Messages sent over MCP transport follow the JSON-RPC 2.0 specification. There ar ``` ### Responses - ```typescript { jsonrpc: "2.0", @@ -152,7 +36,6 @@ Messages sent over MCP transport follow the JSON-RPC 2.0 specification. There ar ``` ### Notifications - ```typescript { jsonrpc: "2.0", @@ -161,7 +44,130 @@ Messages sent over MCP transport follow the JSON-RPC 2.0 specification. There ar } ``` -## Error handling +## Built-in Transport Types + +MCP includes two standard transport implementations: + +### Standard Input/Output (stdio) + +The stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools. + +Use stdio when: +- Building command-line tools +- Implementing local integrations +- Needing simple process communication +- Working with shell scripts + + + + ```typescript + // Server implementation + const server = new Server({ + name: "example-server", + version: "1.0.0" + }); + + const transport = new StdioServerTransport(); + await server.connect(transport); + + // Client implementation + const client = new Client({ + name: "example-client", + version: "1.0.0" + }); + + const transport = new StdioClientTransport({ + command: "./server", + args: ["--option", "value"] + }); + await client.connect(transport); + ``` + + + ```python + # Python implementation coming soon + ``` + + + +### Server-Sent Events (SSE) + +SSE transport enables server-to-client streaming with HTTP POST requests for client-to-server communication. + +Use SSE when: +- Only server-to-client streaming is needed +- Working with restricted networks +- Implementing simple updates + + + + ```typescript + // Server implementation + const server = new Server({ + name: "example-server", + version: "1.0.0" + }); + + const transport = new SSEServerTransport("/message", response); + await server.connect(transport); + + // Client implementation + const client = new Client({ + name: "example-client", + version: "1.0.0" + }); + + const transport = new SSEClientTransport( + new URL("http://localhost:3000/sse") + ); + await client.connect(transport); + ``` + + + ```python + # Python implementation coming soon + ``` + + + +## Custom Transports + +MCP makes it easy to implement custom transports for specific needs. Any transport implementation just needs to conform to the Transport interface: + +You can implement custom transports for: +- Custom network protocols +- Specialized communication channels +- Integration with existing systems +- Performance optimization + + + + ```typescript + interface Transport { + // Start processing messages + start(): Promise; + + // Send a JSON-RPC message + send(message: JSONRPCMessage): Promise; + + // Close the connection + close(): Promise; + + // Callbacks + onclose?: () => void; + onerror?: (error: Error) => void; + onmessage?: (message: JSONRPCMessage) => void; + } + ``` + + + ```python + # Python implementation coming soon + ``` + + + +## Error Handling Transport implementations should handle various error scenarios: @@ -173,29 +179,38 @@ Transport implementations should handle various error scenarios: Example error handling: -```typescript -class ExampleTransport implements Transport { - async start() { - try { - // Connection logic - } catch (error) { - this.onerror?.(new Error(`Failed to connect: ${error}`)); - throw error; - } - } + + + ```typescript + class ExampleTransport implements Transport { + async start() { + try { + // Connection logic + } catch (error) { + this.onerror?.(new Error(`Failed to connect: ${error}`)); + throw error; + } + } - async send(message: JSONRPCMessage) { - try { - // Sending logic - } catch (error) { - this.onerror?.(new Error(`Failed to send message: ${error}`)); - throw error; + async send(message: JSONRPCMessage) { + try { + // Sending logic + } catch (error) { + this.onerror?.(new Error(`Failed to send message: ${error}`)); + throw error; + } + } } - } -} -``` + ``` + + + ```python + # Python implementation coming soon + ``` + + -## Best practices +## Best Practices When implementing or using MCP transport: @@ -210,34 +225,31 @@ When implementing or using MCP transport: 9. Monitor connection health 10. Implement proper security measures -## Security considerations +## Security Considerations When implementing transport: -### Authentication and authorization - +### Authentication and Authorization - Implement proper authentication mechanisms - Validate client credentials - Use secure token handling - Implement authorization checks -### Data security - +### Data Security - Use TLS for network transport - Encrypt sensitive data - Validate message integrity - Implement message size limits - Sanitize input data -### Network security - +### Network Security - Implement rate limiting - Use appropriate timeouts - Handle denial of service scenarios - Monitor for unusual patterns - Implement proper firewall rules -## Debugging transport +## Debugging Transport Tips for debugging transport issues: @@ -251,28 +263,3 @@ Tips for debugging transport issues: 8. Monitor resource usage 9. Test edge cases 10. Use proper error tracking - -## Transport selection guide - -Choose the appropriate transport based on your needs: - -### Use stdio when - -- Building command-line tools -- Implementing local integrations -- Needing simple process communication -- Working with shell scripts - -### Use WebSocket when - -- Real-time updates are needed -- Low latency is required -- Bidirectional communication is necessary -- Working with web applications - -### Use SSE when - -- Only server-to-client streaming is needed -- WebSocket support is limited -- Working with restricted networks -- Implementing simple updates