用于日志分析的 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
▼
answerGroq 承载提取和假设生成；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 substring8 个用例覆盖了不同的故障原型：跨服务资源争用、无界缓存 OOM、重试风暴放大、一次糟糕的发布、两类诱因叠加、一个坏节点造成时钟偏移、一份健康的日志（正确答案是“没有故障”），以及一个做了“强症状掩盖弱小根因”的用例，专门测量 completeness 这个维度。评分是确定性的——概念组 + 同义词词表，并要求必须引用相关证据——没有 LLM 当裁判，所以跑出的结果可复现。报告会拆开成检索遗漏（证据从未到达模型）和推理遗漏（证据在场，却依旧答错），因为它们对应的修法不同。
当前结果：8/8 通过，0 检索遗漏，0 推理遗漏。
排查这套东西本身也是一个不错的工程段子：一个不对称时间窗口 + 一个全局异常扫描，解决了真实的检索脆弱性；Groq 免费层里 max_tokens 是对每分钟 token 预算的保留，而不是“用多少付多少”的上限——超纲值会有 413，即使实际提示没多大；在 gpt-oss 一族模型上需要 reasoning_effort: "low"，否则它会占满预算、在输出合法 JSON 之前就被截断了；而评测框架自身还有两个发分 bug（一种是 Unicode 标点变体，另一种是同个复合标识符的空格变体）都会把正确的答案误报为失败——也值得知道：当你自己的 eval harness 出了问题，它同样需要调试。
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 都正常完成。
环境变量 | 是否需要/用处 | 说明 |
|
| 在 console.groq.com/keys 免费获取。 |
| 独立验证 | 在 aistudio.google.com/apikey 免费获取。没有它，验证将降到同 provider（Groq），不再独立——但不会默默降级后 |
| 可选 | 指向某份真实日志，替代打包好的形沦为 sample。 |
| 可选 | 值为 |
| 可选 | HTTP 端口，默认 |
npm install
npm run build默认读取 fixtures/sample.log，一个合成 vs事件：inventory-service 上一条长时间的不索引查询耗尽了共享 DB 连接池，间接导致 checkout-service 报错。覆盖它，改用真实日志文件：
LOGLENS_LOG_FILE=/path/to/real.log node dist/index.jsnpx 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 留足（脚本都保留好了）。
编辑（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.
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 healthcheckThis server cannot be deployed
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
Search log events, investigate anomalies, and manage cases in your Knowledge Grid tenant.
Read-only access to Auralogs production logs: search logs, inspect errors, review AI analyses.
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
