MCP 伺服器模式
模型上下文協議 (MCP) 可讓 AI 助手從您的伺服器調用工具、讀取資源及使用提示。在建立或維護 MCP 伺服器時，請使用此技能。SDK API 會持續演進；請查閱 Context7（查詢文件 "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()或等效方法註冊。 - 傳輸方式：stdio 用於本地客戶端（例如 Claude Desktop）；對於遠端客戶端（Cursor、雲端），Streamable HTTP 是首選。傳統的 HTTP/SSE 僅用於向後相容。
Node/TypeScript SDK 可能會公開 tool() / resource() 或 registerTool() / registerResource()；官方 SDK 已隨著時間改變。請務必根據當前的 MCP 文件 或 Context7 進行驗證。
使用 stdio 連線
對於本地客戶端，建立一個 stdio 傳輸並將其傳遞給伺服器的連線方法。確切的 API 因 SDK 版本而異（例如建構子與工廠方法的差別）。請參閱官方 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 偏好的 schema 格式）進行輸入驗證。
最佳實務
- Schema 優先：為每個工具定義輸入 schema；記錄參數和回傳形狀。
- 錯誤處理：回傳結構化的錯誤或模型可解讀的訊息；避免原始堆疊追蹤。
- 冪等性：盡可能偏好冪等工具，以便重試安全。
- 速率與成本：對於呼叫外部 API 的工具，請考慮速率限制和成本；在工具描述中記錄。
- 版本管理：在 package.json 中鎖定 SDK 版本；升級時檢查版本發行說明。
官方 SDK 與文件
- JavaScript/TypeScript：
@modelcontextprotocol/sdk(npm)。使用 Context7 並將函式庫名稱設為 "MCP" 以取得當前的註冊與傳輸模式。 - Go：GitHub 上的官方 Go SDK (
modelcontextprotocol/go-sdk)。 - C#：適用於 .NET 的官方 C# SDK。