Community程式設計與開發github.com

mcp-builder

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

mcp-builder 是什麼？

這個技能提供了一份完整指南，用於建立高品質的 MCP (Model Context Protocol) 伺服器，讓 LLM 能透過這些伺服器與外部服務互動。它涵蓋了從深入研究與規劃、實作、測試到建立評估的完整開發流程。指南強調工具命名、錯誤訊息、輸入/輸出結構的最佳實踐，並提供 TypeScript (v1/v2 SDK) 與 Python 的具體實作指引。最終目標是打造一個能讓 LLM 有效完成真實世界任務的伺服器。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/anthropics/skills/tree/main/skills/mcp-builder

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

查看原文→瀏覽所有技能

在你喜歡的 AI 中提問

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

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

MCP 伺服器開發指南

概述

建立 MCP (Model Context Protocol) 伺服器，讓 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 程式碼，得益於其廣泛使用、靜態型別和良好的 linting 工具）
  • 傳輸方式：遠端伺服器使用可串流 HTTP，採用無狀態 JSON（比有狀態會話和串流回應更易於擴展和維護）。本機伺服器則使用 stdio。

載入框架文件：

對於 TypeScript（建議使用）：

TypeScript SDK 有兩個主要版本。在編寫程式碼之前請先選擇一個：

  • v2 (@modelcontextprotocol/server)：目前的穩定版本。新伺服器請使用此版本。
  • v1 (@modelcontextprotocol/sdk)：僅接收錯誤和安全修復。僅在專案的 package.json 已依賴 @modelcontextprotocol/sdk 時使用，或使用 npx @modelcontextprotocol/codemod@latest v1-to-v2 . 遷移該專案。

如果專案已在使用 v1，請用一兩句話告知使用者 v2 (@modelcontextprotocol/server) 是目前的穩定版本，v1 僅接收錯誤和安全修復，並且 npx @modelcontextprotocol/codemod@latest v1-to-v2 . 可用於遷移專案。然後除非使用者要求遷移，否則繼續使用 v1。

請勿在同一個專案中混合使用兩者：v1 的程式碼範例（從 @modelcontextprotocol/sdk/... 導入）不適用於 v2。

  • TypeScript SDK (v2)：使用 WebFetch 載入 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md；完整文件索引為 https://ts.sdk.modelcontextprotocol.io/v2/llms.txt
  • ⚡ TypeScript 指南 (v2) - TypeScript 模式與範例
  • 僅限 v1 專案：https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.md 和 TypeScript 指南 (v1)

對於 Python：

  • Python SDK：使用 WebFetch 載入 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • 🐍 Python 指南 - Python 模式與範例

1.4 規劃你的實作

了解 API： 審閱服務的 API 文件，以識別關鍵端點、認證要求和資料模型。必要時使用網路搜尋和 WebFetch。

工具選擇： 優先考慮全面的 API 覆蓋率。列出要實作的端點，從最常見的操作開始。

第二階段：實作

2.1 設定專案結構

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

2.2 實作核心基礎設施

建立共用工具：

  • 帶有認證的 API 客戶端
  • 錯誤處理輔助函式
  • 回應格式化（JSON/Markdown）
  • 分頁支援

2.3 實作工具

對於每個工具：

輸入 Schema：

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

輸出 Schema：

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

工具描述：

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

實作：

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

註釋：

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

第三階段：審查與測試

3.1 程式碼品質

檢查以下幾點：

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

3.2 建置與測試

TypeScript：

  • 執行 npm run build 以驗證編譯
  • v2 專案：針對建置好的伺服器執行 v2 指南 中的自我檢查腳本
  • 使用 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 vs Markdown）
    • 分頁最佳實踐
    • 傳輸選擇（可串流 HTTP vs stdio）
    • 安全性和錯誤處理標準

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

  • Python SDK：從 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md 取得
  • TypeScript SDK (v2)：從 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md 取得；完整文件索引在 https://ts.sdk.modelcontextprotocol.io/v2/llms.txt
  • TypeScript SDK (v1，僅限現有 v1 專案)：從 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.md 取得

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

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

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

  • ⚡ TypeScript 實作指南 (SDK v2) - 針對 @modelcontextprotocol/server 的完整 TypeScript 指南，包含：

    • 專案設定和伺服器工廠
    • 工具設計：Zod 4 schemas、輸出格式、分頁、錯誤處理
    • 一個提供 stdio 和可串流 HTTP 服務的完整範例，並包含 Bearer 認證
    • 資源、提示和通知
    • 驗證建置伺服器的自我檢查腳本
    • 進階功能的 SDK 範例連結
    • v1 到 v2 的轉換表、遷移步驟和品質檢查清單

  • ⚡ TypeScript 實作指南 (SDK v1) - 針對現有 @modelcontextprotocol/sdk 專案的同等指南

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

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

Individual skills in this repo

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

academy-guide

Stop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.

algorithmic-art

Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists

anthropics/template-skill

Replace with description of the skill and when Claude should use it.

brand-guidelines

Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.

canvas-design

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists

claude-api

|-

discernment-nudge

After you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format.

doc-coauthoring

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

docx

Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of

frontend-design

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

internal-comms

A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

pdf

Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.

pptx

Use this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions \

skill-creator

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill

slack-gif-creator

Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like

theme-factory

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

web-artifacts-builder

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

xlsx

Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like \

相關技能

steipete/bluebubbles

Send and manage iMessages via BlueBubbles, including attachments, tapbacks, edits, replies, and groups.

community

steipete/eightctl

Control Eight Sleep pods (status, temperature, alarms, schedules).

community

steipete/blucli

BluOS CLI (blu) for discovery, playback, grouping, and volume.

community

steipete/bear-notes

Create, search, and manage Bear notes via grizzly CLI.

community

steipete/camsnap

Capture frames or clips from RTSP/ONVIF cameras.

community

steipete/gifgrep

Search GIF providers with CLI/TUI, download results, and extract stills/sheets.

community
← More 程式設計與開發 skills