mcp-logback-analyzer 1.0.2

一个基于 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 路径差异

---

快速开始

环境准备

Python 版本要求

• Python 3.8 或更高版本（推荐 Python 3.9+）
• 支持 Windows、Linux、Mac 操作系统

检查 Python 环境

在开始之前，请确保已安装 Python 并检查版本：

# 检查 Python 版本
python --version
# 或
py --version

预期输出示例：

Python 3.9.0
# 或
Python 3.12.0

如果未安装 Python 或版本过低，请访问 Python 官网 下载并安装。

检查 pip 是否可用

# 检查 pip 版本
pip --version
# 或
py -m pip --version

预期输出示例：

pip 23.0.1 from /usr/local/lib/python3.9/site-packages/pip (python 3.9)

如果 pip 不可用，请参考 pip 安装指南。

安装

pip install mcp-logback-analyzer

验证安装

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

使用步骤

开始使用
    │
    ├─→ 1. 环境准备（检查 Python >= 3.8）
    │
    ├─→ 2. 安装工具（pip install mcp-logback-analyzer）
    │
    ├─→ 3. 配置 Cursor MCP
    │      ├─ 找到配置文件
    │      ├─ 添加服务器配置
    │      └─ 重启 Cursor
    │
    ├─→ 4. 开始使用
    │      ├─ 方式 A: 在 Cursor 中对话
    │      │   └─ "分析一下错误日志"
    │      │
    │      └─ 方式 B: Python 代码调用
    │          └─ from tools.log_analyzer_tool import LogAnalyzer
    │
    └─→ 5. 查看结果
         ├─ 缺陷列表（按严重程度排序）
         ├─ 异常类型和消息
         ├─ 应用包堆栈信息
         └─ 修复建议（AI 生成）

---

在 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 - 分析日志流程

用户请求
    │
    ├─→ 读取日志文件
    │      │
    │      └─ 从 logback 配置或环境变量获取路径
    │
    ├─→ 过滤无关日志行（移除 DEBUG、启动信息等）
    │
    ├─→ 提取异常信息
    │      ├─ 识别异常类型
    │      ├─ 提取异常消息
    │      └─ 过滤堆栈跟踪（保留应用包信息）
    │
    ├─→ 推断严重程度
    │
    ├─→ 按严重程度排序
    │
    ├─→ 限制返回数量（最多 50 个缺陷）
    │
    └─→ 返回结果

search_logs - 搜索日志流程

用户请求
    │
    ├─→ 读取日志文件
    │
    ├─→ 搜索关键词（不区分大小写）
    │
    ├─→ 提取关键信息
    │
    ├─→ 过滤无关日志行
    │
    ├─→ 限制返回数量（最多 30 个匹配）
    │
    └─→ 返回结果

get_logback_config - 获取配置流程

用户请求
    │
    ├─→ 解析 logback XML 文件
    │
    ├─→ 提取配置信息
    │      ├─ 应用名称
    │      ├─ 日志路径
    │      └─ Appender 配置
    │
    ├─→ 合并配置信息
    │
    └─→ 返回配置信息

auto_fix_defect - 生成修复建议流程

用户请求
    │
    ├─→ 分析缺陷类型
    │
    ├─→ 匹配修复模板
    │
    ├─→ 生成修复建议
    │
    └─→ 返回修复建议

---

配置说明

自动配置（推荐）

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

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 读取）

配置优先级说明

获取配置值
    │
    ├─→ 方法参数存在？
    │      │
    │      ├─ 是 → 使用方法参数（优先级 1）✓
    │      │
    │      └─ 否 → 环境变量存在？
    │              │
    │              ├─ 是 → 使用环境变量（优先级 2）✓
    │              │
    │              └─ 否 → logback 配置存在？
    │                      │
    │                      ├─ 是 → 使用 logback 配置（优先级 3）✓
    │                      │
    │                      └─ 否 → 使用默认值（优先级 4）✓
    │
    └─→ 返回配置值

---

常见问题

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