failure analysis MCP

MCP故障分析服务器

MCP（模型上下文协议）服务器，通过Ollama使用本地LLM分析WebdriverIO测试失败。专为与JavaScript/TypeScript测试自动化框架集成而设计。

概述

该服务器通过以下方式为WebdriverIO E2E测试提供智能故障分析：

• 从规范文件及其导入中提取相关代码上下文
• 解析错误消息和堆栈跟踪
• 使用本地LLM（通过Ollama）提供详细的根本原因分析
• 在多个故障分析中维护会话上下文

特性

• 智能代码分析：自动遍历导入依赖关系（最多3级深度）以收集相关上下文
• 会话管理：通过基于TTL的过期维护多个分析的上下文
• 树保姆解析：高效的JavaScript/TypeScript导入提取
• 本地LLM集成：与Ollama合作进行隐私保护分析
• MCP协议：与任何MCP客户端兼容的标准MCP服务器
• WebdriverIO优化：WebdriverIO测试失败的定制提示

安装

先决条件

• Python 3.11+
• 紫外线 用于包管理
• 奥拉玛 使用具有视觉能力的模型（例如。， gemma4:e4b)

设置

1. 克隆存储库并导航到项目：

cd failure_analysis_server

1. 与UV同步依赖关系：

uv sync

1. 创建您的 .env 文件：

cp .env.example .env
# Edit .env with your configuration

1. 确保Ollama使用您选择的型号运行：

ollama pull gemma4:e4b
ollama serve

配置

所有配置都是通过中的环境变量完成的 .env:

WebdriverIO MCP客户端

奥拉马LLM

分析设置

日志记录

用法

运行服务器

开发模式（带检查员）

mcp dev mcp_server.py

生产模式

uv run python mcp_server.py

或者安装入口点：

uv pip install -e .
uv run mcp-server

MCP工具

服务器公开了这些MCP工具：

analyze_failure

使用可选的可视化和DOM上下文分析WebdriverIO测试失败。

参数：

• console_output （string）：测试运行的原始控制台输出（支持ndjson）
• spec_file_path （string）：失败规范文件的绝对路径
• session_id （字符串，可选）：用于维护上下文的会话ID
• screenshot_base64 （字符串，可选）：失败时页面的Base64编码截图
• dom_snapshot （string，可选）：页面的完整DOM快照或可访问性树
• screenshot_mime_type （字符串，可选）：屏幕截图的MIME类型（默认 image/png)

退货： JSON格式 success, analysis, session_id, model, files_analyzed

clear_session

清除会话及其历史记录。

参数：

• session_id （string）：要清除的会话ID

MCP资源

config://current

返回当前服务器配置。

session://{session_id}/status

返回会话状态和失败历史记录。

建筑

WebdriverIO Test Failure
    │
    ▼
┌─────────────────────┐
│  MCP Client (JS)    │
│  (WebdriverIO side) │
└──────────┬──────────┘
           │ stdio/MCP protocol
           ▼
┌─────────────────────┐
│  MCP Server (Python)│
│  - Parse stack trace│
│  - Extract imports  │
│  - Gather code      │
└──────────┬──────────┘
           │ HTTP
           ▼
┌─────────────────────┐
│  Ollama (LLM)       │
│  - Analyze failure  │
│  - Suggest fixes    │
└─────────────────────┘

代码分析

服务器使用树形图来解析JavaScript/TypeScript：

1. 导入提取：解析ES6导入和CommonJS所需
2. 导入分辨率：使用扩展推理解决相对导入问题
3. 代码收集：BFS遍历到配置的深度
4. 文件筛选：大小限制和防止重复

会话管理

会话在多个分析中维护上下文：

• 基于TTL的过期：会话在不活动后过期
• 故障历史：以前的失败通知上下文
• 对话历史：LLM会话保持不变
• 自动清理：过期的会话将自动删除

错误模式

服务器识别常见的WebdriverIO错误模式：

发展

项目结构

failure_analysis_server/
├── mcp_server.py          # Main MCP server
├── pyproject.toml         # Project dependencies
├── .env                   # Configuration
├── .env.example           # Configuration template
├── README.md              # This file
└── CLAUDE.md              # Claude context

运行测试

uv run pytest

添加新工具

1. 定义工具功能 @mcp.tool() 装饰器
2. 使用Pydantic Field 用于参数描述
3. 返回结构化响应的JSON字符串
4. 添加带有信息性消息的错误处理

修改系统提示

这 SYSTEM_PROMPT 常数in mcp_server.py 定义LLM如何分析故障。修改此设置以更改分析行为。

故障排除

Ollama连接问题

Cannot connect to Ollama at http://localhost:11434

解决方案： 确保Olama正在运行： ollama serve

未找到型号

Model gemma4:e4b not found

解决方案： 拉动模型： ollama pull gemma4:e4b

未分析截图

如果LLM在分析中没有引用屏幕截图：

• 验证模型是否支持视觉(ollama show gemma4:e4b 应列出 vision 能力）
• 纯文本模型(qwen2.5-coder:7b)无法处理图像
• 确保 screenshot_base64 是有效的base64字符串

导入解析失败

如果进口问题未得到解决：

1. 检查 MCP_MAX_IMPORT_DEPTH 设置
2. 验证文件路径是相对的（不是绝对的）
3. 确保导入的文件存在并与预期的扩展名匹配

会话到期

会话过期时间 MCP_SESSION_TTL_MINUTES 不活动。对于长时间运行的分析会话，增加此值。

大型DOM快照

如果DOM快照导致上下文窗口溢出：

• 减少 MCP_MAX_DOM_SIZE_KB （默认100KB）
• 发送前在客户端删除脚本/样式
• 发送辅助功能树而不是完整的HTML

与WebdriverIO集成

该服务器旨在与WebdriverIO MCP客户端配合使用。客户应当：

1. 将MCP服务器作为子进程启动
2. 使用MCP协议通过stdio进行通信
3. 发送 analyze_failure 工具调用：

- 控制台输出（原始文本或ndjson行） - 屏幕截图(browser.takeScreenshot() 返回base64 PNG） - DOM快照(document.documentElement.outerHTML) - 规范文件路径

1. 处理JSON响应和显示分析

客户端使用示例（JavaScript）：

// Connect to MCP server
const client = new MCPClient({
  command: 'uv',
  args: ['run', 'python', 'mcp_server.py']
});

// Analyze a failure
const result = await client.callTool('analyze_failure', {
  console_output: testOutput,
  spec_file_path: '/path/to/spec.ts',
  screenshot_base64: await browser.takeScreenshot(),
  dom_snapshot: await browser.execute(() => document.documentElement.outerHTML)
});

许可证

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

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行测试
5. 提交拉取请求

支持

对于问题和功能请求，请使用GitHub问题跟踪器。