Log Detective MCP

Log Detective MCP

MCP 服务，为其他 Agent 实现 Log Detective 的核心日志分析工具。

该服务使用 Drain3 算法将日志消息聚类为模板，并提取有代表性的片段子集，将大量日志缩减到便于下游分析的规模。

安装

需要 Python 3.11+。

pip install .

也可以使用 uv：

uv pip install .

用法

运行服务

logdetective-mcp

或直接运行：

python -m logdetective_mcp.main

MCP 客户端配置

Claude Code

claude mcp add logdetective -- logdetective-mcp

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

{
  "mcpServers": {
    "logdetective": {
      "command": "logdetective-mcp"
    }
  }
}

工具

extract_log_snippets

使用 Drain3 聚类提取有代表性的日志片段。该工具会将日志划分为逻辑消息，对相似消息进行聚类，并为每个簇返回一个代表性片段。

可通过以下三种方式之一提供日志内容（必须且只能使用其中一种）：

参数	类型	说明
log_text	str	直接传入原始日志文本。
log_path	str	服务器文件系统上的日志文件路径。
log_url	str	用于获取日志内容的 HTTP(S) URL。

可选参数：

参数	类型	默认值	说明
max_clusters	int	8	要提取的片段的最大数量。
max_snippet_len	int	2000	每个片段的最大字符长度。
skip_patterns	list[str]	null	正则表达式模式列表。匹配任一模式的日志块会在聚类前排除。
context	int	0	每个片段前后要包含的行数（0-50）。

返回一个 Snippet 对象列表，每个对象包含 line_number（在原始日志中的位置）和 text（提取出的片段内容）。

extract_python_tracebacks

从日志中提取 Python 回溯信息，包括链式异常。

参数	类型	默认值	说明
max_traceback_len	int	2000	每条提取出的回溯信息的最大字符长度。
skip_patterns	list[str]	null	正则表达式模式列表。匹配任一模式的回溯信息会被排除。
context	int	0	每条回溯信息前后要包含的行数（0-50）。

对于这两个提取工具，context 遵循 grep 的 -C 行为：如果有足够的日志行，则会在每侧包含指定数量的相邻行。长度限制适用于提取出的片段或回溯信息；上下文行会额外添加，因此返回的 text 可能超过该限制。启用上下文后，line_number 指向返回内容的第一行。超出 0-50 范围的值会被拒绝。

如果回溯信息被截断，且 max_traceback_len 允许，提取器会保留其开头和结尾，并插入标记；限制更小时则只保留前缀。后续上下文从原始回溯信息之后开始，不会补回其中省略的部分。 如果一行日志因 max_snippet_len 被拆分为多个块，添加上下文时，每个选中的块都会保留自身文本。相邻行不会替换该块，使其恢复为完整的长行。上下文边界遵循块在源日志中的原始行，包括渲染后的块中省略的空行。

大小限制

所有下载的输入（通过 log_url 获取）都限制为 100 MB，无论其格式如何。下载会以分块方式流式进行，一旦超过限制便会中止。

通过 log_path 读取的归档文件也会在解压过程中检查是否超过 100 MB 限制。

压缩文件支持

这两个工具都会透明地解压归档日志文件。支持的格式：

• 单文件压缩： .gz、.bz2、.xz、.lzma
• 归档文件： .zip、.tar、.tar.gz、.tar.bz2、.tar.xz

格式根据文件扩展名（或 URL 路径）识别。归档文件必须恰好包含一个文件。

Zip 炸弹防护通过以下措施实现：

• 最大解压缩大小为 100 MB
• 最大压缩比为 100:1
• 预先检查 zip/tar 标头中声明的大小
• 不递归解压（不解包嵌套归档）

贡献

对此仓库的所有更改都必须通过 pre-commit 检查和测试。

uv run pytest tests/