mcp-logback-analyzer 1.0.1

一个基于 FastMCP 的 Model Context Protocol (MCP) 工具，用于分析 Java Spring Boot 应用的日志文件，自动检测代码缺陷并生成修复建议。

MCP 日志分析工具 - 使用指南

一个基于 FastMCP 的 Model Context Protocol (MCP) 工具，用于分析 Java Spring Boot 应用的日志文件，自动检测代码缺陷并生成修复建议。

---

📋 目录

1. 功能特点
2. 快速开始
3. 在 Cursor 中集成
4. 工具功能
5. 使用示例
6. 常见问题

---

功能特点

核心能力

• 🔍 智能日志分析：自动提取异常信息，不限于预定义模式，可以识别所有类型的异常
• 📊 堆栈跟踪过滤：自动保留应用包下的堆栈信息，过滤底层框架信息（如 java., org.springframework. 等）
• 🎯 缺陷检测：自动识别异常类型并推断严重程度（critical / high / medium）
• 🔧 自动修复建议：将异常信息交给 AI 分析，生成代码修复建议
• 🌐 跨平台支持：支持 Windows、Linux、Mac，自动处理路径差异
• ⚙️ 零配置使用：安装后即可使用，自动从 logback 配置读取信息
• 🚀 Token 优化：智能提取关键信息，过滤无关内容，减少 token 消耗

智能分析特性

自动提取异常信息：

• ✅ 自动识别所有异常类型（不限于预定义模式）
• ✅ 自动提取异常消息
• ✅ 自动推断严重程度
• ✅ 保留应用包下的堆栈信息（类名、方法名、行号）
• ✅ 过滤底层框架信息，减少冗余

Token 优化策略：

• ✅ 自动提取关键信息，去除冗余前缀（时间戳、PID、线程ID等）
• ✅ 过滤无关日志行（DEBUG、启动信息等）
• ✅ 限制返回数量（最多 50 个缺陷，30 个搜索结果）
• ✅ 按严重程度排序，优先显示严重问题

配置灵活性

工具支持多种配置方式，按优先级自动选择：

1. 方法参数（调用时直接传入）
2. 环境变量（Cursor MCP 配置或系统环境变量）
3. logback 配置文件（自动读取）
4. 默认值（工具内置）

无需手动配置即可使用！ 工具会自动：

• 从 logback 配置读取日志路径
• 从配置或目录名推断应用名称
• 从应用名称推断应用包名
• 处理 Windows/Linux 路径差异

---

快速开始

安装

pip install mcp-logback-analyzer

验证安装

python -c "from tools.log_analyzer_tool import LogAnalyzer; print('安装成功！')"

使用流程图

flowchart TD
    Start([开始使用]) --> Install[1. 安装工具<br/>pip install mcp-logback-analyzer]
    Install --> Config[2. 配置 Cursor MCP]
    Config --> Config1[找到配置文件位置]
    Config1 --> Config2[添加 MCP 服务器配置]
    Config2 --> Config3[重启 Cursor]
    Config3 --> Use[3. 开始使用]
    
    Use --> MethodA[方式 A: 在 Cursor 中直接对话]
    Use --> MethodB[方式 B: Python 代码调用]
    
    MethodA --> Dialog1["分析一下错误日志"]
    MethodA --> Dialog2["搜索日志中的关键词"]
    MethodA --> Dialog3["查看 logback 配置"]
    
    MethodB --> Code[from tools.log_analyzer_tool<br/>import LogAnalyzer<br/>analyzer = LogAnalyzer<br/>result = analyzer.analyze_logs]
    
    Dialog1 --> Result[4. 查看结果]
    Dialog2 --> Result
    Dialog3 --> Result
    Code --> Result
    
    Result --> Result1[缺陷列表<br/>按严重程度排序]
    Result --> Result2[异常类型和消息]
    Result --> Result3[应用包堆栈信息]
    Result --> Result4[修复建议<br/>由 AI 生成]
    
    style Start fill:#e1f5ff
    style Install fill:#fff4e1
    style Config fill:#fff4e1
    style Use fill:#fff4e1
    style Result fill:#e8f5e9
    style MethodA fill:#f3e5f5
    style MethodB fill:#f3e5f5

---

在 Cursor 中集成

步骤 1：找到配置文件

根据你的操作系统，找到 Cursor 的 MCP 配置文件：

Windows:

%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Mac:

~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Linux:

~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

步骤 2：添加配置

打开配置文件，添加以下内容：

{
  "mcpServers": {
    "log-analyzer": {
      "command": "python",
      "args": ["-m", "tools.log_analyzer_tool"],
      "cwd": "${workspaceFolder}",
      "env": {
        "LOGBACK_CONFIG_PATH": "${workspaceFolder}/src/resource/logback-spring.xml"
      }
    }
  }
}

说明：

