mcp-builder

MCP 伺服器開發指南

概述

若要建立高品質的 MCP（Model Context Protocol）伺服器，讓 LLM 能有效與外部服務互動，請使用此技能。MCP 伺服器提供工具，讓 LLM 能存取外部服務與 API。MCP 伺服器的品質取決於它能否讓 LLM 利用所提供的工具完成實際任務。

---

流程

🚀 高層級工作流程

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

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

1.1 理解以代理為中心的設計原則

在開始實作之前，請先檢閱這些原則，了解如何為 AI 代理設計工具：

為工作流程而建，而非僅為 API 端點：

• 不要只是包裝現有的 API 端點，而是建立經過深思熟慮、高影響力的工作流程工具
• 合併相關操作（例如 schedule_event 同時檢查可用性並建立事件）
• 專注於能讓代理完成完整任務的工具，而非單一的 API 呼叫
• 思考代理實際上需要完成哪些工作流程

針對有限的上下文進行最佳化：

• 代理的上下文視窗有限，請善用每個 token
• 回傳高訊號的資訊，而非詳盡的資料傾印
• 提供「簡潔」與「詳細」的回應格式選項
• 預設使用人類可讀的識別碼而非技術代碼（名稱優於 ID）
• 將代理的上下文預算視為稀缺資源

設計可操作化的錯誤訊息：

• 錯誤訊息應引導代理朝向正確的使用模式
• 建議具體的下一步：例如「嘗試使用 filter='active_only' 來減少結果」
• 讓錯誤具有教育意義，而不僅是診斷用途
• 透過清晰的回饋幫助代理學習正確的工具使用方式

遵循自然的任務劃分：

• 工具名稱應反映人類思考任務的方式
• 使用一致的前綴來分組相關工具，以利探索
• 圍繞自然的工作流程設計工具，而非僅根據 API 結構

採用評估驅動開發：

• 及早建立真實的評估情境
• 讓代理的回饋驅動工具改進
• 快速原型設計，並根據實際代理效能迭代

1.3 研讀 MCP 協定文件

取得最新的 MCP 協定文件：

使用 WebFetch 載入：https://modelcontextprotocol.io/llms-full.txt

這份完整文件包含完整的 MCP 規格與指南。

1.4 研讀框架文件

載入並閱讀以下參考檔案：

• MCP 最佳實務：📋 檢視最佳實務 - 所有 MCP 伺服器的核心指南

若為 Python 實作，也請載入：

• Python SDK 文件：使用 WebFetch 載入 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• 🐍 Python 實作指南 - Python 專屬的最佳實務與範例

若為 Node/TypeScript 實作，也請載入：

• TypeScript SDK 文件：使用 WebFetch 載入 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• ⚡ TypeScript 實作指南 - Node/TypeScript 專屬的最佳實務與範例

1.5 詳盡研讀 API 文件

若要整合某項服務，請閱讀所有可用的 API 文件：

• 官方 API 參考文件
• 驗證與授權需求
• 速率限制與分頁模式
• 錯誤回應與狀態碼
• 可用的端點及其參數
• 資料模型與結構描述

為收集完整資訊，請視需要使用網路搜尋與 WebFetch 工具。

1.6 建立全面的實作計畫

根據你的研究，建立包含以下項目的詳細計畫：

工具選擇：

• 列出最有價值的端點/操作來實作
• 優先實作能啟用最常見且最重要使用案例的工具
• 考慮哪些工具能協同運作以啟用複雜的工作流程

共用工具與輔助函式：

• 識別常見的 API 請求模式
• 規劃分頁輔助函式
• 設計篩選與格式化工具
• 規劃錯誤處理策略

輸入/輸出設計：

• 定義輸入驗證模型（Python 用 Pydantic，TypeScript 用 Zod）
• 設計一致的回應格式（例如 JSON 或 Markdown），以及可設定的詳細程度（例如詳細或簡潔）
• 規劃大規模使用情境（數千名使用者/資源）
• 實作字元限制與截斷策略（例如 25,000 個 token）

錯誤處理策略：

• 規劃優雅的失敗模式
• 設計清晰、可操作、對 LLM 友善的自然語言錯誤訊息，並提示後續行動
• 考慮速率限制與逾時情境
• 處理驗證與授權錯誤

---

第二階段：實作

現在你已有全面的計畫，請依照語言專屬的最佳實務開始實作。

2.1 設定專案結構

若使用 Python：

• 建立單一的 .py 檔案，若較複雜則組織成模組（請參閱 🐍 Python 指南）
• 使用 MCP Python SDK 進行工具註冊
• 定義 Pydantic 模型進行輸入驗證

若使用 Node/TypeScript：

