Skip to content

Latest commit

 

History

History
788 lines (696 loc) · 22.3 KB

Cursor-API-Testing-MCP-Development-Prompt.md

File metadata and controls

788 lines (696 loc) · 22.3 KB

Cursor API 接口测试 MCP 开发需求提示词

📋 项目背景

基于苗影速选后端系统 API 测试实践经验，我们需要开发一个专门用于 Cursor 环境的 API 接口测试 MCP 服务器，以提升 API 测试的效率和质量。

🎯 核心需求

1. 自动化 API 测试执行

  • 功能: 基于 Swagger/OpenAPI 文档自动执行 API 测试
  • 输入: Swagger 文档 URL 或 JSON 文件路径
  • 输出: 结构化的测试报告（Markdown 格式）
  • 特性:
    • 自动解析 API 端点和参数
    • 支持认证 Token 管理（JWT、Bearer Token）
    • 智能参数填充（基于 Schema 生成测试数据）
    • 并发测试执行优化

2. 智能测试报告生成

  • 功能: 生成专业的 API 测试报告
  • 格式: Markdown 文档，支持中文
  • 内容包含:
    • 测试概览统计（成功率、响应时间、错误分类）
    • 按模块分组的详细测试结果
    • 错误分析和修复建议
    • 性能指标分析
    • 问题优先级分类

3. 错误智能分析

  • 功能: 基于常见错误模式提供修复建议
  • 错误类型识别:
    • 参数验证错误（400 Bad Request）
    • 认证授权错误（401/403）
    • 服务器内部错误（500）
    • 业务逻辑错误
    • 数据库约束冲突
  • 智能建议: 基于错误信息提供具体的修复方案

4. 测试数据管理

  • 功能: 智能生成和管理测试数据
  • 特性:
    • 基于 JSON Schema 自动生成测试数据
    • 支持数据依赖关系（如先创建用户再创建订单）
    • 测试数据清理和重置
    • 支持多环境配置（开发、测试、生产）

🛠️ 技术规格

MCP 服务器架构

基于官方 MCP TypeScript SDK 的标准架构：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// 创建 MCP 服务器实例
const server = new McpServer({
  name: "cursor-api-testing-mcp",
  version: "1.0.0"
});

// 核心工具集设计（符合 MCP 单一职责原则）
const tools = {
  // 1. 解析 Swagger 文档
  parse_swagger_doc: {
    parameters: {
      swagger_url: z.string().url(),
      base_url: z.string().url().optional()
    }
  },

  // 2. 测试单个 API 端点
  test_single_endpoint: {
    parameters: {
      endpoint: z.string(),
      method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']),
      auth_token: z.string().optional(),
      test_data: z.any().optional(),
      timeout: z.number().default(5000)
    }
  },

  // 3. 批量测试模块
  batch_test_module: {
    parameters: {
      module_name: z.string(),
      endpoints: z.array(z.string()),
      concurrent_limit: z.number().default(5),
      auth_token: z.string().optional()
    }
  },

  // 4. 智能错误分析
  analyze_error_pattern: {
    parameters: {
      error_message: z.string(),
      status_code: z.number(),
      endpoint: z.string(),
      context: z.any().optional()
    }
  },

  // 5. 生成测试数据
  generate_test_data: {
    parameters: {
      json_schema: z.any(),
      data_type: z.enum(['create', 'update', 'query']),
      dependencies: z.array(z.string()).optional()
    }
  },

  // 6. 生成测试报告
  generate_markdown_report: {
    parameters: {
      test_results: z.array(z.any()),
      template: z.enum(['detailed', 'summary', 'chinese']).default('chinese'),
      output_path: z.string().optional()
    }
  },

  // 7. 管理测试环境
  configure_test_environment: {
    parameters: {
      environment: z.enum(['development', 'testing', 'production']),
      config: z.object({
        base_url: z.string().url(),
        timeout: z.number().default(10000),
        concurrent_limit: z.number().default(5),
        auth_config: z.any().optional()
      })
    }
  },

  // 8. 清理测试数据
  cleanup_test_data: {
    parameters: {
      cleanup_type: z.enum(['all', 'failed_tests', 'temp_data']),
      confirm: z.boolean().default(false)
    }
  }
};

