Api Tester

API 测试器 MCP 服务

这是一款面向 QA/SDET 工程师的全面 Model Context Protocol（MCP）服务，支持 Swagger/OpenAPI 和 Postman 集合，提供 API 测试能力。

🎉 现已在 NPM 上发布！ 使用 npx @kirti676/api-tester-mcp@latest 安装

🆕 最新动态

• ✅ 增强的进度跟踪 - 实时显示进度、完成百分比和预计剩余时间
• ✅ 可视化进度条 - ASCII 进度条和里程碑通知
• ✅ 性能指标 - 吞吐量计算和执行摘要
• ✅ 已发布到 NPM - 使用 NPX 即可立即安装
• ✅ VS Code 集成 - 一键安装按钮
• ✅ 简化设置 - 无需手动安装 Python
• ✅ 跨平台支持 - 可在 Windows、macOS 和 Linux 上运行
• ✅ 自动更新 - 使用 @latest 始终获取最新版本

🚀 开始使用

📦 安装

API Tester MCP 服务可通过 npx 直接使用，无需安装：

npx @kirti676/api-tester-mcp@latest

⚡ 快速安装：

🤖 Claude Desktop

请按照 MCP 安装指南，并使用下方的标准配置：

{
  "mcpServers": {
    "api-tester": {
      "command": "npx",
      "args": ["@kirti676/api-tester-mcp@latest"]
    }
  }
}

🔗 其他 MCP 客户端

标准配置适用于大多数 MCP 客户端：

{
  "mcpServers": {
    "api-tester": {
      "command": "npx",
      "args": ["@kirti676/api-tester-mcp@latest"]
    }
  }
}

🖥️ 支持的客户端：

• 🤖 Claude Desktop
• 💻 支持 MCP 扩展的 VS Code
• ⚡ Cursor
• 🌊 Windsurf
• 🪿 Goose
• 🔧 任何其他兼容 MCP 的客户端

🐍 Python 安装（替代方式）

pip install api-tester-mcp

💻 从源代码构建

git clone https://github.com/kirti676/api_tester_mcp.git
cd api_tester_mcp
npm install

⚡ 快速开始

立即试用 API Tester MCP 服务：

# Run the server
npx @kirti676/api-tester-mcp@latest

# Check version
npx @kirti676/api-tester-mcp@latest --version

# Get help
npx @kirti676/api-tester-mcp@latest --help

对于 Claude Desktop 等 MCP 客户端，请使用以下配置：

{
  "mcpServers": {
    "api-tester": {
      "command": "npx",
      "args": ["@kirti676/api-tester-mcp@latest"]
    }
  }
}

✨ 功能

• 📥 输入支持：OpenAPI/Swagger 文档、Postman 集合和 GraphQL 模式
• 🔄 测试生成：自动生成 API 和负载测试场景
• 🌐 多语言支持：生成 TypeScript/Playwright、JavaScript/Jest、Python/pytest 等语言的测试
• ⚡ 测试执行：运行生成的测试并提供详细报告
• 🔐 智能身份验证检测：自动分析环境变量并提供配置指南
• 🔐 身份验证：通过 set_env_vars 支持 Bearer 令牌和 API 密钥
• 📊 HTML 报告：通过 MCP 资源提供美观、易于访问的报告
• 📈 实时进度：实时更新进度条和完成百分比
• ⏱️ ETA 计算：估算所有操作的完成时间
• 🎯 里程碑跟踪：在关键进度节点（25%、50%、75% 等）发送特别通知
• 📊 性能指标：吞吐量计算和执行摘要
• ✅ 模式验证：根据模式示例生成请求正文
• 🎯 断言：针对每个端点的状态码断言（2xx、4xx、5xx）
• 📦 项目生成：生成包含依赖项和配置的完整项目脚手架

🌐 多语言测试生成

API Tester MCP 现在支持使用多种编程语言和测试框架生成测试代码：

🔧 支持的语言/框架组合

语言	框架	描述	使用场景
📘 TypeScript	🎭 Playwright	现代端到端测试，具备出色的 API 支持	🏢 企业级 Web 应用
📘 TypeScript	🚀 Supertest	专注于 Express.js 的 API 测试	🟢 Node.js 后端服务
📙 JavaScript	🃏 Jest	流行的测试框架，生态系统完善	🔧 通用 API 测试
📙 JavaScript	🌲 Cypress	端到端测试，提供出色的开发者体验	🌐 全栈应用
🐍 Python	🧪 pytest	全面的测试能力，支持夹具和插件	📊 数据密集型 API 和 ML 服务
🐍 Python	📡 requests	简单的 HTTP 测试，可快速验证	⚡ 快速原型开发和脚本

