MCP 和 Skill 实战-我的编程笔记记录

🎯目标

完成本次培训后，参训人员将能够：

✅ 理解 MCP 和 Skill 的概念与价值
✅ 掌握 Claude Code 和 MCP 服务器的安装配置流程
✅ 使用 SDD（Skill-Driven Development）流程完成前后端模块开发
✅ 开发自定义 Skill 封装团队特定工作流
✅ 开发自定义 MCP 服务扩展 AI 能力边界
✅ 掌握通过上下文工程生成高保真原型的技巧（产品经理重点）
✅ 产出可复用的培训文档和示例代码

AI 编程工具已经普及 – GitHub Copilot、Cursor、Claude Code 等工具正在改变开发方式
效率提升显著 – 正确使用 AI 工具可以将开发效率提升 30%-50%
方法论很重要 – 有方法的 AI 辅助开发（SDD）比随意使用效果更好
团队协作需要 – 统一工具和方法可以降低协作成本

AI 编程工具分类

类别	代表工具	特点	适用场景
代码补全	GitHub Copilot、Codeium	IDE 内嵌、自动补全	日常编码辅助
对话式编程	Claude Code、Cursor Chat	自然语言交互、理解上下文	复杂任务、项目探索
自主代理	Trae、Devin	目标导向、自主执行多步任务	长时间、复杂工作流

为什么选择 Claude Code？

我们选择 Claude Code 作为培训重点，原因如下：

上下文理解能力强 – Claude 模型在理解项目结构和意图方面有优势
项目探索能力出色 – 内置文件搜索、内容搜索、代码解释工具
技能系统完善 – superpowers 技能库开箱即用，覆盖完整开发流程
MCP 支持完整 – 可扩展访问各种外部工具和服务

环境准备

请大家确认已安装以下软件：

# 检查 Node.js（18+  required）
node --version

# 检查 Java（17+ required）
java --version

# 检查 Git
git --version

安装 Claude Code：

# 全局安装
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

# 登录
claude login

模块 1：基础概念

1.1 什么是 MCP？

MCP（Model Context Protocol） 是标准化的 AI 工具接口协议。https://modelcontextprotocol.net.cn/docs/getting-started/intro

核心概念

MCP 定义了 AI 模型与外部工具之间的通信标准，类似 JDBC 之于数据库驱动。

┌─────────────────────────────────────────────────────────┐
│                     Claude Code  (MCP host)             │
├─────────────────────────────────────────────────────────┤
│                        MCP Client                       │
├─────────────────────────────────────────────────────────┤
│   MCP Server 1  │   MCP Server 2  │   MCP Server 3      │
│   (文件系统)     │   (Git)         │   (数据库)            │
└─────────────────────────────────────────────────────────┘

MCP 的三种接口类型

Tools（工具） – 可执行的操作
- 示例：查询数据库、发送 HTTP 请求、执行 Shell 命令
Resources（资源） – 可读取的数据
- 示例：文件内容、API 响应、数据库记录
Prompts（提示） – 预定义的对话模板
- 示例：代码审查模板、需求分析模板

服务器	用途
filesystem	文件操作
postgres	PostgreSQL
puppeteer	浏览器自动化

1.2 什么是 Skill？

Skill（技能） 是 Claude Code 的可复用工作流封装。

superpowers 技能系统

superpowers 是最流行的 Claude Code 技能库，包含：

类别	技能	作用
规划类	brainstorming	需求分析、方案设计
	writing-plans	生成详细实现计划
执行类	executing-plans	按步骤自动执行
	implement	智能代码实现
	frontend-design	前端 UI 设计与实现
质量类	requesting-code-review	代码审查
	security-scan	安全分析
	test	测试生成和运行

SDD（Skill-Driven Development）流程

需求 → brainstorming → writing-plans → executing-plans → 完成
                            ↓
                       code-review
                            ↓
                          test

每个环节都有对应的技能，形成标准化的开发流程。

1.3 安装与配置演示

步骤 1：配置 Claude Code

编辑全局配置文件 ~/.claude/CLAUDE.md：

**交互风格**：专业、简洁
**交互语言**：简体中文

步骤 2：配置 MCP 服务器

编辑项目配置文件 .claude/settings.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/watch"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    }
  }
}

步骤 3：验证配置

cd /path/to/project
claude

在 Claude Code 中测试：

> 列出当前目录的文件
> 查看 git 状态

1.4 技能使用演示

启动技能

claude

/superpowers:brainstorming 为项目添加数据导出功能

查看可用技能

/superpowers:list

技能调用示例

场景	技能命令
新功能需求分析	`/superpowers:brainstorming <需求描述>`
生成实现计划	`/superpowers:writing-plans`
执行计划	`/superpowers:executing-plans`
代码审查	`/superpowers:requesting-code-review`
生成测试	`/superpowers:test`

模块 1 小结

MCP 是标准化的 AI 工具接口
Skill 是可复用的工作流封装
SDD 流程：brainstorming → writing-plans → executing-plans → code-review → test
配置 MCP 服务器可以扩展 Claude 的能力

模块 2：数据导出模块实战

2.1 案例介绍

业务需求：为现有的 Spring Boot 项目添加数据导出功能。

功能需求

需求	描述
导出用户列表数据	将系统中的用户数据导出为文件
支持多种格式	CSV、Excel、PDF 三种格式
筛选条件导出	支持按日期范围、用户状态等条件筛选
前端交互	导出按钮 + 格式选择 + 下载进度提示

技术栈

后端：

Spring Boot 3.x
Apache POI（Excel 导出）
OpenCSV（CSV 导出）
iText 7（PDF 导出）

前端：

React 18
Tailwind CSS
Axios（HTTP 请求）
下载进度组件

2.2 SDD 流程演示

步骤 1：brainstorming（需求分析与设计）

命令：

/superpowers:brainstorming 为 Spring Boot 项目添加数据导出模块

需求：
1. 导出用户列表数据
2. 支持 CSV、Excel、PDF 三种格式
3. 支持按日期范围、状态筛选
4. 前端需要导出按钮、格式选择器、下载进度提示

