MCP 伺服器模式 是做什麼的？
模型上下文協議 (MCP) 讓 AI 助手能夠呼叫您伺服器上的工具、讀取資源以及使用提示。在建立或維護 MCP 伺服器時使用此技能。SDK API 會不斷演進；請查閱 Context7 (查詢-docs 關鍵字 "MCP") 或官方 MCP 文件以取得最新的方法名稱與簽章。
關於一個功能應作為規則、技能、MCP 還是單純的 CLI/API 工作流程的更廣泛路由決策，請參閱 docs/capability-surface-selection.md。
使用時機
在以下情況使用：實作新的 MCP 伺服器、新增工具或資源、選擇 stdio 或 HTTP、升級 SDK，或除錯 MCP 註冊與傳輸問題。
運作方式
核心概念
- 工具：模型可以呼叫的動作 (例如搜尋、執行命令)。根據 SDK 版本使用
registerTool()或tool()註冊。 - 資源：模型可以擷取的唯讀資料 (例如檔案內容、API 回應)。使用
registerResource()或resource()註冊。處理常式通常會接收一個uri參數。 - 提示：可重複使用、參數化的提示模板，客戶端可以呈現 (例如在 Claude Desktop 中)。使用
registerPrompt()或等效方法註冊。 - 傳輸方式：適用於本機客戶端 (例如 Claude Desktop) 的 stdio；遠端 (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" 以取得當前模式。
保持伺服器邏輯 (工具 + 資源) 與傳輸方式無關，以便您可以在進入點插入 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 註冊工具和資源：某些版本使用 server.tool(name, description, schema, handler) (位置參數)，其他版本則使用 server.tool({ name, description, inputSchema }, handler) 或 registerTool()。資源也是如此 — 當 API 提供 uri 時，請在處理常式中包含它。請查閱官方 MCP 文件或 Context7 以取得目前 @modelcontextprotocol/sdk 的簽章，以避免複製貼上錯誤。
使用 Zod (或 SDK 偏好的模式格式) 進行輸入驗證。
最佳實務
- 模式優先：為每個工具定義輸入模式；記錄參數和回傳形狀。
- 錯誤：回傳模型可以解讀的結構化錯誤或訊息；避免原始堆疊追蹤。
- 冪等性：盡可能偏好冪等工具，以便重試是安全的。
- 速率與成本：對於呼叫外部 API 的工具，請考量速率限制和成本；在工具描述中記錄。
- 版本控制：在 package.json 中鎖定 SDK 版本；升級時檢查版本說明。
官方 SDK 與文件
- JavaScript/TypeScript：
@modelcontextprotocol/sdk(npm)。使用 Context7 並將函式庫名稱設為 "MCP" 以取得當前的註冊和傳輸模式。 - Go：GitHub 上的官方 Go SDK (
modelcontextprotocol/go-sdk)。 - C#：適用於 .NET 的官方 C# SDK。