LogLens

用于日志分析的 MCP（Model Context Protocol）服务器。与其把日志文件粘贴进聊天框让 LLM 调试，LogLens 把日志搜索、上下文检索和事件摘要暴露为工具，任何 MCP 兼容客户端（Claude Desktop、Claude Code，或你自己的 agent）都能直接调用——用定向检索替代上下文塞入，并在返回前用一步自验证来捕获那些没有日志数据支撑的根因断言。

为什么存在

作为公开的、作品集版的一个 AI 日志分析器，曾在内部黑客松中夺得第一名。简短版本——它为什么比“粘贴到聊天框”更好：生产日志放不进上下文窗口；聊天框粘贴无法被其他系统调用；纯提示词也没有任何机制去检查模型的回答是否真的基于日志数据。

Related MCP server: Log Analyzer MCP

当前状态

• 核心服务器 + 3 个工具 —— 已对示例日志端到端跑通。✅

• 基于 LLM 的根因生成，含幻觉验证循环——在两个独立轴上验证假设，任一轴失败即重试一次。✅

• 混合 Provider 架构（Groq + Gemini）——验证器运行在与生成器不同的模型家族上，因此检查不会共享生成器的盲点。✅

• 8 用例评估套件，确定性评分，8/8 通过。✅

• Docker 化，以网络可达的 HTTP 服务器运行，并已针对真实容器做端到端验证。✅

• 下一步： 云部署（Azure Container Apps 或类似方案）、一个演示 GIF。

工具

设计架构

Question ──▶ extract search terms (Groq, gpt-oss-20b)
                 │
                 ▼
         search_logs (lexical match)
                 │
                 ▼
    + time-window expansion (asymmetric: 900s before / 180s after —
      causes precede symptoms)
                 │
                 ▼
    + global anomaly scan (all WARN/ERROR lines, not just in-window —
      the explaining line is often itself a warning)
                 │
                 ▼
       generate hypothesis (Groq, gpt-oss-120b)
                 │
                 ▼
    verify: soundness + completeness (Gemini — DIFFERENT provider
    from the generator, on purpose; falls back to same-provider
    Groq if Gemini is unavailable, and reports which happened)
                 │
          unsound/incomplete? ──▶ regenerate once, feeding back
                 │                the lines the first pass overlooked
                 ▼
              answer

两个 provider，刻意为之——不只是省钱的临时方案

Groq 承载提取和假设生成；Gemini 承载验证。一开始这只是配额权宜（Gemini 免费额度 20 次/天，而 Groq 慷慨得多），但后来变成了真正的架构改进：如果一个验证器跑在与生成断言相同的模型上，它就会共享该模型的盲区。 让不同模型家族去检查同一个断言，幻觉检查才能做到真正的独立，而不仅仅是同源异口不。Verification.independent 会报告某次回答到底真的走了跨 provider 检查，还是回退到了同 provider（Gemini 挂掉或未配置）——它被暴露出来，而不是藏起来。

跨服务检索缺口——在测试中暴露，在正确的层去修

早期测试暴露了一个真实局限：summarize_incident 能找到 checkout 失败的直接原因（DB 连接池耗尽），却漏掉了日志里同样编码的更深源原因——一个在另一个服务上长时间运行的查询正占着连接不放。两个结构性问题：

• 检索只有词法层。 提取的搜索词都限定在 checkout 域内，所以 inventory-service 的行无论推理能力多强，永远进不了证据集。用时间窗扩展修复，刻意不对称（前 900 秒 / 后 180 秒）——原因总发生在症状之前，而且常常远超过短对称窗口能捕获的范围——还要全局扫一遍窗口之外的异常（WARN/ERROR）行，因为“解释性”的那一行往往本身就是一条警告（“NTP sync failed”、“rotation skipped”）。

• 验证器原来只能“盖章通过”。 它最初只看被断言引用的几行，因而在结构上不可能察觉不完整的回答——一条描述症状的断言，总会觉得自己当时引用的那几行“完全支撑”它。经验证看到完整证据集，并对 soundness 与 completeness 独立评分；“不完整”的裁决会把被漏掉的行重新喂给到生成循环里。

评测集

npx tsx evals/run-evals.ts          # all 8 cases
npx tsx evals/run-evals.ts 03 08    # a subset, by id substring

8 个用例覆盖了不同的故障原型：跨服务资源争用、无界缓存 OOM、重试风暴放大、一次糟糕的发布、两类诱因叠加、一个坏节点造成时钟偏移、一份健康的日志（正确答案是“没有故障”），以及一个做了“强症状掩盖弱小根因”的用例，专门测量 completeness 这个维度。评分是确定性的——概念组 + 同义词词表，并要求必须引用相关证据——没有 LLM 当裁判，所以跑出的结果可复现。报告会拆开成检索遗漏（证据从未到达模型）和推理遗漏（证据在场，却依旧答错），因为它们对应的修法不同。

当前结果：8/8 通过，0 检索遗漏，0 推理遗漏。

