Communitygithub.com

ASoudy/AGS

一份关于如何构建高质量 MCP(模型上下文协议)服务器的指南,使 LLM 能够通过精心设计的工具与外部服务交互。适用于构建 MCP 服务器以集成外部 API 或服务时,无论使用 Python (FastMCP) 还是 Node/TypeScript (MCP SDK)。

AGS 是什么?

该技能是一份全面的指南,用于开发高质量的 MCP(模型上下文协议)服务器。这些服务器使大型语言模型 (LLM) 能够通过定义良好的工具与外部 API 和服务进行交互。指南涵盖了完整的开发流程,包括四个主要阶段:深度研究和规划、实施、审查与测试,以及创建评估。它强调了现代 MCP 设计原则,如平衡 API 覆盖范围与工作流工具、清晰的工具命名、有效的上下文管理和可操作性的错误信息。技术栈方面,推荐使用 TypeScript(因其高质量的 SDK、良好的 AI 生成兼容性和执行环境支持)或 Python。指南提供了与平台相关的实施模式,用于设置项目、实现核心基础设施和注册工具,并包含了用于检查和测试 MCP 服务器的特定客户端(如 MCP Inspector)的说明。 该技能通过在 SKILL.md 文件中引用 Markdown 格式的外部文档(包括 MCP 最佳实践、TypeScript 和 Python 实施指南,以及评估指南)来运行。它指导 AI 代理使用网络获取 (`WebFetch`) 来加载这些资源,并根据当前阶段加载相应的框架和协议文档。本质上,它为 AI 代理提供了一个结构化的、基于协议的蓝图,用于构建、迭代和验证 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(模型上下文协议)服务器,使 LLM 能够通过精心设计的工具与外部服务交互。MCP 服务器的质量取决于它帮助 LLM 完成实际任务的能力。


流程

🚀 高级工作流

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

阶段 1:深入调研与规划

1.1 理解现代 MCP 设计

API 覆盖 vs. 工作流工具: 在全面的 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 代码,得益于其广泛使用、静态类型和优秀的 lint 工具)
  • 传输:远程服务器使用可流式 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 实现工具

对于每个工具:

输入模式:

  • 使用 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:审查与测试

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 格式规范
    • 示例问题和答案
    • 使用提供的脚本运行评估

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.

相关技能