QA委员会MCP服务器-专业文档

📋 执行摘要

一个生产就绪的自主QA测试系统，实现了“代理委员会”架构，用于自动化测试生成、执行、分析和修复。专为企业级持续集成工作流而设计。

关键能力

多代理架构：7名专业代理与共享的AuditTrail模式协同工作
全生命周期自动化：克隆→ 检查→ 分析→ 生成→ 执行→ Heal → 抄写员
GitHub集成：自动创建带有修复建议的PR
覆盖率分析：全面的测试覆盖率报告
CI/CD就绪：包括GitHub操作工作流

______________________________________________________________________

🏗️ 建筑

┌─────────────────────────────────────────────────────────────┐
│                    Claude (Orchestrator)                     │
│              [Can call agents individually or               │
│               use orchestrate_full_qa_cycle]                │
└────────────────────────┬────────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   Agent 1    │  │   Agent 2    │  │   Agent 3    │
│ Repository   │  │  Inspector   │  │  Generator   │
└──────────────┘  └──────────────┘  └──────────────┘
        │                │                │
        ▼                ▼                ▼
   [Git Ops]      [AST Parse]      [Test Creation]
        │                │                │
        └────────────────┼────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   Agent 4    │  │   Agent 5    │  │   Agent 6    │
│  Executor    │  │  Repairer    │  │    CI/CD     │
└──────────────┘  └──────────────┘  └──────────────┘
        │                │                │
        ▼                ▼                ▼
 [pytest/PW]     [Fix Analysis]   [GH Actions]

代理人职责（7人理事会）

代理	目的	输入	输出	使用的工具
编排器	管道+审计追踪持久性	回购URL	会话上下文JSON	MCP工具
检查员	技术栈发现	文件路径	TechStackManifest	启发式
分析师	基于AST的可测试表面映射	源树	API/UI/逻辑映射	AST解析
发电机	单元/集成/E2E/POM生成	清单+表面	测试文件	模板
执行者	运行并收集FailurePayloads	测试文件	结果+DOM+JSON跟踪	pytest/Playwright
治愈者	选择器/逻辑修复	FailurePayload	修补的页面对象	模糊匹配
抄写员	分支机构/提交/PR/工作流	工件	PR+质量门	git+GitHub API

______________________________________________________________________

🚀 快速开始

先决条件

要求	版本	必需	目的
Docker桌面	20+	是	容器运行时
Docker MCP插件	最新	是	MCP集成
Python	3.9+	本地测试	开发
GitHub Token	不适用	可选	PR创建

安装（5分钟）

# 1. Create project directory
mkdir qa-council-mcp-server
cd qa-council-mcp-server

# 2. Save the files (provided separately)
# - Dockerfile
# - requirements.txt
# - qa_council_server.py (FIXED VERSION)
# - readme.txt (this file)
# - CLAUDE.md

# 3. Build Docker image
docker build -t qa-council-mcp-server:latest .

# Expected time: 5-10 minutes (Playwright browsers are large)

# 4. Configure GitHub token (optional, for PR creation)
docker mcp secret set GITHUB_TOKEN="ghp_your_github_token_here"

# 5. Create MCP catalog entry
mkdir -p ~/.docker/mcp/catalogs
nano ~/.docker/mcp/catalogs/custom.yaml

添加 custom.yaml:

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  qa-council:
    description: "Autonomous QA testing with multi-agent architecture"
    title: "QA Testing Council"
    type: server
    dateAdded: "2026-02-14T00:00:00Z"
    image: qa-council-mcp-server:latest
    ref: ""
    tools:
      - name: clone_repository
      - name: analyze_codebase
      - name: generate_unit_tests
      - name: generate_e2e_tests
      - name: execute_tests
      - name: repair_failing_tests
      - name: generate_github_workflow
      - name: create_test_fix_pr
      - name: orchestrate_full_qa_cycle
    secrets:
      - name: GITHUB_TOKEN
        env: GITHUB_TOKEN
        example: ghp_xxxxxxxxxxxx
    metadata:
      category: automation
      tags: [testing, qa, ci-cd, automation]
      license: MIT
      owner: local

# 6. Update registry
nano ~/.docker/mcp/registry.yaml

添加到下面 registry: 按键：

registry:
  qa-council:
    ref: ""

