mcp-logback-analyzer 1.0.0

日志检索和分析工具 - 基于 FastMCP 的 MCP 工具，支持分析 logback 配置的日志文件

日志分析工具完整文档

📋 目录

1. 项目介绍
2. 安装和运行
3. 工具功能说明
4. 配置说明
5. 分析逻辑说明
6. 使用示例
7. 故障排除
8. 跨平台支持

---

项目介绍

项目概述

一个用于开发 Model Context Protocol (MCP) 工具的 Python 项目，提供日志检索和分析功能。工具可以分析 logback-spring.xml 配置的日志文件，检测代码缺陷并生成修复建议。

项目结构

mcp-tools/
├── src/              # 源代码目录
│   ├── resource/     # 资源文件目录
│   │   └── logback-spring.xml  # 日志配置文件
│   └── tools/        # MCP 工具实现
│       ├── __init__.py
│       ├── log_analyzer_tool.py      # 日志分析工具（核心代码）
│       └── log_analyzer_example.py   # 使用示例代码
├── requirements.txt  # Python 依赖
├── pyproject.toml   # 项目配置
├── .gitignore       # Git 忽略文件
└── README.md        # 项目说明

---

安装和运行

安装依赖

# 安装依赖
py -m pip install -r requirements.txt

运行方式

方式一：在 Cursor 中使用运行按钮（最简单）

1. 运行示例代码

   • 打开文件：src/tools/log_analyzer_example.py
   • 点击右上角的 ▶️ 运行 按钮
   • 或按快捷键 Ctrl + F5（不调试）或 F5（调试模式）

2. 运行 FastMCP 服务器

   • 打开文件：src/tools/log_analyzer_tool.py
   • 点击右上角的 ▶️ 运行 按钮
   • 服务器会在终端中启动

方式二：使用终端运行

