内容
# 质量保证委员会MCP服务器 - 专业文档
## 📋 执行摘要
一个生产就绪的自主质量保证测试系统，实现了一种“委员会代理”架构，用于自动测试生成、执行、分析和修复。设计用于企业级持续集成工作流程。
### 关键功能
- **多代理架构**：7个专门的代理协同工作，共享审计轨迹模式
- **全生命周期自动化**：克隆 → 检查 → 分析 → 生成 → 执行 → 修复 → 记录
- **GitHub集成**：自动创建带有修复建议的PR
- **覆盖率分析**：综合测试覆盖率报告
- **CI/CD就绪**：包含GitHub Actions工作流程
---
## 🏗️ 架构
```
┌─────────────────────────────────────────────────────────────┐
│ Claude（编排器） │
│ [可以单独调用代理或 │
│ 使用orchestrate_full_qa_cycle] │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 代理 1 │ │ 代理 2 │ │ 代理 3 │
│ 仓库管理 │ │ 检查员 │ │ 生成器 │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
▼ ▼ ▼
[Git Ops] [AST解析] [测试创建]
│ │ │
└────────────────┼────────────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 代理 4 │ │ 代理 5 │ │ 代理 6 │
│ 执行器 │ │ 修复者 │ │ CI/CD │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
▼ ▼ ▼
[pytest/PW] [修复分析] [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 Desktop | 20+ | 是 | 容器运行时 |
| Docker MCP插件 | 最新 | 是 | MCP集成 |
| Python | 3.9+ | 本地测试 | 开发 |
| GitHub令牌 | 不适用 | 可选 | PR创建 |
### 安装（5分钟）
```bash
# 1. 创建项目目录
mkdir qa-council-mcp-server
cd qa-council-mcp-server
# 2. 保存文件（单独提供）
# - Dockerfile
# - requirements.txt
# - qa_council_server.py（固定版本）
# - readme.txt（此文件）
# - CLAUDE.md
# 3. 构建Docker镜像
docker build -t qa-council-mcp-server:latest .
# 预期时间：5-10分钟（Playwright浏览器很大）
# 4. 配置GitHub令牌（可选，用于PR创建）
docker mcp secret set GITHUB_TOKEN="ghp_your_github_token_here"
# 5. 创建MCP目录条目
mkdir -p ~/.docker/mcp/catalogs
nano ~/.docker/mcp/catalogs/custom.yaml
```
添加到`custom.yaml`：
```yaml
version: 2
name: custom
displayName: 自定义MCP服务器
registry:
qa-council:
description: "自主质量保证测试，多代理架构"
title: "质量保证测试委员会"
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
```
```bash
# 6. 更新注册表
nano ~/.docker/mcp/registry.yaml
```
在`registry:`键下添加：
```yaml
registry:
qa-council:
ref: ""
```
```bash
# 7. 配置Claude Desktop
# 编辑：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
# 或：%APPDATA%\Claude\claude_desktop_config.json（Windows）
# 或：~/.config/Claude/claude_desktop_config.json（Linux）
```
将自定义目录添加到参数：
```json
{
"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"
]
}
}
}
```
```bash
# 8. 重启Claude Desktop
# 完全退出并重新启动
# 9. 验证安装
docker mcp server list | grep qa-council
```
预期输出：
```
qa-council qa-council-mcp-server:latest Running
```
---
## 💼 铅质工程师使用指南
### 单个代理使用
#### 代理1：仓库管理
```
您： “克隆https://github.com/company/api-service进行测试”
Claude调用：clone_repository(repo_url="..."，branch="main")
结果：代码准备好位于/app/repos/api-service
```
#### 代理2：代码分析
```
您： “分析代码库结构并识别测试目标”
Claude调用：analyze_codebase(repo_path="/app/repos/api-service")
结果：函数、类、复杂度指标列表
```
#### 代理3：测试生成
```
您： “为api/routes.py生成单元测试”
Claude调用：generate_unit_tests(
repo_path="/app/repos/api-service",
target_file="api/routes.py"
)
结果：创建了tests/unit/test_routes.py并包含测试用例
```
#### 代理4：测试执行
```
您： “运行所有测试并覆盖”
Claude调用：execute_tests(repo_path="/app/repos/api-service")
结果：通过/失败计数、覆盖率百分比、报告文件
```
#### 代理5：故障分析
```
您： “分析测试故障并建议修复”
Claude调用：repair_failing_tests(
repo_path="/app/repos/api-service",
test_output="<previous test output>"
)
结果：分类故障并附有特定的修复建议
```
#### 代理6：CI/CD生成
```
您： “为自动化测试创建GitHub Actions工作流程”
Claude调用：generate_github_workflow(
repo_path="/app/repos/api-service",
test_command="pytest --cov=api"
)
结果：.github/workflows/qa_testing.yml已创建
```
### 全生命周期自动化
```
您： “对https://github.com/company/api-service运行完整的质量保证周期”
Claude调用：orchestrate_full_qa_cycle(
repo_url="https://github.com/company/api-service",
branch="develop",
base_url="http://localhost:8000"
)
结果：所有6个代理依次执行：
✅ 仓库代理 → 克隆代码
✅ 检查代理 → 分析15个文件，47个函数
✅ 生成代理 → 创建23个单元测试，8个E2E测试
✅ 执行代理 → 测试运行，覆盖率82%
✅ 修复代理 → 分析3个故障，建议修复
✅ CI/CD代理 → 生成GitHub工作流程
```
### 高级：PR创建
```
您： “使用推荐的测试修复创建PR”
Claude调用：create_test_fix_pr(
repo_url="https://github.com/company/api-service",
test_output="<test results>",
fixes='[{"file": "tests/test_api.py", "content": "..."}]'
)
结果：创建拉取请求，包含：
- 修复分支：qa-council/auto-fix-20260214-143052
- PR标题：🤖 自动测试修复来自QA委员会
- PR描述中的详细分析
```
---
## 🧪 本地测试（无需Docker）
### 环境设置
```bash
# 1. 创建虚拟环境
python3 -m venv venv
# 2. 激活
source venv/bin/activate # macOS/Linux
# 或
venv\Scripts\activate # Windows
# 3. 安装依赖项
pip install -r requirements.txt
# 4. 安装Playwright浏览器
playwright install chromium
playwright install-deps # 仅限Linux
# 5. 验证安装
python -c "import mcp; print('MCP installed')"
playwright --version
```
### 在本地运行服务器
```bash
# 设置环境变量
export GITHUB_TOKEN="ghp_your_token" # 可选
export WORKSPACE_DIR="/tmp/qa-repos"
export TEST_RESULTS_DIR="/tmp/qa-results"
export COVERAGE_DIR="/tmp/qa-coverage"
# 运行服务器
python qa_council_server.py
```
### 测试单个函数
```python
# 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())
```
运行测试：
```bash
python test_agents.py
```
---
## 📊 测试覆盖率策略
### 按组件划分的覆盖率目标
| 组件 | 目标 | 理由 |
|-----------|--------|-----------|
| API端点 | 85%+ | 关键用户代码 |
| 数据库层 | 90%+ | 数据完整性至关重要 |
| 业务逻辑 | 90%+ | 核心功能 |
| 实用工具 | 75%+ | 支持代码 |
| UI组件 | 70%+ | 视觉测试补充 |
### 测量覆盖率
```bash
# 生成覆盖率报告
pytest --cov=. --cov-report=html --cov-report=term
# 查看HTML报告
open htmlcov/index.html
# 检查是否达到阈值
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容器隔离或权限
**解决方案**：
```bash
# 验证仓库是否克隆
docker exec <container_id> ls -la /app/repos
# 检查权限
docker exec <container_id> ls -la /app/repos/<repo_name>
# 尝试使用固定版本（v2.0）
# 包括改进的路径验证
```
### 问题：代理在编排器中未执行
**症状**：`orchestrate_full_qa_cycle`显示的输出很少
**原因**：使用旧版本，不会调用子代理
**解决方案**：
```bash
# 升级到固定版本
cp qa_council_server_fixed.py qa_council_server.py
docker build -t qa-council-mcp-server:latest .
```
### 问题：PR创建失败
**症状**：“GitHub令牌未配置”错误
**原因**：GITHUB_TOKEN未设置
**解决方案**：
```bash
# 设置令牌
docker mcp secret set GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
# 验证
docker mcp secret list
# 重建容器以拾取秘密
docker mcp reload
```
### 问题：Playwright测试失败
**症状**：“可执行文件不存在”错误
**原因**：浏览器未安装
**解决方案**：
```bash
# 重建镜像（浏览器在构建期间安装）
docker build -t qa-council-mcp-server:latest .
# 或手动安装在运行的容器中
docker exec <container_id> playwright install chromium
```
### 问题：测试超时
**症状**：“测试执行超时”（300秒超时）
**原因**：大型测试套件或缓慢测试
**解决方案**：
```python
# 编辑qa_council_server.py
# 在run_pytest函数中，增加超时：
timeout=600 # 10分钟而不是5分钟
```
---
## 🏢 企业集成
### CI/CD管道集成
#### GitHub Actions（包含）
```yaml
# 自动由代理6生成
# 功能：测试执行、覆盖率、PR创建
# 位置：.github/workflows/qa_testing.yml
```
#### GitLab CI
```yaml
# .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
```
#### Jenkins
```groovy
// 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/Teams通知
添加GitHub Actions工作流：
```yaml
- name: Notify Slack
if: always()
uses: 8398a7/action-slack@v3
with:
status: ${{ job.status }}
text: |
质量保证委员会测试结果：
Passed: ${{ steps.test.outputs.passed }}
Failed: {{ steps.test.outputs.failed }}
覆盖率：{{ steps.test.outputs.coverage }}%
webhook_url: {{ secrets.SLACK_WEBHOOK }}
```
### Jira集成
```python
# 创建Jira ticket用于测试失败
@mcp.tool()
async def create_jira_ticket(summary: str, description: str) -> str:
"""为测试失败创建Jira ticket"""
# 使用Jira API实现
```
---
## 📈 指标和报告
### 跟踪的关键指标
1. **测试成功率**：随时间变化的测试通过百分比
2. **覆盖率趋势**：每次提交的覆盖率变化百分比
3. **测试执行时间**：测试套件的持续时间
4. **失败类别**：测试失败的类型
5. **修复时间**：从发现故障到修复完成的时间
### 仪表盘
与以下工具集成：
- **Codecov**：覆盖率可视化
- **SonarQube**：代码质量 + 测试覆盖率
- **TestRail**：测试管理
- **Grafana**：自定义指标仪表盘
---
## 🔐 安全考虑
### 秘密管理
```bash
# 好的：使用Docker秘密
docker mcp secret set GITHUB_TOKEN="token"
docker mcp secret set API_KEY="key"
# 差劲的：在文件中硬编码
GITHUB_TOKEN = "ghp_xxxx" # 千万不要这样做！
```
### 代码扫描
生成的GitHub Actions工作流程包括：
- 依赖项扫描（自动启用）
- SAST扫描（可选，添加CodeQL）
- 机密扫描（GitHub原生）
### 访问控制
```yaml
# 限制工作流权限
permissions:
contents: read
pull-requests: write
issues: write
```
---
## 🎓 最佳实践
### 1. 测试组织
```
tests/
├── unit/ # 快速、隔离的测试
├── integration/ # 组件交互测试
├── e2e/ # 完整用户工作流测试
└── performance/ # 负载和压力测试
```
### 2. 测试命名
```python
# 好的
def test_user_login_with_valid_credentials():
pass
# 差劲的
def test1():
pass
```
### 3. Fixture使用
```python
@pytest.fixture(scope="session")
def db_connection():
"""在测试中重用数据库连接。"""
conn = create_connection()
yield conn
conn.close()
```
### 4. 覆盖率目标
- 从70%总体覆盖率开始
- 逐渐增加到85%+
- 优先关注关键路径
### 5. 测试维护
- 每周检查测试失败
- 立即重构不稳定的测试
- 存档过时的测试
---
## 📞 支持与贡献
### 获取帮助
1. 先查看此README
2. 查看UPGRADE_GUIDE.md了解已知问题
3. 检查Docker日志：`docker logs <container_id>`
4. 查看测试输出中的工件
### 贡献
为了改进质量保证委员会系统：
1. 分叉并创建功能分支
2. 为新功能添加测试
3. 更新文档
4. 提交拉取请求
---
## 📝 更新日志
### v2.0（2026-02-14）- 修复版本
- ✅ 修复了Docker容器中的路径解析问题
- ✅ 修复了编排器实际上调用子代理的问题
- ✅ 添加了GitHub PR创建功能
- ✅ 增强了错误消息和日志记录
- ✅ 改进了GitHub Actions工作流
- ✅ 添加了全面的文档
### v1.0（2026-02-01）- 初始版本
- 初始多代理架构
- 基本测试生成和执行
- 覆盖率报告
- GitHub Actions集成
---
## 📄 许可证
MIT许可证 - 有关详细信息，请参见LICENSE文件
---
## 🙏 致谢
- 灵感来自[OpenObserve的AI代理架构](https://openobserve.ai/blog/autonomous-qa-testing-ai-agents-claude-code/)
- 在Model Context Protocol（MCP）上构建
- 由FastMCP框架提供支持
- 使用pytest和Playwright进行测试
---
**维护者**：质量保证工程团队
**版本**：2.0-fixed
**状态**：生产就绪
**最后更新时间**：2026年2月14日
## MCP工具合同
服务器现在公开了`list_tools`和`call_tool`，以支持代理间通信和反射式编排。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器