• 建立適當的專案結構（請參閱 ⚡ TypeScript 指南）
• 設定 package.json 與 tsconfig.json
• 使用 MCP TypeScript SDK
• 定義 Zod 結構描述進行輸入驗證

2.2 先實作核心基礎設施

開始實作時，請先建立共用工具，再實作工具：

• API 請求輔助函式
• 錯誤處理工具
• 回應格式化函式（JSON 與 Markdown）
• 分頁輔助函式
• 驗證/權杖管理

2.3 系統性地實作工具

針對計畫中的每個工具：

定義輸入結構描述：

• 使用 Pydantic（Python）或 Zod（TypeScript）進行驗證
• 包含適當的限制（最小/最大長度、正規表示式模式、最小/最大值、範圍）
• 提供清晰、具描述性的欄位說明
• 在欄位說明中包含多樣的範例

撰寫完整的文件字串/描述：

• 一行摘要說明工具功能
• 詳細說明用途與功能
• 明確的參數型別與範例
• 完整的回傳型別結構描述
• 使用範例（何時使用、何時不使用）
• 錯誤處理文件，說明在特定錯誤下如何繼續

實作工具邏輯：

• 使用共用工具避免程式碼重複
• 所有 I/O 操作遵循 async/await 模式
• 實作適當的錯誤處理
• 支援多種回應格式（JSON 與 Markdown）
• 遵守分頁參數
• 檢查字元限制並適當截斷

加入工具註解：

• readOnlyHint：true（唯讀操作）
• destructiveHint：false（非破壞性操作）
• idempotentHint：true（重複呼叫效果相同）
• openWorldHint：true（與外部系統互動）

2.4 遵循語言專屬的最佳實務

此時，請載入適當的語言指南：

若使用 Python：載入 🐍 Python 實作指南 並確保以下事項：

• 使用 MCP Python SDK 並正確註冊工具
• 使用 Pydantic v2 模型搭配 model_config
• 全面使用型別提示
• 所有 I/O 操作使用 async/await
• 正確的匯入組織
• 模組層級常數（CHARACTER_LIMIT、API_BASE_URL）

若使用 Node/TypeScript：載入 ⚡ TypeScript 實作指南 並確保以下事項：

• 正確使用 server.registerTool
• Zod 結構描述搭配 .strict()
• 啟用 TypeScript 嚴格模式
• 不使用 any 型別，使用適當型別
• 明確的 Promise<T> 回傳型別
• 設定建置流程（npm run build）

---

第三階段：審查與改進

初步實作完成後：

3.1 程式碼品質審查

為確保品質，請審查程式碼是否：

• DRY 原則：工具之間無重複程式碼
• 可組合性：共用邏輯已提取為函式
• 一致性：類似操作回傳類似格式
• 錯誤處理：所有外部呼叫皆有錯誤處理
• 型別安全：完整的型別涵蓋（Python 型別提示、TypeScript 型別）
• 文件：每個工具都有完整的文件字串/描述

3.2 測試與建置

重要： MCP 伺服器是長時間執行的程序，會透過 stdio/stdin 或 sse/http 等待請求。直接在主程序中執行（例如 python server.py 或 node dist/index.js）會導致程序無限期掛起。

安全測試伺服器的方式：

• 使用評估框架（請參閱第四階段）— 建議方式
• 在 tmux 中執行伺服器，使其獨立於主程序之外
• 測試時使用逾時：timeout 5s python server.py

若使用 Python：

• 驗證 Python 語法：python -m py_compile your_server.py
• 檢視檔案確認匯入正確
• 手動測試：在 tmux 中執行伺服器，然後在主程序中使用評估框架測試
• 或直接使用評估框架（它會為 stdio 傳輸管理伺服器）

若使用 Node/TypeScript：

• 執行 npm run build 並確認無錯誤
• 確認 dist/index.js 已建立
• 手動測試：在 tmux 中執行伺服器，然後在主程序中使用評估框架測試
• 或直接使用評估框架（它會為 stdio 傳輸管理伺服器）

3.3 使用品質檢查清單

為驗證實作品質，請從語言專屬指南中載入適當的檢查清單：

• Python：請參閱 🐍 Python 指南 中的「品質檢查清單」
• Node/TypeScript：請參閱 ⚡ TypeScript 指南 中的「品質檢查清單」

---

第四階段：建立評估

實作 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/llms-full.txt 取得 - 完整的 MCP 規格
• 📋 MCP 最佳實務 - 通用的 MCP 指南，包含：
  • 伺服器與工具命名慣例
  • 回應格式指南（JSON 與 Markdown）
  • 分頁最佳實務
  • 字元限制與截斷策略
  • 工具開發指南
  • 安全性與錯誤處理標準

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 結構描述模式
  • 使用 server.registerTool 註冊工具
  • 完整的可運作範例
  • 品質檢查清單

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

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