# grafana-log-mcp

[![npm version](https://img.shields.io/npm/v/grafana-log-mcp)](https://www.npmjs.com/package/grafana-log-mcp)
[![npm downloads](https://img.shields.io/npm/dm/grafana-log-mcp)](https://www.npmjs.com/package/grafana-log-mcp)
[![license](https://img.shields.io/npm/l/grafana-log-mcp)](https://www.npmjs.com/package/grafana-log-mcp)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen)](https://nodejs.org)
[![GitHub](https://img.shields.io/badge/GitHub-sunshinerich%2Fgrafana--log--mcp-181717?logo=github)](https://github.com/sunshinerich/grafana-log-mcp)

**grafana-log-mcp** is a **generic, reusable log-querying layer** for Grafana/Loki, exposed as a read-only stdio MCP server. It talks to Grafana's API and returns raw logs plus aggregated views — slow queries, error fingerprints, and volume trends — filtered by time window, project, keyword, or duration threshold.

It deliberately ships **no business-specific logic or heuristics**. Once the logs are in hand, correlating them with source code and explaining *why something happened* is left to your AI IDE and the **skills/rules of the business project** being debugged — the server just makes the data available.

中文定位：这是一个**通用的日志查询层**（仅做取数、聚合、返回日志，跨业务复用），不内置任何业务分析与根因归因；具体原因分析由调用方的 AI 结合业务项目源码及项目自身的 skill/经验完成。

## 安装

```bash
# 方式一：npm 全局安装（推荐）
npm install -g grafana-log-mcp
```

全局安装后提供两个命令：`grafana-log-mcp`（启动 MCP Server）、`grafana-log-mcp-login`（交互登录）。

也可不安装、用 npx 一次性运行：`npx -y grafana-log-mcp` / `npx -y grafana-log-mcp-login`。

## 快速开始

### npm 已安装（消费方）

```bash
# 1. 登录（交互输入 Grafana 地址与用户名密码，写入 ~/.grafana-log-mcp/credentials.json，0600）
grafana-log-mcp-login

# 2. 校验凭证（排查"MCP 突然查不了"）
grafana-log-mcp-login --check

# 3. 启动 MCP Server（stdio）
grafana-log-mcp
```

### 源码开发（clone 仓库后）

```bash
# 1. 安装依赖（node >= 18）
npm install

# 2. 登录
node bin/login.js

# 3. 校验凭证
node bin/login.js --check

# 4. 启动 MCP Server（stdio）
npm start          # 即 node src/index.js
```

## 接入 AI IDE（Trae/Claude 等）

在 MCP 配置中添加（按各 IDE 的配置格式）：

```json
{
  "mcpServers": {
    "grafana-log": {
      "command": "npx",
      "args": ["-y", "grafana-log-mcp"],
      "env": { "GRAFANA_URL": "https://your-grafana.example.com" }
    }
  }
}
```

**推荐全局启用**：排障时打开的是业务项目源码仓库，把 MCP 配置加为全局，即可在任意仓库直接"提问 → 查日志 → 读代码 → 给原因"。

## 工具（15 个）

| 层 | 工具 | 用途 |
|---|---|---|
| 发现 | `list_datasources` / `list_projects` | 多数据源枚举、项目发现（含未登记的 app/group） |
| 元数据 | `list_labels` / `list_label_values` | 标签与取值 |
| 查询 | `query_logs` | 原始日志（优先 requestId + 窄时间窗控制数据量） |
| 查询 | `get_full_line` | 取回单条日志完整原文（单行 500 截断时，按该行 time 作 timestamp 查询） |
| 查询 | `query_slow_logs` | 按耗时阈值抓慢日志（如 >30s 的慢 SQL），自动配对回捞 SQL 语句原文；命中超 30 条（循环任务）时自动按操作聚合 |
| 有报错 | `summarize_errors` / `logs_volume` / `trace_context` | 错误归并分级、量级突增、单请求链路 |
| 无报错 | `compare_baseline` / `inspect_fields` / `trace_flow` | 消失的日志模板、空值字段、流程断点 |
| 编排 | `diagnose_issue` | **排障首选**：一次调用出诊断报告 + codeHints |
| 辅助 | `build_explore_url` | 生成 Grafana Explore 深链供人工核对 |

数据量三道硬上限：limit ≤ 1000、单行 500 字符、响应 25k 字符（超出保头尾省中段并标注）。单行被截断时可用 `get_full_line` 按该行 time 取回完整内容。

## 项目登记（projects.json）

登记文件按以下优先级定位（`list_projects` 返回的 `summary.configFile` 会显示当前实际生效位置）：

1. `GRAFANA_CONFIG_PATH` 环境变量指定的文件
2. 包内 `config/projects.json`（源码仓库内）
3. `~/.grafana-log-mcp/projects.json`（与凭证同目录，npm 安装后的默认位置）

参考格式见 `config/projects.example.json`，每项含 `key / datasourceUid / labels{app,group} / aliases(中文别名) / repoPath`。`repoPath` 仅供 AI IDE 定位代码用，MCP 自身不读源码。故障知识库在 `config/failure-patterns.json`，遇到新故障类型追加条目即可。

## 环境变量（可选）

```
GRAFANA_URL=                  # Grafana 地址：作为 grafana-log-mcp-login 的默认地址，并覆盖凭证文件中的地址
GRAFANA_ORG_ID=1              # 可选：仅影响 build_explore_url 生成的 Explore 深链的 orgId 参数（默认 1）；不参与实际日志查询
GRAFANA_CREDENTIALS_PATH=     # 自定义凭证文件位置
GRAFANA_CONFIG_PATH=          # 自定义项目登记文件（projects.json）位置
GRAFANA_MOCK=1                # 本地 mock 模式：不连真实 Grafana、无需登录（2500 条合成日志，验证翻页/截断/慢日志）
```

说明：MCP 不内置任何 Grafana 默认地址与项目配置（通用化），地址来自登录时输入（凭证文件）或 `GRAFANA_URL` 环境变量；实例相关配置（项目登记、数据源 uid）在 projects.json 维护（见上节定位规则）。

## 测试

```bash
node test/unit.mjs         # 纯逻辑单测（合成日志，无网络依赖）：59 通过
node test/integration.mjs  # 编排器端到端（mock client + 独立 fixture 配置）：20 通过
```