开发工具类 Skills 详解

掌握 MCP 服务器开发、Web Artifacts 构建和自动化测试的专业工具

本章概览

本章深入解析 3 个开发工具类 Skills：

Skill	用途	核心技术
mcp-builder	MCP 服务器开发指南	TypeScript/Python SDK
web-artifacts-builder	构建复杂 Web Artifacts	React + Tailwind + shadcn/ui
webapp-testing	Web 应用自动化测试	Playwright (Python)

1. MCP Builder（MCP 服务器开发）

1.1 概述

MCP（Model Context Protocol） 是让 LLM 与外部服务交互的协议。这个 Skill 指导如何创建高质量的 MCP 服务器。

yaml

name: mcp-builder
description: Guide for creating high-quality MCP (Model Context Protocol)
servers that enable LLMs to interact with external services through
well-designed tools. Use when building MCP servers to integrate external
APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

1.2 MCP 设计理念

API 覆盖 vs 工作流工具

方法	优势	适用场景
全面 API 覆盖	灵活，Agent 可自由组合操作	通用场景，不确定时优先选择
高级工作流工具	便捷，完成特定任务更快	特定任务优化，客户端支持代码执行

工具命名和可发现性

✓ 好的命名：github_create_issue, github_list_repos
✓ 一致的前缀 + 动作导向
✗ 避免：模糊的名称、不一致的模式

上下文管理

简洁的工具描述
支持过滤/分页
返回聚焦、相关的数据

可操作的错误信息

✗ 错误："Operation failed"
✓ 好的："Rate limit exceeded. Wait 60 seconds or authenticate for higher limits."

1.3 推荐技术栈

组件	推荐	原因
语言	TypeScript	SDK 支持好，AI 模型擅长生成
传输	Streamable HTTP（远程）/ stdio（本地）	无状态 JSON 更易扩展

1.4 四阶段开发流程

mermaid

graph LR
    A[Phase 1<br>深度研究和规划] --> B[Phase 2<br>实现]
    B --> C[Phase 3<br>审查和测试]
    C --> D[Phase 4<br>创建评估]

Phase 1：深度研究和规划

1.1 学习 MCP 协议

bash

# 获取规范站点地图
https://modelcontextprotocol.io/sitemap.xml

# 获取具体页面（添加 .md 后缀获取 Markdown）
https://modelcontextprotocol.io/specification/draft.md

1.2 学习框架文档

TypeScript（推荐）：

bash

# SDK 文档
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Python：

bash

# SDK 文档
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

1.3 规划实现

理解目标 API
识别关键端点
确定认证需求
规划工具列表

Phase 2：实现

2.1 项目结构（TypeScript）

mcp-server/
├── src/
│   ├── index.ts        # 入口
│   ├── tools/          # 工具定义
│   ├── utils/          # 工具函数
│   └── types/          # 类型定义
├── package.json
└── tsconfig.json

2.2 核心基础设施

typescript

// 共享工具
- API 客户端（带认证）
- 错误处理助手
- 响应格式化（JSON/Markdown）
- 分页支持

2.3 工具实现

输入 Schema（Zod）：

typescript

import { z } from 'zod';

const CreateIssueSchema = z.object({
  repo: z.string().describe('仓库名称，格式：owner/repo'),
  title: z.string().min(1).describe('Issue 标题'),
  body: z.string().optional().describe('Issue 正文'),
  labels: z.array(z.string()).optional().describe('标签列表'),
});

输出 Schema：

typescript

const outputSchema = {
  type: 'object',
  properties: {
    id: { type: 'number' },
    url: { type: 'string' },
    title: { type: 'string' },
  },
};

工具注解：

typescript

const annotations = {
  readOnlyHint: false,      // 是否只读
  destructiveHint: false,   // 是否破坏性
  idempotentHint: true,     // 是否幂等
  openWorldHint: false,     // 是否与外部世界交互
};

Phase 3：审查和测试

代码质量检查

[ ] 无重复代码（DRY 原则）
[ ] 一致的错误处理
[ ] 完整的类型覆盖
[ ] 清晰的工具描述

构建和测试

TypeScript：

bash

# 验证编译
npm run build

# 使用 MCP Inspector 测试
npx @modelcontextprotocol/inspector

Python：

bash

# 验证语法
python -m py_compile your_server.py

# 使用 MCP Inspector 测试

Phase 4：创建评估

评估目的

测试 LLM 是否能有效使用你的 MCP 服务器回答复杂问题。

创建 10 个评估问题

每个问题必须：

独立：不依赖其他问题
只读：只需非破坏性操作
复杂：需要多次工具调用和深度探索
现实：基于人类真正关心的用例
可验证：有单一、明确的答案
稳定：答案不会随时间变化

评估文件格式

xml

<evaluation>
  <qa_pair>
    <question>找到关于 AI 模型发布的讨论，使用动物代号。
    其中一个模型需要特定的安全级别，格式为 ASL-X。
    对于以斑点野猫命名的模型，正在确定的 X 是多少？</question>
    <answer>3</answer>
  </qa_pair>
  <!-- 更多 qa_pairs... -->