// 资源定义（用于数据访问）
const resources = {
  test_reports: "report://latest",           // 最新测试报告
  test_progress: "progress://current",       // 当前测试进度
  environment_config: "config://env",       // 环境配置
  error_patterns: "patterns://errors",      // 错误模式库
  test_templates: "templates://tests"       // 测试模板
};

标准化数据结构

基于 MCP SDK 标准和我们的实际测试经验：

// MCP 工具响应格式（符合 MCP 规范）
interface MCPToolResponse {
  content: Array<{
    type: "text" | "resource_link";
    text?: string;
    uri?: string;
    name?: string;
    mimeType?: string;
  }>;
  isError?: boolean;
}

// 测试结果数据结构（内部使用）
interface APITestResult {
  endpoint: string;
  method: string;
  status: 'success' | 'failed' | 'timeout';
  statusCode: number;
  responseTime: number;
  errorMessage?: string;
  errorCategory?: 'validation' | 'auth' | 'server' | 'business' | 'network';
  suggestions?: string[];
  timestamp: string;
}

// 错误分析结果
interface ErrorAnalysisResult {
  pattern: string;
  category: string;
  severity: 'low' | 'medium' | 'high' | 'critical';
  description: string;
  fixSuggestions: string[];
  affectedEndpoints: string[];
  documentationLinks?: string[];
}

// 测试进度信息
interface TestProgress {
  currentModule: string;
  completedTests: number;
  totalTests: number;
  failedTests: number;
  elapsedTime: number;
  estimatedRemaining: number;
  currentEndpoint?: string;
}

🎨 用户体验设计

1. 符合 MCP 规范的工具调用

基于实际的 MCP 工具调用格式：

// 1. 解析 Swagger 文档并开始测试
await client.callTool({
  name: "parse_swagger_doc",
  arguments: {
    swagger_url: "http://localhost:3000/docs-json",
    base_url: "http://localhost:3000"
  }
});

// 2. 测试单个端点
await client.callTool({
  name: "test_single_endpoint",
  arguments: {
    endpoint: "/api/v1/orders/{id}",
    method: "GET",
    auth_token: "Bearer eyJhbGciOiJIUzI1NiIs...",
    timeout: 5000
  }
});

// 3. 批量测试模块
await client.callTool({
  name: "batch_test_module",
  arguments: {
    module_name: "订单管理模块",
    endpoints: ["/orders", "/orders/{id}", "/orders/statistics"],
    concurrent_limit: 3,
    auth_token: "Bearer eyJhbGciOiJIUzI1NiIs..."
  }
});

// 4. 智能错误分析
await client.callTool({
  name: "analyze_error_pattern",
  arguments: {
    error_message: "Store ID is required for class Order extends base_entity_1.StoreBaseEntity",
    status_code: 500,
    endpoint: "/api/v1/orders/{id}",
    context: { userType: "super_admin", operation: "findOne" }
  }
});

// 5. 生成测试报告
await client.callTool({
  name: "generate_markdown_report",
  arguments: {
    test_results: testResultsArray,
    template: "chinese",
    output_path: "./API测试报告-苗影速选后端系统.md"
  }
});

2. 智能测试流程

  1. 自动发现: 解析 Swagger 文档，识别所有 API 端点
  2. 智能排序: 根据依赖关系排序测试执行顺序
  3. 数据准备: 自动生成或使用预设测试数据
  4. 并发执行: 合理控制并发数，避免服务器过载
  5. 实时反馈: 显示测试进度和实时结果
  6. 报告生成: 自动生成详细的测试报告

3. 错误处理和恢复

  • 网络错误: 自动重试机制
  • 认证失效: 自动刷新 Token
  • 服务器过载: 动态调整并发数
  • 数据冲突: 智能数据清理和重置

📊 实际应用场景

场景1：日常开发测试

// 开发者提交代码后，自动执行 API 测试
const result = await mcp_api-testing_execute_full_test({
  swagger_url: "http://localhost:3000/docs-json",
  auth_token: await getAuthToken(),
  test_modules: ["认证授权", "用户管理", "订单管理"],
  generate_report: true
});

if (result.summary.successRate < 0.8) {
  console.log("⚠️ API 测试失败率过高，请检查以下问题：");
  result.recommendations.forEach(rec => console.log(`- ${rec.message}`));
}

场景2：CI/CD 集成