🎯 语言选择工作流

// 1. Get available languages and frameworks
const languages = await mcp.call("get_supported_languages");

// 2. Choose your preferred combination
await mcp.call("ingest_spec", {
  spec_type: "openapi",
  file_path: "./path/to/your/api-spec.json",
  preferred_language: "typescript",    // python, typescript, javascript
  preferred_framework: "playwright"     // varies by language
});

// 3. Generate test cases with code
await mcp.call("generate_test_cases", {
  language: "typescript",
  framework: "playwright"
});

// 4. Get complete project setup
await mcp.call("generate_project_files", {
  language: "typescript",
  framework: "playwright",
  project_name: "my-api-tests",
  include_examples: true
});

📁 生成的项目结构

generate_project_files 工具会创建一个完整且可直接运行的项目：

📘 TypeScript + Playwright：

my-api-tests/
├── 📦 package.json          # Dependencies & scripts
├── ⚙️ playwright.config.ts  # Playwright configuration
├── 📂 tests/
│   └── 🧪 api.spec.ts      # Generated test code
└── 📖 README.md            # Setup instructions

🐍 Python + pytest：

my-api-tests/
├── 📋 requirements.txt     # Python dependencies
├── ⚙️ pytest.ini         # pytest configuration
├── 📂 tests/
│   └── 🧪 test_api.py    # Generated test code
└── 📖 README.md          # Setup instructions

📙 JavaScript + Jest：

my-api-tests/
├── 📦 package.json       # Dependencies & scripts
├── ⚙️ jest.config.js     # Jest configuration
├── 📂 tests/
│   └── 🧪 api.test.js   # Generated test code
└── 📖 README.md         # Setup instructions

🎯 框架专属功能

• 🎭 Playwright：浏览器自动化、并行执行、详细报告
• 🃏 Jest：快照测试、模拟、开发时监视模式
• 🧪 pytest：夹具、参数化测试、丰富的插件生态系统
• 🌲 Cypress：交互式调试、时间旅行调试、真实浏览器测试
• 🚀 Supertest：Express.js 集成、中间件测试
• 📡 requests：简单的 API 调用、会话管理、身份验证辅助工具

📈 进度跟踪

API Tester MCP 为所有操作提供全面的进度跟踪：

📊 可视化进度指示器

🎯 API Test Execution: [██████████░░░░░░░░░░] 50.0% (5/10) | ETA: 2.5s - GET /api/users ✅

🔥 功能：

• 📊 进度条：使用已填充/未填充指示符的 ASCII 进度条
• 📈 完成百分比：实时显示完成百分比
• ⏰ ETA 计算：根据当前性能估算完成时间
• 🎯 里程碑通知：在关键进度节点特别突出显示
• ⚡ 性能指标：吞吐量和时间统计
• 📋 操作上下文：关于当前执行步骤的详细信息

✅ 适用于：

• 🎬 场景生成
• 🧪 测试用例生成
• 🚀 API 测试执行
• ⚡ 负载测试执行
• 🔄 所有长时间运行的操作

🛠️ MCP 工具

该服务提供 11 个功能全面的 MCP 工具，并附有详细的参数规范：

1. 📥 ingest_spec - 加载 API 规范

加载 OpenAPI/Swagger、Postman 集合或 GraphQL 模式，并设置语言/框架偏好

{
  "spec_type": "openapi",           // openapi, swagger, postman, graphql (optional, auto-detected)
  "file_path": "./api-spec.json",   // Path to JSON, YAML, or GraphQL schema file (required)
  "preferred_language": "python",   // python, typescript, javascript (optional, default: python)
  "preferred_framework": "requests" // pytest, requests, playwright, jest, cypress, supertest (optional, default: requests)
}

2. 🔧 set_env_vars - 配置身份验证和环境

设置环境变量，并自动进行验证和提供指导

{
  "variables": {},                  // Dictionary of custom environment variables (optional)
  "baseUrl": null,                 // API base URL (optional)
  "auth_bearer": null,             // Bearer/JWT token (optional)
  "auth_apikey": null,             // API key (optional)
  "auth_basic": null,              // Base64 encoded credentials (optional)
  "auth_username": null,           // Username for basic auth (optional)
  "auth_password": null            // Password for basic auth (optional)
}