排查这套东西本身也是一个不错的工程段子：一个不对称时间窗口 + 一个全局异常扫描，解决了真实的检索脆弱性；Groq 免费层里 max_tokens 是对每分钟 token 预算的保留，而不是“用多少付多少”的上限——超纲值会有 413，即使实际提示没多大；在 gpt-oss 一族模型上需要 reasoning_effort: "low"，否则它会占满预算、在输出合法 JSON 之前就被截断了；而评测框架自身还有两个发分 bug（一种是 Unicode 标点变体，另一种是同个复合标识符的空格变体）都会把正确的答案误报为失败——也值得知道：当你自己的 eval harness 出了问题，它同样需要调试。

Docker

docker build -t loglens:local .
docker run -d -p 3000:3000 \
  -e GROQ_API_KEY=your-key \
  -e GEMINI_API_KEY=your-key \
  loglens:local
curl http://localhost:3000/health

多阶段构建（编译阶段带 devDependencies，运行阶段仅生产依赖 + 非 root 用户 + 容器 方案健康检查）。容器里跑 HTTP transport（MCP_TRANSPORT=http，镜像默认已设），因为已部署的容器没有父进程或文，能像 Claude Desktop/Claude Code 那样本地拉起。

这里发现并修复了一个真实 bug，超值的——如果你要自己 Builder stateless streamable-HTTP MCP服务器，务必记住： SDK 的 stateless 模式要求每个请求都得传入一个新 transport——因为第一个请求后复用同一个 transport，每请求下一次都会静默返回 500，而且没有任何可捕获的异常。另一个情况是同一个 McpServer 一次只能连接一个 transport（“Already connected to a transport”）。正确修复体面见 createServer() 与 src/index.ts 里的 HTTP handler——它基于每个请求新建一个 McpServer 和一个 StreamableHTTPServerTransport ——这十分便宜，因为 server 只持有工具定义，根本不存在“连接状态”（而且这些工具也没有调用间隔传状态）。对一次真实运行容器的端到端验证已验证：修完 bug 的 search_logs 和完整 summarize_incident 都正常完成。

环境变量

配置

npm install
npm run build

默认读取 fixtures/sample.log，一个合成 vs事件：inventory-service 上一条长时间的不索引查询耗尽了共享 DB 连接池，间接导致 checkout-service 报错。覆盖它，改用真实日志文件：

LOGLENS_LOG_FILE=/path/to/real.log node dist/index.js

纸面回归测试（无需 MCP 客户端）

npx tsx scripts/smoke-test.ts                              # stdio transport
npx tsx scripts/smoke-test-http.ts http://localhost:3000/mcp  # HTTP transport

会（或连接）启动服务器并调用它提供全部三个工具——适合在接真 MCP 客户端之前验证它是否正常。跑完一份完整 summarize_incident 是 Get Dependent，耗时 3-4 轮 LLM 调用约 30~90 秒；若以编程方式间接地调用，请给 timeout 留足（脚本都保留好了）。

接 Claude Desktop

编辑（Windows 下）%APPDATA%\Claude\claude_desktop_config.json，并加入：

{
  "mcpServers": {
    "loglens": {
      "command": "node",
      "args": ["C:\\Users\\sarve\\OneDrive\\Desktop\\LogLens\\dist\\index.js"],
      "env": {
        "GROQ_API_KEY": "your-groq-key",
        "GEMINI_API_KEY": "your-gemini-key"
      }
    }
  }
}

env 写在配置里是必须的，而不是可选的—— MCP 客户端默认会用一份空白干净的环境来启动服务进程，不是继承你 shell 里完整的环境；所以那就算你在机器里全局export，不加 env 密钥是逻辑上对 summarize_incident 不可见的。

重启 Claude Desktop，然后让它去做 类似 "search the logs for 'pool exhausted'"，它会自动拉起 search_logs.

接 Claude Code

codes:

claude mcp add loglens --scope user --env GROQ_API_KEY=your-groq-key --env GEMINI_API_KEY=your-gemini-key -- node C:\Users\sarve\OneDrive\Desktop\LogLens\dist\index.js

（这事也一样——--env 之所以要显式传密钥，是因为派生的进程默认不会继承 shell 环境变量。）

服务端目录结构

src/
  index.ts       MCP server (dual transport: stdio + HTTP) + tool registration
  logParser.ts   log loading, search, time-window expansion, anomaly scan
  summarize.ts   the summarize_incident pipeline: extract -> retrieve -> hypothesize -> verify -> retry
  providers.ts   Groq + Gemini clients, model config, schema-constrained JSON generation
fixtures/
  sample.log     synthetic incident for local testing
evals/
  cases.ts       8 eval case definitions
  run-evals.ts   deterministic scoring harness
  logs/          synthetic logs for eval cases 02-08
scripts/
  smoke-test.ts       stdio transport smoke test
  smoke-test-http.ts  HTTP transport smoke test
Dockerfile       multi-stage build, non-root user, container healthcheck