Communitygithub.com

ASoudy/AGS

建立高品質 MCP (Model Context Protocol) 伺服器之指南,讓大型語言模型能透過精心設計的工具與外部服務互動。適用於建置 MCP 伺服器以整合外部 API 或服務時,無論是使用 Python (FastMCP) 或 Node/TypeScript (MCP SDK)。

AGS 是什麼?

此技能(ASoudy/AGS)作為一份詳盡的開發指南,引導使用者建立高品質的 MCP(Model Context Protocol)伺服器。其核心目標是讓大型語言模型能夠透過設計良好的工具與外部服務順暢互動。指南涵蓋了從深度研究與規劃、實際實作、審查測試,到最終建立評估機制的完整四個階段。此指南支援 TypeScript 與 Python 兩種語言,並推薦使用 TypeScript 以獲得最佳開發體驗。它不僅強調 API 覆蓋率與工作流程工具的平衡,也提供了工具命名、錯誤訊息、以及內容管理等最佳實務。透過此技能,開發者能產出結構嚴謹、易於被 LLM 發現與使用的 MCP 工具,確保 LLM 能有效完成真實世界的複雜任務。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/mcp-builder

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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。

載入框架文件:

對於 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 設定專案結構

請參閱特定語言的專案設定指南:

2.2 實作核心基礎設施

建立共享工具:

  • 帶有驗證的 API 用戶端
  • 錯誤處理輔助工具
  • 回應格式化(JSON/Markdown)
  • 分頁支援

2.3 實作工具

對於每個工具:

輸入結構(Schema):

  • 使用 Zod (TypeScript) 或 Pydantic (Python)
  • 包含限制條件和清晰的描述
  • 在欄位描述中加入範例

輸出結構(Schema):

  • 盡可能定義 outputSchema 以處理結構化資料
  • 在工具回應中使用 structuredContent(TypeScript SDK 功能)
  • 幫助客戶端理解和處理工具輸出

工具描述:

  • 功能摘要
  • 參數描述
  • 回傳型別結構

實作:

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

註解(Annotations):

  • 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)
    • 分頁最佳實務
    • 傳輸方式選擇(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 結構模式
    • 使用 server.registerTool 註冊工具
    • 完整的工作範例
    • 品質檢查清單

評估指南(在階段 4 期間載入)

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

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

相關技能