• command: Python 解释器命令（python 或 py）
• args: 使用模块方式运行（推荐）
• cwd: 工作目录设置为项目根目录
• env: 环境变量配置（可选，工具会自动从 logback 配置读取）

步骤 3：重启 Cursor

保存配置文件后，重启 Cursor IDE 使配置生效。

步骤 4：开始使用

在 Cursor 中直接与 AI 对话：

分析一下错误日志
搜索日志中的 NullPointerException
查看 logback 配置

---

工具功能

工具提供了 4 个主要功能：

1. analyze_logs - 分析日志文件

自动分析日志文件，检测代码缺陷。

参数：

• log_level: 日志级别（"error", "warn", "all"），默认 "error"
• max_lines: 最大读取行数，默认 1000（也可以说"检索行数"）
• error_log_path: 错误日志文件路径（可选）
• warn_log_path: 警告日志文件路径（可选）
• all_log_path: 全部日志文件路径（可选）

使用示例：

分析一下错误日志
分析最近 500 行的错误日志
分析警告级别的日志，检索 2000 行
分析指定路径的日志：D:\logs\error.log

返回结果：

• 缺陷列表（按严重程度排序）
• 异常类型和消息
• 应用包下的堆栈信息
• 最多返回 50 个缺陷

2. search_logs - 搜索日志关键词

在日志文件中搜索指定的关键词。

参数：

• keyword: 搜索关键词（必填）
• log_level: 日志级别，默认 "all"
• max_lines: 最大读取行数，默认 1000
• error_log_path: 错误日志文件路径（可选）
• warn_log_path: 警告日志文件路径（可选）
• all_log_path: 全部日志文件路径（可选）

使用示例：

搜索日志中的 NullPointerException
查找包含 "数据库连接失败" 的日志
在错误日志中搜索 "timeout"

返回结果：

• 匹配的日志行列表
• 行号和关键信息
• 最多返回 30 个匹配结果

3. get_logback_config - 获取 logback 配置

读取并解析 logback 配置文件。

参数：

• logback_config: logback 配置文件路径（可选）

使用示例：

查看 logback 配置
获取日志配置文件信息

返回结果：

• 应用名称
• 日志路径
• Appender 配置

4. auto_fix_defect - 生成修复建议

根据检测到的缺陷信息，生成代码修复建议。

参数：

• defect_info: 缺陷信息字典（必填）
• source_code_path: 源代码文件路径（可选）

使用示例：

帮我修复这个 NullPointerException
为这个数据库异常生成修复建议

---

使用示例

场景 1：日常错误排查

分析一下最近的错误日志

工具会自动：

1. 读取错误日志文件
2. 提取异常信息
3. 识别异常类型和严重程度
4. 返回最严重的缺陷列表

场景 2：搜索特定错误

搜索日志中的 "数据库连接超时"

工具会返回所有匹配的日志行，包括行号和关键信息。

场景 3：自定义日志路径

如果日志文件不在默认位置：

分析这个路径的日志：D:\logs\custom\error.log

或者通过环境变量配置（在 Cursor MCP 配置中）：

"env": {
  "ERROR_LOG_PATH": "D:\\logs\\custom\\error.log"
}

场景 4：分析不同级别的日志

先分析错误日志
再分析警告日志

---

工具调用流程图

analyze_logs - 分析日志流程

flowchart TD
    Start([用户请求: 分析日志]) --> Read[读取日志文件]
    Read --> GetPath[从 logback 配置或<br/>环境变量获取路径]
    GetPath --> Filter[过滤无关日志行]
    Filter --> Remove[移除 DEBUG、启动信息等]
    Remove --> Extract[提取异常信息]
    Extract --> Identify[识别异常类型]
    Extract --> GetMsg[提取异常消息]
    Extract --> FilterStack[过滤堆栈跟踪<br/>保留应用包信息]
    Identify --> Severity[推断严重程度]
    GetMsg --> Severity
    FilterStack --> Severity
    Severity --> Sort[按严重程度排序]
    Sort --> Limit[限制返回数量<br/>最多 50 个缺陷]
    Limit --> Return([返回结果])
    
    style Start fill:#e1f5ff
    style Read fill:#fff4e1
    style Extract fill:#e8f5e9
    style Return fill:#e8f5e9

search_logs - 搜索日志流程

flowchart TD
    Start([用户请求: 搜索关键词]) --> Read[读取日志文件]
    Read --> Search[搜索关键词<br/>不区分大小写]
    Search --> Extract[提取关键信息]
    Extract --> Filter[过滤无关日志行]
    Filter --> Limit[限制返回数量<br/>最多 30 个匹配]
    Limit --> Return([返回结果])
    
    style Start fill:#e1f5ff
    style Search fill:#fff4e1
    style Return fill:#e8f5e9

get_logback_config - 获取配置流程

