# Log Diagnosis MCP Server

> 通用日志诊断 MCP 服务器 —— 让 AI 自动完成「查日志 → 还原调用链 → 扫描代码 → 定位 BUG 根因」的完整闭环。

## 💡 解决什么问题

后端开发者排查线上 BUG 的传统流程：

```
登录日志平台 → 拼查询条件 → 翻页找日志 → 手动还原调用链 → 看代码找根因
```

**痛点**：步骤繁琐、耗时 30 分钟~数小时、容易遗漏关键日志。

**本工具**：通过 MCP 协议将日志查询能力暴露给 AI，让 AI 自动完成整个诊断闭环，**将排查时间缩短到几分钟**。

## ✨ 核心特性

| 特性 | 说明 |
|------|------|
| 🔌 **通用对接** | 支持 Elasticsearch、Grafana Loki、自定义 REST API 三种日志平台 |
| 🔍 **TraceId 链路追踪** | 自动计算时间范围、分页拉取全量日志、还原完整调用链 |
| 🔐 **灵活鉴权** | 支持 API Key、Bearer Token、SecretKey 换 Token 多种方式 |
| 🌍 **多环境切换** | 支持 T1（测试）/ PRE（预发）/ PRD（生产）环境一键切换 |
| 📄 **上下文关联** | 获取可疑日志的前后文，帮助 AI 理解完整场景 |
| 🔗 **双传输模式** | 同时支持 SSE 和 STDIO 两种 MCP 连接方式 |

## 📦 快速开始

### 1. 安装依赖

```bash
git clone https://github.com/your-username/log-diagnosis-server.git
cd log-diagnosis-server
pip install -r requirements.txt
```

### 2. 配置日志平台

**方式一：环境变量（推荐）**

```bash
export LOG_PLATFORM_TYPE=elasticsearch   # elasticsearch / loki / custom
export LOG_PRD_URL=http://your-es-host:9200
export LOG_PRE_URL=http://your-es-pre:9200   # 可选
export LOG_T1_URL=http://your-es-test:9200    # 可选
export LOG_DEFAULT_ENV=PRD
```

**方式二：配置文件**

```bash
cp config.example.json config.json
# 编辑 config.json 填入实际地址
export LOG_DIAG_CONFIG=./config.json
```

### 3. 启动服务

```bash
# STDIO 模式（本地开发推荐）
python server.py

# SSE 模式（远程部署）
MCP_TRANSPORT=sse MCP_PORT=8080 python server.py
```

## 🔌 接入 CodeBuddy

### STDIO 模式

在 CodeBuddy 中添加 `mcp.json`：

```json
{
    "mcpServers": {
        "log-diagnosis-server": {
            "command": "python3",
            "args": ["/path/to/log-diagnosis-server/server.py"],
            "env": {
                "LOG_PLATFORM_TYPE": "elasticsearch",
                "LOG_PRD_URL": "http://your-es-host:9200"
            },
            "timeout": 60
        }
    }
}
```

### SSE 模式

先启动服务，然后在 CodeBuddy 中配置：

```json
{
    "mcpServers": {
        "log-diagnosis-server": {
            "url": "http://your-server:8080/sse",
            "timeout": 60
        }
    }
}
```

## 🛠️ 提供的工具 (Tools)

| # | 工具名 | 功能 | 典型场景 |
|---|--------|------|----------|
| 1 | `get_access_token` | 鉴权获取 Token | 首次连接日志平台 |
| 2 | `query_logs` | 通用日志查询 | 按条件搜索日志 |
| 3 | `count_logs` | 日志计数 | 评估数据量、决定分页 |
| 4 | `query_logs_by_trace_id` | TraceId 全链路查询 | **核心** — 一键拉取完整调用链 |
| 5 | `get_log_context` | 日志上下文 | 查看可疑日志前后发生了什么 |

### 查询语法

工具使用统一的查询语法（会自动转换为目标平台语法）：

