Communitygithub.com

MCP 服务器开发指南

创建高质量 MCP(模型上下文协议)服务器的指南,使 LLM 能够通过设计精良的工具与外部服务交互。在构建 MCP 服务器以集成外部 API 或服务时使用,支持 Python (FastMCP) 或 Node/TypeScript (MCP SDK)。

MCP 服务器开发指南 是什么?

该技能提供了一个全面的指南,用于创建高质量的 MCP(模型上下文协议)服务器,使 LLM 能够通过精心设计的工具与外部服务交互。它涵盖了一个四阶段工作流程:深度研究与规划、实现、审查与测试,以及创建评估。该指南强调 TypeScript(由于 SDK 支持优秀、兼容性好,且 AI 模型擅长生成 TypeScript 代码),但也提供了 Python 选项。关键原则包括平衡 API 覆盖率和专用工作流工具、清晰的工具命名规范、上下文管理、可操作错误消息,以及使用 Zod(TypeScript)或 Pydantic(Python)进行输入验证。该技能鼓励使用“Streamable HTTP”传输进行远程服务器部署,使用 stdio 进行本地部署。它包含详细参考文件,如最佳实践、语言特定实现指南和评估创建标准。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/David-Li0406/meta-skill-evloving/tree/HEAD/AgentSkillOS/data/skill_seeds/mcp-builder

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

MCP 服务器开发指南 是做什么的?

概述

创建 MCP(模型上下文协议)服务器,使 LLM 能够通过设计精良的工具与外部服务交互。MCP 服务器的质量取决于它使 LLM 完成实际任务的能力。


流程

🚀 高级工作流

创建高质量的 MCP 服务器包括四个主要阶段:

第一阶段:深度研究与规划

1.1 理解现代 MCP 设计

API 覆盖与工作流工具: 在全面的 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:使用 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 设置项目结构

有关项目设置,请参阅特定语言指南:

2.2 实现核心基础设施

创建共享实用工具:

  • 包含身份验证的 API 客户端
  • 错误处理辅助函数
  • 响应格式化(JSON/Markdown)
  • 分页支持

2.3 实现工具

针对每个工具:

输入模式:

  • 使用 Zod(TypeScript)或 Pydantic(Python)
  • 包含约束和清晰的描述
  • 在字段描述中添加示例

输出模式:

  • 尽可能定义 outputSchema 以获取结构化数据
  • 在工具响应中使用 structuredContent(TypeScript SDK 功能)
  • 帮助客户端理解并处理工具输出

工具描述:

  • 功能简洁摘要
  • 参数描述
  • 返回类型模式

实现:

  • 对 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 验证编译
  • 使用 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:从 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md 获取

特定语言实现指南(在第二阶段加载)

  • 🐍 Python 实现指南 - 完整的 Python/FastMCP 指南,包括:

    • 服务器初始化模式
    • Pydantic 模型示例
    • 使用 @mcp.tool 注册工具
    • 完整的可工作示例
    • 质量检查清单
  • ⚡ TypeScript 实现指南 - 完整的 TypeScript 指南,包括:

    • 项目结构
    • Zod 模式模式
    • 使用 server.registerTool 注册工具
    • 完整的可工作示例
    • 质量检查清单

评估指南(在第四阶段加载)

  • ✅ 评估指南 - 完整的评估创建指南,包括:
    • 问题创建指导
    • 答案验证策略
    • XML 格式规范
    • 示例问题和答案
    • 使用提供的脚本运行评估

Individual skills in this repo

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

David-Li0406/meta-skill-evloving

Browser automation with persistent page state. Use when users ask to navigate websites, fill forms, take screenshots, extract web data, test web apps, or automate browser workflows. Trigger phrases include "go to [url]", "click on", "fill out the form", "take a screenshot", "scrape", "automate", "test the website", "log into", or any browser interaction request.

David-Li0406/meta-skill-evloving

Create technical diagrams using Mermaid syntax for architecture, sequences, ERDs, flowcharts, and state machines. Use for visualizing system design, data flows, and processes. Triggers: diagram, mermaid, architecture diagram, sequence diagram, flowchart, ERD, entity relationship, state diagram, C4 model, component diagram, visualize, draw.

David-Li0406/meta-skill-evloving

Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks

David-Li0406/meta-skill-evloving

