Rf Log

БесплатноНе проверен

An MCP server for analyzing Robot Framework test results. It provides LLMs with tools to parse, summarize, and search through test execution logs from XML or JS

автор: cceniam

GitHub

Описание

An MCP server for analyzing Robot Framework test results. It provides LLMs with tools to parse, summarize, and search through test execution logs from XML or JSON output files.

README

用于检查 Robot Framework 结果文件的 MCP Server，面向 LLM 提供简洁证据视图。

功能概览

支持输入：

output.xml：Robot / Rebot 6.0.x / 6.1+ / 7.x
output.json：Robot / Rebot 7.2+

暴露的 MCP 能力：

Tools
- parse_result
- get_view
- search_messages
Resources
- rf://runs/{run_id}/summary
- rf://runs/{run_id}/tests/{test_id}

支持的视图：

summary
failure_path
step_window

通用返回字段：

run_id：整数运行编号，推荐后续调用都使用它
estimated_tokens：当前返回体的估算 token 数
truncated：兼容字段，只表示返回内容发生过任意截断
message_truncated：长消息被缩短
budget_truncated：为了满足 budget 限制裁剪了返回内容
page_truncated：当前页后面还有更多数据
next_cursor：分页游标；为空表示没有下一页

关键说明

这个项目是 MCP stdio server
正确方式是：MCP 宿主启动 rf-log-mcp 进程，再通过 stdio 调用工具和资源

快速开始

1. 安装依赖

uv sync

2. 推荐的 MCP 配置示例

{
  "mcpServers": {
    "rf-log-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "rf_log_mcp"
      ]
    }
  }
}

打包与安装

构建

uv build

构建后生成：

dist/rf_log_mcp-0.1.0-py3-none-any.whl
dist/rf_log_mcp-0.1.0.tar.gz

安装 wheel

uv pip install dist/rf_log_mcp-0.1.0-py3-none-any.whl

安装后可直接启动：

rf-log-mcp

已安装包的 MCP 配置示例

{
  "mcpServers": {
    "rf-log-mcp": {
      "command": "rf-log-mcp",
      "args": []
    }
  }
}

Windows 显式路径示例

{
  "mcpServers": {
    "rf-log-mcp": {
      "command": "D:\\project\\rf_log_mcp\\.venv\\Scripts\\rf-log-mcp.exe",
      "args": []
    }
  }
}

典型调用流程

第一步：解析结果文件

parse_result(path="tests/fixtures/single_failure_611.xml")

典型返回：

{
  "ok": true,
  "run_id": 1,
  "source_format": "xml"
}

第二步：获取摘要

get_view(run_id=1, view="summary")

如果失败用例较多，可以指定分页大小：

get_view(run_id=1, view="summary", page_size=10)
get_view(run_id=1, view="summary", cursor="<next_cursor>", page_size=10)

第三步：获取失败路径

get_view(run_id=1, view="failure_path")
get_view(run_id=1, view="failure_path", selector="s1-t2")

failure_path 会从失败测试中选择更短、更关键的失败分支；当同层分支长度相同，会优先返回包含更高严重级别消息的分支。

第四步：查看步骤窗口

get_view(run_id=1, view="step_window", selector="s1-t2")

step_window 的 selector 可以传测试节点，也可以传关键字/步骤节点。传步骤节点时，返回会自动定位到所属测试，并尽量把该节点放在窗口中间。

分页示例：

get_view(run_id=1, view="step_window", selector="s1-t2-k13", page_size=20)
get_view(run_id=1, view="step_window", selector="s1-t2-k13", cursor="<next_cursor>", page_size=20)

第五步：检索消息

search_messages(run_id=1, query="timeout")

search_messages 按普通文本匹配。%、_、\ 会作为字面量处理，不会被当成 SQL LIKE 通配符。

环境变量

`RF_LOG_MCP_DB`

用于覆盖默认 SQLite 数据库路径。

PowerShell 示例：

$env:RF_LOG_MCP_DB="D:\data\rf-log-mcp\store.sqlite3"
rf-log-mcp

MCP 配置示例：

{
  "mcpServers": {
    "rf-log-mcp": {
      "command": "rf-log-mcp",
      "args": [],
      "env": {
        "RF_LOG_MCP_DB": "D:\\data\\rf-log-mcp\\store.sqlite3"
      }
    }
  }
}

