MCP Server实践:AI错误诊断工具,让报错不再难懂
最近 MCP 生态里冒出来的工具,十有八九是“连接数据库”“操作浏览器”“读写文件”这类偏基础设施的 server。这次看到的这个项目方向不太一样:它是一个“能看懂错误消息到底在说什么”的 MCP server。简单说,你把一段报错丢给它,它帮你拆解错误原因、给出排查思路,甚至是修复建议。
这个项目出现在 Show HN 上,本质上是围绕 MCP 协议做的一个错误诊断服务。它不追求帮你自动改代码,而是解决一个更实际的问题:开发时遇到一长串看不懂的异常日志,不知道是环境问题、依赖问题、权限问题还是代码逻辑问题。有了这个 MCP server,调试路径可以变成“把报错发给它 -> 拿到结构化分析和排查清单 -> 按步骤定位”,而不是把整段报错复制到搜索引擎里碰运气。
下面这篇会先给核心能力速览,再讲适用场景,然后给一套通用的本地部署和启动流程,重点演示如何通过 MCP 客户端调用它来分析错误消息,最后补充性能观察、常见问题和工程化建议。由于项目本身是公开的 MCP server,具体安装方式以仓库 README 为准,下面会用一套可复用的通用流程来说明。
1. 核心能力速览
| 能力项 | 说明 |
|---|---|
| 项目类型 | MCP Server,错误消息诊断与排查辅助 |
| 核心功能 | 接收错误消息,输出错误原因分析、排查建议、修复思路 |
| MCP 协议 | 基于 Model Context Protocol,可接入支持 MCP 的客户端 |
| 适用客户端 | Claude Desktop、Cursor、Dify、Codex、Trae 等支持 MCP 的 AI 编程/对话工具 |
| 启动方式 | 命令行启动,通常通过npx或本地脚本注册到 MCP 客户端 |
| 是否支持 API | 支持,MCP 本身就是一种接口调用方式,客户端可通过 tool 调用 |
| 是否支持批量任务 | 可以,支持一次丢入多条错误日志做批量分析 |
| 显存/GPU 需求 | 无,属于纯逻辑处理,实际消耗取决于底层大模型接口 |
| 主要门槛 | 需要一个可用的 LLM 接口作为分析引擎,可以是本地模型,也可以是云端模型 |
| 适合场景 | 本地开发调试、日志分析、CI 失败排查、错误知识库整理 |
从材料看,这个项目定位很清楚:不是“又一个 MCP 万能工具”,而是专注在错误消息理解和诊断建议这个细分场景。它把 MCP 的 tool 调用能力和 LLM 的错误分析能力结合起来,等于给 AI 编程工具加了一个“报错翻译官”。
2. 适用场景与使用边界
2.1 适合谁
这个工具最适合以下几类人:
- 日常用 Cursor、Claude Desktop、Trae 这类 AI 编程工具的开发者,经常遇到 AI 生成的代码报错,但 AI 无法直接看到终端里的完整错误堆栈。
- 需要批量分析日志的运维或后端开发,比如服务报错、登录失败、连接超时、HTTP 500 这类高频问题。
- 正在学习和研究 MCP 协议的开发者,可以用这个项目当样本,理解 MCP server 如何定义 tool、如何接收结构化输入、如何返回结果。
2.2 能解决什么问题
- 错误消息看不懂,搜索引擎又搜不到精确结果。
- 报错信息混杂了环境问题、权限问题、依赖问题,手动定位成本高。
- 同一个错误反复出现,想沉淀成团队内部的知识库。
- 调用大模型分析报错时,上下文里塞了太多无关日志,需要先做结构化提取。
2.3 不适合什么场景
- 需要实时监控线上日志并自动修复的场景,这个工具偏向“分析+建议”,不适合直接做自动化运维。
- 完全离线的隐私敏感环境,如果底层大模型走云端接口,日志内容会经过外部模型处理,需谨慎评估。
2.4 使用边界与合规提醒
这里必须强调:错误消息里经常包含服务器路径、数据库连接串、IP 地址、接口参数、甚至令牌信息。无论是把这个 MCP server 接入云端大模型,还是把日志批量丢给它分析,都要先做脱敏处理。涉及用户数据、生产环境日志、商业机密时,要先确认授权和合规边界。不要拿未经脱敏的生产日志直接做外部 API 调用。
3. MCP 是什么,为什么适合做错误诊断
3.1 MCP 基础概念
MCP,全称 Model Context Protocol,是一个让 AI 模型与外部工具、数据源交互的开放协议。它解决的核心问题是:大模型不能直接读取本地文件、不能直接查询数据库、不能直接调用命令行,而 MCP 就是中间那层“适配器”。
一个 MCP server 会暴露一组标准化的工具(tool),客户端(比如 Claude Desktop、Cursor、Dify)通过协议调用这些工具,并把结果返回给模型。这样模型就能在对话中动态获取外部信息,而不是只能靠训练数据里的记忆。
3.2 为什么错误诊断适合做成 MCP server
错误诊断有几个特点,正好适合 MCP 这种形态:
- 输入短,输出长。一个错误消息可能只有几行,但分析结果可能是一份排查清单。
- 强工具属性。它不依赖对话历史,每次调用都是独立的“输入报错 -> 返回分析”。
- 可组合性强。多个 MCP server 可以同时挂在一个客户端上,这个负责错误分析,另一个负责查数据库,还有一个负责操作浏览器。
- 本地优先。MCP server 本身跑在本地,数据经过程序处理后按需发给模型,比直接把整个控制台日志粘贴给 AI 更可控。
从搜热词里能看到,现在 MCP 相关问题的搜索量已经很高了,比如“mcp是什么”“mcp server”“dify添加本地mcp服务”“codex mcp”“playwright mcp”。这个项目属于 MCP 生态里的应用型 server,不需要 GPU,部署门槛低,对刚接触 MCP 的开发者来说也是一个不错的学习样本。
4. 环境准备与前置条件
在部署之前,先确认环境满足下面这些条件。由于项目本身没有提供非常详细的硬件说明,下面给的是常见 MCP server 部署的通用要求,具体以仓库 README 为准。
4.1 操作系统
建议使用 macOS 或 Linux,Windows 也可以跑,但需要额外确认 Node.js 环境变量和 MCP 客户端的 JSON 配置路径。
4.2 运行时环境
这类工具通常是 Node.js 或 Python 写的。从 MCP server 的常见形态推测,这个项目大概率是基于 Node.js 的 MCP SDK 开发,因此需要准备:
node -v npm -v如果没有安装 Node.js,建议先装 LTS 版本。部分 MCP 客户端对 Node 版本有要求,不要用太老的版本。
4.3 大模型接口
这个 MCP server 本身不生成分析结果,它需要调用一个大模型来理解错误消息。你需要准备以下任意一种:
- OpenAI 兼容的 API 接口(本地或云端均可)
- Anthropic API
- 本地部署的模型,比如通过 Ollama、llama.cpp 启动的服务
- 其他支持 OpenAI 兼容协议的网关服务
这里的核心是:MCP server 负责把错误消息整理成结构化输入,大模型负责生成分析结果。没有可用的模型接口,这个 server 只能做格式处理,无法输出诊断建议。
4.4 磁盘空间
MCP server 本身很小,几十 MB 到几百 MB 不等。主要的空间消耗来自依赖包和日志缓存,预留 1GB 就足够了。不需要下载大模型。
4.5 端口占用
MCP 的一种常见工作模式是 stdio,即通过标准输入输出与客户端通信,这种情况不占用 HTTP 端口。如果项目支持 HTTP 模式,就需要检查端口是否被占用。
| 检查项 | 命令示例 | 说明 |
|---|---|---|
| Node 版本 | node -v | 需要 LTS 或更高版本 |
| npm 版本 | npm -v | 随 Node 一起安装 |
| 端口占用 | lsof -i:3000 | 如果跑 HTTP 模式需要检查 |
| 模型接口连通性 | curl http://127.0.0.1:11434/api/tags | 以本地 Ollama 为例 |
5. 安装部署与启动方式
5.1 安装方式一:通过 npx 直接注册
很多 Node.js 写的 MCP server 支持直接用npx启动,不需要手动 clone 仓库。通用命令如下:
npx <package-name>@latest具体包名需要以项目仓库提供的为准。如果仓库 README 里给了一键安装命令,直接复制即可。
5.2 安装方式二:clone 源码手动启动
如果需要修改源码或定制提示词,推荐 clone 仓库的方式:
git clone <repository-url> cd <repository-folder> npm install安装依赖后,可以先用命令行单独测试一下 server 是否正常启动:
node index.js如果显示 MCP server 启动成功的日志,说明基础环境没有问题。
5.3 注册到 Claude Desktop
以 Claude Desktop 为例,在配置文件claude_desktop_config.json中添加 MCP server 配置:
{ "mcpServers": { "error-analyzer": { "command": "npx", "args": ["<package-name>"], "env": { "OPENAI_API_KEY": "your-api-key", "OPENAI_BASE_URL": "http://127.0.0.1:11434/v1" } } } }配置说明:
command是启动命令,可以是npx、node或python。args是启动参数,改成实际包名或脚本路径。env是环境变量,按项目要求填写模型接口的 key 和 base URL。
5.4 注册到 Dify
在 Dify 中添加本地 MCP 服务的思路类似,需要在“工具”配置里选择 MCP 类型,然后填写启动命令和环境变量。具体路径以 Dify 版本界面为准。
从搜热词可以确认,“dify添加本地mcp服务”“dify mcp怎么使用”是当前开发者关注度比较高的问题,所以这一步可以重点讲清楚通用逻辑:MCP 配置本质上就是告诉客户端“用什么命令启动一个子进程”。
5.5 验证启动
注册完成后,重启 MCP 客户端,然后在对话中发送一条测试消息,比如:
请调用错误分析工具,分析下面这段报错: Error: ENOENT: no such file or directory, open '/app/config.json'如果配置正确,客户端会尝试调用 MCP server 的 tool,并返回结构化分析结果。
6. 功能测试与效果验证
6.1 测试目标
部署 MCP server 后,先验证几个核心能力:
- 能否正确接收错误消息。
- 能否区分错误类型(文件缺失、权限不足、网络超时、依赖版本冲突等)。
- 能否给出具体的排查步骤。
- 能否在真实 MCP 客户端中正常调用,而不是只在命令行里能跑。
6.2 测试用例一:文件缺失类错误
输入示例:
Error: ENOENT: no such file or directory, open '/app/config.json'预期结果:
- 识别出这是文件系统错误。
- 指出可能原因:配置文件不存在、路径错误、工作目录不对。
- 给出排查步骤:检查文件是否存在、检查相对路径基准目录、检查挂载卷是否生效。
判断标准:输出结果里应包含“ENOENT”“文件路径”“工作目录”等关键词,而不是泛泛的“这是一个系统错误”。
6.3 测试用例二:网络连接类错误
输入示例:
Error: getaddrinfo ENOTFOUND servicewechat.com这是搜热词里真实出现过的错误消息格式。预期结果:
- 识别出是 DNS 解析失败。
- 指出可能原因:域名拼写错误、DNS 服务器异常、本地 hosts 文件干扰、网络环境限制。
- 给出排查步骤:
nslookup检查解析、ping测试连通性、检查代理配置。
判断标准:能区分“域名不存在”和“域名存在但连不通”,这两个场景的排查方向完全不同。
6.4 测试用例三:认证与权限类错误
输入示例:
Sign-in failed: login server error: token exchange failed: token endpoint returned 400预期结果:
- 识别出是 OAuth / Token 交换失败。
- 指出可能原因:client_id 或 client_secret 配置错误、授权码过期、重定向地址不匹配。
- 给出排查步骤:检查请求参数、刷新令牌、对比 OAuth 端点配置。
判断标准:能结合错误上下文提示“token exchange failed”通常意味着认证流程的第二步出了问题,而不是账号密码错误。
6.5 测试用例四:服务端异常类错误
输入示例:
500 Internal Server Error: llama-server process has terminated: exit status 1预期结果:
- 识别出是服务端进程崩溃。
- 指出可能原因:模型文件损坏、显存不足、端口被占用、参数配置错误。
- 给出排查步骤:查看服务端日志、检查进程内存占用、减少并发请求、确认模型路径。
判断标准:能给出“先查子进程退出码”“再查启动参数”这种有实际意义的排查路径。
6.6 批量任务测试
错误诊断最常见的场景不是一条一条问,而是批量分析。可以准备一个errors.txt,每行一条错误消息,然后通过脚本逐条调用 MCP server 的 tool。
import subprocess import json # 通过 MCP 客户端调用时需要走特定协议,这里只给一个读取批量日志的思路 with open("errors.txt", "r", encoding="utf-8") as f: errors = [line.strip() for line in f if line.strip()] print(f"共读取到 {len(errors)} 条错误消息") for err in errors[:5]: print("---") print(err)在实际使用中,批量场景往往是这样的:把 CI 构建日志、应用运行日志导出成文本文件,然后用脚本按错误类型分组,再交给 MCP server 做批量诊断。这样比逐个复制粘贴更高效。
6.7 判断成功的标准
- 工具返回的结果是否结构化,比如分了几类原因、几个排查步骤。
- 给出的建议是否符合该错误类型的通用排查逻辑。
- 批量处理多行错误消息时,是否会混淆上下文。
7. 接口 API 调用与批量任务设计
7.1 MCP 工具本质上是接口
MCP server 暴露的 tool 可以理解为一种接口。客户端通过 JSON-RPC 与 server 通信。虽然没有 REST API 那么直观,但它的标准化程度很高,同一个工具可以被 Claude Desktop、Cursor、Dify 等多个客户端共用。
7.2 通用请求数据结构
一个典型的 MCP tool 调用请求,结构类似:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "analyze_error", "arguments": { "error_message": "Error: ENOENT: no such file or directory, open '/app/config.json'" } } }实际的 method 名称、tool 名称和参数名称要以项目仓库的 README 为准。这里只是展示 MCP 调用的通用结构。
7.3 Python 批量调用思路
如果不想用现成的 MCP 客户端,也可以自己写脚本通过 stdio 模式调用。核心思路是用子进程启动 server,然后按 MCP 协议写入请求,读取返回。
import subprocess import json proc = subprocess.Popen( ["node", "index.js"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True ) request = { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "analyze_error", "arguments": { "error_message": "Error: getaddrinfo ENOTFOUND servicewechat.com" } } } proc.stdin.write(json.dumps(request) + "\n") proc.stdin.flush() result = proc.stdout.readline() print(result)注意:不同 MCP SDK 实现的 stdio 协议细节可能有差异,务必参考项目 README。不要把这个脚本当成直接可用的代码,它只是说明批量调用的思路。
7.4 批量任务队列设计
如果需要分析大量错误日志,建议设计一个简单的队列任务:
- 输入目录
./errors:存放原始错误日志。 - 输出目录
./results:存放分析结果。 - 日志文件
./logs/analysis.log:记录每条任务的执行状态。 - 脱敏规则:在提交给大模型之前,先替换 IP、令牌、文件路径等敏感信息。
input_dir: ./errors output_dir: ./results log_dir: ./logs max_retry: 3 timeout_seconds: 60 sanitize_rules: - pattern: "(?i)(token|secret|password)=[a-zA-Z0-9_-]+" replace: "[REDACTED]" - pattern: "\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}" replace: "[IP]"失败重试建议:单条错误分析超时或返回空结果时,重试 2 到 3 次;连续失败就把该条错误单独存到一个failed.txt,避免阻塞整个批量队列。
8. 资源占用与性能观察
8.1 显存与 GPU
这个 MCP server 本身不需要 GPU。它的资源消耗主要在两个方面:
- 运行 MCP server 进程本身的 CPU 和内存占用。
- 底层大模型接口的消耗,如果使用云端模型,本地几乎不消耗 GPU;如果使用本地模型,显存占用取决于模型大小。
更稳妥的判断是:MCP server 进程的内存占用通常在几十 MB 到几百 MB 之间,具体以实际启动后的监控为准。
8.2 如何观察资源占用
启动 MCP server 后,可以用系统监控工具观察:
# macOS top -o mem -pid $(pgrep -f "node .*mcp*") # Linux top -p $(pgrep -f "node .*mcp*")核心观察指标:
- 常驻内存(RSS)
- CPU 使用率
- 启动时是否短暂出现高 CPU(依赖加载阶段)
如果走 HTTP 模式,还会有一个端口监听进程,可以用lsof查看。
8.3 性能影响因素
- 错误消息长度越长,提交给大模型的 token 越多,响应越慢。
- 批量任务并发数太高会触发模型的 rate limit。
- 如果接入的模型需要排队,整体耗时会被拉长。
- 本地部署小模型时,分析质量可能不如云端大模型稳定,但隐私性更好。
8.4 降低资源占用的建议
- 分析前先对错误消息做大小写归一化和去重,减少重复提交。
- 只提交错误堆栈的关键部分,不要提交整份日志文件。
- 批量任务控制在 5 个并发以内,避免触发接口限流。
- 如果不需要图形界面,就不要启动无关的 MCP 客户端。
9. 常见问题与排查方法
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| 客户端找不到 MCP server | 配置路径错误或包名错误 | 检查mcpServersJSON 配置 | 确认包名、命令、参数与 README 一致 |
| 启动后秒退 | Node 版本过低或依赖安装不完整 | 在命令行手动运行启动命令观察报错 | 升级 Node,重新npm install |
| 调用工具后返回空结果 | 大模型接口配置错误 | 检查env中的 API Key 和 Base URL | 用 curl 单独验证模型接口连通性 |
| 错误消息被截断 | 上下文长度限制 | 检查使用的模型上下文窗口 | 先截取错误堆栈核心部分 |
| 批量任务部分失败 | 遇到模型限流或超时 | 查看日志中的 HTTP 状态码 | 加大重试间隔,降低并发数 |
| 分析结果太泛 | 模型能力不足或提示词不完整 | 尝试换更大的模型,或补充错误上下文 | 升级模型接口,或手动补充环境信息 |
| 端口冲突 | 多个 MCP server 使用同一 HTTP 端口 | lsof -i:<port>查看占用进程 | 换一个端口或者改用 stdio 模式 |
| 日志泄露风险 | 提交了未脱敏数据 | 检查日志内容和传输通道 | 增加脱敏规则,评估本地模型方案 |
9.1 依赖安装失败
MCP server 依赖安装失败是最高频问题。常见原因包括:
- 网络原因导致 npm 包下载失败。
- Node 版本过低,部分依赖要求 Node 18 以上。
- 本机已有全局依赖冲突。
建议先删掉node_modules和package-lock.json,重新安装:
rm -rf node_modules package-lock.json npm install如果网络下载慢,可以配置 npm 镜像,但要注意镜像源的选择需要符合所在网络环境的规定。
9.2 模型接口连通性验证
这里给出一个通用的连通性检查命令,以 OpenAI 兼容接口为例:
curl http://127.0.0.1:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "qwen2.5:7b", "messages": [{"role": "user", "content": "hi"}]}'如果这个请求不能正常返回,说明问题不在 MCP server,而在底层模型接口。
9.3 分析结果不准确
这是最需要调优的地方。MCP server 的输出质量由三个因素决定:
- 底层模型的能力。
- 提交上下文的信息量。
- 工具提示词的设计。
如果结果太泛,先从这些方向排查:模型是否太小、错误消息是否被截断、是否缺少错误发生时的环境信息。在提交前补上“操作系统版本”“Node 版本”“最近变更”等上下文,能显著提升分析质量。
10. 最佳实践与使用建议
10.1 第一次先小参数测试
不要一上来就批量分析几百条历史错误日志。先用 3 到 5 条典型错误做验证,确认 MCP server 的输出质量和接口稳定性,再扩大规模。
10.2 维护一套最小可运行配置
把可用的配置模板、模型接口地址、测试错误样例保存到项目目录下,下次换机器或换模型时可以直接复用。
{ "mcpServers": { "error-analyzer": { "command": "npx", "args": ["<package-name>"], "env": { "OPENAI_BASE_URL": "http://127.0.0.1:11434/v1", "OPENAI_API_KEY": "ollama", "MODEL_NAME": "qwen2.5:7b" } } } }10.3 数据脱敏要前置
错误日志里经常出现 IP、文件路径、令牌、数据库连接串。批量分析前先用正则替换掉敏感信息,尤其是要走云端模型接口时。这一步不能省。
10.4 批量任务要加日志和重试
每次调用 MCP server 的分析请求,都记录请求时间、错误消息哈希、模型返回状态。失败重试加延迟,不要把同一个请求在短时间内反复提交。
10.5 接口服务要限制访问范围
如果 MCP server 以 HTTP 模式运行并暴露到局域网或公网,一定要加访问限制。最好的方式是不监听公网地址,只允许本机或内网固定 IP 调用。
10.6 与 CI 流程结合
更实用的场景是把错误分析接入 CI。构建失败后,把失败的日志片段先做脱敏,再通过 MCP 工具调用错误分析,然后把结果写入 issue 或飞书消息。这样团队成员在提交代码后就能直接看到 AI 给出的排查建议。
10.7 沉淀错误知识库
每次分析结果如果质量不错,可以存成一份结构化的错误知识库条目,包含错误原文、原因分类、排查步骤、修复方案。长期积累下来,团队内部搜索引擎能直接命中重复问题,比每次重新问 AI 效率高得多。
error_id: err-20250101-001 error_type: dns_resolution_failed keyword: ENOTFOUND severity: medium symptom: | Error: getaddrinfo ENOTFOUND servicewechat.com root_cause: | 域名无法解析,可能是 DNS 服务器异常或域名拼写错误 steps: - step: 检查域名拼写和 hosts 文件 command: "cat /etc/hosts" - step: 检查 DNS 解析 command: "nslookup servicewechat.com" - step: 检查代理设置 fix: | 如果本地有代理规则,确认是否拦截了该域名11. 总结与下一步
这个 MCP server 最值得尝试的点,是它把一个所有人都会遇到的痛点(看不懂报错)做成了标准化的 MCP 工具。它不挑显卡,不需要下载大模型,只要能接入一个可用的模型接口,就能在 Cursor、Dify、Claude Desktop 这类工具里获得一个随时可用的错误诊断助手。
最先应该验证的是三类错误:文件缺失类(ENOENT)、网络解析类(ENOTFOUND)、认证流程类(token exchange failed)。这三类覆盖了日常开发里很高比例的问题。验证通过后再考虑批量日志分析,而不是一开始就上量。
最容易踩的坑有两个:一个是大模型接口没配好,导致 MCP server 起来后输出空结果;另一个是不做脱敏直接把生产日志丢给外部模型接口。前者影响使用体验,后者是合规风险。
后续可以扩展的方向包括:把分析结果接入内部知识库、按团队成员共享一套 MCP 配置、把错误分类结果回传给 CI 工具做自动标签。对刚接触 MCP 的开发者来说,这也是一个很好的学习项目——读完它的源码,基本就理解了 MCP server 的定义、工具注册、参数校验和结果返回这一整套流程。
