Skip to content

Waiting-Chai/log-mcp-rs

BranchesTags

Repository files navigation

Log Search MCP Server

Rust 实现的高性能日志搜索 MCP (Model Context Protocol) 服务器，支持 SSE (Server-Sent Events) 和 Stdio 两种模式。

它允许 AI Agent (如 Trae, Claude Desktop, Bisheng 等) 实时读取、搜索和分析服务器上的日志文件。支持多行日志解析、逻辑组合搜索、时间范围过滤以及并发文件扫描。

License Rust

🌟 核心特性

  • 双模式支持：
    • SSE 模式：通过 HTTP 提供服务，支持远程访问，适用于 Bisheng 等 web 架构的 Agent。
    • Stdio 模式：通过标准输入输出交互，适用于本地 Trae、Claude Desktop 等客户端。
  • 高效搜索：
    • 支持逻辑组合 (AND/OR/NOT)、正则表达式、时间范围过滤。
    • 自动识别多行日志（如 Java 堆栈跟踪）。
    • 并发扫描多个日志文件。
  • 配置热更新：修改配置文件后自动重载，无需重启服务。
  • 部署友好：
    • 提供 Docker 和 Docker Compose 一键部署方案。
    • 针对国内网络环境优化了 Docker 构建过程（使用阿里云源和 rsproxy）。
  • 文件处理：自动处理 Gzip 压缩文件，支持多种编码检测。

💡 场景用例 (Scenario Use Cases)

RCS 车辆交管状况分析 (RCS Traffic Analysis)

用户提问: "昨天晚上九点车辆的交管状况"

Agent 行为:

  1. 自动调用 search_logs 工具。
  2. 设定时间范围 (例如 2025-11-08 21:00:00 左右)。
  3. 搜索关键词 [TRAFFIC] 或车辆 ID。
  4. 获取日志并分析车辆坐标、路径锁定情况。

MCP 工具返回结果示例:

{
  "total_hits": 2256,
  "page": 1,
  "page_size": 20,
  "total_pages": 113,
  "hits": [
    {
      "file_path": "/Users/maweilong/fsdownload/rcs-kernel-traffic-2025-11-08-14-1.log",
      "start_line": 31,
      "end_line": 135,
      "content": "2025-11-08 14:00:00.272 DEBUG [TRAFFIC] [TID:348] [Thread:TrafficExecutor-test] [Class:TrafficLog] [Method:doLogic] [Line:65] - --------------------------------------------------------------------------------\ntraffic#logic#whole areaId: [test], trafficNumber: [44170], vehicleId: [sim_0015]\n---> checkPoint: [[LM7360, LM95936, LM7365, PP95939, LM95935, AP9358]]\n---> checkPoint details: [[{\"flgIsRotation\":false,\"lockedTime\":1762581593939,\"pointId\":\"LM7360\",\"vehicleId\":\"sim_0015\",\"vehicleSpace\":{\"spaceBoxes\":[{\"key\":\"VEHICLE_SCALE\",\"value\":{\"centerX\":79.1399993896484,\"centerY\":-60.2760009765625,\"halfHeight\":0.3000000000000031,\"halfWidth\":0.499999999999998,\"height\":0.6000000000000062,\"width\":0.999999999999996,\"x1\":79.44000122624892,\"x2\":79.43999755304382,\"x3\":78.83999755304787,\"x4\":78.84000122625297,\"xAxis\":[-3.673205100085412E-6,0.9999999999932538],\"y1\":-60.775999874597595,\"y2\":-59.775999874604345,\"y3\":-59.776002078527405,\"y4\":-60.776002078520655,\"yAxis\":[-0.9999999999932537,-3.673205100085359E-6]}},{\"key\":\"ROTATION\",\"value\":{}}],\"trafficVehicleScale\":{\"angle\":90.00021045914971,\"height\":0.00999999977648258,\"length\":1.0,\"mapId\":\"test\",\"tripe\":{\"x\":79.149,\"y\":-64.758,\"z\":0.0},\"vehicleId\":\"sim_0015\",\"vehicleType\":\"AMR\",\"width\":0.6},\"vehicleId\":\"sim_0015\"}}, ...]]"
    }
  ]
}