现有项目结构：
- 已有 User 实体和 UserRepository
- 已有基础的 CRUD API
- 前端使用 React + Tailwind CSS

brainstorming 技能会执行：

探索项目上下文，了解现有架构
提出澄清问题（一次一个）
提出 2-3 个技术方案并对比
呈现推荐的设计方案

可能的澄清问题：

导出数据量级大概是多少？（影响是否需要分页导出）
是否需要异步导出？（大数据量时建议后台任务）
有没有特定的权限控制需求？

推荐方案：

方案 A：同步导出（简单，适合小数据量）
方案 B：异步导出 + 通知（复杂，适合大数据量）
推荐：方案 A（培训场景，简单直观）

步骤 2：writing-plans（生成实现计划）

设计方案批准后，技能自动过渡到 writing-plans：

/superpowers:writing-plans

生成的任务清单示例：

TODO: 数据导出模块实现

[ ] 1. 后端 - 添加 Maven 依赖（POI、OpenCSV、iText）
[ ] 2. 后端 - 创建 ExportController（REST API）
[ ] 3. 后端 - 创建 ExportService（导出业务逻辑）
[ ] 4. 后端 - 实现 CSV 导出方法
[ ] 5. 后端 - 实现 Excel 导出方法
[ ] 6. 后端 - 实现 PDF 导出方法
[ ] 7. 后端 - 添加筛选条件支持
[ ] 8. 前端 - 创建 ExportButton 组件
[ ] 9. 前端 - 创建 FormatSelector 组件
[ ] 10. 前端 - 创建 DownloadProgress 组件
[ ] 11. 前端 - 集成到用户列表页面
[ ] 12. 测试 - 生成单元测试
[ ] 13. 测试 - 运行验证

步骤 3：executing-plans（执行计划）

/superpowers:executing-plans

技能执行过程：

按顺序处理任务
更新任务状态（pending → in_progress → completed）
处理依赖关系（如：先有 Service 再有 Controller）
关键节点请求确认

后端代码示例 – ExportController.java：

@RestController
@RequestMapping("/api/users")
public class ExportController {

    private final ExportService exportService;

    @GetMapping("/export")
    public ResponseEntity<byte[]> exportUsers(
            @RequestParam String format,
            @RequestParam(required = false) LocalDate startDate,
            @RequestParam(required = false) LocalDate endDate,
            @RequestParam(required = false) String status) {

        byte[] exportedData = exportService.exportUsers(format, startDate, endDate, status);

        String contentType = switch (format.toLowerCase()) {
            case "csv" -> "text/csv";
            case "excel" -> "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
            case "pdf" -> "application/pdf";
            default -> "application/octet-stream";
        };

        String fileName = switch (format.toLowerCase()) {
            case "csv" -> "users.csv";
            case "excel" -> "users.xlsx";
            case "pdf" -> "users.pdf";
            default -> "users.dat";
        };

        return ResponseEntity.ok()
                .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=" + fileName)
                .contentType(MediaType.parseMediaType(contentType))
                .body(exportedData);
    }
}

前端代码示例 – ExportButton.tsx：

import React, { useState } from 'react';
import axios from 'axios';

interface ExportButtonProps {
  filters: {
    startDate?: string;
    endDate?: string;
    status?: string;
  };
}

export const ExportButton: React.FC<ExportButtonProps> = ({ filters }) => {
  const [format, setFormat] = useState<'csv' | 'excel' | 'pdf'>('csv');
  const [progress, setProgress] = useState<number>(0);
  const [downloading, setDownloading] = useState<boolean>(false);

  const handleExport = async () => {
    setDownloading(true);
    setProgress(0);

    try {
      const response = await axios.get('/api/users/export', {
        params: { format, ...filters },
        responseType: 'blob',
        onDownloadProgress: (progressEvent) => {
          const percentCompleted = Math.round(
            (progressEvent.loaded * 100) / (progressEvent.total || 1)
          );
          setProgress(percentCompleted);
        },
      });

      // 触发下载
      const blob = new Blob([response.data], { type: response.headers['content-type'] });
      const url = window.URL.createObjectURL(blob);
      const link = document.createElement('a');
      link.href = url;
      link.download = `users.${format === 'excel' ? 'xlsx' : format}`;
      link.click();
      window.URL.revokeObjectURL(url);
    } catch (error) {
      console.error('导出失败', error);
      alert('导出失败，请重试');
    } finally {
      setDownloading(false);
    }
  };

  return (
    <div className="flex items-center gap-2">
      <select
        value={format}
        onChange={(e) => setFormat(e.target.value as 'csv' | 'excel' | 'pdf')}
        className="px-3 py-2 border rounded-md"
        disabled={downloading}
      >
        <option value="csv">CSV</option>
        <option value="excel">Excel</option>
        <option value="pdf">PDF</option>
      </select>

      <button
        onClick={handleExport}
        disabled={downloading}
        className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:bg-gray-400"
      >
        {downloading ? '导出中...' : '导出'}
      </button>

      {downloading && (
        <div className="w-32 bg-gray-200 rounded-full h-2">
          <div
            className="bg-blue-600 h-2 rounded-full transition-all"
            style={{ width: `${progress}%` }}
          />
        </div>
      )}
    </div>
  );
};

步骤 4：frontend-design（前端设计规范）

/superpowers:frontend-design

frontend-design 技能会：

分析现有前端代码风格
遵循设计系统（如 Ant Design、Tailwind UI）
生成符合规范的组件代码
确保响应式和可访问性

设计规范检查清单：

颜色使用 Tailwind 色板
组件尺寸一致（按钮高度 36px/40px）
字体大小符合层级
间距使用统一的 spacing scale
支持键盘导航
有加载状态和错误状态

步骤 5：code-review（代码审查）

/superpowers:requesting-code-review 审查刚才实现的数据导出模块

审查维度：

维度	检查项
代码质量	命名规范、代码结构、重复代码
安全性	输入验证、XSS 防护、权限控制
性能	大数据量处理、内存管理
测试	单元测试覆盖率、边界条件

