Logoclaudeskills文档

MCP 构建指南

Agent Skill 手册：用于构建 Model Context Protocol 服务器、定义工具，并编写 Claude 可依赖的评测套件。

来源：基于 anthropics/skills（MIT）内容改写。

概览

如需创建高质量的 MCP（Model Context Protocol）服务器，使 LLM 能够高效调用外部服务，请使用本技能。MCP 服务器通过工具（tools）为 LLM 援引外部服务与 API。衡量 MCP 服务器质量的关键在于：它是否真正帮助 LLM 利用这些工具完成真实世界的任务。

工作流程

高层流程概览

打造高质量 MCP 服务器大致分四个阶段：

阶段 1：深入调研与规划

1.1 理解以 Agent 为中心的设计原则

在动手实现前，请先学习以下原则，了解如何为 AI Agent 设计工具：

围绕工作流而非简单 API 封装：

  • 不要只做简单的 API 包装；设计高价值的工作流型工具
  • 将相关操作整合，例如一个 schedule_event 工具可同时查询空闲时间并创建日程
  • 聚焦“完成任务”的工具，而不仅是单一 API 调用
  • 思考 Agent 实际要达成的场景与目标

针对有限上下文进行优化：

  • Agent 的上下文窗口有限，每个 token 都要物尽其用
  • 返回高信号信息，避免冗长的数据 dump
  • 提供“精简/详细”两种响应格式选项
  • 优先使用人类可读的标识（名称而非 ID）
  • 把 Agent 的上下文预算视作稀缺资源

设计可执行的错误信息：

  • 错误提示应指导 Agent 正确使用工具
  • 给出明确下一步建议：“试试 filter='active_only' 以缩小结果”
  • 让错误信息具有教育意义，而不是简单报错
  • 通过清晰反馈帮助 Agent 学会正确用法

遵循自然任务拆分：

  • 工具名称应贴合人类对任务的理解方式
  • 相关工具可使用前缀分组，提高可发现性
  • 工具设计应围绕自然工作流，而非 API 结构本身

以评测驱动开发：

  • 早期就创建真实的评测场景
  • 让 Agent 的反馈驱动工具迭代
  • 快速原型，基于实际表现持续改进

1.3 熟读 MCP 协议文档

获取最新 MCP 协议说明：

使用 WebFetch 加载：https://modelcontextprotocol.io/llms-full.txt

该文档包含完整的 MCP 规范与指导。

1.4 研读框架文档

加载并阅读以下参考文件：

若使用 Python 实现，还需阅读：

  • Python SDK 文档：WebFetch 加载 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • Python 实现指南 —— Python 版最佳实践与示例

若使用 Node/TypeScript，实现需阅读：

  • TypeScript SDK 文档：WebFetch 加载 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
  • TypeScript 实现指南 —— 针对 Node/TS 的最佳实践与示例

1.5 彻底研读待接入服务的 API 文档

集成某项服务前，请完整阅读所有可用 API 文档：

  • 官方 API 参考
  • 认证与授权要求
  • 速率限制与分页模式
  • 错误响应与状态码
  • 可用端点及其参数
  • 数据模型与模式定义

必要时可结合网页搜索与 WebFetch 工具，全面收集信息。

1.6 制定详细的实现计划

基于调研，编写详尽计划，需涵盖以下内容：

工具选择：

  • 列出最有价值的端点 / 操作
  • 优先实现常见且重要的用例
  • 考虑工具之间如何组合实现复杂工作流

通用工具与助手：

  • 找出典型的 API 请求模式
  • 规划分页辅助函数
  • 设计过滤与格式化工具
  • 确定统一的错误处理策略

输入 / 输出设计：

  • 定义输入校验模型（Python 用 Pydantic，TypeScript 用 Zod）
  • 设计一致的返回格式（JSON/Markdown），并支持“详细 / 精简”等可配置层级
  • 考虑大规模使用场景（成千上万用户 / 资源）
  • 规划字符长度与截断策略（如上限 25,000 tokens）

错误处理策略：

  • 设计优雅的失败模式
  • 输出清晰、可执行且易懂的自然语言错误提示
  • 考虑限流与超时场景
  • 处理认证与授权失败的提示

阶段 2：实现 MCP 服务器

本阶段目标是编写可靠的 MCP 工具组件，并在三个层面进行：连接与认证、工具实现、工具响应。

2.1 设置项目结构

Python 建议结构：

