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