典型审查反馈：

⚠️ 发现 3 个改进建议：

1. [安全性] ExportController 缺少输入验证
   建议：添加 @Valid 注解和自定义验证器

2. [性能] PDF 导出生成大文件时可能 OOM
   建议：使用流式处理或限制最大导出量

3. [测试] 缺少单元测试
   建议：为 ExportService 生成测试用例

步骤 6：test（测试生成与验证）

/superpowers:test

生成的测试用例示例：

@SpringBootTest
class ExportServiceTest {

    @Autowired
    private ExportService exportService;

    @Test
    void testExportToCsv() {
        // Given
        LocalDate startDate = LocalDate.now().minusDays(7);
        LocalDate endDate = LocalDate.now();

        // When
        byte[] result = exportService.exportUsers("csv", startDate, endDate, "ACTIVE");

        // Then
        assertThat(result).isNotEmpty();
        assertThat(new String(result)).contains("id,name,email");
    }

    @Test
    void testExportToExcel() {
        byte[] result = exportService.exportUsers("excel", null, null, null);
        assertThat(result).isNotEmpty();
    }

    @Test
    void testExportToPdf() {
        byte[] result = exportService.exportUsers("pdf", null, null, null);
        assertThat(result).isNotEmpty();
    }
}

2.3 模块 2 小结

SDD 流程回顾：

brainstorming（需求分析）
    ↓
writing-plans（任务分解）
    ↓
executing-plans（自动执行）
    ↓
frontend-design（UI 设计）
    ↓
code-review（质量审查）
    ↓
test（测试验证）

关键收获：

AI 生成的代码需要审查和测试
SDD 流程保证代码质量
技能可以编排使用，形成工作流

模块 3：自定义 Skill 开发实战

3.1 为什么需要自定义 Skill？

官方 superpowers 技能虽然强大，但每个团队有特定的工作流：

场景	官方 Skill	自定义 Skill
公司特定流程	❌ 不支持	✅ 封装内部审批流程
代码规范检查	⚠️ 通用检查	✅ 按团队规范定制
专有工具集成	❌ 不支持	✅ 集成内部工具链
领域知识注入	⚠️ 通用知识	✅ 注入业务领域知识

本模块实战案例：开发一个”API 文档生成 Skill”，自动为公司项目生成符合内部规范的 API 文档。

3.2 Skill 结构解析

Skill 文件组成

一个完整的 Skill 通常包含：

my-custom-skill/
├── SKILL.md              # 技能主文件（必需）
├── prompts/              # 子提示词目录（可选）
│   └── reviewer-prompt.md
└── references/           # 参考资料目录（可选）
    └── api-style-guide.md

SKILL.md 标准结构

---
name: skill-name           # 技能名称（调用时使用）
description: 技能描述       # 简短描述技能用途
---

# 技能标题

## 技能说明
详细描述技能的作用和使用场景。

## Checklist
技能执行时必须完成的步骤：
1. **步骤 1** - 说明
2. **步骤 2** - 说明
3. **步骤 3** - 说明

## 输出要求
技能应该产出什么：代码、文档、测试结果

3.3 实战：开发 API 文档生成 Skill

步骤 1：创建 Skill 目录

# 在技能目录中创建
mkdir -p ~/.claude/plugins/my-skills/api-doc-generator
cd ~/.claude/plugins/my-skills/api-doc-generator

# 创建目录结构
mkdir -p prompts
mkdir -p references

步骤 2：编写 SKILL.md

---
name: api-doc-generator
description: 为公司项目生成符合内部规范的 API 文档
---

# API 文档生成器

本 Skill 用于分析 Spring Boot 项目的 Controller 代码，自动生成符合公司内部规范的 API 文档。

## Checklist

1. **探索项目结构** — 找到所有 Controller 文件
2. **分析 API 端点** — 提取每个端点的详细信息
3. **检查命名规范** — 验证是否符合 RESTful 规范
4. **生成文档草稿** — 按公司模板生成 Markdown 文档
5. **质量审查** — 检查文档完整性和准确性
6. **输出最终文档** — 保存到 docs/api/ 目录

## API 规范检查清单

### RESTful 规范
- [ ] 使用正确的 HTTP 方法（GET/POST/PUT/DELETE）
- [ ] URL 使用复数名词（/users 而非 /user）
- [ ] URL 使用小写和连字符（/user-profiles 而非 /userProfiles）
- [ ] 避免在 URL 中使用动词

### 响应规范
- [ ] 成功响应返回 200/201/204
- [ ] 错误响应包含 error_code 和 message
- [ ] 分页响应包含 page/size/total 字段

### 文档规范
- [ ] 每个端点有中文描述
- [ ] 请求参数有说明和示例
- [ ] 响应字段有说明和示例

步骤 3：配置和使用自定义 Skill

编辑 ~/.claude/settings.json：

{
  "skills": {
    "sources": [
      {
        "type": "local",
        "path": "/Users/your-name/.claude/plugins/my-skills"
      }
    ]
  }
}

步骤 4：使用 Skill

/superpowers:api-doc-generator 为当前项目生成 API 文档

3.4 Skill 执行过程演示

阶段	内容
1. 探索项目结构	找到所有 Controller 文件
2. 分析 API 端点	提取端点信息（方法、URL、参数、响应）
3. 检查命名规范	对照 RESTful 规范检查
4. 生成文档草稿	按公司模板生成 Markdown
5. 质量审查	检查完整性
6. 输出最终文档	保存到 docs/api/

3.5 模块 3 小结

关键收获：

自定义 Skill 可以封装团队特定工作流
SKILL.md 是技能的核心配置文件
Checklist 确保技能执行的完整性

模块 4：自定义 MCP 服务开发

4.1 为什么需要自定义 MCP 服务？

官方 MCP 服务器提供通用功能，但公司内部往往有特定需求：

