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. 安装依赖

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

2. 配置日志平台

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

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

方式二：配置文件

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

3. 启动服务

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

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

🔌 接入 CodeBuddy

STDIO 模式

在 CodeBuddy 中添加 mcp.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 中配置：

{
    "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