# Drain3 MCP Server

基于 [Drain3](https://github.com/logpai/Drain3) 的 Python MCP Server，把流式日志模板挖掘、只读匹配、参数提取和模型持久化封装成标准的 Model Context Protocol 工具。

## 功能

- 逐条或批量训练日志模板
- 在不修改模型的前提下匹配新日志
- 提取 IP、数字、UUID、URL、十六进制值及 Drain3 通配参数
- 查询、排序和分页浏览已学习的模板
- 原子化文件快照，服务重启后自动恢复
- 同时支持 `stdio`、Streamable HTTP 和旧版 SSE 传输
- 返回结构化 MCP 输出，便于 Agent 稳定消费

## MCP 工具

| 工具 | 用途 | 是否修改模型 |
| --- | --- | --- |
| `train_log` | 学习一条日志并返回模板、簇和参数 | 是 |
| `train_logs` | 按顺序批量学习日志 | 是 |
| `match_log` | 匹配一条日志，不创建新模板 | 否 |
| `match_logs` | 批量只读匹配 | 否 |
| `list_templates` | 查询已学习模板，支持排序和分页 | 否 |
| `extract_log_parameters` | 按指定模板提取动态参数 | 否 |
| `get_stats` | 查看模板数、消息数和有效配置 | 否 |
| `save_state` | 立即将完整模型状态写入快照 | 写快照 |

服务还公开以下 MCP Resources：

- `drain3://stats`
- `drain3://templates`
- `drain3://templates/{cluster_id}`

## 安装与启动

需要 Python 3.10 或更高版本。

```bash
python -m venv .venv

# Linux / macOS
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

pip install -e .
drain3-mcp-server
```

默认启动 `stdio` 传输，适合 Codex、Claude Desktop 等 MCP Host。也可以启动 Streamable HTTP：

```bash
drain3-mcp-server --transport streamable-http --host 127.0.0.1 --port 8000
```

MCP 端点是 `http://127.0.0.1:8000/mcp`。

### MCP Host 配置示例

仓库开发模式：

```json
{
  "mcpServers": {
    "drain3": {
      "command": "D:/code/Drain3MCPServer/.venv/Scripts/python.exe",
      "args": ["-m", "drain3_mcp_server"],
      "env": {
        "DRAIN3_MCP_STATE_PATH": "D:/data/drain3/state.bin"
      }
    }
  }
}
```

安装为命令后，可将 `command` 改成 `drain3-mcp-server`，并移除 `args`。

## 配置

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `DRAIN3_MCP_CONFIG_PATH` | 包内 `default_drain3.ini` | 自定义 Drain3 INI 配置路径 |
| `DRAIN3_MCP_STATE_PATH` | `data/drain3_state.bin` | 模型快照路径；设为 `none` 或 `:memory:` 禁用持久化 |
| `DRAIN3_MCP_MAX_BATCH_SIZE` | `1000` | 单次批量调用允许的最大日志条数 |

默认配置会掩码 IP、数字、UUID、URL 和十六进制值。生产环境通常应通过 `DRAIN3_MCP_CONFIG_PATH` 提供针对业务日志设计的 masking 规则。完整的 Drain3 参数定义请参考 [Drain3 配置说明](https://github.com/logpai/Drain3#configuration)。

## 调用示例

先训练两条相似日志：

```json
{
  "log_messages": [
    "User 123 logged in from 10.0.0.1",
    "User 456 logged in from 10.0.0.2"
  ]
}
```

`train_logs` 会学习到类似下面的模板：

```text
User <NUM> logged in from <IP>
```

之后使用 `match_log` 可以对新日志做只读推理，并取得 `NUM`、`IP` 对应的参数值。

## Docker

```bash
docker build -t drain3-mcp-server .
docker run --rm -p 8000:8000 -v drain3-data:/data drain3-mcp-server
```

容器默认监听 `0.0.0.0:8000`，模型写入 `/data/drain3_state.bin`。

## 开发与测试

```bash
pip install -e ".[dev]"
pytest
ruff check .
```

核心代码位于：

- `src/drain3_mcp_server/service.py`：线程安全的 Drain3 服务层
- `src/drain3_mcp_server/server.py`：MCP 工具、资源与启动入口
- `src/drain3_mcp_server/default_drain3.ini`：默认模板挖掘配置

## 设计说明

- 训练调用会沿用 Drain3 自身的快照策略；如需确保最新的簇计数立即落盘，请在训练批次结束后调用 `save_state`。
- HTTP 模式下，单进程内的调用共享同一个 Drain3 模型，并通过可重入锁串行化访问。
- 若部署多个副本，每个副本应使用独立状态文件，或扩展为 Redis/Kafka 等共享持久化方案；本项目当前默认实现面向单实例。
- HTTP 传输本身未配置身份认证。默认只监听回环地址；对外暴露时应放在带认证和 TLS 的网关之后。
- Drain3 使用 `jsonpickle` 恢复快照，因此状态文件必须来自可信位置，不要加载第三方提供的快照。

## License

[MIT](LICENSE)