// 在 CI/CD 流水线中集成 API 测试
const testResult = await mcp_api-testing_execute_ci_test({
  environment: "test",
  coverage_threshold: 0.9,
  performance_threshold: 500, // ms
  fail_on_error: true
});

// 生成测试报告并上传到测试管理平台
await mcp_api-testing_upload_report({
  result: testResult,
  platform: "jenkins",
  build_number: process.env.BUILD_NUMBER
});

场景3：API 质量监控

// 定期执行 API 健康检查
const healthCheck = await mcp_api-testing_health_check({
  endpoints: ["GET /health", "GET /api/v1/status"],
  interval: "5m",
  alert_threshold: 0.95
});

// 性能回归测试
const regressionTest = await mcp_api-testing_regression_test({
  baseline_report: "./baseline-report.json",
  current_results: testResults,
  performance_tolerance: 0.1 // 10% 性能下降容忍度
});

🔧 配置和扩展

1. 环境配置

{
  "environments": {
    "development": {
      "base_url": "http://localhost:3000",
      "timeout": 5000,
      "concurrent_limit": 5
    },
    "testing": {
      "base_url": "https://test-api.example.com",
      "timeout": 10000,
      "concurrent_limit": 10
    },
    "production": {
      "base_url": "https://api.example.com",
      "timeout": 15000,
      "concurrent_limit": 3
    }
  }
}

2. 测试模板配置

# 测试报告模板
report_template:
  language: "zh"
  sections:
    - summary
    - module_results
    - error_analysis
    - performance_metrics
    - recommendations
  format: "markdown"
  include_charts: true

3. 错误规则配置

const errorRules = {
  "Store ID is required": {
    category: "business_logic",
    severity: "high",
    suggestion: "检查 StoreBaseEntity 继承问题，确保超级管理员权限正确处理",
    fix_examples: [
      "在 Repository 层添加超级管理员权限检查",
      "修改 API 定义明确要求 storeId 参数"
    ]
  },
  "Cannot read properties of undefined": {
    category: "parameter_validation",
    severity: "medium",
    suggestion: "添加请求体参数验证，确保必需参数存在",
    fix_examples: [
      "使用 class-validator 装饰器验证参数",
      "添加 DTO 参数验证"
    ]
  }
};

🚀 开发优先级

Phase 1: 核心功能（MVP）

  1. ✅ 基础 API 测试执行 - 支持 GET/POST/PUT/DELETE 请求
  2. ✅ Swagger 文档解析 - 自动识别 API 端点和参数
  3. ✅ 基础测试报告生成 - Markdown 格式输出
  4. ✅ JWT Token 认证支持 - 自动管理认证状态

Phase 2: 智能化增强

  1. 🔄 智能错误分析 - 基于常见错误模式提供修复建议
  2. 🔄 测试数据自动生成 - 基于 JSON Schema 生成测试数据
  3. 🔄 并发测试优化 - 提升测试执行效率
  4. 🔄 多环境配置支持 - 支持开发/测试/生产环境

Phase 3: 高级功能

  1. ⏳ 性能监控和分析 - API 性能回归测试
  2. ⏳ CI/CD 集成 - 与主流 CI/CD 平台集成
  3. ⏳ 可视化报告 - 生成图表和可视化测试报告
  4. ⏳ API 契约测试 - 支持 API 版本兼容性测试

📝 开发指南

1. MCP 服务器核心实现

基于官方 MCP TypeScript SDK 的标准实现：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// 创建 MCP 服务器
const server = new McpServer({
  name: "cursor-api-testing-mcp",
  version: "1.0.0"
});

// 注册核心测试工具
server.registerTool(
  "parse_swagger_doc",
  {
    title: "解析 Swagger 文档",
    description: "解析 Swagger/OpenAPI 文档并提取 API 端点信息",
    inputSchema: {
      swagger_url: z.string().url().describe("Swagger 文档的 URL"),
      base_url: z.string().url().optional().describe("API 基础 URL")
    }
  },
  async ({ swagger_url, base_url }) => {
    try {
      const response = await fetch(swagger_url);
      const swaggerDoc = await response.json();
      
      const endpoints = extractEndpoints(swaggerDoc, base_url);
      
      return {
        content: [{
          type: "text",
          text: `成功解析 Swagger 文档，发现 ${endpoints.length} 个 API 端点`
        }, {
          type: "resource_link",
          uri: "swagger://parsed",
          name: "解析结果",
          mimeType: "application/json"
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `解析失败: ${error.message}`
        }],
        isError: true
      };
    }
  }
);