flowchart TD
    Start([用户请求: 获取配置]) --> Parse[解析 logback XML 文件]
    Parse --> ExtractName[提取应用名称]
    Parse --> ExtractPath[提取日志路径]
    Parse --> ExtractAppender[提取 Appender 配置]
    ExtractName --> Merge[合并配置信息]
    ExtractPath --> Merge
    ExtractAppender --> Merge
    Merge --> Return([返回配置信息])
    
    style Start fill:#e1f5ff
    style Parse fill:#fff4e1
    style Return fill:#e8f5e9

auto_fix_defect - 生成修复建议流程

flowchart TD
    Start([用户请求: 生成修复建议]) --> Analyze[分析缺陷类型]
    Analyze --> Match[匹配修复模板]
    Match --> Generate[生成修复建议]
    Generate --> Return([返回修复建议])
    
    style Start fill:#e1f5ff
    style Analyze fill:#fff4e1
    style Return fill:#e8f5e9

---

配置说明

自动配置（推荐）

工具会自动从以下位置获取配置：

1. logback 配置文件：自动读取 logback-spring.xml 中的配置
2. 应用名称：从 logback 配置或当前目录名自动推断
3. 日志路径：从 logback 配置自动获取

无需手动配置即可使用！

可选配置

如果需要自定义，可以在 Cursor MCP 配置中添加环境变量：

"env": {
  "LOGBACK_CONFIG_PATH": "${workspaceFolder}/src/resource/logback-spring.xml",
  "SPRING_APPLICATION_NAME": "your-app-name",
  "APP_PACKAGE": "com.example.yourpackage",
  "ERROR_LOG_PATH": "${workspaceFolder}/logs/error.log"
}

环境变量说明：

环境变量	说明	是否必需
LOGBACK_CONFIG_PATH	logback 配置文件路径	否（有默认值）
SPRING_APPLICATION_NAME	应用名称	否（自动推断）
APP_PACKAGE	应用包名（用于过滤堆栈跟踪）	否（自动推断）
ERROR_LOG_PATH	错误日志文件路径	否（从 logback 读取）
WARN_LOG_PATH	警告日志文件路径	否（从 logback 读取）
ALL_LOG_PATH	全部日志文件路径	否（从 logback 读取）

配置优先级流程图

flowchart TD
    Start([获取配置值]) --> Check1{方法参数<br/>是否存在?}
    Check1 -->|是| Use1[使用方法参数<br/>优先级 1]
    Check1 -->|否| Check2{环境变量<br/>是否存在?}
    Check2 -->|是| Use2[使用环境变量<br/>优先级 2]
    Check2 -->|否| Check3{logback 配置<br/>是否存在?}
    Check3 -->|是| Use3[使用 logback 配置<br/>优先级 3]
    Check3 -->|否| Use4[使用默认值<br/>优先级 4]
    
    Use1 --> Result([返回配置值])
    Use2 --> Result
    Use3 --> Result
    Use4 --> Result
    
    style Start fill:#e1f5ff
    style Use1 fill:#ffebee
    style Use2 fill:#fff3e0
    style Use3 fill:#e8f5e9
    style Use4 fill:#f3e5f5
    style Result fill:#e8f5e9

---

常见问题

Q1: 工具无法找到日志文件？

解决方案：

1. 检查 logback 配置：

   查看 logback 配置
   

2. 使用绝对路径：

   分析这个路径的日志：D:\data\logs\app\error.log
   

3. 在 Cursor MCP 配置中设置：

   "env": {
     "ERROR_LOG_PATH": "D:\\data\\logs\\app\\error.log"
   }
   

Q2: 应用名称识别不正确？

解决方案：

在 Cursor MCP 配置中添加：

"env": {
  "SPRING_APPLICATION_NAME": "your-app-name"
}

Q3: 堆栈跟踪信息太多？

解决方案：

配置应用包名，工具会自动过滤框架包的堆栈信息：

"env": {
  "APP_PACKAGE": "com.example.yourpackage"
}

工具会自动：

• 过滤掉 java., org.springframework. 等框架包
• 只保留应用包下的堆栈信息
• 最多保留 3 层应用堆栈

Q4: 在 Cursor 中无法使用工具？

检查清单：

1. ✅ 工具是否已安装：pip show mcp-logback-analyzer
2. ✅ MCP 配置文件是否正确
3. ✅ Cursor 是否已重启
4. ✅ Python 路径是否正确

调试方法：

手动测试工具：

python -m tools.log_analyzer_tool

如果工具正常运行，说明安装正确，问题可能在 Cursor 配置。

Q5: Windows 路径问题？

工具会自动处理路径转换：

• Linux 路径 /data/logs 会自动转换为 D:\data\logs（根据项目所在磁盘）

如果仍有问题，使用绝对路径：

"env": {
  "ERROR_LOG_PATH": "D:\\data\\logs\\app\\error.log"
}

---

版本：1.0.0
最后更新：2025-01-13