MCP 伺服器開發指南
概述
建立 MCP（模型上下文協定）伺服器，讓大型語言模型能透過設計良好的工具與外部服務互動。MCP 伺服器的品質，取決於它能多好地協助大型語言模型完成真實世界的任務。
流程
🚀 高階工作流程
建立高品質的 MCP 伺服器包含四個主要階段：
階段 1：深入研究與規劃
1.1 了解現代 MCP 設計
API 覆蓋率 vs. 工作流程工具： 在全面的 API 端點覆蓋率與專門的工作流程工具之間取得平衡。工作流程工具在特定任務上可能更方便，而全面的 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 程式碼，受益於其廣泛使用、靜態型別和良好的 lint 工具）
- 傳輸方式：對遠端伺服器使用 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 實作工具
針對每個工具：
輸入結構描述：
- 使用 Zod（TypeScript）或 Pydantic（Python）
- 包含約束條件和清晰描述
- 在欄位描述中加入範例
輸出結構描述：
- 盡可能定義
outputSchema以取得結構化資料 - 在工具回應中使用
structuredContent（TypeScript SDK 功能） - 幫助客戶端理解並處理工具輸出
工具描述：
- 功能簡潔摘要
- 參數描述
- 回傳型別結構描述
實作：
- 對 I/O 操作使用 async/await
- 使用可操作的訊息進行適當的錯誤處理
- 在適用時支援分頁
- 使用現代 SDK 時，同時回傳文字內容和結構化資料
註解：
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 了解評估目的
使用評估來測試大型語言模型是否能有效地使用你的 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 格式規範
- 範例問題與答案
- 使用提供的腳本執行評估