Complete color manipulation and green screen effects system. PROACTIVELY activate for: (1) Green screen/chromakey removal, (2) Color grading with LUTs, (3) Color correction (levels, curves, white balance), (4) Colorkey/color removal effects, (5) Hue/saturation manipulation, (6) Color space conversions (BT.709, BT.2020, HDR), (7) Color isolation effects, (8) Teal and orange look, (9) Vintage/film looks, (10) Color keying for transparency. Provides: chromakey and colorkey filters, LUT application (lut3d), curves and levels adjustment, color balance, selective color manipulation, color space handling, HDR tone mapping, professional color grading chains.

David-Li0406/meta-skill-evloving

Convert files and office documents to Markdown. Supports PDF, DOCX, PPTX, XLSX, images (with OCR), audio (with transcription), HTML, CSV, JSON, XML, ZIP, YouTube URLs, EPubs and more.

David-Li0406/meta-skill-evloving

Build with OpenAI's stateless APIs - Chat Completions (GPT-5, GPT-4o), Embeddings, Images (DALL-E 3), Audio (Whisper + TTS), and Moderation. Includes Node.js SDK and fetch-based approaches for Cloudflare Workers. Use when: implementing chat completions with GPT-5/GPT-4o, streaming responses with SSE, using function calling/tools, creating structured outputs with JSON schemas, generating embeddings for RAG (text-embedding-3-small/large), generating images with DALL-E 3, editing images with GPT-Image-1, transcribing audio with Whisper, synthesizing speech with TTS (11 voices), moderating content (11 safety categories), or troubleshooting rate limits (429), invalid API keys (401), function calling failures, streaming parse errors, embeddings dimension mismatches, or token limit exceeded.

David-Li0406/meta-skill-evloving

Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale.

David-Li0406/meta-skill-evloving

Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks

David-Li0406/meta-skill-evloving

Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, .tsv, etc) for: (1) Creating new spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modify existing spreadsheets while preserving formulas, (4) Data analysis and visualization in spreadsheets, or (5) Recalculating formulas

David-Li0406/meta-skill-evloving

Download YouTube videos with customizable quality and format options. Use this skill when the user asks to download, save, or grab YouTube videos. Supports various quality settings (best, 1080p, 720p, 480p, 360p), multiple formats (mp4, webm, mkv), and audio-only downloads as MP3.

David-Li0406/meta-skill-evloving

Best practices for Remotion - Video creation in React

David-Li0406/meta-skill-evloving

Provides bidirectional translation (Chinese/English), grammar checking, and sentence polishing. Supports specific tense constraints, context-aware tone adjustment, and natural expression optimization. Outputs direct text without formatting.

David-Li0406/meta-skill-evloving

指导如何通过自定义注解(如@Unicom)标识Dubbo接口,利用BeanDefinitionRegistryPostProcessor在启动时扫描并动态注册ReferenceBean,实现RPC调用的封装。

David-Li0406/meta-skill-evloving

生成Python脚本,利用FFmpeg将图片序列按3x3布局合并,或将合并图拆分。要求使用subprocess模块执行命令,并支持用户交互式输入路径。

David-Li0406/meta-skill-evloving

SOP for extracting and analyzing promotional activity details, handling time formatting, location mapping, payment logic, and step-by-step process validation.

David-Li0406/meta-skill-evloving

Specializes in creating TikTok short video scripts using an anthropomorphic 'Chef' perspective to explain wildlife food chains and survival environments, utilizing real field footage.

David-Li0406/meta-skill-evloving

针对TikTok平台,以拟人化视角(如动物作为厨师)创作系列短视频脚本。重点介绍野生动物、食物链及生态环境,要求使用野外实拍素材,风格幽默且具有教育意义。

David-Li0406/meta-skill-evloving

Generates KWL (Know, Want to know, Learned) charts for educational videos, specifically BrainPOP, using simple 7th-grade language and short, concise bullet points.

David-Li0406/meta-skill-evloving

Develops DAX measures to calculate promo and regular volumes and generates a calculated table of dates excluding continuous promo date ranges, handling multiple periods and nulls.

David-Li0406/meta-skill-evloving

Tracks complex, multi-session work using the Beads issue tracker and dependency graphs, and provides persistent memory that survives conversation compaction. Use when work spans multiple sessions, has complex dependencies, or needs persistent context across compaction cycles. Trigger with phrases like "create task for", "what's ready to work on", "show task", "track this work", "what's blocking", or "update status".

相关技能