mcp-server-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP Server Patterns

MCP服务器模式

The Model Context Protocol (MCP) lets AI assistants call tools, read resources, and use prompts from your server. Use this skill when building or maintaining MCP servers. The SDK API evolves; check Context7 (query-docs for "MCP") or the official MCP documentation for current method names and signatures.

模型上下文协议（MCP）允许AI助手调用你的服务器中的工具、读取资源并使用提示词。在构建或维护MCP服务器时可使用本技能。SDK API会不断演进；如需获取当前的方法名称和签名，请查看Context7（搜索“MCP”文档）或官方MCP文档。

When to Use

适用场景

Use when: implementing a new MCP server, adding tools or resources, choosing stdio vs HTTP, upgrading the SDK, or debugging MCP registration and transport issues.

适用于以下场景：实现新的MCP服务器、添加工具或资源、选择stdio或HTTP传输方式、升级SDK，或调试MCP注册和传输问题。

How It Works

工作原理

Core concepts

核心概念

Tools: Actions the model can invoke (e.g. search, run a command). Register with
```
registerTool()
```
or
```
tool()
```
depending on SDK version.
Resources: Read-only data the model can fetch (e.g. file contents, API responses). Register with
```
registerResource()
```
or
```
resource()
```
. Handlers typically receive a
```
uri
```
argument.
Prompts: Reusable, parameterised prompt templates the client can surface (e.g. in Claude Desktop). Register with
```
registerPrompt()
```
or equivalent.
Transport: stdio for local clients (e.g. Claude Desktop); Streamable HTTP is preferred for remote (Cursor, cloud). Legacy HTTP/SSE is for backward compatibility.

The Node/TypeScript SDK may expose

tool()

resource()

registerTool()

registerResource()

; the official SDK has changed over time. Always verify against the current MCP docs or Context7.

工具（Tools）：模型可以调用的操作（如搜索、运行命令）。根据SDK版本不同，使用
```
registerTool()
```
或
```
tool()
```
进行注册。
资源（Resources）：模型可以获取的只读数据（如文件内容、API响应）。使用
```
registerResource()
```
或
```
resource()
```
进行注册。处理器通常会接收一个
```
uri
```
参数。
提示词（Prompts）：客户端可以调用的可复用、带参数的提示词模板（如在Claude Desktop中）。使用
```
registerPrompt()
```
或等效方法注册。
传输方式（Transport）：本地客户端（如Claude Desktop）使用stdio；远程客户端（Cursor、云服务）优先使用Streamable HTTP。传统HTTP/SSE仅用于向后兼容。

Node/TypeScript SDK可能会暴露

tool()

resource()

或

registerTool()

registerResource()

；官方SDK的接口随时间有所变化。请始终对照当前的MCP文档或Context7进行验证。

Connecting with stdio

基于stdio连接

For local clients, create a stdio transport and pass it to your server’s connect method. The exact API varies by SDK version (e.g. constructor vs factory). See the official MCP documentation or query Context7 for "MCP stdio server" for the current pattern.

Keep server logic (tools + resources) independent of transport so you can plug in stdio or HTTP in the entrypoint.

对于本地客户端，创建一个stdio传输实例并传递给服务器的连接方法。具体API因SDK版本而异（如构造函数 vs 工厂方法）。如需当前实现模式，请查看官方MCP文档或在Context7中搜索“MCP stdio server”。

请保持服务器逻辑（工具+资源）与传输方式解耦，以便你可以在入口文件中灵活切换stdio或HTTP传输。

Remote (Streamable HTTP)

远程连接（Streamable HTTP）

For Cursor, cloud, or other remote clients, use Streamable HTTP (single MCP HTTP endpoint per current spec). Support legacy HTTP/SSE only when backward compatibility is required.

对于Cursor、云服务或其他远程客户端，请使用Streamable HTTP（符合当前规范的单一MCP HTTP端点）。仅当需要向后兼容时才支持传统HTTP/SSE。

Examples

示例

Install and server setup

安装与服务器设置

bash

npm install @modelcontextprotocol/sdk zod

typescript

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.tool(name, description, schema, handler)

(positional args), others use

server.tool({ name, description, inputSchema }, handler)

registerTool()

. Same for resources — include a

uri

in the handler when the API provides it. Check the official MCP docs or Context7 for the current

@modelcontextprotocol/sdk

signatures to avoid copy-paste errors.

Use Zod (or the SDK’s preferred schema format) for input validation.

bash

npm install @modelcontextprotocol/sdk zod

typescript

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

根据你使用的SDK版本，使用对应的API注册工具和资源：部分版本使用

server.tool(name, description, schema, handler)

（位置参数），其他版本使用

server.tool({ name, description, inputSchema }, handler)

或

registerTool()

。资源注册同理——当API提供时，处理器中需包含

uri

参数。为避免复制粘贴错误，请查看官方MCP文档或Context7中当前

@modelcontextprotocol/sdk

的方法签名。

使用Zod（或SDK推荐的 schema 格式）进行输入验证。

Best Practices

最佳实践

Schema first: Define input schemas for every tool; document parameters and return shape.
Errors: Return structured errors or messages the model can interpret; avoid raw stack traces.
Idempotency: Prefer idempotent tools where possible so retries are safe.
Rate and cost: For tools that call external APIs, consider rate limits and cost; document in the tool description.
Versioning: Pin SDK version in package.json; check release notes when upgrading.

Schema优先：为每个工具定义输入schema；记录参数和返回结构。
错误处理：返回模型可以解析的结构化错误或信息；避免返回原始堆栈跟踪。
幂等性：尽可能优先使用幂等工具，确保重试操作是安全的。
速率与成本：对于调用外部API的工具，请考虑速率限制和成本；并在工具描述中注明。
版本控制：在package.json中固定SDK版本；升级时查看发布说明。

Official SDKs and Docs

官方SDK与文档

JavaScript/TypeScript:
```
@modelcontextprotocol/sdk
```
(npm). Use Context7 with library name "MCP" for current registration and transport patterns.
Go: Official Go SDK on GitHub (
```
modelcontextprotocol/go-sdk
```
).
C#: Official C# SDK for .NET.

JavaScript/TypeScript：
```
@modelcontextprotocol/sdk
```
（npm包）。如需当前的注册和传输模式，请在Context7中搜索库名称“MCP”。
Go：GitHub上的官方Go SDK（
```
modelcontextprotocol/go-sdk
```
）。
C#：适用于.NET的官方C# SDK。