</evaluation>

1.5 参考文档

文档	用途
`reference/mcp_best_practices.md`	MCP 最佳实践
`reference/node_mcp_server.md`	TypeScript 实现指南
`reference/python_mcp_server.md`	Python 实现指南
`reference/evaluation.md`	评估创建指南

2. Web Artifacts Builder（Web Artifacts 构建器）

2.1 概述

用于构建复杂的、多组件的 claude.ai HTML Artifacts。

yaml

name: web-artifacts-builder
description: 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.

2.2 技术栈

React 18 + TypeScript + Vite + Parcel（打包）+ Tailwind CSS + shadcn/ui

2.3 设计原则

关键：避免"AI 风格"

❌ 避免：
- 过度居中的布局
- 紫色渐变
- 均匀圆角
- Inter 字体

✓ 追求：
- 独特的设计选择
- 有个性的布局
- 差异化的配色

2.4 五步工作流

mermaid

graph LR
    A[初始化项目] --> B[开发 Artifact]
    B --> C[打包为单文件 HTML]
    C --> D[分享给用户]
    D --> E[可选：测试]

Step 1：初始化项目

bash

bash scripts/init-artifact.sh <project-name>
cd <project-name>

初始化脚本创建：

✅ React + TypeScript (via Vite)
✅ Tailwind CSS 3.4.1 + shadcn/ui 主题系统
✅ 路径别名 (@/) 配置
✅ 40+ shadcn/ui 组件预装
✅ 所有 Radix UI 依赖
✅ Parcel 打包配置
✅ Node 18+ 兼容

Step 2：开发 Artifact

编辑生成的文件，参考 shadcn/ui 组件文档。

Step 3：打包为单文件 HTML

bash

bash scripts/bundle-artifact.sh

脚本操作：

安装打包依赖（parcel, html-inline 等）
创建 .parcelrc 配置
使用 Parcel 构建
使用 html-inline 内联所有资源

输出 bundle.html：自包含的 Artifact，可直接在 Claude 对话中分享。

Step 4：分享 Artifact

将打包后的 HTML 文件分享给用户，他们可以作为 Artifact 查看。

Step 5（可选）：测试

如有需要，使用 Playwright 或其他工具测试 Artifact。通常不需要提前测试，可在展示后根据反馈调整。

2.5 项目结构

project-name/
├── src/
│   ├── components/     # React 组件
│   │   └── ui/         # shadcn/ui 组件
│   ├── App.tsx         # 主应用
│   └── main.tsx        # 入口
├── index.html          # HTML 模板
├── package.json
├── tailwind.config.js
└── tsconfig.json

3. WebApp Testing（Web 应用测试）

3.1 概述

使用 Playwright 测试本地 Web 应用的工具包。

yaml

name: webapp-testing
description: 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.

3.2 决策树

用户任务 → 是静态 HTML？
    │
    ├─ 是 → 直接读取 HTML 文件识别选择器
    │         ├─ 成功 → 使用选择器编写 Playwright 脚本
    │         └─ 失败/不完整 → 按动态应用处理
    │
    └─ 否（动态 webapp）→ 服务器已运行？
        │
        ├─ 否 → 运行: python scripts/with_server.py --help
        │        使用 helper + 编写简化的 Playwright 脚本
        │
        └─ 是 → 侦察后行动：
            1. 导航并等待 networkidle
            2. 截图或检查 DOM
            3. 从渲染状态识别选择器
            4. 使用发现的选择器执行操作

3.3 核心辅助脚本

with_server.py

管理服务器生命周期，支持多服务器。

单服务器：

bash

python scripts/with_server.py \
  --server "npm run dev" \
  --port 5173 \
  -- python your_automation.py

多服务器（后端 + 前端）：

bash

python scripts/with_server.py \
  --server "cd backend && python server.py" --port 3000 \
  --server "cd frontend && npm run dev" --port 5173 \
  -- python your_automation.py

3.4 Playwright 脚本模板

python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    # 始终使用无头模式
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()

    # 导航
    page.goto('http://localhost:5173')

    # [关键] 等待 JS 执行完成
    page.wait_for_load_state('networkidle')

    # ... 自动化逻辑

    browser.close()

3.5 侦察后行动模式

步骤 1：检查渲染的 DOM

python

# 截图
page.screenshot(path='/tmp/inspect.png', full_page=True)

# 获取内容
content = page.content()

# 列出所有按钮
page.locator('button').all()

步骤 2：识别选择器

从检查结果中确定要使用的选择器。

步骤 3：执行操作

使用发现的选择器执行自动化操作。

3.6 常见陷阱

python

# ❌ 错误：在动态应用中未等待就检查 DOM
page.goto('http://localhost:5173')
content = page.content()  # 可能获取到未渲染的内容

# ✓ 正确：等待 networkidle 后再检查
page.goto('http://localhost:5173')
page.wait_for_load_state('networkidle')
content = page.content()