# 7. Configure Claude Desktop
# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
#   or: %APPDATA%\Claude\claude_desktop_config.json (Windows)
#   or: ~/.config/Claude/claude_desktop_config.json (Linux)

将自定义目录添加到args：

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "/Users/YOUR_USERNAME/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

# 8. Restart Claude Desktop
# Quit completely and relaunch

# 9. Verify installation
docker mcp server list | grep qa-council

预期产量：

qa-council    qa-council-mcp-server:latest    Running

______________________________________________________________________

💼 首席质量保证工程师使用指南

个人代理使用

代理1：存储库管理

You: "Clone https://github.com/company/api-service for testing"

Claude calls: clone_repository(repo_url="...", branch="main")

Result: Code ready at /app/repos/api-service

代理2：代码分析

You: "Analyze the codebase structure and identify test targets"

Claude calls: analyze_codebase(repo_path="/app/repos/api-service")

Result: List of functions, classes, complexity metrics

代理3：测试生成

You: "Generate unit tests for api/routes.py"

Claude calls: generate_unit_tests(
    repo_path="/app/repos/api-service",
    target_file="api/routes.py"
)

Result: tests/unit/test_routes.py created with test cases

代理4：测试执行

You: "Run all tests with coverage"

Claude calls: execute_tests(repo_path="/app/repos/api-service")

Result: Pass/fail counts, coverage percentage, report files

代理5：故障分析

You: "Analyze the test failures and suggest fixes"

Claude calls: repair_failing_tests(
    repo_path="/app/repos/api-service",
    test_output="
"
)

Result: Categorized failures with specific fix suggestions

代理6:CI/CD生成

You: "Create GitHub Actions workflow for automated testing"

Claude calls: generate_github_workflow(
    repo_path="/app/repos/api-service",
    test_command="pytest --cov=api"
)

Result: .github/workflows/qa_testing.yml created

全生命周期自动化

You: "Run complete QA cycle on https://github.com/company/api-service"

Claude calls: orchestrate_full_qa_cycle(
    repo_url="https://github.com/company/api-service",
    branch="develop",
    base_url="http://localhost:8000"
)

Result: All 6 agents execute in sequence:
  ✅ Repository Agent → Code cloned
  ✅ Inspector Agent → 15 files, 47 functions analyzed
  ✅ Generator Agent → 23 unit tests, 8 E2E tests created
  ✅ Executor Agent → Tests run, 82% coverage
  ✅ Repairer Agent → 3 failures analyzed, fixes suggested
  ✅ CI/CD Agent → GitHub workflow generated

高级：公关创作

You: "Create a PR with the recommended test fixes"

Claude calls: create_test_fix_pr(
    repo_url="https://github.com/company/api-service",
    test_output="",
    fixes='[{"file": "tests/test_api.py", "content": "..."}]'
)

Result: Pull request created with:
  - Fix branch: qa-council/auto-fix-20260214-143052
  - PR title: 🤖 Automated Test Fixes from QA Council
  - Detailed analysis in PR description

______________________________________________________________________

🧪 本地测试（无Docker）

环境设置

# 1. Create virtual environment
python3 -m venv venv

# 2. Activate
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate  # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Install Playwright browsers
playwright install chromium
playwright install-deps  # Linux only

# 5. Verify installation
python -c "import mcp; print('MCP installed')"
playwright --version

在本地运行服务器

# Set environment variables
export GITHUB_TOKEN="ghp_your_token"  # Optional
export WORKSPACE_DIR="/tmp/qa-repos"
export TEST_RESULTS_DIR="/tmp/qa-results"
export COVERAGE_DIR="/tmp/qa-coverage"

# Run server
python qa_council_server.py

测试单个功能

# test_agents.py
import asyncio
from qa_council_server import (
    clone_repository,
    analyze_codebase,
    generate_unit_tests
)

async def test_repository_agent():
    result = await clone_repository(
        repo_url="https://github.com/test/repo",
        branch="main"
    )
    print(result)
    assert "✅" in result

async def test_inspector_agent():
    result = await analyze_codebase(
        repo_path="/app/repos/test-repo",
        file_pattern="*.py"
    )
    print(result)
    assert "📊" in result

if __name__ == "__main__":
    asyncio.run(test_repository_agent())
    asyncio.run(test_inspector_agent())

运行测试：