server.registerTool(
  "test_single_endpoint",
  {
    title: "测试单个 API 端点",
    description: "对指定的 API 端点执行测试",
    inputSchema: {
      endpoint: z.string().describe("API 端点路径"),
      method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).describe("HTTP 方法"),
      auth_token: z.string().optional().describe("认证 Token"),
      test_data: z.any().optional().describe("测试数据"),
      timeout: z.number().default(5000).describe("超时时间（毫秒）")
    }
  },
  async ({ endpoint, method, auth_token, test_data, timeout }) => {
    const startTime = Date.now();
    
    try {
      const result = await executeAPITest({
        endpoint,
        method,
        auth_token,
        test_data,
        timeout
      });
      
      const responseTime = Date.now() - startTime;
      
      return {
        content: [{
          type: "text",
          text: `✅ ${method} ${endpoint} 测试成功\n状态码: ${result.statusCode}\n响应时间: ${responseTime}ms`
        }]
      };
    } catch (error) {
      const responseTime = Date.now() - startTime;
      
      return {
        content: [{
          type: "text",
          text: `❌ ${method} ${endpoint} 测试失败\n错误: ${error.message}\n响应时间: ${responseTime}ms`
        }],
        isError: true
      };
    }
  }
);

// 注册测试报告资源
server.registerResource(
  "test_report",
  "report://latest",
  {
    title: "最新测试报告",
    description: "最近一次 API 测试的详细报告",
    mimeType: "text/markdown"
  },
  async (uri) => {
    const report = await generateLatestReport();
    return {
      contents: [{
        uri: uri.href,
        text: report,
        mimeType: "text/markdown"
      }]
    };
  }
);

// 启动服务器
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Cursor API Testing MCP Server started");
}

main().catch(console.error);

2. Cursor MCP 配置

为了在 Cursor 中使用这个 MCP 服务器，需要在 ~/.cursor/mcp.json 中添加配置：