3. 🎬 generate_scenarios - 创建测试场景

根据已加载的规范生成测试场景

{
  "include_negative_tests": true,   // Generate failure scenarios (default: true)
  "include_edge_cases": true        // Generate boundary conditions (default: true)
}

4. 🧪 generate_test_cases - 转换为可执行测试

将测试场景转换为首选语言/框架中的可执行测试用例

{
  "scenario_ids": null              // Array of scenario IDs or null for all (optional)
}

5. 🚀 run_api_tests - 执行 API 测试

执行 API 测试，并提供详细结果和报告

{
  "test_case_ids": null,           // Array of test case IDs or null for all (optional)
  "max_concurrent": 10             // Number of concurrent requests 1-50 (default: 10)
}

6. ⚡ run_load_tests - 执行性能测试

使用可配置参数执行负载/性能测试

{
  "test_case_ids": null,           // Array of test case IDs or null for all (optional)
  "duration": 60,                  // Test duration in seconds (default: 60)
  "users": 10,                     // Number of concurrent virtual users (default: 10)
  "ramp_up": 10                    // Ramp up time in seconds (default: 10)
}

7. 🌐 get_supported_languages - 列出语言/框架选项

获取受支持的编程语言和测试框架列表

// No parameters required
{}

8. 📦 generate_project_files - 生成完整项目

生成包含依赖项和配置的完整项目结构

{
  "project_name": null,            // Project folder name (optional, auto-generated if null)
  "include_examples": true         // Include example test files (default: true)
}

9. 📁 get_workspace_info - 工作区信息

获取工作区目录和文件生成位置的信息

// No parameters required
{}

10. 🔍 debug_file_system - 文件系统诊断

获取全面的工作区信息和文件系统诊断结果

// No parameters required
{}

11. 📊 get_session_status - 会话状态和进度

获取当前会话信息及进度详情

// No parameters required
{}

📚 MCP 资源

• file://reports - 列出所有可用的测试报告
• file://reports/{report_id} - 访问单个 HTML 测试报告

💡 MCP 提示词

• create_api_test_plan - 生成全面的 API 测试计划
• analyze_test_failures - 分析测试失败并提供建议

🔍 智能环境变量分析

API Tester MCP 现在会自动分析你的 API 规范，以检测所需的环境变量，并提供实用的设置指导：

🎯 自动检测

• 🔐 身份验证方案：Bearer 令牌、API 密钥、Basic 身份验证、OAuth2
• 🌐 基础 URL：从规范中的 servers/hosts 提取
• 🔗 模板变量：Postman 集合变量，例如 {{baseUrl}}、{{authToken}}
• 📍 路径参数：路径中的动态值，例如 /users/{userId}

💡 智能建议

// 1. Ingest specification - automatic analysis included
const result = await mcp.call("ingest_spec", {
  spec_type: "openapi",
  file_path: "./api-specification.json"
});

// Check the setup message for immediate guidance
console.log(result.setup_message);
// "⚠️ 2 required environment variable(s) detected..."

// 2. Get detailed setup instructions
const suggestions = await mcp.call("get_env_var_suggestions");
console.log(suggestions.setup_instructions);
// Provides copy-paste ready configuration examples

🎯 默认参数键

现在，所有 MCP 工具都会提供实用的默认参数键，帮助用户了解可以设置哪些值：

🔧 环境变量（set_env_vars）

🔑 所有参数均为可选项——只需提供所需参数：

// Option 1: Just the base URL
await mcp.call("set_env_vars", {
  baseUrl: "https://api.example.com/v1"
});

// Option 2: Just authentication
await mcp.call("set_env_vars", {
  auth_bearer: "your-jwt-token-here"
});

// Option 3: Multiple parameters
await mcp.call("set_env_vars", {
  baseUrl: "https://api.example.com/v1",
  auth_bearer: "your-jwt-token",
  auth_apikey: "your-api-key"
});

// Option 4: Using variables dict for custom values
await mcp.call("set_env_vars", {
  variables: {
    "baseUrl": "https://api.example.com/v1",
    "custom_header": "custom-value"
  }
});

🌐 语言和框架选择

默认值可帮助你了解可用选项：