场景	官方 MCP	自定义 MCP
数据库查询	❌ 不支持	✅ 封装内部数据库访问
内部 API 调用	❌ 不支持	✅ 封装公司微服务
业务系统对接	❌ 不支持	✅ 对接 ERP/CRM 系统
权限验证	❌ 不支持	✅ 集成公司 SSO

本模块实战案例：开发一个”数据库查询 MCP 服务”，让 Claude 可以直接查询公司业务数据库。

4.2 MCP 协议解析

MCP 架构

┌────────────────────────────────────────────┐
│            Claude Code (Host)              │
├────────────────────────────────────────────┤
│              MCP Client                    │
├──────────────┬──────────────┬──────────────┤
│   Tool       │  Resource    │   Prompt     │
│   (工具)      │  (资源)      │   (提示)      │
└──────────────┴──────────────┴──────────────┘
                        ↑
                MCP Protocol
                        ↓
┌────────────────────────────────────────────┐
│           自定义 MCP Server                │
│  ┌──────────┬──────────┬──────────────────┐│
│  │ register │ call     │ list             ││
│  └──────────┴──────────┴──────────────────┘│
└────────────────────────────────────────────┘

三种接口类型

1. Tools（工具） – 可执行的操作

// 定义工具
{
  name: "query_database",
  description: "执行 SQL 查询并返回结果",
  inputSchema: {
    type: "object",
    properties: {
      sql: { type: "string", description: "SQL 查询语句" },
      params: { type: "array", description: "参数列表" }
    }
  }
}

// 调用工具
{
  "name": "query_database",
  "arguments": {
    "sql": "SELECT * FROM users WHERE status = ?",
    "params": ["active"]
  }
}

2. Resources（资源） – 可读取的数据

// 定义资源
{
  uri: "db://users/active",
  name: "活跃用户列表",
  mimeType: "application/json"
}

// 读取资源
GET db://users/active
→ [{ id: 1, name: "张三" }, ...]

3. Prompts（提示） – 预定义的对话模板

// 定义提示模板
{
  name: "analyze_query_result",
  description: "分析查询结果并生成报告",
  arguments: {
    query: { description: "原始 SQL 查询", required: true },
    result: { description: "查询结果", required: true }
  }
}

4.3 脚手架搭建

步骤 1：创建项目

# 创建项目目录
mkdir mcp-db-server
cd mcp-db-server

# 初始化 npm 项目
npm init -y

# 安装依赖
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript

# 初始化 TypeScript
npx tsc --init

步骤 2：配置 tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

步骤 3：配置 package.json

{
  "name": "mcp-db-server",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "mcp-db-server": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "ts-node src/index.ts"
  }
}

4.4 业务逻辑实现

完整代码示例 – src/index.ts

#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  Tool,
} from '@modelcontextprotocol/sdk/types.js';
import mysql from 'mysql2/promise';

// 数据库连接池
let pool: mysql.Pool | null = null;

async function getPool() {
  if (!pool) {
    pool = mysql.createPool({
      host: process.env.DB_HOST || 'localhost',
      user: process.env.DB_USER || 'root',
      password: process.env.DB_PASSWORD || '',
      database: process.env.DB_NAME || 'test',
      waitForConnections: true,
      connectionLimit: 10,
    });
  }
  return pool;
}

// 定义工具
const QUERY_TOOL: Tool = {
  name: 'query_database',
  description: '执行 SQL 查询并返回结果（只读操作）',
  inputSchema: {
    type: 'object',
    properties: {
      sql: {
        type: 'string',
        description: 'SQL 查询语句（仅支持 SELECT）'
      },
      params: {
        type: 'array',
        description: '参数列表',
        items: { type: 'string' }
      }
    },
    required: ['sql']
  }
};

const LIST_TABLES_TOOL: Tool = {
  name: 'list_tables',
  description: '列出数据库中的所有表',
  inputSchema: {
    type: 'object',
    properties: {}
  }
};

const DESCRIBE_TABLE_TOOL: Tool = {
  name: 'describe_table',
  description: '查看表结构',
  inputSchema: {
    type: 'object',
    properties: {
      table: {
        type: 'string',
        description: '表名'
      }
    },
    required: ['table']
  }
};

// 创建服务器
const server = new Server(
  {
    name: 'db-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// 处理列出工具请求
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [QUERY_TOOL, LIST_TABLES_TOOL, DESCRIBE_TABLE_TOOL],
  };
});

// 处理调用工具请求
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    switch (name) {
      case 'query_database': {
        const sql = args?.sql as string;
        const params = args?.params as string[] | undefined;

        // 安全校验：只允许 SELECT
        if (!sql.trim().toUpperCase().startsWith('SELECT')) {
          throw new Error('只支持 SELECT 查询');
        }

        const pool = await getPool();
        const [rows] = await pool.execute(sql, params);

        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(rows, null, 2),
            },
          ],
        };
      }

      case 'list_tables': {
        const pool = await getPool();
        const [rows] = await pool.execute('SHOW TABLES');

        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(rows, null, 2),
            },
          ],
        };
      }

      case 'describe_table': {
        const table = args?.table as string;
        const pool = await getPool();
        const [rows] = await pool.execute(`DESCRIBE ${table}`);

        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(rows, null, 2),
            },
          ],
        };
      }

      default:
        throw new Error(`Unknown tool: ${name}`);
    }
  } catch (error) {
    return {
      content: [
        {
          type: 'text',
          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
        },
      ],
    };
  }
});

// 启动服务器
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('MCP Database Server running on stdio');
}

main().catch((error) => {
  console.error('Fatal error:', error);
  process.exit(1);
});

4.5 配置与集成

步骤 1：构建项目

npm run build

步骤 2：配置 Claude Code

编辑项目级配置 .claude/settings.json：

{
  "mcpServers": {
    "db-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-db-server/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database"
      }
    }
  }
}

步骤 3：验证配置

claude

> 你有哪些可用的工具？

列出数据库中的所有表
查询 users 表的数据

步骤 4：环境变量管理（推荐）

创建 .env 文件：

# .env
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=secret
DB_NAME=production

修改配置引用：