{
  "servers": {
    "cursor-api-testing": {
      "command": "node",
      "args": ["path/to/cursor-api-testing-mcp/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

3. 项目结构

cursor-api-testing-mcp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts                 # 主入口文件
│   ├── server.ts               # MCP 服务器实现
│   ├── tools/                  # 工具实现
│   │   ├── swagger-parser.ts   # Swagger 解析器
│   │   ├── api-tester.ts       # API 测试执行器
│   │   ├── report-generator.ts # 报告生成器
│   │   └── error-analyzer.ts   # 错误分析器
│   ├── resources/              # 资源管理
│   │   ├── test-reports.ts     # 测试报告资源
│   │   └── configurations.ts   # 配置资源
│   ├── types/                  # 类型定义
│   │   └── index.ts
│   └── utils/                  # 工具函数
│       ├── http-client.ts      # HTTP 客户端
│       └── data-generator.ts   # 测试数据生成器
├── dist/                       # 编译输出
└── README.md

4. 安装和构建

# 创建项目
npm init -y
npm install @modelcontextprotocol/sdk zod axios

# 开发依赖
npm install -D typescript @types/node tsx

# 构建脚本 (package.json)
{
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts",
    "start": "node dist/index.js"
  }
}

# TypeScript 配置 (tsconfig.json)
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

5. 基于实际经验的错误分析规则

根据我们测试 89 个 API 的经验，内置常见错误模式：

// 错误分析规则库
const ERROR_PATTERNS = {
  "Store ID is required": {
    category: "business_logic",
    severity: "high",
    description: "StoreBaseEntity 继承问题导致的系统性错误",
    suggestions: [
      "检查 Repository 层是否正确处理超级管理员权限",
      "修改 API 定义明确要求 storeId 参数",
      "在 BaseRepository 中添加权限检查逻辑"
    ],
    affectedPattern: /Store ID is required for class \w+ extends base_entity_1\.StoreBaseEntity/,
    documentationLinks: [
      "https://typeorm.io/repository-api",
      "https://docs.nestjs.com/techniques/database#repository-pattern"
    ]
  },
  
  "Cannot read properties of undefined": {
    category: "validation",
    severity: "medium", 
    description: "请求体参数验证缺失",
    suggestions: [
      "添加 DTO 参数验证装饰器",
      "使用 class-validator 进行参数检查",
      "在控制器方法中添加参数存在性检查"
    ],
    affectedPattern: /Cannot read properties of undefined \(reading '(\w+)'\)/,
    documentationLinks: [
      "https://docs.nestjs.com/techniques/validation",
      "https://github.com/typestack/class-validator"
    ]
  },

  "duplicate key value violates unique constraint": {
    category: "business_logic",
    severity: "medium",
    description: "数据库唯一约束冲突",
    suggestions: [
      "在创建前检查记录是否已存在",
      "返回 400 Bad Request 而非 500 Internal Server Error",
      "提供更友好的错误消息"
    ],
    affectedPattern: /duplicate key value violates unique constraint "(\w+)"/
  },

  "Validation failed": {
    category: "validation", 
    severity: "low",
    description: "参数类型或格式验证失败",
    suggestions: [
      "检查 Swagger UI 默认参数值",
      "更新 DTO 验证规则",
      "处理空字符串和类型转换"
    ],
    affectedPattern: /Validation failed \((.+)\)/
  }
};

// 智能错误分析工具实现
server.registerTool(
  "analyze_error_pattern",
  {
    title: "智能错误分析",
    description: "基于常见错误模式分析并提供修复建议",
    inputSchema: {
      error_message: z.string().describe("错误信息"),
      status_code: z.number().describe("HTTP 状态码"),
      endpoint: z.string().describe("出错的 API 端点"),
      context: z.any().optional().describe("额外上下文信息")
    }
  },
  async ({ error_message, status_code, endpoint, context }) => {
    // 匹配错误模式
    const matchedPattern = findMatchingPattern(error_message, ERROR_PATTERNS);
    
    if (matchedPattern) {
      const analysis = {
        pattern: matchedPattern.name,
        category: matchedPattern.category,
        severity: matchedPattern.severity,
        description: matchedPattern.description,
        suggestions: matchedPattern.suggestions,
        endpoint: endpoint,
        statusCode: status_code
      };
      
      return {
        content: [{
          type: "text",
          text: `🔍 **错误分析结果**

**错误模式**: ${analysis.pattern}
**分类**: ${analysis.category}
**严重程度**: ${analysis.severity}
**影响端点**: ${analysis.endpoint}

**问题描述**:
${analysis.description}

**修复建议**:
${analysis.suggestions.map((s, i) => `${i + 1}. ${s}`).join('\n')}

**相关文档**:
${matchedPattern.documentationLinks?.map(link => `- ${link}`).join('\n') || '无'}`
        }]
      };
    } else {
      return {
        content: [{
          type: "text",
          text: `⚠️ 未识别的错误模式: ${error_message}\n\n建议手动分析或添加到错误模式库中。`
        }]
      };
    }
  }
);

🎯 成功指标

功能指标

  • ✅ 支持 90% 以上的常见 API 测试场景
  • ✅ 自动生成专业的测试报告
  • ✅ 提供准确的错误分析和修复建议
  • ✅ 支持多种认证方式（JWT、OAuth、API Key）

性能指标

  • ⚡ 单个 API 测试响应时间 < 2s
  • ⚡ 100 个 API 并发测试完成时间 < 30s
  • ⚡ 测试报告生成时间 < 5s
  • ⚡ 内存占用 < 100MB

用户体验指标

  • 📚 完整的使用文档和示例
  • 🎨 友好的错误提示和修复建议
  • 🔧 简单的配置和扩展机制
  • 🚀 与 Cursor 环境无缝集成

📞 总结

这个 API 测试 MCP 服务器将极大提升 Cursor 环境下的 API 测试效率，基于我们在苗影速选项目中的实际测试经验，提供智能化的测试执行、错误分析和报告生成功能。

核心价值：

  1. 🚀 效率提升 - 自动化测试执行，节省 80% 手动测试时间
  2. 🎯 质量保证 - 智能错误分析，快速定位和修复问题
  3. 📊 可视化报告 - 专业的测试报告，便于团队协作
  4. 🔧 易于扩展 - 模块化设计，支持自定义测试规则

适用场景：

  • 日常开发测试验证
  • CI/CD 流水线集成
  • API 质量监控
  • 性能回归测试
  • 团队协作和知识分享