rf-log-mcp

用于检查 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：分页游标；为空表示没有下一页

Related MCP server: wopee-mcp

关键说明

• 这个项目是 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

1. 本地环境的依赖版本可能和 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 分页。工具只提供数据与结构，不负责判断根因或建议模型下一步操作。

实施顺序

1. 定义规范化节点类型、projection、cursor 和循环压缩契约。

2. 增加深循环、失败迭代、条件分支、Continue On Failure 和 Teardown 失败测试夹具。

3. 基于现有节点模型实现完整树索引、后代严重级别聚合和直接子节点展开。

4. 实现 PASS 迭代压缩，并保留原始迭代的查询入口。

5. 增加子树限定搜索和运行时调用路径。

6. 补齐源码字段来源、继承规则和版本差异。

7. 更新 MCP 文档和相关 Skill 能力说明。

8. 根据真实调用记录决定是否引入持久化节点索引、高级分组和长消息读取能力。

开发检查

uv run ruff check .
uv run pytest