Tai-ch0802 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 功能) - 幫助客戶端理解與處理工具輸出
工具描述:
- 功能的簡潔摘要
- 參數描述
- 返回型別 schema
實作:
- 針對 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 了解評估目的
使用評估來測試 LLM 是否能有效使用您的 MCP 伺服器回答真實且複雜的問題。
4.2 建立 10 個評估問題
要建立有效的評估，請遵循評估指南中列出的流程：
- 工具檢查: 列出可用工具並了解其能力
- 內容探索: 使用 READ-ONLY (唯讀) 操作探索可用資料
- 問題生成: 建立 10 個複雜、真實的問題
- 答案驗證: 自行解決每個問題以驗證答案
4.3 評估要求
確保每個問題符合：
- 獨立性: 不依賴其他問題
- 唯讀: 只需要非破壞性操作
- 複雜性: 需要多次呼叫工具和深度探索
- 真實性: 基於人類關心的真實用例
- 可驗證性: 單一、明確的答案，可透過字串比對進行驗證
- 穩定性: 答案不會隨時間改變
4.4 輸出格式
建立具有此結構的 XML 檔案：
<evaluation>
<qa_pair>
<question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
<answer>3</answer>
</qa_pair>
<!-- 更多 qa_pairs... -->
</evaluation>
參考檔案
📚 文件庫
開發期間視需要載入這些資源：
核心 MCP 文件 (優先載入)
- MCP Protocol: 從網站地圖
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 schema 模式
- 使用
server.registerTool註冊工具 - 完整可用範例
- 品質檢查清單
評估指南 (階段 4 載入)
- ✅ 評估指南 - 完整的評估建立指南，包含：
- 問題建立準則
- 答案驗證策略
- XML 格式規格
- 問題與答案範例
- 使用提供的腳本執行評估