```
# 精确匹配
service=order-service

# 模糊匹配
message~NullPointerException

# 逻辑组合
service=order-service AND level=ERROR
service=order-service AND message~timeout AND NOT level=DEBUG
```

## 🚀 使用示例

在 CodeBuddy 的 Craft Agent 中直接描述需求：

**示例 1 — TraceId 链路诊断：**
```
帮我查一下这个 TraceId 的完整调用链路：a1b2c3d4e5f67890a1b2c3d4e5f67890
环境是预发(PRE)，看看哪里出了问题
```

**示例 2 — 错误日志排查：**
```
order-service 在过去 1 小时内有大量 ERROR 日志，帮我分析根因
```

**示例 3 — SQL 问题定位：**
```
有个查询结果为空的 BUG，TraceId 是 abc123...，帮我看看 SQL 是否有问题
```

AI 会自动调用工具完成：鉴权 → 查询日志 → 分析调用链 → 定位根因 → 给出修复建议

## ⚙️ 配置参数说明

| 参数 | 必填 | 说明 | 示例值 |
|------|------|------|--------|
| `LOG_PLATFORM_TYPE` | 是 | 日志平台类型 | `elasticsearch` / `loki` / `custom` |
| `LOG_PRD_URL` | 是 | 生产环境日志平台地址 | `http://your-es-host:9200` |
| `LOG_PRE_URL` | 否 | 预发环境日志平台地址 | `http://your-es-pre:9200` |
| `LOG_T1_URL` | 否 | 测试环境日志平台地址 | `http://your-es-test:9200` |
| `LOG_DEFAULT_ENV` | 否 | 默认环境，默认 PRD | `PRD` / `PRE` / `T1` |
| `LOG_REQUEST_TIMEOUT` | 否 | 请求超时时间（秒），默认 30 | `30` |
| `LOG_DIAG_CONFIG` | 否 | 配置文件路径（优先级高于环境变量） | `./config.json` |

## 📊 效率对比

| 步骤 | 传统方式 | 使用本工具 |
|------|---------|-----------|
| 登录日志平台 | 1-2 分钟 | ✅ AI 自动鉴权 |
| 拼查询条件 | 3-5 分钟 | ✅ AI 自动生成 |
| 翻页找日志 | 5-15 分钟 | ✅ 自动分页全量拉取 |
| 还原调用链 | 10-30 分钟 | ✅ 自动按时间排序分析 |
| 看代码定位根因 | 10-60 分钟 | ✅ AI 扫描代码关联 |
| **总计** | **30 分钟 ~ 数小时** | **几分钟** |

## 🔧 支持的日志平台

| 平台 | 配置值 | 说明 |
|------|--------|------|
| Elasticsearch | `elasticsearch` / `es` | 支持 ES 7.x / 8.x / OpenSearch |
| Grafana Loki | `loki` | 通过 LogQL 查询 |
| 自定义 REST API | `custom` | 对接任意实现标准接口的日志平台 |

### 自定义平台接口协议

如果你的日志平台不是 ES/Loki，只需实现以下 REST API：

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/auth/token` | POST | 鉴权，请求体 `{"secretKey": "..."}` |
| `/api/logs/query` | POST | 查询日志 |
| `/api/logs/count` | POST | 计数 |
| `/api/logs/context/{id}` | POST | 获取上下文 |

## 📁 项目结构

```
log-diagnosis-server/
├── server.py                        # MCP Server 主入口（5 个工具定义）
├── config.py                        # 配置管理（环境变量 / 配置文件）
├── adapters/
│   ├── __init__.py                  # 适配器工厂
│   ├── base.py                      # 适配器基类 + 通用查询语法解析
│   ├── elasticsearch_adapter.py     # Elasticsearch 适配器
│   ├── loki_adapter.py              # Grafana Loki 适配器
│   └── custom_adapter.py           # 自定义 REST API 适配器
├── config.example.json              # 配置文件示例
├── requirements.txt                 # Python 依赖
├── LICENSE                          # MIT 开源协议
├── .gitignore                       # Git 忽略规则
└── README.md                        # 本文件
```

## 📄 License

MIT