# MCP 日志分析工具 - 使用指南
一个基于 FastMCP 的 Model Context Protocol (MCP) 工具，用于分析 Java Spring Boot 应用的日志文件，自动检测代码缺陷并生成修复建议。
Nacos MCP 服务请参考：[packages/nacos_helper/README.md](../nacos_helper/README.md)
---
## 📋 目录
1. [功能特点](#功能特点)
2. [快速开始](#快速开始)
3. [在 Cursor 中集成](#在-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 并检查版本：
```bash
# 检查 Python 版本
python --version
# 或
py --version
```
**预期输出示例**：
```
Python 3.9.0
# 或
Python 3.12.0
```
如果未安装 Python 或版本过低，请访问 [Python 官网](https://www.python.org/downloads/) 下载并安装。
#### 检查 pip 是否可用
```bash
# 检查 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 安装指南](https://pip.pypa.io/en/stable/installation/)。
### 安装
#### 从 PyPI 安装（默认）
```bash
pip install mcp-logback-analyzer
```
#### 使用国内镜像源（推荐国内用户）
如果无法访问 PyPI 或下载速度慢，可以使用国内镜像源：
**清华大学镜像（推荐）**：
```bash
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mcp-logback-analyzer
```
**阿里云镜像**：
```bash
pip install -i https://mirrors.aliyun.com/pypi/simple/ mcp-logback-analyzer
```
**腾讯云镜像**：
```bash
pip install -i https://mirrors.cloud.tencent.com/pypi/simple mcp-logback-analyzer
```
**华为云镜像**：
```bash
pip install -i https://mirrors.huaweicloud.com/repository/pypi/simple mcp-logback-analyzer
```
**豆瓣镜像**：
```bash
pip install -i https://pypi.douban.com/simple/ mcp-logback-analyzer
```
#### 永久配置镜像源（推荐）
如果经常使用，可以永久配置镜像源，这样就不需要每次都加 `-i` 参数：
**Windows**：
1. 在用户目录下创建 `pip` 文件夹：`%APPDATA%\pip`
2. 创建 `pip.ini` 文件，内容如下：
```ini
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
```
**Linux/Mac**：
1. 创建配置文件：`~/.pip/pip.conf`
2. 内容如下：
```ini
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
```
配置后，直接使用 `pip install mcp-logback-analyzer` 即可从镜像源下载。
### 验证安装
```bash
python -c "from mcp_services.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 mcp_services.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：添加配置
打开配置文件，添加以下内容：
```json
{
"mcpServers": {
"log-analyzer": {
"command": "python",
"args": ["-m", "mcp_services.log_analyzer.tool"],
"cwd": "${workspaceFolder}",
"env": {
"LOGBACK_CONFIG_PATH": "${workspaceFolder}/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 配置中）：
```json
"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 配置中添加环境变量：
```json
"env": {
"LOGBACK_CONFIG_PATH": "${workspaceFolder}/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 配置中设置**：
```json
"env": {
"ERROR_LOG_PATH": "D:\\data\\logs\\app\\error.log"
}
```
### Q2: 应用名称识别不正确？
**解决方案**：
在 Cursor MCP 配置中添加：
```json
"env": {
"SPRING_APPLICATION_NAME": "your-app-name"
}
```
### Q3: 堆栈跟踪信息太多？
**解决方案**：
配置应用包名，工具会自动过滤框架包的堆栈信息：
```json
"env": {
"APP_PACKAGE": "com.example.yourpackage"
}
```
工具会自动：
- 过滤掉 `java.`, `org.springframework.` 等框架包
- 只保留应用包下的堆栈信息
- 最多保留 3 层应用堆栈
### Q4: 在 Cursor 中无法使用工具？
**检查清单**：
1. ✅ 工具是否已安装：`pip show mcp-logback-analyzer`
2. ✅ MCP 配置文件是否正确
3. ✅ Cursor 是否已重启
4. ✅ Python 路径是否正确
**调试方法**：
手动测试工具：
```bash
python -m mcp_services.log_analyzer.tool
```
如果工具正常运行，说明安装正确，问题可能在 Cursor 配置。
### Q5: Windows 路径问题？
工具会自动处理路径转换：
- Linux 路径 `/data/logs` 会自动转换为 `D:\data\logs`（根据项目所在磁盘）
如果仍有问题，使用绝对路径：
```json
"env": {
"ERROR_LOG_PATH": "D:\\data\\logs\\app\\error.log"
}
```
---
**版本**：1.0.2
**最后更新**：2025-01-13