{
  "mcpServers": {
    "db-server": {
      "command": "node",
      "args": ["/path/to/mcp-db-server/dist/index.js"],
      "env": {
        "DB_HOST": "${DB_HOST}",
        "DB_USER": "${DB_USER}",
        "DB_PASSWORD": "${DB_PASSWORD}",
        "DB_NAME": "${DB_NAME}"
      }
    }
  }
}

4.6 安全最佳实践

1. SQL 注入防护

// ✅ 使用参数化查询
await pool.execute('SELECT * FROM users WHERE id = ?', [userId]);

// ❌ 避免字符串拼接
await pool.execute(`SELECT * FROM users WHERE id = ${userId}`);

2. 权限控制

// 只读校验
if (!sql.trim().toUpperCase().startsWith('SELECT')) {
  throw new Error('只支持 SELECT 查询');
}

// 黑名单过滤
const forbiddenKeywords = ['DROP', 'DELETE', 'UPDATE', 'INSERT', 'TRUNCATE'];
for (const keyword of forbiddenKeywords) {
  if (sql.toUpperCase().includes(keyword)) {
    throw new Error(`不允许的操作：${keyword}`);
  }
}

3. 审计日志

// 记录所有查询
console.error(`[AUDIT] Query executed: ${sql} by user: ${process.env.CURRENT_USER}`);

4. 查询限制

// 限制返回行数
const [rows] = await pool.execute(`${sql} LIMIT 1000`);

// 超时设置
const pool = mysql.createPool({
  ...config,
  acquireTimeout: 10000, // 10 秒超时
});

4.7 扩展：添加更多功能

添加 Schema 浏览工具

const LIST_SCHEMAS_TOOL: Tool = {
  name: 'list_schemas',
  description: '列出所有数据库 schema',
  inputSchema: {
    type: 'object',
    properties: {}
  }
};

// 在 handler 中添加
case 'list_schemas': {
  const pool = await getPool();
  const [rows] = await pool.execute('SHOW DATABASES');
  return {
    content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }],
  };
}

添加数据导出工具

const EXPORT_TOOL: Tool = {
  name: 'export_to_csv',
  description: '将查询结果导出为 CSV',
  inputSchema: {
    type: 'object',
    properties: {
      sql: { type: 'string', description: 'SQL 查询' },
      filename: { type: 'string', description: '输出文件名' }
    },
    required: ['sql', 'filename']
  }
};

4.8 模块 4 小结

关键收获：

MCP 协议定义了 Tool/Resource/Prompt 三种接口
使用 @modelcontextprotocol/sdk 可以快速开发自定义服务
安全是自定义 MCP 的首要考虑（SQL 注入、权限控制、审计日志）
通过 MCP 可以将内部系统暴露给 AI，极大扩展能力边界

下一步：

为公司内部 API 创建 MCP 封装
为数据库查询添加权限验证
集成公司 SSO 认证

模块 5：高保真原型生成（30 分钟，产品经理重点）

5.1 什么是上下文工程？

上下文工程（Context Engineering） 是通过精心设计的 Prompt 和上下文信息，引导 AI 生成稳定、可预测、符合规范的输出。

传统 Prompt vs 上下文工程

维度	传统 Prompt	上下文工程
角色设定	“你是一个助手”	“你是资深产品设计师，10 年企业级 SaaS 经验”
设计约束	“做好看点”	“遵循 Ant Design 4.x 规范，主色#1890ff”
组件引用	“用些组件”	“使用 shadcn/ui 的 Card、Button、Table 组件”
输出格式	随意	结构化：React + Tailwind + TypeScript
迭代	重新生成	基于反馈的增量修改

5.2 上下文工程四要素

要素 1：角色设定（Role）

普通设定：

你是一个助手

专业设定：

你是资深产品设计师，专精于企业级 SaaS 产品设计。
你有 10 年设计经验，熟悉 Ant Design、Material Design 等设计系统。
你的设计风格简洁、专业，注重可用性和可访问性。

要素 2：设计约束（Constraints）

模糊约束：

做好看点，专业一点

精确约束：

设计要求：
1. 使用 Ant Design 4.x 组件库
2. 主色调：#1890ff（Ant Design 默认蓝）
3. 字体：系统字体栈，正文 14px，标题 16-24px
4. 间距：使用 4/8/12/16/24/32px 等级
5. 圆角：4px（小）、8px（中）
6. 阴影：使用 Ant Design 默认阴影层级

要素 3：组件引用（Components）

模糊引用：

用一些现成的组件

精确引用：

使用以下组件：
- Card：内容卡片容器
- Button：操作按钮（size: middle, type: primary）
- Table：数据表格（pagination: true, bordered: true）
- DatePicker.RangePicker：日期范围选择器
- Select：下拉选择器（mode: multiple）
- Space：水平间距容器

要素 4：输出格式（Format）

模糊格式：

给我一个页面

精确格式：

输出格式：
- React 18 + TypeScript
- Tailwind CSS 样式
- 函数式组件，使用 hooks
- 包含完整的类型定义
- 导出默认组件

5.3 实战案例：数据导出功能原型

完整 Prompt 示例

你是资深产品设计师，专精于企业级 SaaS 产品设计。

## 任务
为"用户数据导出功能"设计一个高保真原型页面。

## 设计要求
1. 使用 Ant Design 4.x 组件库
2. 主色调：#1890ff
3. 风格：简洁专业，符合企业级 SaaS 产品
4. 响应式：支持桌面端和平板

## 页面元素
1. 筛选条件区域
   - 日期范围选择器（DatePicker.RangePicker）
   - 用户状态下拉框（Select，多选）
   - 搜索框（Input.Search）
2. 数据表格
   - 列：ID、姓名、邮箱、注册时间、状态
   - 支持分页
   - 支持排序
3. 导出操作区
   - 导出按钮
   - 格式选择（CSV/Excel/PDF 单选）
   - 下载进度指示器

## 技术栈
- React 18 + TypeScript
- Tailwind CSS
- Ant Design 4.x

## 输出
完整的 React 组件代码，包含类型定义和示例数据