3.7 最佳实践

实践	说明
脚本作为黑盒	先用 `--help` 查看用法，不要立即读取源码
同步 API	使用 `sync_playwright()`
关闭浏览器	完成后始终 `browser.close()`
描述性选择器	`text=`, `role=`, CSS 选择器或 ID
适当等待	`page.wait_for_selector()` 或 `page.wait_for_timeout()`

3.8 示例文件

文件	用途
`examples/element_discovery.py`	发现页面上的按钮、链接和输入框
`examples/static_html_automation.py`	使用 file:// URL 处理本地 HTML
`examples/console_logging.py`	自动化过程中捕获控制台日志

4. 本章小结

开发类 Skills 对比

Skill	输入	输出	核心价值
mcp-builder	API 需求	MCP 服务器	让 LLM 连接外部服务
web-artifacts-builder	UI 需求	单文件 HTML	复杂交互式 Artifact
webapp-testing	Web 应用	测试结果	自动化验证 UI

技术栈总结

MCP 开发：
├── TypeScript + MCP SDK（推荐）
└── Python + FastMCP

Web Artifacts：
├── React 18 + TypeScript
├── Tailwind CSS + shadcn/ui
└── Vite + Parcel

Web 测试：
└── Playwright (Python sync API)

共同设计理念

文档优先：先读文档，再动手
渐进式：从简单开始，按需增加复杂度
可验证：重视测试和评估
实用主义：提供脚本和工具减少重复工作

上一章：文档处理类 Skills

下一章：工作流类 Skills

开发工具类 Skills 详解 ​

本章概览 ​

1. MCP Builder（MCP 服务器开发） ​

1.1 概述 ​

1.2 MCP 设计理念 ​

API 覆盖 vs 工作流工具 ​

工具命名和可发现性 ​

上下文管理 ​

可操作的错误信息 ​

1.3 推荐技术栈 ​

1.4 四阶段开发流程 ​

Phase 1：深度研究和规划 ​

1.1 学习 MCP 协议 ​

1.2 学习框架文档 ​

1.3 规划实现 ​

Phase 2：实现 ​

2.1 项目结构（TypeScript） ​

2.2 核心基础设施 ​

2.3 工具实现 ​

Phase 3：审查和测试 ​

代码质量检查 ​

构建和测试 ​

Phase 4：创建评估 ​

评估目的 ​

创建 10 个评估问题 ​

评估文件格式 ​

1.5 参考文档 ​

2. Web Artifacts Builder（Web Artifacts 构建器） ​

2.1 概述 ​

2.2 技术栈 ​

2.3 设计原则 ​

2.4 五步工作流 ​

Step 1：初始化项目 ​

Step 2：开发 Artifact ​

Step 3：打包为单文件 HTML ​

Step 4：分享 Artifact ​

Step 5（可选）：测试 ​

2.5 项目结构 ​

3. WebApp Testing（Web 应用测试） ​

3.1 概述 ​

3.2 决策树 ​

3.3 核心辅助脚本 ​

with_server.py ​

3.4 Playwright 脚本模板 ​

3.5 侦察后行动模式 ​

步骤 1：检查渲染的 DOM ​

步骤 2：识别选择器 ​

步骤 3：执行操作 ​

3.6 常见陷阱 ​

3.7 最佳实践 ​

3.8 示例文件 ​

4. 本章小结 ​

开发类 Skills 对比 ​

技术栈总结 ​

共同设计理念 ​

开发工具类 Skills 详解

本章概览

1. MCP Builder（MCP 服务器开发）

1.1 概述

1.2 MCP 设计理念

API 覆盖 vs 工作流工具

工具命名和可发现性

上下文管理

可操作的错误信息

1.3 推荐技术栈

1.4 四阶段开发流程

Phase 1：深度研究和规划

1.1 学习 MCP 协议

1.2 学习框架文档

1.3 规划实现

Phase 2：实现

2.1 项目结构（TypeScript）

2.2 核心基础设施

2.3 工具实现

Phase 3：审查和测试

代码质量检查

构建和测试

Phase 4：创建评估

评估目的

创建 10 个评估问题

评估文件格式

1.5 参考文档

2. Web Artifacts Builder（Web Artifacts 构建器）

2.1 概述

2.2 技术栈

2.3 设计原则

2.4 五步工作流

Step 1：初始化项目

Step 2：开发 Artifact

Step 3：打包为单文件 HTML

Step 4：分享 Artifact

Step 5（可选）：测试

2.5 项目结构

3. WebApp Testing（Web 应用测试）

3.1 概述

3.2 决策树

3.3 核心辅助脚本

with_server.py

3.4 Playwright 脚本模板

3.5 侦察后行动模式

步骤 1：检查渲染的 DOM

步骤 2：识别选择器

步骤 3：执行操作

3.6 常见陷阱

3.7 最佳实践

3.8 示例文件

4. 本章小结

开发类 Skills 对比

技术栈总结

共同设计理念