// Ingest with defaults shown
await mcp.call("ingest_spec", {
  spec_type: "openapi",        // openapi, swagger, postman
  file_path: "./api-spec.json", // Path to JSON or YAML specification file
  preferred_language: "python", // python, typescript, javascript
  preferred_framework: "requests" // pytest, requests, playwright, jest, cypress, supertest
});

// Project generation with defaults
await mcp.call("generate_project_files", {
  language: "python",          // python, typescript, javascript
  framework: "requests",       // Framework matching the language
  project_name: "api-tests",   // Project folder name
  include_examples: true       // Include example test files
});

⚡ 测试执行参数

性能调优默认值一目了然：

// API tests with concurrency control
await mcp.call("run_api_tests", {
  test_case_ids: null,        // ["test_1", "test_2"] or null for all
  max_concurrent: 10          // Number of concurrent requests (1-50)
});

// Load tests with performance parameters  
await mcp.call("run_load_tests", {
  test_case_ids: null,        // ["test_1", "test_2"] or null for all
  duration: 60,               // Test duration in seconds
  users: 10,                  // Number of concurrent virtual users
  ramp_up: 10                 // Ramp up time in seconds
});

🔧 配置示例

// NEW: Check supported languages and frameworks
const languages = await mcp.call("get_supported_languages");
console.log(languages.supported_combinations);

// Ingest specification with language preferences
await mcp.call("ingest_spec", {
  spec_type: "openapi",
  file_path: "./openapi-specification.json",
  preferred_language: "typescript",
  preferred_framework: "playwright"
});

// Set environment variables for authentication
await mcp.call("set_env_vars", {
  variables: {
    "baseUrl": "https://api.example.com",
    "auth_bearer": "your-bearer-token",
    "auth_apikey": "your-api-key"
  }
});

// Generate test scenarios
await mcp.call("generate_scenarios", {
  include_negative_tests: true,
  include_edge_cases: true
});

// Generate test cases in TypeScript/Playwright
await mcp.call("generate_test_cases", {
  language: "typescript",
  framework: "playwright"
});

// Generate complete project files
await mcp.call("generate_project_files", {
  language: "typescript",
  framework: "playwright",
  project_name: "my-api-tests",
  include_examples: true
});

// Run API tests (still works with existing execution engine)
await mcp.call("run_api_tests", {
  max_concurrent: 5
});

🚀 完整工作流示例

以下是测试 Petstore API 的完整示例：

# 1. Start the MCP server
npx @kirti676/api-tester-mcp@latest

然后在 MCP 客户端（例如 Claude Desktop）中：

// 1. Load the Petstore OpenAPI spec
await mcp.call("ingest_spec", {
  spec_type: "openapi",
  file_path: "./examples/petstore_openapi.json"
});

// 2. Set environment variables
await mcp.call("set_env_vars", {
  pairs: {
    "baseUrl": "https://petstore.swagger.io/v2",
    "auth_apikey": "special-key"
  }
});

// 3. Generate test cases
const tests = await mcp.call("get_generated_tests");

// 4. Run API tests
const result = await mcp.call("run_api_tests");

// 5. View results in HTML report
const reports = await mcp.call("list_resources", {
  uri: "file://reports"
});

📖 使用示例

🔄 基本 API 测试工作流

1. 📥 加载 API 规范

   {
     "tool": "ingest_spec",
     "params": {
       "spec_type": "openapi",
       "content": "{ ... your OpenAPI spec ... }"
     }
   }
   

2. 🔐 配置身份验证

   {
     "tool": "set_env_vars", 
     "params": {
       "variables": {
         "auth_bearer": "your-token",
         "baseUrl": "https://api.example.com"
       }
     }
   }
   

3. 🚀 生成并运行测试

   {
     "tool": "generate_scenarios",
     "params": {
       "include_negative_tests": true
     }
   }
   

4. 📊 查看结果

   • 📄 通过 MCP 资源访问 HTML 报告
   • 📈 获取会话状态和统计信息

🚀 GraphQL API 测试工作流

1. 📥 加载 GraphQL 模式

   {
     "tool": "ingest_spec",
     "params": {
       "spec_type": "graphql",
       "file_path": "./schema.graphql"
     }
   }
   

2. 🔐 配置 GraphQL 端点

   {
     "tool": "set_env_vars", 
     "params": {
       "graphqlEndpoint": "https://api.example.com/graphql",
       "auth_bearer": "your-jwt-token"
     }
   }
   

