MCP 伺服器開發指南

MCP 伺服器開發指南 是做什麼的？

概覽

建立 MCP（模型上下文協定）伺服器，讓 LLM 能透過精心設計的工具與外部服務互動。MCP 伺服器的品質取決於它能多好地幫助 LLM 完成真實世界的任務。

---

流程

🚀 高層次工作流程

建立高品質的 MCP 伺服器包含四個主要階段：

第一階段：深度研究與規劃

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.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

實作：

• 使用 async/await 進行 I/O 操作
• 使用可操作的訊息進行適當的錯誤處理
• 在適用的情況下支援分頁
• 使用現代 SDK 時，同時回傳文字內容和結構化資料

註解：

• readOnlyHint：true/false
• destructiveHint：true/false
• idempotentHint：true/false
• openWorldHint：true/false

---

第三階段：審查與測試

3.1 程式碼品質

審查以下項目：

• 無重複程式碼（DRY 原則）
• 一致的錯誤處理
• 完整的型別覆蓋率
• 清晰的工具描述

3.2 建置與測試

TypeScript：

• 執行 npm run build 以驗證編譯
• 使用 MCP Inspector 測試：npx @modelcontextprotocol/inspector

Python：

• 驗證語法：python -m py_compile your_server.py
• 使用 MCP Inspector 測試

請參閱特定語言的指南以取得詳細的測試方法和品質檢查清單。

---

第四階段：建立評估

在實作你的 MCP 伺服器之後，建立全面的評估以測試其有效性。

載入 ✅ 評估指南 以取得完整的評估指南。

4.1 了解評估目的

使用評估來測試 LLM 是否能有效地使用你的 MCP 伺服器來回答真實、複雜的問題。

4.2 建立 10 個評估問題

為建立有效的評估，請遵循評估指南中概述的流程：

1. 工具檢查：列出可用的工具並了解其功能
2. 內容探索：使用唯讀操作探索可用的資料
3. 問題生成：建立 10 個複雜、真實的問題
4. 答案驗證：親自解決每個問題以驗證答案

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 與 Markdown）
  • 分頁最佳實踐
  • 傳輸選擇（Streamable HTTP 與 stdio）
  • 安全性和錯誤處理標準

SDK 文件（在第一/二階段載入）

• Python SDK：從 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md 取得
• TypeScript SDK：從 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md 取得

特定語言的實作指南（在第二階段載入）

• 🐍 Python 實作指南 - 完整的 Python/FastMCP 指南，包含：

  • 伺服器初始化模式
  • Pydantic 模型範例
  • 使用 @mcp.tool 註冊工具
  • 完整的運作範例
  • 品質檢查清單

• ⚡ TypeScript 實作指南 - 完整的 TypeScript 指南，包含：

  • 專案結構
  • Zod schema 模式
  • 使用 server.registerTool 註冊工具
  • 完整的運作範例
  • 品質檢查清單

評估指南（在第四階段載入）

• ✅ 評估指南 - 完整的評估建立指南，包含：
  • 問題建立指南
  • 答案驗證策略
  • XML 格式規格
  • 範例問題與答案
  • 使用提供的腳本執行評估