使用说明

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="<previous 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="<test results>",
    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%<75%目标）-需要关注

🔧 故障排除

问题：“路径不存在”错误

症状：代理工具失败，找不到路径原因：Docker容器隔离或权限 解决方案:

# Verify repository was cloned
docker exec <container_id> ls -la /app/repos

# Check permissions
docker exec <container_id> ls -la /app/repos/<repo_name>

# 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 <container_id> 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

📈 指标和报告

跟踪的关键指标

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

仪表盘

与以下内容集成：

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.测试维护

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

📞 支持和贡献

获取帮助

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

贡献

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

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

📝 更新日志

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

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

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

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

📄 许可证

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

🙏 致谢

受启发于 Openbserve的人工智能代理架构
基于模型上下文协议（MCP）
由FastMCP框架提供支持
使用pytest和Playwright进行测试

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

MCP工具合同

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