常见问题

1. 为什么使用uv

本地环境的依赖版本可能和 mcp的冲突, 需要venv 来隔离依赖冲突(conda 太慢, uv快)

2. `truncated` 和三个细分字段有什么区别？

truncated 是总开关，任意一种截断都会为 true。

message_truncated=true：消息字段太长，被缩短显示
budget_truncated=true：返回体超过 budget，服务主动裁剪了条目或消息
page_truncated=true：还有下一页，应继续传 next_cursor

排查失败链时优先关注 budget_truncated。如果它为 true，可以调大 budget 或缩小 page_size 后重新查询。

3. `get_view` / `search_messages` 能传文件路径吗？

可以。
如果该文件已经被解析过，服务会先把路径转换成对应的 run_id 再查询。
但仍然推荐优先使用 parse_result() 返回的整数 run_id。

4. Windows 上推荐用哪种启动方式？

开发临时验证可以使用：

uv run python -m rf_log_mcp

接入 MCP 宿主时，更推荐使用虚拟环境里的解释器直接启动，减少 uv 或 .exe 启动器额外进程带来的文件占用问题：

{
  "mcpServers": {
    "rf-log-mcp": {
      "command": "D:\\project\\rf_log_mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "rf_log_mcp"
      ]
    }
  }
}

5. 什么情况下不能直接使用这个项目？

如果你的 LLM 平台：

不支持 MCP
或不支持启动本地进程

那就不能直接接入，需要额外做一层集成。

开发路线图

路线图借鉴 Robot Framework VS Code 插件 Output View 的核心语义：先建立完整运行树，再按节点及后代的严重级别生成可展开视图。插件使用事件流和 Webview；本项目继续使用现有标准化模型和 MCP 查询接口，不引入前端状态或 rfstream 协议。

Tree View 用于理解 Suite、Test、Keyword、控制流和消息之间的结构。现有 step_window、cursor 和全局消息搜索继续保留，用于还原完整时序和跨分支追踪。

v0.2：Tree Projection MVP

增加 tree 视图，支持从运行根节点、测试或任意节点开始按需展开直接子节点：

get_view(
  run_id=1,
  view="tree",
  selector="s1-t1",
  projection="failures",
  cursor=None,
  page_size=25
)

selector=None 表示运行根节点。首版支持以下投影：

all：返回全部直接子节点
failures：返回自身失败或包含失败后代的节点，并保留必要祖先
warnings：返回子树最高严重度达到 WARN 或 FAIL 的节点，并保留必要祖先

投影必须基于完整树计算，不能先删除 PASS 节点或原始事件。先确定当前 selector 下符合投影的子节点，再按稳定的 sequence 顺序分页。cursor 应绑定 run_id、selector、projection 和排序条件，不能跨查询条件复用。

节点摘要计划包含：

node_id、parent_id、owner_test_id 和 sequence
规范化节点类型与原始 keyword_type，覆盖 SUITE、TEST、SETUP、TEARDOWN、KEYWORD、FOR、ITERATION、IF、ELSE、TRY、EXCEPT、FINALLY、WHILE 等结构
name、status、elapsed_ms、libname 和参数摘要
child_count、failed_descendant_count、max_descendant_level 和 has_children
可用时返回 source 和 lineno；缺失时保持为空，不根据关键字名称猜测源码位置
用于继续展开的节点引用和分页 cursor

默认只返回节点摘要，不展开大量 TRACE/INFO 正文。Test 只有行号但没有源码路径时，可以使用所属 Suite 的源码路径作为明确的继承来源。

大循环压缩

参考 Output View 对大量成功迭代的处理，Tree View 应压缩同一父节点下连续的 PASS ITERATION，但保留原始节点的可查询性。聚合节点示例：

{
  "group_id": "ig:s1-t1-k2:1-949",
  "kind": "ITERATION_GROUP",
  "status": "PASS",
  "count": 949,
  "first_node_id": "s1-t1-k2-k1",
  "last_node_id": "s1-t1-k2-k949",
  "expand_selector": "ig:s1-t1-k2:1-949"
}

压缩规则：