3. 🧪 生成 GraphQL 测试

   {
     "tool": "generate_test_cases",
     "params": {
       "preferred_language": "python",
       "preferred_framework": "pytest"
     }
   }
   

4. 📊 执行 GraphQL 测试

   {
     "tool": "run_api_tests",
     "params": {
       "max_concurrent": 5
     }
   }
   

⚡ 负载测试

{
  "tool": "run_load_tests",
  "params": {
    "users": 10,
    "duration": 60,
    "ramp_up": 10
  }
}

🔍 测试生成特性

• ✅ 正向测试：有效请求及预期的 2xx 响应
• ❌ 负向测试：身份验证无效（401）、方法错误（405）
• 🎯 边界情况：大型负载、边界条件
• 🏗️ 基于 Schema 的请求体：根据 OpenAPI Schema 自动生成请求体
• 🔍 全面断言：状态码、响应时间、内容验证

📊 HTML 报告

生成的报告包括：

• 📈 测试执行摘要，包含通过/失败统计
• ⏱️ 详细测试结果，包含计时信息
• 🔍 断言明细和错误详情
• 👁️ 响应预览和调试信息
• 📱 适配移动设备的响应式设计

🔒 身份验证支持

• 🎫 Bearer Tokens：auth_bearer 环境变量
• 🔑 API Keys：auth_apikey 环境变量（作为 X-API-Key 标头发送）
• 👤 Basic Auth：auth_basic 环境变量

🔧 要求

• 🐍 Python：3.8 或更高版本
• 🟢 Node.js：14 或更高版本（用于 npm 安装）

📦 依赖项

🐍 Python 依赖项

• 🚀 fastmcp>=0.2.0
• 📊 pydantic>=2.0.0
• 🌐 requests>=2.28.0
• ✅ jsonschema>=4.0.0
• 📝 pyyaml>=6.0
• 🎨 jinja2>=3.1.0
• ⚡ aiohttp>=3.8.0
• 🎭 faker>=19.0.0

🟢 Node.js 依赖项

• ✨ 无（独立软件包）

🔧 故障排除

❗ 常见问题

📦 NPX 命令无法运行

# If npx command fails, try:
npm install -g @kirti676/api-tester-mcp@latest

# Or run directly:
node ./node_modules/@kirti676/api-tester-mcp/cli.js

🐍 找不到 Python

# Make sure Python 3.8+ is installed and in PATH
python --version

# Install Python dependencies manually if needed:
pip install fastmcp>=0.2.0 pydantic>=2.0.0 requests>=2.28.0

🔗 MCP 客户端连接问题

• ✅ 确保 MCP 服务正在使用 stdio 传输方式运行（默认）
• 🔄 检查 MCP 客户端是否支持最新的 MCP 协议版本
• 📝 确认配置 JSON 语法正确

🆘 获取帮助

1. 📖 查看 Examples 目录中的可用配置
2. 🔍 使用 --verbose 标志运行，以获取详细日志
3. 🐛 在 GitHub Issues 上报告问题

🤝 贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

📄 许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

🐛 问题与支持

• NPM 软件包： @kirti676/api-tester-mcp
• 报告 Bug：GitHub Issues

📈 路线图

• 多语言测试生成 - 支持 TypeScript/Playwright、JavaScript/Jest、Python/pytest ✨ 全新！
• 完整项目生成 - 包含依赖项和配置的完整项目脚手架 ✨ 全新！
• GraphQL API 支持 - 支持 GraphQL Schema ✨ 全新！
• 其他身份验证方式（OAuth2、JWT）
• Go/Golang 测试生成（使用 testify/ginkgo）
• C#/.NET 测试生成（使用 NUnit/xUnit）
• 性能监控和告警
• 与 CI/CD 流水线集成（GitHub Actions、Jenkins）
• 根据示例和 Schema 生成高级测试数据
• 支持 Pact 的 API 契约测试
• 用于开发的 Mock 服务生成

📄 版权与使用

© 2025 kirti676。保留所有权利。

本仓库及其内容受版权法保护。如需获得重用、引用或再分发本项目任何部分的许可，请通过 [email protected] 联系所有者。

✅ 无需许可即可进行的活动：

• 个人学习和实验
• 通过 Pull Requests 为本仓库做出贡献

❓ 需要许可的活动：

• 商业使用或集成
• 以修改后的形式再分发
• 发布衍生作品

如有许可相关咨询、合作机会或许可申请，请联系 [email protected]。

---