预期输出示例

import React, { useState } from 'react';
import { Card, Table, Button, DatePicker, Select, Input, Radio, Progress, Space, Tag } from 'antd';
import type { ColumnsType } from 'antd/es/table';
import { SearchOutlined, DownloadOutlined } from '@ant-design/icons';
import dayjs from 'dayjs';

const { RangePicker } = DatePicker;
const { Option } = Select;
const { Search } = Input;

interface UserData {
  id: number;
  name: string;
  email: string;
  registerDate: string;
  status: 'active' | 'inactive' | 'suspended';
}

// 示例数据
const mockData: UserData[] = [
  { id: 1, name: '张三', email: 'zhangsan@example.com', registerDate: '2024-01-15', status: 'active' },
  { id: 2, name: '李四', email: 'lisi@example.com', registerDate: '2024-02-20', status: 'active' },
  { id: 3, name: '王五', email: 'wangwu@example.com', registerDate: '2024-03-10', status: 'inactive' },
];

const statusMap: Record<string, { color: string; label: string }> = {
  active: { color: 'green', label: '活跃' },
  inactive: { color: 'gray', label: '未激活' },
  suspended: { color: 'red', label: '已冻结' },
};

const ExportPage: React.FC = () => {
  const [dateRange, setDateRange] = useState<[dayjs.Dayjs, dayjs.Dayjs] | null>(null);
  const [selectedStatuses, setSelectedStatuses] = useState<string[]>([]);
  const [searchText, setSearchText] = useState('');
  const [exportFormat, setExportFormat] = useState('excel');
  const [downloading, setDownloading] = useState(false);
  const [progress, setProgress] = useState(0);

  const columns: ColumnsType<UserData> = [
    { title: 'ID', dataIndex: 'id', key: 'id', sorter: (a, b) => a.id - b.id },
    { title: '姓名', dataIndex: 'name', key: 'name' },
    { title: '邮箱', dataIndex: 'email', key: 'email' },
    {
      title: '注册时间',
      dataIndex: 'registerDate',
      key: 'registerDate',
      sorter: (a, b) => a.registerDate.localeCompare(b.registerDate),
    },
    {
      title: '状态',
      dataIndex: 'status',
      key: 'status',
      render: (status: string) => {
        const { color, label } = statusMap[status] || { color: 'default', label: status };
        return <Tag color={color}>{label}</Tag>;
      },
    },
  ];

  const handleExport = () => {
    setDownloading(true);
    setProgress(0);

    // 模拟下载进度
    const timer = setInterval(() => {
      setProgress((prev) => {
        if (prev >= 100) {
          clearInterval(timer);
          setDownloading(false);
          return 100;
        }
        return prev + 10;
      });
    }, 200);
  };

  return (
    <div className="min-h-screen bg-gray-50 p-6">
      <Card title="用户数据导出" className="max-w-7xl mx-auto">
        {/* 筛选条件区域 */}
        <Space wrap className="mb-4" size="middle">
          <RangePicker
            value={dateRange}
            onChange={(dates) => setDateRange(dates as [dayjs.Dayjs, dayjs.Dayjs] | null)}
          />
          <Select
            mode="multiple"
            placeholder="选择状态"
            style={{ width: 200 }}
            value={selectedStatuses}
            onChange={setSelectedStatuses}
          >
            <Option value="active">活跃</Option>
            <Option value="inactive">未激活</Option>
            <Option value="suspended">已冻结</Option>
          </Select>
          <Search
            placeholder="搜索姓名或邮箱"
            allowClear
            enterButton={<SearchOutlined />}
            style={{ width: 300 }}
            value={searchText}
            onChange={(e) => setSearchText(e.target.value)}
          />
        </Space>

        {/* 数据表格 */}
        <Table
          columns={columns}
          dataSource={mockData}
          rowKey="id"
          pagination={{ pageSize: 10, showTotal: (total) => `共 ${total} 条` }}
          bordered
        />

        {/* 导出操作区 */}
        <div className="mt-4 flex items-center justify-between border-t pt-4">
          <Space>
            <Radio.Group value={exportFormat} onChange={(e) => setExportFormat(e.target.value)}>
              <Radio value="csv">CSV</Radio>
              <Radio value="excel">Excel</Radio>
              <Radio value="pdf">PDF</Radio>
            </Radio.Group>
          </Space>

          <Space>
            {downloading && <Progress percent={progress} size="small" style={{ width: 150 }} />}
            <Button
              type="primary"
              icon={<DownloadOutlined />}
              onClick={handleExport}
              loading={downloading}
            >
              导出
            </Button>
          </Space>
        </div>
      </Card>
    </div>
  );
};

export default ExportPage;

5.4 迭代反馈流程

第一轮：生成基础原型

请生成一个数据导出页面原型

第二轮：添加反馈

这个原型整体不错，但需要调整：

1. 筛选区域太紧凑，增加一些间距
2. 导出按钮不够醒目，使用 Primary 按钮并加大尺寸
3. 添加一个"全选"复选框功能
4. 进度条改为弹窗显示，而不是内嵌

第三轮：细化交互

现在添加以下交互：

1. 日期范围选择后自动刷新表格
2. 导出完成后显示成功提示（notification）
3. 导出失败时显示错误提示
4. 添加"取消导出"按钮

5.5 上下文工程技巧总结

技巧 1：分步引导

不要一次性要求完整功能，而是分步骤：

第一步：生成页面布局
第二步：添加筛选组件
第三步：添加数据表格
第四步：添加导出功能
第五步：添加交互逻辑

技巧 2：提供参考

参考 Ant Design 的 ProTable 组件设计：
https://procomponents.ant.design/components/table

技巧 3：约束输出

代码要求：
- 不使用 class 组件，只用函数式组件 + hooks
- 样式使用 Tailwind CSS，不使用 styled-components
- 类型定义完整，不使用 any

技巧 4：迭代而非重写

保持现有设计，只修改：
1. 将蓝色主题改为绿色
2. 按钮从右边移到中间

