aiskillstore/marketplace

MCP 伺服器開發指南

概覽

建立 MCP (模型上下文協定) 伺服器，讓 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)。

需要檢閱的關鍵頁面：

• 規範總覽與架構
• 傳輸機制 (可串流 HTTP、stdio)
• 工具、資源與提示定義

1.3 研讀框架文件

建議的技術棧：

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

工具描述：

• 功能簡潔摘要
• 參數描述
• 返回型別模式

實作：

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

註釋：

• readOnlyHint：true/false
• destructiveHint：true/false
• idempotentHint：true/false
• openWorldHint：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 個評估問題

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

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 vs Markdown)
  • 分頁最佳實踐
  • 傳輸選擇 (可串流 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 格式規格
  • 範例問題與答案
  • 使用提供的腳本執行評估