只压缩达到阈值的连续 PASS 迭代
自身不是 PASS，或子树包含 WARN、FAIL、ERROR 的迭代不参与压缩
失败投影必须直接暴露失败迭代及其必要祖先
聚合节点使用稳定的 group_id；将其作为 selector 时，按 sequence 和分页返回覆盖范围内的原始迭代

重点验收场景：

1000 次循环中只有一个失败迭代时，可以直接定位该 ITERATION，其余连续成功迭代被压缩
Run Keyword And Continue On Failure 场景保留实际失败分支和后续执行结果
Setup、Test、Teardown 分别失败时可以独立展开
IF/ELSE、TRY/EXCEPT/FINALLY、FOR/WHILE 及其迭代节点保持正确父子关系
XML 和 RF 7.2+ JSON 输入生成一致的规范化节点语义
现有 summary、failure_path、step_window 和 search_messages 保持兼容

首版可基于现有 NodeRecord.parent_id 和 sequence 在内存中构建索引。只有真实日志证明扫描成本不可接受时，再增加持久化 nodes 表或其他结构索引。

v0.3：限定范围的消息搜索

扩展 search_messages，允许把检索范围限制到测试、节点或子树：

search_messages(
  run_id=1,
  query="param invalid",
  selector="s1-t1-k2",
  scope="subtree",
  level=None,
  cursor=None
)

范围搜索必须使用完整节点关系确定目标子树，再搜索该范围内的消息，不能先过滤原始事件后重新建树。搜索结果补充所属节点、节点状态、sequence 和简短运行时调用路径。模型可以在失败 ITERATION 内查询请求、回包和变量，也可以继续使用全局搜索追踪对象在 Setup、Test 和 Teardown 中的完整生命周期。

如果真实数据表明内存子树扫描或现有消息索引无法满足延迟目标，再增加节点关系表、递归索引或消息范围索引。

v0.4：源码与节点元数据增强

在 v0.2 基础字段之上，补齐不同 Robot XML/JSON 版本中的源码和调用元数据差异：

{
  "source": "path/to/case.robot",
  "lineno": 123,
  "libname": "SystemIntegrationCommon",
  "source_origin": "node"
}

该阶段需要明确字段来源和可信度，例如节点直接提供、从所属 Suite 继承或输入格式不支持。运行树负责定位实际调用实例、分支、迭代和参数，源码元数据用于解释关键字定义和业务逻辑。缺失字段保持为空，不通过关键字名称猜测文件位置。

v0.5：真实使用评估

Tree View 上线后，通过真实日志分析记录以下聚合指标：

Tree View 的展开深度、分页次数、返回 token 和 projection 使用比例
PASS 迭代压缩前后的节点数量及失败迭代命中率
step_window 是否仍被频繁用于大范围查询
子树搜索是否减少跨测试或跨迭代的无关命中
消息截断是否经常导致二次查询
循环、retry 和重复 TRACE/INFO 是否仍是主要返回体积来源

在积累足够使用记录后，再决定是否增加：

按循环迭代或运行节点分组的搜索结果
重复消息折叠及首次、末次样本
单条长消息的分片读取
持久化节点索引和更复杂的节点筛选

这些能力不会提前写成固定接口，避免基于假设过度设计。结构化查询仍作为可选能力；get_view 保留自定义 budget 和 cursor 分页，search_messages 保留全局搜索和 cursor 分页。工具只提供数据与结构，不负责判断根因或建议模型下一步操作。

实施顺序

定义规范化节点类型、projection、cursor 和循环压缩契约。
增加深循环、失败迭代、条件分支、Continue On Failure 和 Teardown 失败测试夹具。
基于现有节点模型实现完整树索引、后代严重级别聚合和直接子节点展开。
实现 PASS 迭代压缩，并保留原始迭代的查询入口。
增加子树限定搜索和运行时调用路径。
补齐源码字段来源、继承规则和版本差异。
更新 MCP 文档和相关 Skill 能力说明。
根据真实调用记录决定是否引入持久化节点索引、高级分组和长消息读取能力。

开发检查

uv run ruff check .
uv run pytest

Как установить

Выполни в терминале:

claude mcp add rf-log-mcp -- npx

Command Palette