Drain3 MCP Server

基于 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 或更高版本。

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：

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

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

MCP Host 配置示例

仓库开发模式：

{
  "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 配置说明。

调用示例

先训练两条相似日志：

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

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

User <NUM> logged in from <IP>

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

Docker

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。

开发与测试

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