# log-agent-server

**Repository Path**: apollozhu/log-agent-server

## Basic Information

- **Project Name**: log-agent-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-29
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# log-agent-server

基于 Spring Boot 3.3.5 + Spring AI 的 MCP (Model Context Protocol) 日志分析服务器，通过 stdio 协议为 Claude Desktop 等 AI Agent 提供日志查询、分析、导出和审计能力。

## 快速集成到 Claude Desktop

### 前置条件

- JDK 17+
- Apache Maven 3.6+

### 1. 构建项目

```bash
mvn clean package -DskipTests
```

构建成功后，jar 包位于 `target/log-agent-server-1.0.0.jar`。

### 2. 配置 Claude Desktop

编辑 Claude Desktop 的 MCP 配置文件：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux** (非官方包): `~/.config/Claude/claude_desktop_config.json`

添加如下配置：

```json
{
  "mcpServers": {
    "log-agent": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/log-agent-server/target/log-agent-server-1.0.0.jar"
      ]
    }
  }
}
```

> 将 `/path/to/log-agent-server` 替换为你的实际项目路径。

### 3. 重启 Claude Desktop

重启后，在输入框右下角会看到 🔌 图标（MCP 已连接），表示 log-agent 工具已就绪。

### 集成到其他 Agent

任何支持 MCP 协议的 Agent 客户端都可以用相同方式集成，只需在客户端的 MCP Server 配置中添加上述 `command` + `args`。常见客户端：

| 客户端 | 配置文件位置 |
|--------|-------------|
| Claude Desktop | `claude_desktop_config.json` (见上) |
| Continue (VS Code) | `~/.continue/config.json` → `mcpServers` 字段 |
| Cursor | `~/.cursor/mcp.json` |
| OpenCode | `opencode.json` → `mcpServers` 字段 |

## 使用示例

以下示例基于项目中 `samples/apache.log`（Apache HTTP Server 错误日志，2005年6月～9月，约 56,000 行）的真实数据。集成后直接在 Claude Desktop 中用自然语言即可操作。

### 场景 1：导入日志文件

```
帮我分析 samples/apache.log 这个 Apache 错误日志
```

Claude 自动执行以下步骤：
1. 调用 `sampleLogFile` 采样日志行，识别格式为 `[时间戳] [级别] [消息]`
2. 推导正则表达式并调用 `validateLogPattern` 验证匹配率
3. 调用 `importLogsFromFile` 将 5.6 万条日志导入分析工作区

### 场景 2：错误根因分析

```
日志里有大量 env.createBean2 和 config.update 错误，帮我分析根因
```

触发 `error-root-cause` 提示词，Claude 会：
1. 用 `queryLogs` 按关键词 `createBean2` 筛选相关错误
2. 用 `analyzeLogs(cross)` 交叉分析错误类型与时间分布
3. 用 `queryLogsByTimeRange` 聚焦错误爆发的时间窗口，定位到 `channel.jni`、`worker.jni` 等 JNI 组件初始化失败

### 场景 3：URL 安全分析

```
分析一下这个 Apache 日志中访问了哪些可疑路径
```

Claude 调用 `analyzeLogs(url_path)` 和 `analyzeLogs(url_category)`，从错误日志中提取出：
- 大量 `/var/www/html/` 的 "Directory index forbidden" 记录（来自不同客户端 IP）
- `/var/www/html/sumthin` 等不存在的文件请求
- 按 URL 类别归组：目录遍历、文件探测、正常访问

### 场景 4：日报——分析某天错误分布

```
导出 6月9日 的所有 error 级别日志，统计错误数量
```

Claude 依次调用：
1. `queryLogsByTimeRange(from="2005-06-09T00:00:00", to="2005-06-10T00:00:00", level="ERROR")` 查询当日错误
2. `analyzeLogs(groupBy="level")` 获取各级别占比
3. `exportLogs(format="csv", level="ERROR")` 导出为 CSV

输出摘要：6月9日共产生 XXX 条错误，集中在启动阶段的 JNI 工厂错误。

### 场景 5：安全审计

```
对日志做安全审计，重点关注 mod_security 相关记录和异常客户端
```

触发 `security-audit` 提示词，Claude 自动：
1. `analyzeLogs(url_path)` — 提取所有 URL 路径，发现高频目录遍历尝试
2. `analyzeLogs(url_category)` — 将路径分类为 `exploit`、`cms`、`admin` 等
3. `queryLogs(keyword="mod_security")` — 检查安全模块运行状态
4. `queryAuditLogs` — 回溯工具调用历史

### 场景 6：全量日志概览

```
给我一个 apache.log 的总体概览：时间跨度、各级别数量、主要错误类型
```

Claude 调用：
1. `analyzeLogTimeRange` — 获取最早/最晚时间戳和日志总量
2. `analyzeLogs(groupBy="level")` — 统计 notice/error/warn 三级分布
3. `analyzeLogs(groupBy="url_path")` — 识别高频错误模式

输出示例：
- 时间范围：2005-06-09 ～ 2005-09-28
- 总计 56,481 条，其中 error 38,081 (67%)，notice 13,755 (24%)，warn 168 (<1%)
- 主要错误：Directory index forbidden、File does not exist、JNI 初始化失败、child process 未退出

## 效果演示

![Claude Desktop 日志分析演示](docs/demo.png)

## 内置工具一览

共 **14 个工具**，分为 6 组：

### 导入工具 (ImportTools)
| 工具 | 说明 |
|------|------|
| `sampleLogFile` | 从日志文件采样代表性行，供推导正则表达式 |
| `validateLogPattern` | 验证自定义解析表达式，返回匹配率和不匹配样本 |
| `importLogsFromFile` | 使用正则表达式导入日志到分析工作区 |

### 查询工具 (LogTools)
| 工具 | 说明 |
|------|------|
| `queryLogs` | 按级别/服务/关键词/时间范围灵活查询 |
| `queryLogsByServices` | 跨服务批量查询 |
| `queryLogsByTimeRange` | 精确时间段查询 |
| `getCacheStats` | 缓存统计 |
| `clearCache` | 清空缓存 |

### 分析工具 (AnalyzeTools)
| 工具 | 说明 |
|------|------|
| `analyzeLogs` | 按 level/service/cross/error_rate/url_path/url_category 聚合分析 |
| `analyzeLogTimeRange` | 时间范围分布分析 |

### 导出工具 (ExportTools)
| 工具 | 说明 |
|------|------|
| `exportLogs` | 导出为 JSON 或 CSV 格式 |

### 审计工具 (AuditTools)
| 工具 | 说明 |
|------|------|
| `queryAuditLogs` | 查询工具调用审计记录 |
| `getToolUsageStats` | 工具使用频率统计 |

### 工作区工具 (WorkspaceTools)
| 工具 | 说明 |
|------|------|
| `clearAnalysisWorkspace` | 清空导入日志和缓存（审计日志保留） |

## 内置提示词

共 **6 个提示词模板**，覆盖常见运维场景：

| 提示词 | 用途 | 参数 |
|--------|------|------|
| `incident-investigation` | 事故排查 | service(必填), hours, keyword |
| `system-health-check` | 系统健康检查 | hours |
| `security-audit` | 安全审计 | hours |
| `error-root-cause` | 错误根因分析 | service(必填), hours |
| `daily-summary` | 日报生成 | hours |
| `monthly-report` | 月度报告 | yearMonth(必填), service, includeSecurity |

## 典型工作流

```
sampleLogFile → validateLogPattern → importLogsFromFile → 分析/查询/导出 → clearAnalysisWorkspace
```

以 `samples/apache.log` 为例：

1. 用 `sampleLogFile(path="samples/apache.log")` 采样，得到如下样本：
   ```
   [Thu Jun 09 06:07:04 2005] [notice] LDAP: Built with OpenLDAP LDAP SDK
   [Thu Jun 09 06:07:05 2005] [error] env.createBean2(): Factory error creating channel.jni:jni
   [Thu Jun 09 07:11:21 2005] [error] [client 204.100.200.22] Directory index forbidden by rule: /var/www/html/
   ```
2. 推导正则表达式（需包含 `timestamp`、`level`、`message` 命名组）：
   ```regex
   ^\[(?<timestamp>[A-Z][a-z]{2} [A-Z][a-z]{2} \d{2} \d{2}:\d{2}:\d{2} \d{4})\] \[(?<level>[a-z]+)\](?: \[client (?<client>[^\]]+)\])? (?<message>.*)$
   ```
3. 用 `validateLogPattern` 验证正则匹配率，检查 `unmatchedSamples`
4. 用 `importLogsFromFile(mode="replace")` 导入全部 56,481 条日志
5. 调用 `queryLogs`、`analyzeLogs`、`exportLogs` 进行分析
6. 用 `clearAnalysisWorkspace` 清理工作区

## 技术架构

| 组件 | 技术选型 |
|------|----------|
| 框架 | Spring Boot 3.3.5 (禁用 Web) |
| MCP | Spring AI MCP Server 1.1.7 (stdio 模式) |
| 数据库 | SQLite (Hibernate JPA, ddl-auto: update) |
| 缓存 | Caffeine 内存缓存 |
| 安全 | AOP 切面: 角色校验 / 频率限制 / 审计日志 |

## 项目结构

```
src/main/java/com/logagent/
├── LogAgentApplication.java       # 入口
├── tool/                          # 6 组工具类 (14 个工具)
│   ├── ImportTools.java           # 日志导入
│   ├── LogTools.java              # 日志查询
│   ├── AnalyzeTools.java          # 聚合分析
│   ├── ExportTools.java           # 导出
│   ├── AuditTools.java            # 审计
│   └── WorkspaceTools.java        # 工作区清理
├── prompt/
│   └── LogAgentPrompts.java       # 6 个 MCP 提示词模板
├── config/
│   └── ToolConfig.java            # 工具注册
├── security/                      # AOP 切面 (角色/限流/审计)
├── cache/                         # Caffeine 缓存服务
├── entity/                        # JPA 实体
├── dto/                           # 数据传输对象
└── repository/                    # JPA 仓库
```