mcp-server-patterns

MCP Server Patterns

Model Context Protocol (MCP) 讓 AI 助理能夠呼叫您伺服器上的工具 (tools)、讀取資源 (resources) 並使用提示詞範本 (prompts)。在開發或維護 MCP 伺服器時請使用此 Skill。由於 SDK API 會持續演進，請透過 Context7（查詢 "MCP" 相關文件）或官方 MCP 文件確認最新的方法名稱與簽章。

關於能力的整體路由決策——何時該將功能實作爲 rule、skill、MCP 或單純的 CLI/API 工作流程，請參閱 docs/capability-surface-selection.md。

使用時機

適用於：實作全新的 MCP 伺服器、新增工具 (tools) 或資源 (resources)、評估 stdio 與 HTTP 傳輸方式的選擇、升級 SDK，或排查 MCP 註冊與傳輸層相關問題。

運作原理

核心概念

• Tools：模型可呼叫的動作（例如：搜尋、執行命令）。依 SDK 版本不同，透過 registerTool() 或 tool() 進行註冊。
• Resources：模型可讀取的唯讀資料（例如：檔案內容、API 回應）。透過 registerResource() 或 resource() 進行註冊。處理函式通常會接收到一個 uri 參數。
• Prompts：用戶端可呈現給使用者的可複用參數化提示詞範本（例如在 Claude Desktop 中）。透過 registerPrompt() 或同等方法進行註冊。
• Transport：stdio 用於本機用戶端（例如 Claude Desktop）；遠端用戶端（Cursor、雲端環境）則偏好使用 Streamable HTTP。傳統的 HTTP/SSE 僅用於需要相容舊版的情境。

Node/TypeScript SDK 可能會提供 tool() / resource() 或 registerTool() / registerResource()；官方 SDK API 曾進行過調整。請務必對照最新的 MCP 文件 或 Context7。

使用 stdio 連接

針對本機用戶端，建立 stdio 傳輸物件並將其傳入伺服器的 connect 方法。具體 API 依 SDK 版本而異（例如建構子 vs 工廠函式）。請參考官方 MCP 文件或在 Context7 查詢 "MCP stdio server" 以取得目前的實作模式。

保持伺服器邏輯（tools + resources）獨立於傳輸層之外，以便能在進入點 (entrypoint) 彈性切換 stdio 或 HTTP。

遠端 (Streamable HTTP)

針對 Cursor、雲端或其它遠端用戶端，請使用 Streamable HTTP（依據最新規範，每個 MCP 僅需單一 HTTP 端點）。只有在需要相容舊版時才支援傳統的 HTTP/SSE。

範例

安裝與伺服器設定

npm install @modelcontextprotocol/sdk zod

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 來註冊 tools 與 resources：部分版本使用 server.tool(name, description, schema, handler)（位置參數），其它版本則使用 server.tool({ name, description, inputSchema }, handler) 或 registerTool()。Resources 亦同——當 API 提供時，請在 handler 中包含 uri。請查閱官方 MCP 文件或 Context7 以確認最新的 @modelcontextprotocol/sdk 簽章，避免直接複製貼上導致錯誤。

請使用 Zod（或 SDK 偏好的 schema 格式）進行輸入驗證。

最佳實踐

• Schema 優先：為每個 tool 定義輸入 schema，並詳細記錄參數與回傳結構。
• 錯誤處理：回傳結構化錯誤或模型可解讀的訊息，避免直接暴露原始堆疊追蹤 (raw stack traces)。
• 冪等性：盡可能優先採用冪等 (idempotent) 工具，確保重試操作時的安全性。
• 速率與成本：對於會呼叫外部 API 的工具，需考量呼叫頻率限制 (rate limits) 與成本，並於 tool 的 description 中載明。
• 版本控管：在 package.json 中固定 SDK 版本；升級時請務必確認版本釋出說明 (release notes)。

官方 SDK 與文件

• JavaScript/TypeScript：@modelcontextprotocol/sdk (npm)。使用 Context7 搭配套件名稱 "MCP" 即可查詢最新的註冊與傳輸模式。
• Go：GitHub 上的官方 Go SDK (modelcontextprotocol/go-sdk)。
• C#：官方 .NET C# SDK。