1. 打开终端：按 Ctrl + `（反引号）打开集成终端
2. 运行命令：

# 运行示例
py src/tools/log_analyzer_example.py

# 运行 FastMCP 服务器
py src/tools/log_analyzer_tool.py

方式三：使用调试配置（推荐）

1. 点击左侧的 🐛 运行和调试 图标（或按 Ctrl + Shift + D）
2. 在顶部下拉菜单中选择：
   • 运行日志分析工具 (FastMCP 服务器) - 启动 MCP 服务器
   • 运行日志分析示例 - 运行示例代码
3. 点击绿色的 ▶️ 按钮或按 F5

---

工具功能说明

1. analyze_logs - 分析日志文件

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

功能：

• 支持 error、warn、all 三种日志级别
• 智能分析模式：自动提取所有异常信息，交给大模型分析，无需预定义错误模式
• 自动识别异常类型和严重程度
• 大模型生成修复建议

参数：

• log_level (str): 日志级别，可选值："error", "warn", "all"，默认："error"
• max_lines (int): 最大读取行数，默认：1000
  • 支持自然语言：可以直接说"检索最近 500 行"、"读取 2000 行日志"等，不需要说 max_lines
• logback_config (str, 可选): logback 配置文件路径
• error_log_path (str, 可选): 错误日志文件路径
• warn_log_path (str, 可选): 警告日志文件路径
• all_log_path (str, 可选): 全部日志文件路径

自然语言使用示例：

• "分析最近 500 行错误日志"
• "检索最近 2000 行日志"
• "读取最近 1000 行警告日志"
• "分析最近 3000 行全部日志"

2. get_logback_config - 获取 logback 配置信息

解析 logback-spring.xml 配置文件，提取日志路径、应用名称等信息。

参数：

• logback_config (str, 可选): logback 配置文件路径

3. auto_fix_defect - 自动修复建议

根据缺陷信息生成自动修复建议，提供代码修复模板。

参数：

• defect_info (dict): 缺陷信息字典（必需）
• source_code_path (str, 可选): 源代码文件路径

支持的缺陷类型：

• 空指针异常
• 数组越界异常
• 数据库异常
• 连接异常
• 内存溢出
• 栈溢出
• 类未找到
• 方法未找到
• 超时异常
• 文件未找到
• 权限拒绝

4. search_logs - 搜索日志关键词

在日志中搜索关键词，支持多文件搜索，返回匹配的行号和内容。

优化措施（减少 token 消耗）：

• ✅ 过滤无关日志：自动过滤无关内容
• ✅ 提取关键信息：只保留匹配关键词的核心内容
• ✅ 限制返回数量：最多返回 30 个匹配结果
• ✅ 精简日志内容：每条日志最多 150 字符

参数：

• keyword (str): 搜索关键词（必需）
• log_level (str): 日志级别，默认："all"
• max_lines (int): 最大读取行数，默认：1000
• logback_config (str, 可选): logback 配置文件路径
• error_log_path (str, 可选): 错误日志文件路径
• warn_log_path (str, 可选): 警告日志文件路径
• all_log_path (str, 可选): 全部日志文件路径

---

配置说明

配置优先级

工具参数 > 环境变量 > logback 配置

详细说明：

• 工具参数：调用工具时传入的参数（最高优先级）
• 环境变量：在 Cursor MCP 配置或系统环境变量中设置
• logback 配置：从 logback-spring.xml 配置文件中读取（最低优先级）

配置方式

方式一：在 Cursor MCP 配置中设置环境变量（推荐）

配置文件位置：

• Windows: %APPDATA%\Cursor\User\globalStorage\mcp.json
• macOS: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
• Linux: ~/.config/Cursor/User/globalStorage/mcp.json

完整配置示例：

{
  "mcpServers": {
    "log-analyzer": {
      "command": "py",
      "args": [
        "${workspaceFolder}/src/tools/log_analyzer_tool.py"
      ],
      "cwd": "${workspaceFolder}",
      "env": {
        "LOGBACK_CONFIG_PATH": "${workspaceFolder}/src/resource/logback-spring.xml",
        "ERROR_LOG_PATH": "${workspaceFolder}/logs/error.log",
        "WARN_LOG_PATH": "${workspaceFolder}/logs/warn.log",
        "ALL_LOG_PATH": "${workspaceFolder}/logs/all.log"
      },
      "description": "日志分析工具"
    }
  }
}

环境变量说明：

环境变量	说明	是否必需	默认值
LOGBACK_CONFIG_PATH	logback 配置文件路径	否	src/resource/logback-spring.xml
SPRING_APPLICATION_NAME	应用名称（Spring Boot 标准，优先级高）	否	从 logback 配置或目录名推断
APP_NAME	应用名称（通用备用，仅在 SPRING_APPLICATION_NAME 不存在时使用）	否	从 logback 配置或目录名推断
ERROR_LOG_PATH	错误日志文件路径	否	从 logback 读取
WARN_LOG_PATH	警告日志文件路径	否	从 logback 读取
ALL_LOG_PATH	全部日志文件路径	否	从 logback 读取
APP_PACKAGE	应用包名（用于过滤堆栈跟踪）	否	从应用名称自动推断

注意：

• SPRING_APPLICATION_NAME 和 APP_NAME 只需要设置一个即可，推荐使用 SPRING_APPLICATION_NAME（Spring Boot 应用的标准环境变量）。如果两个都设置了，SPRING_APPLICATION_NAME 优先级更高。
• APP_PACKAGE：用于过滤堆栈跟踪，只保留应用包下的堆栈信息，移除底层框架信息（如 java., javax., org.springframework. 等）。如果不配置，工具会尝试从应用名称自动推断（如 cdc-major-disease-service → cdc.major.disease），或自动过滤掉常见的框架包。

其他配置示例：

1. 只配置 logback（使用 logback 中的路径，应用名称从 logback 读取）：

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

注意：如果 logback 配置中没有应用名称，工具会自动从当前工作目录推断，或使用环境变量 SPRING_APPLICATION_NAME 或 APP_NAME。

2. 只配置日志文件路径（不使用 logback）：

{
  "mcpServers": {
    "log-analyzer": {
      "command": "py",
      "args": ["${workspaceFolder}/src/tools/log_analyzer_tool.py"],
      "env": {
        "ERROR_LOG_PATH": "/var/log/myapp/error.log",
        "WARN_LOG_PATH": "/var/log/myapp/warn.log",
        "ALL_LOG_PATH": "/var/log/myapp/all.log"
      }
    }
  }
}

3. 混合配置（部分使用环境变量，部分从 logback 读取）：

{
  "mcpServers": {
    "log-analyzer": {
      "command": "py",
      "args": ["${workspaceFolder}/src/tools/log_analyzer_tool.py"],
      "env": {
        "LOGBACK_CONFIG_PATH": "${workspaceFolder}/config/logback-spring.xml",
        "SPRING_APPLICATION_NAME": "my-service",
        "ERROR_LOG_PATH": "/custom/path/error.log"
      }
    }
  }
}

方式二：调用工具时传入参数

在 Cursor 的 AI 聊天中直接使用，支持自然语言描述：

基本用法：

请使用 analyze_logs 工具分析日志

指定日志级别：

请使用 analyze_logs 工具分析错误日志
请分析警告级别的日志

指定检索行数（支持自然语言，不需要说 max_lines）：

请分析最近 500 行错误日志
请检索最近 2000 行日志
读取最近 1000 行日志进行分析

指定配置文件路径：

请使用 analyze_logs 工具分析日志，配置文件路径是 /path/to/logback-spring.xml

指定日志文件路径：

请使用 analyze_logs 工具分析错误日志，日志文件路径是 D:\logs\myapp-error.log

组合使用：

请分析最近 2000 行错误日志，日志文件路径是 D:\logs\error.log

方式三：设置系统环境变量

# Windows PowerShell
$env:LOGBACK_CONFIG_PATH="D:\project\config\logback-spring.xml"
$env:ERROR_LOG_PATH="D:\project\logs\error.log"

# Linux/Mac
export LOGBACK_CONFIG_PATH="/path/to/logback-spring.xml"
export ERROR_LOG_PATH="/path/to/error.log"

日志文件路径配置

配置优先级（针对日志文件路径）

方法参数 > 实例配置 > 环境变量 > logback 配置

使用示例

示例 1：只配置错误日志路径

analyze_logs(
    log_level="error",
    error_log_path="/custom/path/error.log"
)

示例 2：配置所有日志路径

analyze_logs(
    log_level="all",
    error_log_path="/logs/error.log",
    warn_log_path="/logs/warn.log",
    all_log_path="/logs/all.log"
)

示例 3：不配置，使用 logback 默认值

analyze_logs(log_level="error")
# 自动从 logback-spring.xml 读取路径

---

分析逻辑说明

整体分析流程

1. 读取配置 → 2. 定位日志文件 → 3. 读取日志 → 4. 模式匹配 → 5. 生成报告

详细分析步骤

第一步：初始化配置解析

1. 读取 logback-spring.xml 配置文件
2. 使用 XML 解析器解析配置
3. 提取关键信息：
   • contextName → 应用名称
   • logging.path → 日志文件路径
   • spring.application.name → 应用名称（备用）
   • appender 配置 → 日志文件路径模板

第二步：确定要分析的日志文件

根据 log_level 参数选择日志文件：

• error → 分析 log_error.log
• warn → 分析 log_warn.log
• all → 分析 all.log

第三步：读取日志文件

1. 展开变量：将配置中的变量替换为实际值
2. 文件存在性检查：先尝试绝对路径，如果不存在，尝试相对路径
3. 读取策略：只读取文件的最后 N 行（默认 1000 行），避免处理大文件
4. 错误处理：使用 errors='ignore' 忽略编码错误

第四步：模式匹配分析（核心逻辑）

优化措施（减少 token 消耗）：

• ✅ 过滤无关日志：自动过滤 DEBUG 级别、启动信息等无关内容
• ✅ 提取关键信息：只保留错误相关的核心内容，去除时间戳、PID 等冗余信息
• ✅ 限制返回数量：最多返回 50 个缺陷（按严重程度排序）
• ✅ 精简日志内容：每条日志最多 150 字符，去除堆栈跟踪等冗余信息

工具内置了 11 种常见错误模式：

错误模式	描述	严重程度
NullPointerException	空指针异常	high
IndexOutOfBoundsException	数组越界异常	high
SQLException|DatabaseException	数据库异常	high
Connection.*refused|Connection.*timeout	连接异常	medium
OutOfMemoryError	内存溢出	critical
StackOverflowError	栈溢出	critical
ClassNotFoundException	类未找到	high
MethodNotFoundException	方法未找到	high
TimeoutException|ReadTimeout|ConnectTimeout	超时异常	medium
FileNotFoundException	文件未找到	medium
Permission denied|Access denied	权限拒绝	medium

匹配过程：

• 遍历每一行日志
• 对每一行应用所有错误模式
• 使用正则表达式匹配（不区分大小写）
• 记录匹配的缺陷信息

第五步：生成修复建议

根据匹配的错误模式，自动生成修复建议：

错误类型	修复建议
NullPointerException	添加空值检查，使用 Optional 或空值判断
IndexOutOfBoundsException	检查数组/列表边界，确保索引在有效范围内
SQLException	检查 SQL 语句、数据库连接和事务处理
Connection refused/timeout	检查网络连接、服务是否启动、超时配置
OutOfMemoryError	增加 JVM 堆内存或优化内存使用
StackOverflowError	检查递归调用深度，优化算法
ClassNotFoundException	检查类路径配置和依赖项
MethodNotFoundException	检查方法名和方法签名
TimeoutException	增加超时时间或优化处理逻辑
FileNotFoundException	检查文件路径和文件是否存在
Permission denied	检查文件/目录权限

第六步：生成分析报告

返回结果包含：

• total_defects: 缺陷总数
• defects: 缺陷列表（最多 50 个，按严重程度排序）
  • 每条缺陷包含：行号、精简后的日志内容（最多 150 字符）、类型、严重程度、修复建议
• log_files_analyzed: 分析的日志文件列表
• analysis_time: 分析时间（ISO 格式）
• note: 如果缺陷数量超过限制，会提示显示的数量

优化说明：

• 自动过滤无关日志（DEBUG、启动信息等）
• 提取关键错误信息，去除时间戳、PID、线程ID等冗余内容
• 限制返回数量，优先显示严重程度高的问题
• 精简日志内容，每条最多 150 字符

分析流程图

开始
  ↓
读取 logback-spring.xml
  ↓
提取：应用名、日志路径
  ↓
根据 log_level 选择日志文件
  ↓
读取日志文件（最后 N 行）
  ↓
逐行扫描日志
  ↓
对每一行应用 11 个错误模式
  ↓
匹配成功？
  ├─ 是 → 记录缺陷信息
  │        ↓
  │      生成修复建议
  │        ↓
  └─ 否 → 继续下一行
  ↓
汇总所有缺陷
  ↓
生成分析报告
  ↓
结束

---

使用示例

示例 1：分析错误日志

from log_analyzer_tool import LogAnalyzer

# 创建分析器
analyzer = LogAnalyzer("src/resource/logback-spring.xml")

# 分析错误日志
result = analyzer.analyze_logs(log_level="error", max_lines=1000)

# 查看结果
print(f"发现 {result['total_defects']} 个缺陷")

# 遍历每个缺陷
for defect in result['defects']:
    print(f"行号: {defect['line_number']}")
    print(f"类型: {defect['defect_type']}")
    print(f"严重程度: {defect['severity']}")
    print(f"建议: {defect['suggestion']}")
    print(f"日志: {defect['log_line']}")

示例 2：搜索日志关键词

# 搜索包含 "Exception" 的日志
result = analyzer.search_logs("Exception", log_level="error")

print(f"找到 {result['total_matches']} 个匹配结果")
for match in result['matches']:
    print(f"文件: {match['file']}")
    print(f"行号: {match['line_number']}")
    print(f"内容: {match['content']}")

示例 3：获取 logback 配置

# 获取配置信息
config = analyzer.config
print(f"应用名称: {config.get('app_name')}")
print(f"日志路径: {config.get('log_path')}")

示例 4：在 Cursor 中使用

在 Cursor 的 AI 聊天中：

请使用 analyze_logs 工具分析错误日志

或指定配置：

请使用 analyze_logs 工具分析错误日志，日志文件路径是 D:\logs\error.log

---

故障排除

问题 1：找不到配置文件

错误：FileNotFoundError 或配置为空

解决：

• 检查文件路径是否正确
• 使用绝对路径而不是相对路径
• 确认文件确实存在
• 检查环境变量 LOGBACK_CONFIG_PATH 是否正确设置

问题 2：路径包含特殊字符

解决：

• Windows 路径使用双反斜杠：D:\\path\\to\\file.xml
• 或使用正斜杠：D:/path/to/file.xml
• 在 JSON 中正确转义

问题 3：环境变量未生效

解决：

• 重启 Cursor
• 检查环境变量名称是否正确
• 在工具调用时直接传入参数

问题 4：运行后没有输出或日志文件不存在

错误：返回结果中 warnings 字段提示日志文件不存在

原因：

• logback 配置中的路径可能是 Linux 路径（如 /data/logs），在 Windows 上不存在
• 日志文件路径配置不正确

解决：

1. 使用环境变量配置 Windows 路径：

   {
     "mcpServers": {
       "log-analyzer": {
         "env": {
           "ERROR_LOG_PATH": "D:\\workspaceNew\\mcp-tools\\logs\\error.log",
           "WARN_LOG_PATH": "D:\\workspaceNew\\mcp-tools\\logs\\warn.log",
           "ALL_LOG_PATH": "D:\\workspaceNew\\mcp-tools\\logs\\all.log"
         }
       }
     }
   }
   

2. 调用工具时指定路径：

   请使用 analyze_logs 工具，日志文件路径是 D:\logs\error.log
   

3. 检查返回结果中的 warnings： 工具会在返回结果中添加 warnings 字段，提示路径问题和解决建议

注意：

• 工具会自动检测跨平台路径问题
• 如果日志文件不存在，会返回空结果但不会报错
• 建议在 Windows 上使用环境变量或参数指定日志文件路径

问题 5：出现编码错误

解决： 在终端中设置编码：

# Windows PowerShell
$env:PYTHONIOENCODING="utf-8"
py src/tools/log_analyzer_example.py

问题 6：如何停止运行中的程序

解决：在终端中按 Ctrl + C

---

最佳实践

1. 使用绝对路径：避免相对路径带来的问题
2. 使用环境变量：便于在不同环境间切换
3. 配置验证：首次配置后先测试
4. 定期分析：建议定期运行分析，及时发现新问题
5. 关注严重程度：优先处理 critical 和 high 级别的缺陷
6. 结合上下文：查看完整的日志行，了解错误发生的上下文
7. 验证建议：修复建议是通用的，需要结合实际情况调整
8. 跨平台路径：在 Windows 上使用环境变量配置日志文件路径，避免 Linux 路径问题

---

跨平台支持

Windows 和 Linux 路径差异

工具支持跨平台使用，但需要注意路径差异：

默认路径

• Windows: 自动将 Linux 路径转换为 Windows 格式
  • logback 配置：/data/logs → Windows：<磁盘盘符>:\data\logs
  • 转换规则：根据项目所在磁盘盘符自动转换
    • 项目路径：D:\workspaceNew\CDC-MAJOR-DISEASE-SERVICE\cdc-major-disease-service
    • 日志路径：D:\data\logs\cdc-major-disease-service\log_error.log
  • 说明：日志路径不在项目目录下，而是在项目所在磁盘的根目录下
• Linux/Mac: 使用 /data/logs
  • 例如：/data/logs/cdc-major-disease-service/log_error.log

常见问题

问题：logback 配置中的路径是 Linux 格式（/data/logs），在 Windows 上不存在

解决：

1. 自动路径转换（默认）：

   • 工具会自动将 Linux 路径 /data/logs 转换为 Windows 路径 <磁盘盘符>:\data\logs
   • 例如：项目在 D:\workspaceNew\... → 日志路径：D:\data\logs\...
   • 注意：日志路径在磁盘根目录下，不在项目目录下

2. 使用环境变量配置（推荐，用于自定义路径）：

   {
     "mcpServers": {
       "log-analyzer": {
         "env": {
           "ERROR_LOG_PATH": "D:\\data\\logs\\cdc-major-disease-service\\log_error.log"
         }
       }
     }
   }
   

3. 调用工具时指定路径：

   请使用 analyze_logs 工具，日志文件路径是 D:\logs\error.log
   

4. 查看返回结果中的 warnings： 工具会自动检测路径问题，在返回结果的 warnings 字段中提供提示

路径验证

工具会自动验证日志文件路径：

• 如果文件不存在，会在返回结果中添加 warnings 字段
• 提供解决建议（如使用环境变量配置）
• 不会中断执行，返回空结果

最佳实践

1. Windows 环境：

   • 默认行为：工具会自动将 logback 配置中的 Linux 路径（如 /data/logs）转换为 Windows 路径（如 D:\data\logs）
   • 路径位置：日志路径在项目所在磁盘的根目录下（如 D:\data\logs），不在项目目录下
   • 自定义路径：使用环境变量 ERROR_LOG_PATH、WARN_LOG_PATH、ALL_LOG_PATH 配置自定义路径
   • 使用绝对路径或相对于项目目录的路径

2. Linux/Mac 环境：

   • 可以使用 logback 配置中的路径
   • 或使用环境变量覆盖

3. 跨平台项目：

   • 建议使用环境变量配置，便于在不同平台切换

---

许可证

MIT

---

相关资源

• 配置示例文件：查看 cursor-mcp-config-example.json
• 源代码：src/tools/log_analyzer_tool.py
• 使用示例：src/tools/log_analyzer_example.py

---

最后更新：2026-01-12