mcp-builder

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）。

需要檢視的關鍵頁面：

• 規格概述與架構
• 傳輸機制（可串流 HTTP、stdio）
• 工具、資源和提示的定義

1.3 研讀框架文件

建議技術棧：

• 語言：TypeScript（高品質 SDK 支援，且在許多執行環境中相容性佳，例如 MCPB。此外，AI 模型擅長生成 TypeScript 程式碼，受益於其廣泛使用、靜態型別和良好的 lint 工具）
• 傳輸：遠端伺服器使用可串流 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

實作：

• 非同步/等待 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_pair... -->
</evaluation>

---

參考檔案

📚 文件庫

在開發過程中視需要載入這些資源：

核心 MCP 文件（優先載入）

• MCP 協定：從網站地圖 https://modelcontextprotocol.io/sitemap.xml 開始，然後使用 .md 後綴取得特定頁面
• 📋 MCP 最佳實踐 - 通用 MCP 指南，包括：
  • 伺服器和工具命名慣例
  • 回應格式指南（JSON vs Markdown）
  • 分頁最佳實踐
  • 傳輸選擇（可串流 HTTP vs 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 格式規格
  • 範例問題與答案
  • 使用提供的腳本執行評測