mcp_server/
├─ server.py         # 入口
├─ tools/            # 工具实现
│   ├─ __init__.py
│   ├─ base.py       # 通用工具基类
│   ├─ calendar.py   # 示例模块
│   └─ ...
├─ schemas/          # Pydantic 模型
├─ utils/            # 通用工具
├─ config/           # 配置（可能含 secrets）
└─ evaluations/      # 评测脚本 / prompt

TypeScript 建议结构：

src/
├─ index.ts          # 服务器入口
├─ tools/
│   ├─ base.ts
│   ├─ calendar.ts
│   └─ ...
├─ schemas/
├─ services/
├─ utils/
├─ config/
└─ evaluations/

2.2 连接与认证

支持多种连接方式：

  • 标准输入 / 输出（stdio）
  • Server-Sent Events（SSE）
  • Streamable HTTP

确保：

  • 自定义参数与环境变量配置（API 密钥等）
  • 提供认证失败的清晰提示

2.3 工具设计

创建工具时遵循：

  • 使用数据类（Python）或类（TS）表达工具；封装名字、描述、输入输出 schema
  • 根据工作流拆分工具，不要仅对 API 端点 1:1 映射
  • 为长流程提供分页、过滤、批量工具
  • 将格式化、数据转换、错误处理封装为通用函数

示例（Python 伪代码）：

class CalendarTool(Tool):
    name = "create_calendar_event"
    description = "Create a calendar event with availability checks"
    input_model = CreateEventInput

    async def execute(self, input: CreateEventInput) -> ToolResult:
        """
        创建事件，包含：空闲检查、冲突提醒、事件创建。
        返回人类可读摘要与机器可解析结构。
        """
        availability = await calendar_service.check_availability(...)
        if not availability.is_clear:
            return ToolResult(
                success=False,
                error="日程冲突：请调整时间或邀请人。",
                suggestions=["尝试使用 find_available_times 工具"]
            )

        event = await calendar_service.create_event(...)
        return ToolResult(
            success=True,
            summary=Markdown(...),
            data=JSON(...)
        )

2.4 响应结构

输出应具备：

  • 结构化 JSON 数据（便于后续使用）
  • 人类可读摘要（Markdown）
  • 成功 / 失败标记
  • 建议的下一步行动（若失败）
  • 带标签的字段，便于 Agent 理解

阶段 3：构建评测与示例

3.1 设计评测

评测应覆盖：

  • 常规工作流（happy path）
  • 边界场景（大量数据、分页、多语言）
  • 错误触发（认证失败、404、限流）
  • 恢复能力（失败后再次尝试）

3.2 编写评测脚本

推荐结构（Python）：

from typing import List
from evaluations.runner import EvaluationRunner
from evaluations.scenarios import Scenario, Step

scenarios: List[Scenario] = [
    Scenario(
        name="create_event_success",
        steps=[
            Step(
                tool="create_calendar_event",
                description="创建包含可用性检查的事件",
                input={
                    ...
                },
                expected={
                    "success": True,
                    "contains": ["已创建日程", "冲突提醒"],
                },
            ),
            ...
        ],
    ),
]

if __name__ == "__main__":
    runner = EvaluationRunner()
    runner.run(scenarios)

3.3 撰写使用示例

包括：

  • 逐步调用示例
  • 典型 prompts
  • 错误处理演示
  • 响应格式说明

阶段 4：部署、测试与维护

4.1 端到端测试

执行以下测试：

  • 认证与连接（stdio / SSE / HTTP）
  • 工具功能（核心场景 + 边界）
  • 错误 / 恢复流程
  • 多 Agent 运行时并发情况

4.2 部署准备

文档中须说明：

  • 启动命令、环境变量
  • API 密钥存储方式
  • 依赖安装 / requirements
  • 日志级别与输出

4.3 日志与监控

记录信息：

  • 工具调用摘要（匿名）
  • 失败原因
  • 性能数据（时延 / 成功率）

4.4 定期维护

检查：

  • API 变化与弃用
  • Rate limit / 定价调整
  • Agent 反馈的错误用例
  • 新的业务需求

技术参考

连接管理（示例代码）

文件 scripts/mcp_connection.py 提供了标准输入、SSE、HTTP 三种连接实现。该模块封装了会话生命周期管理、工具列表查询、工具调用等常见操作，便于在评测或自动化脚本中复用。

# 节选：类 MCPConnection 及其派生实现

GitHub 访问

在 GitHub 查看

Artifacts Builder 前端制品构建

Agent Skill：使用 React、Tailwind、shadcn 组件与自动化脚本，将前端作品打包成单文件 HTML Artifact。

Webapp Testing

基于 Playwright 的 Web 应用测试技能手册，包含服务器编排辅助脚本与故障排查提示。