效果: Agent 能够读取完整的日志上下文（包含多行 JSON 结构），解析出车辆 sim_0015 在特定时刻的详细状态：

  • 位置: 坐标 (79.14, -60.28)
  • 路径锁定: 正在通过 LM7360, LM95936 等关键点。
  • 车辆姿态: 角度 90.0 度。 从而帮助用户判断车辆是否在路口发生死锁或路径规划异常。

🛠️ 可用工具 (Available Tools)

本服务提供两个核心 MCP 工具，Agent 可通过 JSON-RPC 协议调用。

1. list_log_files

列出指定路径下符合条件的日志文件列表。

参数说明:

  • root_path (string, 可选): 扫描的根目录。如果未提供，默认使用 config.yaml 中配置的全局路径。
  • include_globs (array[string], 可选): 包含的文件名模式 (Glob)，例如 ["*.log", "**/*.txt"]。
  • exclude_globs (array[string], 可选): 排除的文件名模式，例如 ["*.gz", "*.tmp"]。

用途: 在开始搜索前，Agent 可以先调用此工具查看有哪些日志文件可用，或者根据文件名模式筛选目标文件。

2. search_logs

执行深度日志搜索，支持逻辑组合、正则匹配和时间过滤。这是本服务的核心工具。

参数结构详解:

该工具接受一个 JSON 对象作为输入，包含以下顶级字段：

1. scan_config (Object, 必填)

定义文件扫描的范围和策略。

  • root_path (string, 可选):
    • 扫描的起始根目录（绝对路径）。
    • 如果未提供或为空，服务将回退到使用 config.yaml 中 log_sources.log_file_paths 配置的全局文件列表。
  • include_globs (array[string], 可选):
    • 白名单匹配模式。仅处理匹配这些 Glob 模式的文件。
    • 示例: ["*.log", "error-*.txt", "**/*.log"]
  • exclude_globs (array[string], 可选):
    • 黑名单匹配模式。忽略匹配这些 Glob 模式的文件。
    • 示例: ["*.gz", "*.tmp", "access.log"]

2. logical_query (Object, 必填)

定义核心搜索逻辑。支持布尔逻辑组合（AND/OR/NOT）。

  • must (Array): AND (必须包含)
    • 列表中的所有条件都必须满足。
  • any (Array): OR (至少包含一个)
    • 列表中的条件至少有一个必须满足。
  • none (Array): NOT (不能包含)
    • 列表中的所有条件都必须不存在。

条件单元 (Query Unit) 的格式: must, any, none 数组中的每个元素可以是：

  1. 简单字符串: "Error" (默认不区分大小写，非正则，非全词匹配)
  2. 高级对象: 
    {
  "query": "正则表达式或关键词",
  "regex": true,           // (bool) 是否作为正则表达式处理。默认为 false
  "case_sensitive": true,  // (bool) 是否区分大小写。默认为 false
  "whole_word": false      // (bool) 是否全词匹配。默认为 false
}

3. time_filter (Object, 可选)

按日志时间戳进行过滤。如果未提供，则搜索所有时间。

  • start_time (string, 可选):
    • 搜索起始时间（包含）。
    • 别名: startTime, after
    • 格式: 支持常见的 ISO 8601 或类似格式，如 2024-01-01 12:00:00。
  • end_time (string, 可选):
    • 搜索结束时间（包含）。
    • 别名: endTime, before
  • timestamp_regex (string, 可选):
    • 用于从日志行中提取时间戳的正则表达式。
    • 如果未提供，将使用 config.yaml 中的 default_timestamp_regex。

4. 分页与控制参数 (Top-level fields)

  • page (integer): 页码，从 1 开始。默认 1。
  • page_size (integer): 每页返回的条数。默认 20。
  • max_hits (integer, 可选):
    • 搜索命中数达到此值后提前停止。用于性能优化。
  • hard_timeout_ms (integer, 可选):
    • 搜索执行的硬超时时间（毫秒）。超时后返回部分结果。
  • include_content (boolean):
    • 结果中是否包含完整的日志行内容。默认为 true。
    • 如果仅需统计数量，可设为 false 以减少网络传输。
  • log_start_pattern (string, 可选):
    • 用于识别多行日志起始行的正则表达式。
    • 用于覆盖 config.yaml 中的默认设置，适应不同格式的日志文件。