5.6 产品经理专属 Prompt 模板

你是【角色：资深产品设计师】，擅长【领域：企业级 SaaS 产品设计】。

## 任务背景
【简要描述产品需求和目标用户】

## 设计要求
1. 设计风格：【简洁/活泼/专业/...】
2. 参考产品：【类似产品的截图或链接】
3. 设计系统：【Ant Design / Material Design / ...】

## 页面元素
- 【元素 1】：【描述】
- 【元素 2】：【描述】
- ...

## 交互流程
1. 用户首先...
2. 然后点击...
3. 最后...

## 输出要求
- 技术栈：React + Tailwind CSS
- 包含示例数据
- 包含完整类型定义

5.7 模块 5 小结

关键收获：

上下文工程 = 角色 + 约束 + 组件 + 格式
分步引导比一次性生成效果更好
迭代反馈可以精确控制输出
产品经理可以用这套方法生成高保真原型

产品经理工作流程：

需求文档 → 上下文工程 Prompt → 高保真原型 → 需求评审 → 开发交接

模块 6：最佳实践与 Q&A（20 分钟）

6.1 推荐 Skill 清单

日常开发高频 Skill

Skill	使用频率	典型场景	命令示例
`brainstorming`	⭐⭐⭐⭐⭐	新功能需求分析、架构设计	`/superpowers:brainstorming 添加用户反馈功能`
`writing-plans`	⭐⭐⭐⭐⭐	复杂任务分解	`/superpowers:writing-plans`
`executing-plans`	⭐⭐⭐⭐⭐	自动执行任务清单	`/superpowers:executing-plans`
`requesting-code-review`	⭐⭐⭐⭐⭐	代码提交前审查	`/superpowers:requesting-code-review`
`test`	⭐⭐⭐⭐⭐	生成测试用例	`/superpowers:test`

按需使用的 Skill

Skill	使用频率	典型场景
`frontend-design`	⭐⭐⭐⭐	前端 UI 开发
`security-scan`	⭐⭐⭐	安全敏感代码审查
`simplify`	⭐⭐⭐	代码重构和优化
`refactor`	⭐⭐⭐	大规模代码重构
`docs`	⭐⭐	生成文档

Skill 组合使用模式

模式 1：新功能开发

brainstorming → writing-plans → executing-plans → frontend-design → test → code-review

模式 2：Bug 修复

brainstorming（分析原因）→ writing-plans → executing-plans → test

模式 3：代码重构

simplify → refactor → test → code-review

6.2 推荐 MCP 服务器

官方推荐

服务器	用途	安装命令
`filesystem`	文件操作	`npx -y @modelcontextprotocol/server-filesystem /path`
`git`	Git 操作	`npx -y @modelcontextprotocol/server-git`
`github`	GitHub 集成	`npx -y @modelcontextprotocol/server-github`
`postgres`	PostgreSQL	`npx -y @modelcontextprotocol/server-postgres`
`puppeteer`	浏览器自动化	`npx -y @modelcontextprotocol/server-puppeteer`

社区推荐

服务器	用途
`brave-search`	网页搜索
`memory`	长期记忆存储
`time`	时间相关操作
`fetch`	网页内容抓取

自定义 MCP

参考模块 3，为公司内部系统开发专属 MCP 服务：

数据库查询服务
内部 API 调用服务
业务系统对接服务

6.3 常见问题解答（FAQ）

Q1: AI 生成的代码可靠吗？

A: AI 生成的代码需要审查和测试。建议使用流程：

AI 生成代码 → requesting-code-review → 修复问题 → test → 人工复核 → 提交

最佳实践：

永远不要直接提交 AI 生成的代码
使用 requesting-code-review 技能进行审查
确保测试覆盖率
关键代码人工复核

Q2: SDD 流程会不会太慢？

A: 初期可能稍慢（熟悉流程），但熟练后效率更高：

阶段	传统开发	SDD 开发
需求分析	30 分钟（人工）	10 分钟（brainstorming）
任务分解	20 分钟（人工）	5 分钟（writing-plans）
编码	60 分钟（人工）	20 分钟（executing-plans）
代码审查	20 分钟（人工）	5 分钟（requesting-code-review）
测试	30 分钟（人工）	10 分钟（test）
总计	160 分钟	50 分钟

Q3: 如何说服团队采用 AI 编程工具？

A: 用小步快跑的方式证明价值：

选择试点项目 – 选择一个非核心项目作为试点
量化收益 – 记录开发时间、代码质量、测试覆盖率等指标
分享案例 – 在团队内部分享成功案例
培训赋能 – 组织培训帮助同事上手
持续优化 – 收集团队反馈，优化使用流程

Q4: Trae 和 Claude Code 应该选哪个？

A: 两者互补，根据场景选择：

场景	推荐工具	理由
深度理解项目	Claude Code	上下文理解能力强
使用技能系统	Claude Code	superpowers 生态完善
长时间自主任务	Trae	自主执行能力强
简单代码补全	任意	差异不大

推荐配置：Claude Code（主力）+ Trae（辅助）

Q5: 如何保证 AI 不泄露公司代码？

A: 采取以下安全措施：

本地部署 – 使用本地模型（如有条件）
代码脱敏 – 移除敏感信息后再发送
权限控制 – 限制 AI 访问的文件范围
审计日志 – 记录所有 AI 交互
人工复核 – 所有输出必须人工复核

Q6: 技能执行失败怎么办？

A: 按以下顺序排查：

检查技能是否安装
```
/superpowers:list
```

检查技能版本

# 更新技能
# 根据技能安装方式更新

查看错误信息
- 仔细阅读错误提示
- 常见错误：依赖缺失、配置错误、权限不足
寻求帮助
- 查看技能文档
- 在 GitHub 提 issue
- 在社区询问

6.4 学习路径与行动计划

第一周：基础入门

安装 Claude Code 并登录
配置 MCP 服务器（filesystem、git）
尝试使用 brainstorming 技能
完成一个小功能（如添加一个 API 端点）

第二周：技能熟悉

