MCP 伺服器開發指南
概覽
建立 MCP (Model Context Protocol) 伺服器,讓大型語言模型 (LLM) 能透過精心設計的工具與外部服務互動。MCP 伺服器的品質取決於其協助 LLM 完成真實世界任務的能力。
流程
🚀 高階工作流程
建立高品質的 MCP 伺服器包含四個主要階段:
階段 1:深度研究與規劃
1.1 了解現代 MCP 設計
API 覆蓋率 vs. 工作流程工具: 在全面的 API 端點覆蓋率與專門的工作流程工具之間取得平衡。工作流程工具對於特定任務可能更方便,而全面的覆蓋率則賦予代理組合操作的靈活性。效能因客戶端而異——某些客戶端受益於能結合基本操作的程式碼執行,而其他客戶端則更適合高階工作流程。若不確定,應優先追求全面的 API 覆蓋率。
工具命名與可發現性:
清晰、描述性的工具名稱有助於代理快速找到正確的工具。使用一致的命名前綴(例如 github_create_issue、github_list_repos)以及行動導向的命名方式。
上下文管理: 代理受益於簡潔的工具描述以及篩選/分頁結果的能力。設計能回傳重點、相關資料的工具。部分客戶端支援程式碼執行,這能幫助代理有效地篩選和處理資料。
可操作的錯誤訊息: 錯誤訊息應引導代理找到解決方案,並提供具體建議和後續步驟。
1.2 研讀 MCP 協定文件
瀏覽 MCP 規格:
從網站地圖開始,尋找相關頁面:https://modelcontextprotocol.io/sitemap.xml
然後以 .md 後綴取得特定頁面的 Markdown 格式(例如 https://modelcontextprotocol.io/specification/draft.md)。
需要審查的關鍵頁面:
- 規格概述與架構
- 傳輸機制(Streamable HTTP、stdio)
- 工具、資源和提示詞定義
1.3 研讀框架文件
推薦技術棧:
- 語言:TypeScript(高品質的 SDK 支援,且在許多執行環境(如 MCPB)中具有良好的相容性。此外,AI 模型擅長生成 TypeScript 程式碼,受益於其廣泛使用、靜態型別及良好的 linting 工具)
- 傳輸方式:遠端伺服器使用 Streamable HTTP,採用無狀態 JSON(相比有狀態工作階段和串流回應,更易於擴展和維護)。本地伺服器使用 stdio。
載入框架文件:
- MCP 最佳實務:📋 檢視最佳實務 - 核心指南
對於 TypeScript(推薦):
- TypeScript SDK:使用 WebFetch 載入
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md - ⚡ TypeScript 指南 - TypeScript 模式與範例
對於 Python:
- Python SDK:使用 WebFetch 載入
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - 🐍 Python 指南 - Python 模式與範例
1.4 規劃你的實作
了解 API: 檢視服務的 API 文件,找出關鍵端點、驗證需求和資料模型。必要時使用網路搜尋和 WebFetch。
工具選擇: 優先考慮全面的 API 覆蓋率。列出要實作的端點,從最常見的操作開始。
階段 2:實作
2.1 設定專案結構
請參閱特定語言的專案設定指南:
- ⚡ TypeScript 指南 - 專案結構、package.json、tsconfig.json
- 🐍 Python 指南 - 模組組織、相依性
2.2 實作核心基礎設施
建立共享工具:
- 帶有驗證的 API 用戶端
- 錯誤處理輔助工具
- 回應格式化(JSON/Markdown)
- 分頁支援
2.3 實作工具
對於每個工具:
輸入結構(Schema):
- 使用 Zod (TypeScript) 或 Pydantic (Python)
- 包含限制條件和清晰的描述
- 在欄位描述中加入範例
輸出結構(Schema):
- 盡可能定義
outputSchema以處理結構化資料 - 在工具回應中使用
structuredContent(TypeScript SDK 功能) - 幫助客戶端理解和處理工具輸出
工具描述:
- 功能摘要
- 參數描述
- 回傳型別結構
實作:
- 使用 Async/await 處理 I/O 操作
- 提供帶有可操作訊息的適當錯誤處理
- 在適用的情況下支援分頁
- 使用現代 SDK 時,回傳文字內容和結構化資料
註解(Annotations):
readOnlyHint:true/falsedestructiveHint:true/falseidempotentHint:true/falseopenWorldHint:true/false
階段 3:審查與測試
3.1 程式碼品質
檢查項目:
- 無重複程式碼(DRY 原則)
- 一致的錯誤處理
- 完整的型別覆蓋
- 清晰易懂的工具描述
3.2 建置與測試
TypeScript:
- 執行
npm run build以驗證編譯 - 使用 MCP Inspector 測試:
npx @modelcontextprotocol/inspector
Python:
- 驗證語法:
python -m py_compile your_server.py - 使用 MCP Inspector 測試
有關詳細的測試方法和品質檢查清單,請參閱特定語言的指南。
階段 4:建立評估
在你的 MCP 伺服器實作完成後,建立全面的評估來測試其有效性。
載入 ✅ 評估指南 以取得完整的評估準則。
4.1 了解評估目的
使用評估來測試 LLM 是否能有效使用你的 MCP 伺服器來回答真實、複雜的問題。
4.2 建立 10 個評估問題
為了建立有效的評估,請遵循評估指南中概述的流程:
- 工具檢視:列出可用工具並了解其能力
- 內容探索:使用唯讀操作探索可用資料
- 問題生成:建立 10 個複雜、真實的問題
- 答案驗證:親自解決每個問題以驗證答案
4.3 評估要求
確保每個問題都符合以下條件:
- 獨立性:不依賴於其他問題
- 唯讀:僅需非破壞性操作
- 複雜性:需要多次工具呼叫和深度探索
- 真實性:基於人類會關心的真實使用案例
- 可驗證性:單一、明確的答案,可透過字串比對驗證
- 穩定性:答案不會隨時間改變
4.4 輸出格式
建立一個具有以下結構的 XML 檔案:
<evaluation>
<qa_pair>
<question>尋找關於以動物代號命名的 AI 模型發布的討論。其中一個模型需要一個特定的安全指定名稱,其格式為 ASL-X。以某種有斑點野生貓科動物命名的模型,其 X 數字是多少?</question>
<answer>3</answer>
</qa_pair>
<!-- 更多 qa_pairs... -->
</evaluation>
參考檔案
📚 文件庫
在開發過程中,視需要載入這些資源:
核心 MCP 文件(優先載入)
- MCP 協定:從網站地圖開始:
https://modelcontextprotocol.io/sitemap.xml,然後以.md後綴取得特定頁面 - 📋 MCP 最佳實務 - 通用 MCP 指南,包含:
- 伺服器與工具命名慣例
- 回應格式指南(JSON vs Markdown)
- 分頁最佳實務
- 傳輸方式選擇(Streamable HTTP vs stdio)
- 安全性與錯誤處理標準
SDK 文件(在階段 1/2 期間載入)
- Python SDK:從
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md取得 - TypeScript SDK:從
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md取得
特定語言的實作指南(在階段 2 期間載入)
-
🐍 Python 實作指南 - 完整的 Python/FastMCP 指南,包含:
- 伺服器初始化模式
- Pydantic 模型範例
- 使用
@mcp.tool註冊工具 - 完整的工作範例
- 品質檢查清單
-
⚡ TypeScript 實作指南 - 完整的 TypeScript 指南,包含:
- 專案結構
- Zod 結構模式
- 使用
server.registerTool註冊工具 - 完整的工作範例
- 品質檢查清單
評估指南(在階段 4 期間載入)
- ✅ 評估指南 - 完整的評估建立指南,包含:
- 問題建立指南
- 答案驗證策略
- XML 格式規範
- 範例問題與答案
- 使用提供的腳本執行評估