完整调用示例 (JSON):

{
  "scan_config": {
    "root_path": "/var/log",
    "include_globs": ["syslog", "*.err"]
  },
  "logical_query": {
    "must": [
      { "query": "error", "case_sensitive": false }
    ],
    "any": [
      { "query": "timeout" },
      { "query": "connection refused" }
    ],
    "none": [
      "test_environment",
      { "query": "^DEBUG", "regex": true }
    ]
  },
  "time_filter": {
    "after": "2024-12-15 10:00:00",
    "before": "2024-12-15 11:00:00"
  },
  "page": 1,
  "page_size": 50,
  "include_content": true
}

🚀 快速开始 (Docker Compose 推荐)

这是最简单的部署方式，适合在服务器上长期运行。

1. 获取代码

git clone https://github.com/your-repo/log-mcp-rs.git
cd log-mcp-rs

2. 配置

项目根目录已经包含 docker-compose.yml 和 config.example.yaml。

你可以根据需要修改 docker-compose.yml 中的卷映射，将主机上的日志目录映射到容器内：

volumes:
  - ./config.yaml:/app/config.yaml  # 配置文件
  - /var/log:/var/log               # 系统日志目录
  - /home/logs:/home/logs           # 应用日志目录 (根据实际情况修改)

确保 config.yaml 存在（可以复制示例）：

cp config.example.yaml config.yaml

修改 config.yaml 以匹配你的需求，特别是 log_file_paths：

server:
  mode: http       # 使用 http 模式以支持 SSE
  port: 3000
  host: "0.0.0.0"

log_sources:
  log_file_paths:
    - "/var/log/syslog"
    - "/home/logs/app.log"

3. 启动服务

docker compose up -d --build

服务将在 http://localhost:3000 启动。

🛠️ 本地开发与测试

如果你想在本地运行而不使用 Docker：

前置要求

  • Rust 1.75+
  • Cargo

运行

# 1. 复制配置文件
cp config.example.yaml config.yaml

# 2. 运行 (默认读取 config.yaml)
cargo run --release -- config.yaml

🔌 集成指南

1. 集成到 Bisheng (SSE 模式)

在 Bisheng 的 MCP 服务器配置中，添加以下 JSON 配置：

{
  "mcpServers": {
    "log-search": {
      "type": "sse",
      "name": "日志搜索服务",
      "description": "提供服务器日志的实时搜索和查询功能。支持按关键词、正则表达式、时间范围过滤日志。适用于系统故障排查、错误日志定位。",
      "url": "http://<你的服务器IP>:3000/sse"
    }
  }
}

2. 集成到 Trae / Claude Desktop (Stdio 模式)

如果作为本地工具运行，或者通过 SSH 隧道连接，可以使用 Stdio 模式。

修改 config.yaml：

server:
  mode: stdio

在 Trae/Claude 的配置中添加：

{
  "mcpServers": {
    "log-search": {
      "command": "/path/to/log-search-mcp",
      "args": [
        "/path/to/config.yaml"
      ]
    }
  }
}

⚙️ 配置文件说明 (config.yaml)

server:
  mode: http         # 运行模式: http, stdio, 或 both
  port: 3000         # HTTP 端口 (仅 http/both 模式有效)
  host: "0.0.0.0"    # 监听地址

log_parser:
  line_start_regex: '^\d{4}-\d{2}-\d{2}'  # 用于识别多行日志的起始行正则
  default_timestamp_regex: '\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}' # 时间戳提取正则

search:
  default_page_size: 20
  max_page_size: 200
  default_timeout_ms: 5000
  max_concurrent_files: 4

log_sources:
  log_file_paths:    # 待扫描的日志文件绝对路径
    - "/var/log/syslog"

📡 API 接口 (SSE 模式)

  • GET /sse: 建立 SSE 连接，接收服务端事件。
  • POST /message: 发送 JSON-RPC 请求 (如 list_tools, call_tool)。

📝 开发日志

  • 2025-12-12:
    • 新增 SSE Server 支持，兼容标准 MCP 协议。
    • 添加 docker-compose 支持，优化部署流程。
    • 优化 Dockerfile 国内构建速度。
    • 修复多行日志解析问题。

About

High-performance Rust MCP for log diagnostics.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages