内容
志修剪器 MCP 服务器
一款 Python MCP 服务器，通过日志文件处理减少约 98% 的令牌使用。自动检测文件格式，去除噪音（Kubernetes 元数据、重复字段、模板），并返回仅可操作的信号。与任何常见的日志格式配合使用 - 无需手动转换。
## 工具列表
| 工具 | 功能 |
|------|-------------|
| `read_logs` | 读取任何日志文件，返回紧凑表格。自动检测格式和日志类型（HTTP 与应用程序）。 |
| `query_logs` | 直接查询 OpenSearch API，返回紧凑表格 |
| `summarize_logs` | 聚合摘要：级别分布，顶级记录器/端点，错误率 |
| `get_errors` | 错误的完整详细信息 — HTTP 5xx，应用程序日志 ERROR/WARN，ImpEx 失败，堆栈跟踪 |
| `get_context` | 时间戳 N 秒内的所有条目 — 类似 `grep -C` 用于日志 |
## 支持的格式
###化（基于 JSON）
| 格式 | 示例源 |
|--------|---------------|
| **OpenSearch/Elasticsearch JSON** | Kibana 导出，API 响应 (`hits.hits[]._source`) |
| **NDJSON** logs`，`docker logs --format json`，Fluent Bit，CloudWatch |
| **JSON 数组** | API 响应，自定义导出工具 (`[{...}, {...}]`) |
| **OpenSearch/Kibana CSV** | Kibana Discover CSV 导出（带有 `_source.*` 列或 `log` 列） |
### 纯文本
| 格式 | 模式 |
|--------|---------|
Spring Boot** | `2026-06-06T15:12:44.842Z INFO 1 --- [thread] logger : message` |
Log4j / Logback** | `2026-06-06 15:12:44,842 INFO [thread] [logger] - message` |
| **Python 日志** | `2026-06-06 15:12:44,842 - module - ERROR - message` |
| **Nginx / Apache 访问日志** | `10.0.0.1 - - [12/Jun/2026:10:53:07 +0000] "GET /path HTTP/1.1" 200 1234` |
| **Docker 容器** | `2026-06-06T15:12:44.842Z stdout F message` |
| **Syslog** | `Jun 12 10:53:07 hostname process[pid]: message` |
| **通用 ISO + 级别** | `2026-06-06T15:12:44Z ERROR something broke` |
| **通用 ISO 时间戳 `2026-06T15:12: any message here` |
是自动的 - 只任何日志文件路径。不需要配置。
## 日志类型自动检测
| 类型 | 检测 |
|------|-----------|-------- **HTTP 访问日志**具有状态码，请求响应时间 | 紧：时间戳，状态，字节，IP，请求 |
| **应用程序日志** | 具有级别，消息，线程/记录器 | 紧：时间戳，级别，消息 |
如果 HTTP 解析没有结果，工具会自动回应用程序日志解析。
##特定错误检测
### SAP Commerce ImpEx
`get_errors` 识别 ImpEx 部署失败，这些失败通常在 INFO 级别记录：
- `dumped: N` （其中 N > 0）— 无法导入的行
- `could not lines` — 最终
- `Can not resolve any more lines` — 解析失败
- `Impex import failed` — SystemSetupException
- `SHUTTING DOWN`下文启动失败
这些被显示为 `[IMPEX FAILURE]` 条目，与常规错误一起。
> 模式检测可扩展的 - 将您自己的领域特定模式添加到 `src/parser.py` 中的 `IMPEX_ERROR_PATTERNS`。
## 设置
### 1. 安装依赖项
```bash
cd log-pruner
pip install -r requirements.txt
```
### 2. 配置 OpenSearch（可选，用于实时 API 访问）
```bash
export OPENSEARCH_URL="https://your-op-cluster:9200"
export OPENSEARCH_USER="export OPENSEARCH_PASSWORD="secret"
```
### 3. 添加到 Claude Code
```json
{
"mcpServers": {
"log-pruner": {
"command": "python",
"args": ["/absolute/path/to/log-pruner/server.py"]
}
}
}
```
对于实时 OpenSearch 访问，请为每个环境添加一个具有连接详细信息的条目：
```json
{
"mcpServers": {
"log-pruner-dev": {
"command": "python",
"args": ["/absolute/path/to/log-pruner/server.py"],
"env": {
"OPENSEARCH_URL": "https://dev-opensearch-cluster:9200",
"OPENSEARCH_USER": "admin",
"OPENSEARCH_PASSWORD": "dev-password"
}
},
"log-pruner-staging": {
"command": "python",
"args": ["/absolute/path/to/log-pruner/server.py"],
"env": {
"OPENSEARCH_URL": "https://staging-opensearch-cluster:9200",
"OPENSEARCH_USER": "admin",
"OPENSEARCH_PASSWORD": "staging-password"
}
}
}
}
```
### 4. 重启 Claude Code
### 5. 添加到您的项目的 CLAUDE.md
```markdown
## 日志分析
当用户提供日志文件或要求分析/调试日志时：
- 不要使用内置的读取工具读取文件 - 它会淹没上下文
- 将文件路径传递给 log-pruner MCP 工具，它们会去除约 98% 的噪音：
- `mcp__log-pruner__read_logs` — 任意日志文件的紧凑表格
- `mcp__log-pruner__summarize_logs` — 概述（级别分布，顶级记录器，错误率）
- `mlog-pruner__get_errors` — 具有完整详细信息的错误
- `mcp__log-pruner__get_context` — 特定时间戳周围的条目
- `mcp__log-pruner__query_logs` — 查询实时 OpenSearch（需要环境变量）
```
## 使用示例
### 任意纯文本日志文件
```
read_logs(path="app.log")
→ 1327 app log entries
TIMESTAMP | LVL | THREAD | MESSAGE
2026-06-06T15:12:44Z | INFO | main | Starting application
2026-06T15:12:45Z | | http-nio--exec-1 |Exception at line 42
2026-06T15:12Z | WARN | scheduler-1 | Job took 5000ms
```
### Nginx/Apache 访问日志
```
read_logs(path="access.log", status_filter="5xx")
→ 3 hits (of 50000 total)
TIMESTAMP | ST | MS | BYTES | REQUEST
12/Jun/2026:10:53:07Z | 500 | | 56 | 10.0.0.2 | POST /api/login
12/Jun/2026:10:53:09Z | 502 | 0 |.0.0. | GET /api/users
```
### NDJSON（kubectl logs，docker logs）
```
read_logs(path="pod-logs.json")
→ 500 app log entries
TIMESTAMP | LVL | THREAD | MESSAGE
2026-06-06T15:12:44Z | ERROR | | Connection refused
2026-06-06T15:12:45Z | INFO | | Retrying in 5s...
```
### 聚合摘要
```
summarize_logs(path="deployment.log")
→ === App Log Summary (3808 entries) ===
级别分布：
INFO: 3749 (98.5%)
WARN: 55 (1.4%)
ERROR: 4 (0.1%)
顶级记录器：
2x de.hybris.platform.impex.jalo.imp.ImpExWorker
215x de.hybris.platform.servicelayer.impex.impl.DefaultImportService
...
警告/错误（22 个唯一）：
[WARN] column absolute of type Discount is read-only...
[ERROR] Can not resolve any more lines...
```
### 错误检测（具有 ImpEx 意识）
```
get_errors(path="deployment.log")
→ === ImpEx Failures ( ===
[IMPEX FAILURE] 2026-06-06T15:12:46Z
线程： main
记录器： de.hybris.platform.impex.jalo.cronjob.ImpExImportJob
消息： Can not resolve any more lines ... Aborting further passes (at pass 3).
=== Errors (2) ===
[ERROR] 2026-06-06T15:12:46Z
线程： main
记录器： debris.platform.core.Initial 消息： SystemSetupException: Impex import failed '00037874--Import'
```
### 故障排除工作流
. read_logs(path.log") → 快速扫描（紧凑，低令牌）
2. summarize_logs(path="file.log") → 级别分布，顶级记录器
3. get_errors(path="file.log") → 所有错误 + ImpEx 失败
4. get_context(path="file.log") → 特定时间周围的条目
```
## 令牌节省
| 输入 | 无 log-pruner | 有 log-pruner | 节省 |
|-------|-------------------|-----------------|---------|
| 10 次点击 OpenSearch JSON | ~2,500 令牌 | ~50 令牌 | ~98% |
| 4MB CSV 导出（3,800 行） | ~400,000 令牌 | ~3,000 令牌 | ~99% |
| 1000 行 Spring Boot 日志 | ~15,000 令牌 | ~200 令牌 | ~99% |
| Nginx 访问日志（10k 行） | ~150,000 令牌 | ~500 令牌 | ~99% |
| 从任何格式中提取错误 | ~400,000 令牌 | ~500 令牌 | ~99% |
## 限制
- 纯文本解析依赖于模式匹配 - 自定义格式如果没有公认的时间戳模式将不会被解析（跳过行）
- 应用程序日志解析期望 `log` 字段中的 JSON 或直接 `level`/`message` 字段