熟悉所有高频 Skill
完成 SDD 全流程练习
配置 2-3 个 MCP 服务器
在实际项目中使用一次完整流程

第三周：进阶应用

学习自定义 MCP 服务开发
为团队创建一个实用 MCP 服务
分享使用经验给同事
优化团队开发流程

第四周：融会贯通

总结最佳实践
建立团队使用规范
持续优化工作流
关注社区动态和更新

6.5 资源推荐

官方文档

社区资源

学习视频

（待补充）

培训总结

核心内容回顾

基础概念
- MCP：标准化的 AI 工具接口
- Skill：可复用的工作流封装
- SDD：技能驱动的开发流程
实战技能
- 数据导出模块开发（brainstorming → writing-plans → executing-plans → frontend-design → code-review → test）
- 自定义 MCP 服务开发（协议解析 → 脚手架 → 业务逻辑 → 配置集成）
- 高保真原型生成（上下文工程四要素）
最佳实践
- 高频 Skill 清单
- 推荐 MCP 服务器
- 常见问题解答

下一步行动

个人练习 – 完成学习路径中的四周计划
团队分享 – 将本次培训内容分享给更多同事
实战应用 – 在实际项目中应用 SDD 流程
持续优化 – 总结经验，建立团队规范

附录 A：命令速查表

Claude Code 基础命令

# 安装
npm install -g @anthropic-ai/claude-code

# 登录
claude login

# 启动
claude

# 清除对话
/clear

# 获取帮助
/help

常用 Skill 命令

# 需求分析
/superpowers:brainstorming <需求描述>

# 生成计划
/superpowers:writing-plans

# 执行计划
/superpowers:executing-plans

# 代码审查
/superpowers:requesting-code-review

# 生成测试
/superpowers:test

# 前端设计
/superpowers:frontend-design

MCP 服务器配置

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    }
  }
}

附录 B：项目结构示例

Spring Boot 项目结构

spring-boot-demo/
├── src/main/java/com/example/demo/
│   ├── controller/
│   │   ├── BookController.java
│   │   └── ExportController.java (新增)
│   ├── service/
│   │   ├── BookService.java
│   │   └── ExportService.java (新增)
│   ├── repository/
│   │   ├── BookRepository.java
│   │   └── UserRepository.java
│   ├── model/
│   │   ├── Book.java
│   │   └── User.java
│   └── config/
│       └── WebConfig.java
├── src/main/resources/
│   ├── application.properties
│   └── data.sql
├── .claude/
│   └── settings.json
└── pom.xml

MCP 服务项目结构

mcp-db-server/
├── src/
│   └── index.ts
├── dist/
│   └── index.js
├── package.json
├── tsconfig.json
├── .env
└── .claude/
    └── settings.json

附录 C：Troubleshooting

问题 1：技能无法加载

现象：执行 /superpowers:xxx 无响应

解决方案：

检查技能是否已安装
检查网络连接
重启 Claude Code

问题 2：MCP 服务器连接失败

现象：Claude 无法调用 MCP 工具

解决方案：

检查 MCP 服务器路径是否正确
检查环境变量配置

手动运行 MCP 服务器测试：

npx -y @modelcontextprotocol/server-filesystem /path

问题 3：AI 生成代码不符合项目规范

现象：生成的代码风格与项目不一致

解决方案：

在 Prompt 中明确说明项目规范
提供参考文件让 AI 学习
使用 simplify 技能进行代码审查和优化

THE END

未分类

MCP 和 Skill 实战

AI 编程工具分类

为什么选择 Claude Code？

环境准备

模块 1：基础概念

1.1 什么是 MCP？

核心概念

MCP 的三种接口类型

推荐的 MCP 服务器

1.2 什么是 Skill？

superpowers 技能系统

SDD（Skill-Driven Development）流程

1.3 安装与配置演示

步骤 1：配置 Claude Code

步骤 2：配置 MCP 服务器

步骤 3：验证配置

1.4 技能使用演示

启动技能

查看可用技能

技能调用示例

模块 1 小结

模块 2：数据导出模块实战

2.1 案例介绍

功能需求

技术栈

2.2 SDD 流程演示

步骤 1：brainstorming（需求分析与设计）

步骤 2：writing-plans（生成实现计划）

步骤 3：executing-plans（执行计划）

步骤 4：frontend-design（前端设计规范）

步骤 5：code-review（代码审查）

步骤 6：test（测试生成与验证）

2.3 模块 2 小结

模块 3：自定义 Skill 开发实战

3.1 为什么需要自定义 Skill？

3.2 Skill 结构解析

Skill 文件组成

SKILL.md 标准结构

3.3 实战：开发 API 文档生成 Skill

步骤 1：创建 Skill 目录

步骤 2：编写 SKILL.md

步骤 3：配置和使用自定义 Skill

步骤 4：使用 Skill

3.4 Skill 执行过程演示

3.5 模块 3 小结

模块 4：自定义 MCP 服务开发

4.1 为什么需要自定义 MCP 服务？

4.2 MCP 协议解析

MCP 架构

三种接口类型

4.3 脚手架搭建

步骤 1：创建项目

步骤 2：配置 tsconfig.json

步骤 3：配置 package.json

4.4 业务逻辑实现

完整代码示例 – src/index.ts

4.5 配置与集成

步骤 1：构建项目

步骤 2：配置 Claude Code

步骤 3：验证配置

步骤 4：环境变量管理（推荐）

4.6 安全最佳实践

1. SQL 注入防护

2. 权限控制

3. 审计日志

4. 查询限制

4.7 扩展：添加更多功能

添加 Schema 浏览工具

添加数据导出工具

4.8 模块 4 小结

模块 5：高保真原型生成（30 分钟，产品经理重点）

5.1 什么是上下文工程？

传统 Prompt vs 上下文工程

5.2 上下文工程四要素

要素 1：角色设定（Role）

要素 2：设计约束（Constraints）

要素 3：组件引用（Components）

要素 4：输出格式（Format）

5.3 实战案例：数据导出功能原型

完整 Prompt 示例