LogLens

ログ分析のための MCP (Model Context Protocol) サーバーです。ログファイルをチャットに貼り付けて LLM にデバッグさせる代わりに、LogLens はログ検索、コンテキスト取得、インシデント要約をツールとして公開します。MCP 互換クライアント（Claude Desktop、Claude Code、自作エージェントなど）はこれを直接呼び出すことができます。コンテキストを詰め込むのではなく狙った情報だけを取得し、根拠のない根本原因の主張が返される前に検出する自己検証ステップも備えています。

存在する理由

社内ハッカソンで 1 位を獲得した AI 駆動ログアナライザーの、公開用ポートフォリオ版として構築しました。チャットへの貼り付けより優れている理由を短く言えば、本番ログはコンテキストウィンドウに収まらない、チャットへの貼り付けは他のシステムから呼び出せない、そして素のプロンプトにはモデルの回答が実際にログデータに基づいているかを確認する仕組みがない、ということです。

Related MCP server: Log Analyzer MCP

ステータス

• コアサーバー、3 つのツール — サンプルログに対してエンドツーエンドで動作。✅

• LLM による根本原因生成 — 仮説を 2 つの独立した軸で検証し、どちらかに失敗したら 1 回だけ再試行するハルシネーション検証ループを搭載。✅

• マルチプロバイダー構成（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

意図的に2つのプロバイダーを使う — 単なるコスト回避ではない

Groq が抽出と疑念生成を受け持ち、Gemini が検証を受け持ちます。これは元々はクォータ回避策として始まりました（Gemini の無料枠は 1 日最大 20 件、Groq ははるかに多い）が、実際のアーキテクチャ改善となりました。自分が生成したモデルと同じモデルで検証を行うと、そのモデルの盲点を共有してしまうのです。 別のモデルファミリーで主張を確認することで、ハルシネーション検証は真に独立し、同根ソースからの単なる第2の意見とは異なります。Verification.independent は、回答が実際にプロバイダーまたぎの検証を通過したのか、それとも同じプロバイダーにフォールバックしたのか（Gemini 停止・未設定）を報告します。隠さずきちんと顕示します。

サービス間の取得ギャップ — テストで発見して、適切なレイヤーで修正

初期テストで、現実的な限界が明らかになりました。summarize_incident はチェックアウト障害の直接原因（DB プール枯渇）を検出できたものの、サンプルログがまた含む上流原因（別のサービスがコネクションを保持し続ける長時間クエリ）を見落としていました。構造上の問題は2つあります。

• 取得が純粋に語彙的でした。 抽出された語はチェックアウトに閉じてしまい、したがって、どれだけ推論が優れていても inventory-service の行は証拠集合に入りませんでした。修正には、意図的に非対称な時間ウィンドウ（前 900 秒 / 後 180 秒）を導入しました。原因は症状に先行する場合が多く、短い対称ウィンドウでは捕捉できないことが理由です。さらに、ウィンドウに関係なく不可ライン（WARN/ERROR）をグローバルにスキャンします。原因を説明する行それ自体が警告であることが多いからです（「NTP同期できず」「ローテーションがスキップ」など）。

• 検証器はスタンプを押すだけでした。 当初は、主張が引用した行だけを対象にし、それゆえに偽数です。不完全な 回答を検出することが構造的にできません。症状を説明するだけの主張は、それが参照した行によって見かけ上は裏付けされています。現在は証拠セット全体を見て 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、リトライストーム増幅、デプロイの障害、2つの重なる原因、単一障害ノードのクロックスキュー、健康なログ（「何も正常でない」が答である）、そして明明症が微妙な原因を隠す事例（完全次軸を意図的にテストするために作られた）。スコアリングは決定的です。同義概念グループ、必要な証拠の引用が使わ、LLM の判定はありません（結果は再現可能）。レポートは取得ミス（証拠がモデルに届か）と推論ミス（証拠があったのに誤った回答）を分離します。修正の種類が異なるためです。

現在の結果: 8/8 合格、取得ミス0、問ミス0。

このスイートのデバッグ自体も有用な技術的な知見です。非対称な時間ウィンドウとグローバルな異常検出スキャンが、検索の作り脆さを解消します。Groq の無料枠では、max_tokens は分間トークン予約（リザテ）であり、従量課金の上限ではありません。サイズ多きを見すぎると実際のプロンプトサイズとは関係なく欲 413 が返ります。また gpt-oss モデル群では reasoning_effort: "low" が必要でした。そうでないと予算を推論トークンが消費してしまい、有効な JSON を出す前に途切れてしまいました。さらテストランナー自体に 2 つのスコアリングバグがありました（まず Unicode の句読点違い、次に同じ複合識別子の余字母の違い）で、正しく答えても「失敗」として報告するものでした。自分で評価ハーネスを書くなら大知の価値があります。それもまたデバッグが必要です。

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

マルチステージビルド（開発依存キャッシュでコンパイルし、本番用依存のみ使用、非ルート root ユーザー、/health のヘルスチェック込み）です。コンテナは stdioではなく HTTP トランスポート（ MCP_TRANSPORT=http 、イメージでデフォルト）で動くため、Claude Desktop/Code のようにローカルで 親プロセルが起動する環境ではありません。

ステートレスの streamable-HTTP MCP サーバーを自分で作る場合に知っておくべき、実際に発見して修正したバグもあります。 SDK のステートレスモードでは、リクエストごとに新鮮なトランスポート が必要です。1 つトランスポートを複数のリクエストで再利用すると、初回以後すべてのリクエストが明かに 500 になり、そして例外も出ませんありません。また1 つの McpServer は同時に 1 つのトランスポートにしか接続できません（「Already connected to a transport」）。修正方法（ createServer() と src/index.ts の HTTP ハンドラを参照）は、リクエストごとに新しい McpServer と StreamableHTTPServerTransport を作るです。サーバーはツールの定義しか持たないから、コストは小さくく、接続ごとに状態はありません（そもそもこれらのツールはどれも呼び出しを越えて状態を持ちません）。実際のコンテナでの検証済みです。修正後、search_logs と summarize_incident はどちらも正常に完了しました。

環境変数

セットアップ

npm install
npm run build

デフォルトのままでは fixtures/sample.log を読み取ります。これは合成のインシデント（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

サーバを起動（または接続）して 3 つツールを全部呼び出ます。実際のクライアントを組み込む前に動作確認に便利です。完全なsummarize_incidentを実行するには言語合成のLLM呼び出しが 3-4 回（30〜90秒）なので、特定プログラムから呼ぶとき timeout に十分な時間を与えてくださいます（両スクリプトが行うえます）。

Claude Desktop に接続

{
  "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クライアントはデフォルトで、起動するサーバーはクリーンアップされ、あなたのシェルの完全な配物を含む環境ではありません。そのため、マシンのグローバルに設定しても env ブロックに下さいないと、summarize_incident はこのキーを参照できません。

Claude Desktop を再起動して、たとえば 「ログから 'pool exhausted' を検索して」 のように頼んでください。search_logs を自動的に呼び出すはずです。

Claude Code に接続

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 が明示的に取り扱う必要があります。）

プロジェクト構造

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