python test_agents.py

______________________________________________________________________

📊 测试覆盖策略

按组成部分列出的覆盖目标

组成部分	目标	基本原理
API终结点	85%+	关键用户界面代码
数据库层	90%+	数据完整性至关重要
业务逻辑	90%+	核心功能
实用程序	75%+	支持代码
UI组件	70%+	视觉测试补充

衡量覆盖范围

# Generate coverage report
pytest --cov=. --cov-report=html --cov-report=term

# View HTML report
open htmlcov/index.html

# Check if meets threshold
pytest --cov=. --cov-fail-under=85

覆盖报告解释

Name                 Stmts   Miss  Cover   Missing
--------------------------------------------------
api/routes.py          156     22    86%   45-47, 89-92
database/models.py      89      8    91%   145-152
utils/helpers.py        45     12    73%   23-34
--------------------------------------------------
TOTAL                  290     42    85%

分析:

✅ API路线：可接受（86%>85%目标）
✅ 数据库：优秀（91%>90%目标）
⚠️ 公用事业：低于目标（73%\ ls -la /app/repos

Check permissions

docker exec ls -la /app/repos/

Try using the fixed version (v2.0)

Includes improved path verification


### 问题：代理程序未在编排器中执行

**症状**: `orchestrate_full_qa_cycle` 显示最小输出
**原因**：使用不调用子代理的旧版本
**解决方案**:

Upgrade to fixed version

cp qa_council_server_fixed.py qa_council_server.py docker build -t qa-council-mcp-server:latest .


### 问题：PR创建失败

**症状**：“GitHub令牌未配置”错误
**原因**：GITHUB_TOKEN未设置
**解决方案**:

Set token

docker mcp secret set GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

Verify

docker mcp secret list

Rebuild container to pick up secret

docker mcp reload


### 问题：剧作家测试失败

**症状**：“可执行文件不存在”错误
**原因**：未安装浏览器
**解决方案**:

Rebuild image (browsers install during build)

docker build -t qa-council-mcp-server:latest .

Or install manually in running container

docker exec playwright install chromium


### 问题：测试超时

**症状**：“测试执行超时”（超时300秒）
**原因**：大型测试套件或慢速测试
**解决方案**:

Edit qa_council_server.py

In run_pytest function, increase timeout:

timeout=600 # 10 minutes instead of 5


______________________________________________________________________

## 🏢 企业集成

### CI/CD管道集成

#### GitHub操作（包括）

Automatically generated by Agent 6

Features: test execution, coverage, PR creation

Location: .github/workflows/qa_testing.yml


#### GitLab 的

.gitlab-ci.yml

test: image: python:3.11 script: - pip install -r requirements.txt - pytest --cov=. --cov-report=xml artifacts: reports: coverage_report: coverage_format: cobertura path: coverage.xml


#### 詹金斯

// Jenkinsfile pipeline { agent { docker { image 'python:3.11' } } stages { stage('Test') { steps { sh 'pip install -r requirements.txt' sh 'pytest --cov=. --junitxml=results.xml' } } } post { always { junit 'results.xml' } } }


### Slack/团队通知

添加到GitHub操作工作流：

name: Notify Slack

if: always() uses: 8398a7/action-slack@v3 with: status: ${{ job.status }} text: | QA Council Test Results: Passed: ${{ steps.test.outputs.passed }} Failed: ${{ steps.test.outputs.failed }} Coverage: ${{ steps.test.outputs.coverage }}% webhook_url: ${{ secrets.SLACK_WEBHOOK }}


### Jira集成

Create Jira ticket for test failures

@mcp.tool() async def create_jira_ticket(summary: str, description: str) -> str: """Create Jira ticket for test failures.""" # Implementation using Jira API


______________________________________________________________________

## 📈 指标和报告

### 跟踪的关键指标

1. **测试成功率**：随着时间的推移，通过测试的百分比
1. **覆盖趋势**：每次提交的覆盖率百分比变化
1. **测试执行时间**：测试套件的持续时间
1. **故障类别**：测试失败的类型
1. **固定时间**：从故障检测到修复合并的时间

### 仪表盘

与以下内容集成：

- **Codecov**：覆盖范围可视化
- **声纳立方**：代码质量+测试覆盖率
- **TestRail**：测试管理
- **格拉法纳**：自定义指标仪表板

______________________________________________________________________

## 🔐 安全注意事项

### 秘密管理

GOOD: Use Docker secrets

docker mcp secret set GITHUB_TOKEN="token" docker mcp secret set API_KEY="key"

BAD: Hardcode in files

GITHUB_TOKEN = "ghp_xxxx" # Never do this!


### 代码扫描

生成的GitHub Actions工作流包括：

- 依赖关系扫描（自动启用）
- SAST扫描（可选，添加CodeQL）
- 秘密扫描（GitHub原生）

### 访问控制

Limit workflow permissions

permissions: contents: read pull-requests: write issues: write


______________________________________________________________________

## 🎓 最佳实践

### 1.测试组织

tests/ ├── unit/ # Fast, isolated tests ├── integration/ # Component interaction tests ├── e2e/ # Full user workflow tests └── performance/ # Load and stress tests


### 2.测试命名

GOOD

def test_user_login_with_valid_credentials(): pass

BAD

def test1(): pass


### 3.夹具使用

@pytest.fixture(scope="session") def db_connection(): """Reuse database connection across tests.""" conn = create_connection() yield conn conn.close()


### 4.覆盖目标

- 从70%的总体覆盖率开始
- 逐渐增加到85%+
- 首先关注关键路径

### 5.测试维护

- 每周审查测试失败
- 立即重构片状测试
- 归档过时的测试

______________________________________________________________________

## 📞 支持和贡献

### 获取帮助

1. 请先查看此自述文件
1. 查看UPGRADE_GUIDE.md以了解已知问题
1. 检查Docker日志： `docker logs `
1. 审查工件中的测试输出

### 贡献

改进质量保证委员会制度：

1. 分叉并创建特征分支
1. 添加新功能的测试
1. 更新文档
1. 提交拉取请求

______________________________________________________________________

## 📝 更新日志

### v2.0（2026-02-14）-固定版本

- ✅ 修复了Docker容器中的文件路径解析问题
- ✅ 修复了实际调用子代理的编排器
- ✅ 添加了GitHub PR创建功能
- ✅ 增强的错误消息和日志记录
- ✅ 改进了GitHub操作工作流程
- ✅ 添加了全面的文档

### v1.0（2026-02-01）-首次发布

- 初始多代理架构
- 基本测试生成和执行
- 覆盖率报告
- GitHub操作集成

______________________________________________________________________

## 📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

______________________________________________________________________

## 🙏 致谢

- 受启发于 [Openbserve的人工智能代理架构](https://openobserve.ai/blog/autonomous-qa-testing-ai-agents-claude-code/)
- 基于模型上下文协议（MCP）
- 由FastMCP框架提供支持
- 使用pytest和Playwright进行测试

______________________________________________________________________

**由维护**：QA工程团队\
**版本**：2.0固定\
**状态**：生产就绪\
**最后更新**2026年2月14日

## MCP工具合同

服务器现在公开了这两个 `list_tools` 和 `call_tool` 以支持代理间通信和反射式编排。

Qa Sub Agents

快速接入

详细介绍

QA委员会MCP服务器-专业文档

📋 执行摘要

关键能力

🏗️ 建筑

代理人职责（7人理事会）

🚀 快速开始

先决条件

安装（5分钟）

💼 首席质量保证工程师使用指南

个人代理使用

代理1：存储库管理

代理2：代码分析

代理3：测试生成

代理4：测试执行

代理5：故障分析

代理6:CI/CD生成

全生命周期自动化

高级：公关创作

🧪 本地测试（无Docker）

环境设置

在本地运行服务器

测试单个功能

📊 测试覆盖策略

按组成部分列出的覆盖目标

衡量覆盖范围

覆盖报告解释

Check permissions

Try using the fixed version (v2.0)

Includes improved path verification

Upgrade to fixed version

Set token

Verify

Rebuild container to pick up secret

Rebuild image (browsers install during build)

Or install manually in running container

Edit qa_council_server.py

In run_pytest function, increase timeout:

Automatically generated by Agent 6

Features: test execution, coverage, PR creation

Location: .github/workflows/qa_testing.yml

.gitlab-ci.yml

Create Jira ticket for test failures

GOOD: Use Docker secrets

BAD: Hardcode in files

Limit workflow permissions

GOOD

BAD

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP