做一个 MCP server 来解析错误信息听起来像是给大模型加了一个“日志翻译器”实际用过之后会发现它解决的是排查链路里最耗时的一段从一堆报错里找到真正的原因再把这个原因转化成下一步动作。MCP server 在这个场景里的价值不只是把错误文本接收下来而是能把原始错误、运行上下文、知识库和修复建议组合成一个标准化的诊断结果。这篇内容适合经常面对错误日志、API 报错、服务告警又不想每次手动复制粘贴到搜索引擎里翻半天的开发者。下面我会按“它解决什么问题、MCP 为什么适配、怎么搭建、怎么接入客户端、常见坑和边界”这个顺序拆开讲。1. 为什么“能看懂错误信息”的 MCP Server 值得关注1.1 传统错误排查方式的最大瓶颈是上下文缺失我见过太多这种场景测试环境里某个接口突然返回一个错误码日志里只有一行error code -5000没有请求参数、没有调用链、没有附近日志。开发者第一反应是把错误码复制到搜索框结果搜出来的内容要么是别家产品的同名错误要么是不同语言、不同版本的实现跟当前问题对不上。更麻烦的是同一个错误信息在不同环境里往往对应不同原因。比如网络超时可能是服务端负载过高也可能是客户端防火墙拦截还可能是依赖的下游接口变慢了。只看一行错误文本谁都没法直接给出准确结论。传统排查需要人脑去补上下文翻配置文件、看日志上下文、查最近变更、确认调用链。这些操作本身不复杂但特别碎尤其是同时处理多个服务告警的时候效率会被严重拖低。1.2 MCP Server 能把“错误文本”转成“诊断动作”MCPModel Context Protocol模型上下文协议是一个让 AI 应用通过标准方式调用外部工具和资源的协议。一个专门的错误解析 MCP server相当于在错误信息和开发者之间加了一层解释层你扔给它一条原始报错它返回的是“这句话大概率在说什么、可能由什么引起、建议先查哪里”。这跟普通聊天式提问不一样。普通提问是人在对话窗口里贴错误信息然后让模型猜。MCP server 则可以把上下文也带上甚至可以提前配置好团队内部的知识库、错误码表、常见修复手册。这样模型不是凭空发挥而是在已有经验库的基础上做匹配和推理准确率和可操作性会明显好很多。1.3 适合谁用核心解决什么问题如果你是后端开发、运维、SRE或者在做 API 集成经常需要面对不熟悉的错误信息这类 MCP server 能帮你减少“复制报错 - 搜索 - 翻文档 - 试错”的时间。它尤其适合以下几种情况错误信息来自第三方 SDK 或远端 API本地拿不到完整源码。日志量很大需要先把错误聚合成可读的摘要和原因。团队里有沉淀下来的排查经验想分享给 AI 助手使用而不是只留在某个人的笔记里。但也要先说清楚边界它能帮你解释错误和给出排查方向不等于能自动修复问题。修改配置、改代码、处理生产事故仍然需要人工判断和确认。把它当成一个“懂行的排查助理”而不是“全自动修复器”才是合理的预期。2. MCP Server 的基本工作方式与错误解析场景适配2.1 MCP 不是又一个 API 网关很多人第一次听 MCP容易把它理解成“把各种 API 包一层让大模型调用”。这种理解不够准确。MCP 更像一套约定客户端比如一个支持 MCP 的 AI 应用如何发现服务端的能力服务端如何暴露工具、资源和提示词两边怎么传输请求、返回结果。协议层面大致是这样客户端负责接收用户问题并在需要时发起工具调用。服务端暴露一个或多个 tools每个工具都有名称、描述、参数 schema。调用完成后服务端把结构化的结果返回给客户端由大模型组织成回答。所以一个 MCP server 本质上是一个“能力提供者”。错误解析 MCP server 提供的能力就是“理解错误信息并生成诊断建议”。2.2 工具、资源、提示词三种能力怎么落到错误分析场景MCP 协议里服务端通常具备三类能力Tools可执行的函数比如explain_error、analyze_log_batch、lookup_error_code。用户可以让客户端调用这些工具来拿到分析结果。Resources可读取的上下文比如团队的错误码表、某台服务器的配置信息、最近变更记录。模型在回答前可以自动获取这些资料。Prompts预先设计好的提示词模板比如“你是后端排错助手先看错误类型再查日志上下文最后给修复建议”。错误解析服务最适合的形态是把 Tools 和 Resources 配合起来。工具负责接收输入资源负责提供额外上下文。举个例子当用户问“这个getaddrinfo ENOTFOUND是什么意思”工具可以先把错误信息标准化再从资源里读取“当前服务依赖了哪些域名、近期 DNS 配置是否变更”等信息最后生成一个针对当前环境的回答而不只是给一个通用解释。2.3 一条错误信息的完整处理数据流一个设计得比较完整的错误解析 MCP server内部通常走这样一条链路接收原始错误文本以及可选的项目名、环境、日志片段。先做预处理去敏感信息、统一换行符、判断是否包含堆栈、提取关键错误码。在本地知识库或规则引擎里做一次匹配看是否能直接命中已知错误。未命中或命中不完整时再调用大模型补充分析。把分析结果按统一结构返回比如错误含义、可能原因、排查步骤、置信度。这个链路的好处是不是所有错误都要交给大模型常见错误可以直接查表返回速度快、结果稳定新错误和复杂错误再交给模型做推理减少幻觉风险。输入材料里提到过的unsupported_country_region_territory、certificate file(p12) invalid or wrong、maximum context length、getaddrinfo ENOTFOUND这类错误都属于可以用结构化方式解析的典型样本。3. 动手搭建一个能解析错误信息的 MCP Server3.1 环境准备先说明下面的实现是参考思路具体 API 要以你安装的 MCP SDK 版本为准。MCP 生态迭代很快几个月前的代码可能已经需要调整导入路径或初始化方式。我建议本地准备这些条件Python 3.9 及以上推荐 3.11 或更高。一个可以调用的大模型服务可以是本地部署的模型也可以是团队内网已有的模型网关。安装 MCP Python SDK我一般用pip install mcp安装到虚拟环境。如果你只是先验证流程不急着接真实模型也可以先让 MCP server 返回固定规则的结果。先把协议跑通再接入模型这个顺序最稳。3.2 最小项目结构与依赖目录结构可以保持简单不要一开始就堆复杂模块error-mcp-server/ ├── pyproject.toml ├── error_mcp_server.py └── examples/ ├── sample_error.txt └── log_sample.txt这样做的原因有两个一是排错时容易定位问题二是入门阶段不需要把所有功能都做成微服务。真正要扩展时再按“规则库、知识库、模型调用、格式化输出”拆分模块也不迟。依赖方面核心只需要mcp外加一个 HTTP 请求库用来调用模型服务。如果你用的是 OpenAI 兼容接口requests就够了不一定要绑定某个厂商 SDK。3.3 核心代码从原始错误到结构化建议下面是一个最小可运行版本的参考代码。它暴露了一个工具explain_error接收错误文本、可选的上下文和语言参数返回一段结构化的分析文本。# error_mcp_server.py import requests from mcp.server.fastmcp import FastMCP mcp FastMCP(error-explain-server) # 这里换成你实际的模型服务地址 LLM_URL http://127.0.0.1:11434/v1/chat/completions LLM_MODEL local-llm # 按实际部署模型名修改 def call_llm(system_prompt: str, user_prompt: str) - str: 调用 OpenAI 兼容格式的模型服务。 payload { model: LLM_MODEL, messages: [ {role: system, content: system_prompt}, {role: user, content: user_prompt}, ], temperature: 0.2, max_tokens: 1200, } response requests.post(LLM_URL, jsonpayload, timeout90) response.raise_for_status() data response.json() return data[choices][0][message][content] mcp.tool() def explain_error(error_text: str, context: str , language: str zh) - str: 分析一条错误信息返回错误含义、可能原因和排查建议。 Args: error_text: 原始错误信息建议尽量完整。 context: 可选的运行上下文比如项目名、环境、最近操作、相关配置。 language: 输出语言默认中文。 if not error_text.strip(): return 错误信息不能为空请传入原始报错文本。 # 1. 先尝试命中本地规则 rule_result match_local_rules(error_text) if rule_result: return rule_result # 2. 本地规则没有命中时再调用模型 system_prompt ( 你是一名资深的软件排查助手。请根据用户提供的错误信息 给出准确、可执行的诊断结果。不要臆造原因不要直接给出修改代码的结论 必须说明验证步骤。 ) user_prompt f 错误信息 {error_text} 额外上下文 {context} 输出要求 1. 用一句话概括错误含义。 2. 列出 2 到 5 个可能原因按可能性从高到低排列。 3. 针对每个原因给出对应的验证或修复步骤。 4. 如果错误信息里包含错误码、超时时间、端口、域名、文件路径等关键信息请单独指出。 请用{language}输出。 try: return call_llm(system_prompt, user_prompt) except Exception as e: return ( f模型服务调用失败{e}\n 临时建议先检查模型服务是否启动、网络是否可达再直接查看错误文本关键词。 ) def match_local_rules(error_text: str) - str | None: 一个非常简单的本地规则表用于演示。 lower_text error_text.lower() if timeout in lower_text or timed out in lower_text: return ( 错误含义请求超时。\n 可能原因服务端响应慢、网络抖动、连接池耗尽。\n 验证步骤先看下游服务监控再看客户端超时配置最后看网络链路是否稳定。 ) if permission denied in lower_text or permissiondenied in lower_text: return ( 错误含义权限不足。\n 可能原因运行账号没有文件或目录权限、IAM 角色缺失、密钥无效。\n 验证步骤确认进程运行身份检查目标文件权限验证密钥是否过期。 ) return None if __name__ __main__: mcp.run()代码里最关键的是mcp.tool()装饰器。它告诉 MCP 客户端“这个 server 提供一个叫explain_error的工具”。工具的参数会被自动转换成协议里的输入 schema客户端可以根据这些参数提示用户填写或自动拼装。你可能已经注意到代码里先走match_local_rules再走模型。这个顺序很重要常见错误用规则返回速度和稳定性都更好模型只处理规则覆盖不到的部分既能减少调用成本也能降低模型乱说的概率。3.4 启动服务和连通性验证在项目目录下运行python error_mcp_server.py如果终端输出类似MCP server running或者监听传输层的信息说明服务已经起来。在 MCP 生态里服务本身不会像传统 Web 接口那样直接返回 HTTP它需要被 MCP 客户端连接后才能看到效果。我建议第一次验证时用 MCP Inspector 或支持 MCP 的工具把服务加进去然后手动调用explain_error输入一条已知报错比如Error: getaddrinfo ENOTFOUND api.example.com正常结果应该包含“域名解析失败”“检查 DNS 配置”“检查依赖域名是否可访问”这一类的信息。这样能确认协议链路通了再继续扩展功能。4. 让 MCP Server 真正“知道”错误含义知识库与大模型的配合4.1 直接把错误信息扔给模型不一定够很多人以为MCP server 里接一个大模型错误解析就能做到很好。实测下来会发现大模型的问题在于“泛”和“旧”它确实见过很多通用错误但遇上你团队内部私有系统的错误码、特定中间件版本的坑、某个供应商接口的新变化模型给出的结论经常是“看起来合理但完全没用”。比如unsupported_country_region_territory这个错误模型可能给出“当前请求的区域不受支持”的泛泛解释但实际排错还需要知道这个接口由哪个服务发出、账号配置在哪个区域、是不是测试环境误用了生产密钥、有没有合规限制。这些信息只存在于你当前项目的上下文里不在模型的通用知识里。所以一个真正能用的错误解析 MCP server不能只靠模型必须要有一个可控的知识来源。4.2 构建一个轻量错误知识库比较稳妥的做法是先维护一份结构化的错误知识清单。它不需要很大可以先从团队里最常遇到的 20 到 50 条错误开始。示例格式如下{ error_code: DNS_ENOTFOUND, pattern: getaddrinfo ENOTFOUND, severity: high, summary: 域名解析失败通常与 DNS 配置、网络策略或域名是否可访问有关。, possible_causes: [ { cause: 本机或容器内 DNS 配置错误, check: 执行 nslookup 或 dig 验证域名是否能解析 }, { cause: 依赖域名未在防火墙或安全组放行, check: 检查目标域名端口连通性并确认安全组规则 }, { cause: 服务在启动时资源不足导致解析超时, check: 查看服务启动日志和系统资源占用 } ], suggestions: [ 确认域名拼写, 检查 DNS 服务地址, 检查网络策略和代理环境变量 ] }MCP server 每收到一条报错先做两件事一是用字符串匹配或正则抽取错误码二是拿命中后的条目做结构化返回。如果本地知识库匹配到了就不调用模型匹配不到或置信度低再进入模型推理。这样做的好处是常见错误响应快几毫秒就能返回。团队内部经验能持续沉淀越用越准。模型不会在已知错误上重复犯错。4.3 输出格式和置信度判断如果知识库命中可以直接返回固定 JSON 结构。如果知识库没有命中模型接口返回的文本最好也转成同样的结构方便客户端后续自动化。一个推荐的输出结构是{ error_summary: 一句话概括, severity: low | medium | high | critical, possible_causes: [ {priority: 1, cause: 原因, action: 验证步骤} ], confidence: 0.8, source: local_knowledge_base | llm }confidence 字段很关键。它可以帮助使用者判断要不要直接相信这个结果。当来源是本地知识库、且错误码完全匹配时置信度可以设高一点当来源是大模型、且输入信息不完整时置信度要保守一些。这里有一个经验不要试图让模型自己输出置信度模型对自己的确信程度经常不准。更可靠的方式是从业务侧设置规则比如“是否命中已知错误码”“是否提供了完整堆栈”“是否包含上下文信息”。命中项目越多置信度就越高。5. 接入客户端落地到日常排查流程5.1 在 MCP 客户端里注册使用MCP server 本身不提供界面它需要配合支持 MCP 的客户端使用。常见的客户端配置方式是在配置文件中声明 server 名称、启动命令和参数。下面是一个和 stdin 传输方式匹配的示例{ mcpServers: { error-explain: { command: python, args: [/path/to/error_mcp_server.py], env: {} } } }具体配置项要看你使用的客户端和 MCP SDK 版本但核心逻辑一样客户端启动 server 进程通过协议发现工具在大模型对话中按需调用。第一次接入时先不要急着处理批量日志先用一条错误信息验证整个链路。5.2 从单条错误到日志文件批量分析单条工具调用跑通之后再考虑批量。批量场景是错误解析 MCP server 最有价值的地方也是最容易踩坑的地方。一个比较实用的做法是不直接让 MCP server 读超大日志文件而是先在外层用脚本把日志里疑似错误的部分提取出来再逐批调用 MCP server 的分析工具。输出侧要处理三件事每次分析的错误数量要限制比如一批 20 条防止模型上下文超长。输出命名要稳定建议按时间戳和日志文件来源生成结果文件。要设计失败重试某条分析失败时不要中断整个任务。如果输入材料里有maximum context length is 1048576 tokens这类错误你更会意识到上下文管理有多重要。MCP server 接收错误信息时应尽量只保留关键堆栈而不是把整段完整日志都塞给模型。5.3 给输出加一层人工确认机制错误解析 MCP server 可以给出分析但真正要执行修复动作时最好还是加一道人工确认。尤其是涉及生产环境、权限操作、配置变更、代码修改的场景直接自动化风险太高。我一般会在结果里额外输出“建议人工确认项”。比如“这个改动会影响线上连接池需要先在测试环境验证。”“权限调整需要管理员账号请确认合规流程。”“该错误可能和近期发布有关建议先回滚相关配置再观察。”不要觉得这一步多余。AI 辅助排查最怕的不是慢而是“看起来很有道理的错误结论”导致误操作。加一层确认其实是在保护你自己和你的团队。6. 运行中的常见问题与排查链路6.1 服务能启动但客户端连不上如果你看到 MCP server 进程已经启动但客户端始终提示connection failed先不要急着检查代码逻辑。按下面这个顺序排查确认启动命令里的路径是否正确。很多配置会挂在相对路径上客户端的工作目录和项目目录不一致时命令会找不到文件。确认传输方式一致。如果 server 默认监听 stdio客户端却用 SSE 或 HTTP 去连接自然连不上。查看 server 的标准错误输出。MCP 调试最方便的手段就是让 server 把日志写到 stderr然后从客户端查看启动日志。6.2 工具调用超时或返回空工具调用成功但结果为空或一直转圈通常不是协议问题而是 server 内部某个环节卡住了。排查顺序应该是先看模型服务是否可达。如果 server 调用本地模型可以先在终端直接 curl 一下模型接口。再看来回耗时。错误分析涉及模型调用经常要几十秒。客户端默认超时时间如果太短会出现“调用失败但 server 没报错”的假象。最后看输入内容。错误信息太长或格式不对可能导致模型拒绝返回或返回空字符串。6.3 错误信息被截断或乱码这条在真实场景里非常常见。日志里有中英文混排、Windows 和 Linux 路径分隔符不一致、特殊转义字符都会让解析结果变得很奇怪。处理建议是在进入 MCP server 之前先把原始错误文本做一次清洗。把不可见字符替换成普通空格限制单条错误长度尽量保留堆栈的最后若干行。如果错误信息包含二进制内容或编码异常先丢弃不要让模型强行分析。6.4 敏感信息泄露与脱敏错误日志里最容易出现的是访问密钥、IP、用户名、内部域名、请求 ID。如果 MCP server 会把错误信息发给远程模型服务或者写入结果文件必须先做脱敏。我常用的脱敏规则是替换sk-...、AK...等密钥前缀。正则替换邮箱和手机号。把内网 IP 替换成x.x.x.x。保留域名后缀但把子域名打码比如api.***.com。脱敏要放在调用模型之前而不是前后端传输之前。这样能确保模型拿到的只是清洗后的文本不会把敏感信息带进回答里。7. 使用边界与实践建议7.1 它能做什么不能做什么现在可以给这类错误解析 MCP server 做一个更清醒的定位。它能做的事情包括把一条看不懂的错误信息翻译成人类能理解的描述。结合本地知识库给出针对本项目的可能原因。提供按优先级排列的排查步骤。在批量日志中快速聚合错误减少人工翻阅时间。它不能做的事情包括不能保证解释一定准确因为错误信息本身可能不完整。不能直接访问你没授权给它的系统资源。不能替你做生产变更和代码修改。不能把所有问题都抽象成“配置问题”或“网络问题”那对排查没有意义。7.2 更适合作为“第二意见”而不是“自动驾驶”实际使用过程中我建议把它当作一个“第二意见”工具。你心里可以先有一个模糊判断然后让 MCP server 分析一遍看看结果能不能印证你的想法或者能不能补充你没想到的角度。它比较适合的工作流是报错出现先看日志上下文自己有个初步方向。把错误信息和上下文喂给 MCP server。对比输出结果和自己的判断。如果有分歧再回日志里验证。确认后再执行修复动作。这样既不会盲目相信 AI也不会让 MCP server 沦为摆设。排查链路里最贵的其实是人的注意力而错误解析 MCP server 能帮你把注意力集中在真正需要判断的地方。7.3 后续可以扩展的方向如果你已经在团队里用起来了后面可以考虑这些扩展方向错误知识库持续沉淀每分析一个有效错误就把“错误特征、原因、修复步骤”回写到知识库里积累多了以后大部分常见错误都能直接从本地命中。结合告警平台把 MCP server 接入到告警推送流程里告警触发时自动附上初步诊断信息减少人工翻日志的时间。多环境上下文识别在输入中带上项目名、环境、版本号让知识库按环境维度存储避免测试环境的结论误用在生产环境。自动化生成排查文档把一段时间内的高频错误和对应处理结果汇总成周报帮助团队发现系统性隐患。这些方向都不复杂核心还是先有一个跑得稳的最小版本再把经验源源不断地喂进去。最后留一个我一直保留的使用习惯先跑单条错误确认输出可靠再扩大到批量日志先看本地规则能否命中再考虑调用模型先脱敏再发送给远端服务。很多问题不是 MCP server 能力不够而是输入的错误信息没整理干净或者知识库还没沉淀到位。把这个基础打好错误解析 MCP server 会是一个越用越顺手的排错助手。
用MCP Server构建错误解析助手：从日志到诊断动作
做一个 MCP server 来解析错误信息听起来像是给大模型加了一个“日志翻译器”实际用过之后会发现它解决的是排查链路里最耗时的一段从一堆报错里找到真正的原因再把这个原因转化成下一步动作。MCP server 在这个场景里的价值不只是把错误文本接收下来而是能把原始错误、运行上下文、知识库和修复建议组合成一个标准化的诊断结果。这篇内容适合经常面对错误日志、API 报错、服务告警又不想每次手动复制粘贴到搜索引擎里翻半天的开发者。下面我会按“它解决什么问题、MCP 为什么适配、怎么搭建、怎么接入客户端、常见坑和边界”这个顺序拆开讲。1. 为什么“能看懂错误信息”的 MCP Server 值得关注1.1 传统错误排查方式的最大瓶颈是上下文缺失我见过太多这种场景测试环境里某个接口突然返回一个错误码日志里只有一行error code -5000没有请求参数、没有调用链、没有附近日志。开发者第一反应是把错误码复制到搜索框结果搜出来的内容要么是别家产品的同名错误要么是不同语言、不同版本的实现跟当前问题对不上。更麻烦的是同一个错误信息在不同环境里往往对应不同原因。比如网络超时可能是服务端负载过高也可能是客户端防火墙拦截还可能是依赖的下游接口变慢了。只看一行错误文本谁都没法直接给出准确结论。传统排查需要人脑去补上下文翻配置文件、看日志上下文、查最近变更、确认调用链。这些操作本身不复杂但特别碎尤其是同时处理多个服务告警的时候效率会被严重拖低。1.2 MCP Server 能把“错误文本”转成“诊断动作”MCPModel Context Protocol模型上下文协议是一个让 AI 应用通过标准方式调用外部工具和资源的协议。一个专门的错误解析 MCP server相当于在错误信息和开发者之间加了一层解释层你扔给它一条原始报错它返回的是“这句话大概率在说什么、可能由什么引起、建议先查哪里”。这跟普通聊天式提问不一样。普通提问是人在对话窗口里贴错误信息然后让模型猜。MCP server 则可以把上下文也带上甚至可以提前配置好团队内部的知识库、错误码表、常见修复手册。这样模型不是凭空发挥而是在已有经验库的基础上做匹配和推理准确率和可操作性会明显好很多。1.3 适合谁用核心解决什么问题如果你是后端开发、运维、SRE或者在做 API 集成经常需要面对不熟悉的错误信息这类 MCP server 能帮你减少“复制报错 - 搜索 - 翻文档 - 试错”的时间。它尤其适合以下几种情况错误信息来自第三方 SDK 或远端 API本地拿不到完整源码。日志量很大需要先把错误聚合成可读的摘要和原因。团队里有沉淀下来的排查经验想分享给 AI 助手使用而不是只留在某个人的笔记里。但也要先说清楚边界它能帮你解释错误和给出排查方向不等于能自动修复问题。修改配置、改代码、处理生产事故仍然需要人工判断和确认。把它当成一个“懂行的排查助理”而不是“全自动修复器”才是合理的预期。2. MCP Server 的基本工作方式与错误解析场景适配2.1 MCP 不是又一个 API 网关很多人第一次听 MCP容易把它理解成“把各种 API 包一层让大模型调用”。这种理解不够准确。MCP 更像一套约定客户端比如一个支持 MCP 的 AI 应用如何发现服务端的能力服务端如何暴露工具、资源和提示词两边怎么传输请求、返回结果。协议层面大致是这样客户端负责接收用户问题并在需要时发起工具调用。服务端暴露一个或多个 tools每个工具都有名称、描述、参数 schema。调用完成后服务端把结构化的结果返回给客户端由大模型组织成回答。所以一个 MCP server 本质上是一个“能力提供者”。错误解析 MCP server 提供的能力就是“理解错误信息并生成诊断建议”。2.2 工具、资源、提示词三种能力怎么落到错误分析场景MCP 协议里服务端通常具备三类能力Tools可执行的函数比如explain_error、analyze_log_batch、lookup_error_code。用户可以让客户端调用这些工具来拿到分析结果。Resources可读取的上下文比如团队的错误码表、某台服务器的配置信息、最近变更记录。模型在回答前可以自动获取这些资料。Prompts预先设计好的提示词模板比如“你是后端排错助手先看错误类型再查日志上下文最后给修复建议”。错误解析服务最适合的形态是把 Tools 和 Resources 配合起来。工具负责接收输入资源负责提供额外上下文。举个例子当用户问“这个getaddrinfo ENOTFOUND是什么意思”工具可以先把错误信息标准化再从资源里读取“当前服务依赖了哪些域名、近期 DNS 配置是否变更”等信息最后生成一个针对当前环境的回答而不只是给一个通用解释。2.3 一条错误信息的完整处理数据流一个设计得比较完整的错误解析 MCP server内部通常走这样一条链路接收原始错误文本以及可选的项目名、环境、日志片段。先做预处理去敏感信息、统一换行符、判断是否包含堆栈、提取关键错误码。在本地知识库或规则引擎里做一次匹配看是否能直接命中已知错误。未命中或命中不完整时再调用大模型补充分析。把分析结果按统一结构返回比如错误含义、可能原因、排查步骤、置信度。这个链路的好处是不是所有错误都要交给大模型常见错误可以直接查表返回速度快、结果稳定新错误和复杂错误再交给模型做推理减少幻觉风险。输入材料里提到过的unsupported_country_region_territory、certificate file(p12) invalid or wrong、maximum context length、getaddrinfo ENOTFOUND这类错误都属于可以用结构化方式解析的典型样本。3. 动手搭建一个能解析错误信息的 MCP Server3.1 环境准备先说明下面的实现是参考思路具体 API 要以你安装的 MCP SDK 版本为准。MCP 生态迭代很快几个月前的代码可能已经需要调整导入路径或初始化方式。我建议本地准备这些条件Python 3.9 及以上推荐 3.11 或更高。一个可以调用的大模型服务可以是本地部署的模型也可以是团队内网已有的模型网关。安装 MCP Python SDK我一般用pip install mcp安装到虚拟环境。如果你只是先验证流程不急着接真实模型也可以先让 MCP server 返回固定规则的结果。先把协议跑通再接入模型这个顺序最稳。3.2 最小项目结构与依赖目录结构可以保持简单不要一开始就堆复杂模块error-mcp-server/ ├── pyproject.toml ├── error_mcp_server.py └── examples/ ├── sample_error.txt └── log_sample.txt这样做的原因有两个一是排错时容易定位问题二是入门阶段不需要把所有功能都做成微服务。真正要扩展时再按“规则库、知识库、模型调用、格式化输出”拆分模块也不迟。依赖方面核心只需要mcp外加一个 HTTP 请求库用来调用模型服务。如果你用的是 OpenAI 兼容接口requests就够了不一定要绑定某个厂商 SDK。3.3 核心代码从原始错误到结构化建议下面是一个最小可运行版本的参考代码。它暴露了一个工具explain_error接收错误文本、可选的上下文和语言参数返回一段结构化的分析文本。# error_mcp_server.py import requests from mcp.server.fastmcp import FastMCP mcp FastMCP(error-explain-server) # 这里换成你实际的模型服务地址 LLM_URL http://127.0.0.1:11434/v1/chat/completions LLM_MODEL local-llm # 按实际部署模型名修改 def call_llm(system_prompt: str, user_prompt: str) - str: 调用 OpenAI 兼容格式的模型服务。 payload { model: LLM_MODEL, messages: [ {role: system, content: system_prompt}, {role: user, content: user_prompt}, ], temperature: 0.2, max_tokens: 1200, } response requests.post(LLM_URL, jsonpayload, timeout90) response.raise_for_status() data response.json() return data[choices][0][message][content] mcp.tool() def explain_error(error_text: str, context: str , language: str zh) - str: 分析一条错误信息返回错误含义、可能原因和排查建议。 Args: error_text: 原始错误信息建议尽量完整。 context: 可选的运行上下文比如项目名、环境、最近操作、相关配置。 language: 输出语言默认中文。 if not error_text.strip(): return 错误信息不能为空请传入原始报错文本。 # 1. 先尝试命中本地规则 rule_result match_local_rules(error_text) if rule_result: return rule_result # 2. 本地规则没有命中时再调用模型 system_prompt ( 你是一名资深的软件排查助手。请根据用户提供的错误信息 给出准确、可执行的诊断结果。不要臆造原因不要直接给出修改代码的结论 必须说明验证步骤。 ) user_prompt f 错误信息 {error_text} 额外上下文 {context} 输出要求 1. 用一句话概括错误含义。 2. 列出 2 到 5 个可能原因按可能性从高到低排列。 3. 针对每个原因给出对应的验证或修复步骤。 4. 如果错误信息里包含错误码、超时时间、端口、域名、文件路径等关键信息请单独指出。 请用{language}输出。 try: return call_llm(system_prompt, user_prompt) except Exception as e: return ( f模型服务调用失败{e}\n 临时建议先检查模型服务是否启动、网络是否可达再直接查看错误文本关键词。 ) def match_local_rules(error_text: str) - str | None: 一个非常简单的本地规则表用于演示。 lower_text error_text.lower() if timeout in lower_text or timed out in lower_text: return ( 错误含义请求超时。\n 可能原因服务端响应慢、网络抖动、连接池耗尽。\n 验证步骤先看下游服务监控再看客户端超时配置最后看网络链路是否稳定。 ) if permission denied in lower_text or permissiondenied in lower_text: return ( 错误含义权限不足。\n 可能原因运行账号没有文件或目录权限、IAM 角色缺失、密钥无效。\n 验证步骤确认进程运行身份检查目标文件权限验证密钥是否过期。 ) return None if __name__ __main__: mcp.run()代码里最关键的是mcp.tool()装饰器。它告诉 MCP 客户端“这个 server 提供一个叫explain_error的工具”。工具的参数会被自动转换成协议里的输入 schema客户端可以根据这些参数提示用户填写或自动拼装。你可能已经注意到代码里先走match_local_rules再走模型。这个顺序很重要常见错误用规则返回速度和稳定性都更好模型只处理规则覆盖不到的部分既能减少调用成本也能降低模型乱说的概率。3.4 启动服务和连通性验证在项目目录下运行python error_mcp_server.py如果终端输出类似MCP server running或者监听传输层的信息说明服务已经起来。在 MCP 生态里服务本身不会像传统 Web 接口那样直接返回 HTTP它需要被 MCP 客户端连接后才能看到效果。我建议第一次验证时用 MCP Inspector 或支持 MCP 的工具把服务加进去然后手动调用explain_error输入一条已知报错比如Error: getaddrinfo ENOTFOUND api.example.com正常结果应该包含“域名解析失败”“检查 DNS 配置”“检查依赖域名是否可访问”这一类的信息。这样能确认协议链路通了再继续扩展功能。4. 让 MCP Server 真正“知道”错误含义知识库与大模型的配合4.1 直接把错误信息扔给模型不一定够很多人以为MCP server 里接一个大模型错误解析就能做到很好。实测下来会发现大模型的问题在于“泛”和“旧”它确实见过很多通用错误但遇上你团队内部私有系统的错误码、特定中间件版本的坑、某个供应商接口的新变化模型给出的结论经常是“看起来合理但完全没用”。比如unsupported_country_region_territory这个错误模型可能给出“当前请求的区域不受支持”的泛泛解释但实际排错还需要知道这个接口由哪个服务发出、账号配置在哪个区域、是不是测试环境误用了生产密钥、有没有合规限制。这些信息只存在于你当前项目的上下文里不在模型的通用知识里。所以一个真正能用的错误解析 MCP server不能只靠模型必须要有一个可控的知识来源。4.2 构建一个轻量错误知识库比较稳妥的做法是先维护一份结构化的错误知识清单。它不需要很大可以先从团队里最常遇到的 20 到 50 条错误开始。示例格式如下{ error_code: DNS_ENOTFOUND, pattern: getaddrinfo ENOTFOUND, severity: high, summary: 域名解析失败通常与 DNS 配置、网络策略或域名是否可访问有关。, possible_causes: [ { cause: 本机或容器内 DNS 配置错误, check: 执行 nslookup 或 dig 验证域名是否能解析 }, { cause: 依赖域名未在防火墙或安全组放行, check: 检查目标域名端口连通性并确认安全组规则 }, { cause: 服务在启动时资源不足导致解析超时, check: 查看服务启动日志和系统资源占用 } ], suggestions: [ 确认域名拼写, 检查 DNS 服务地址, 检查网络策略和代理环境变量 ] }MCP server 每收到一条报错先做两件事一是用字符串匹配或正则抽取错误码二是拿命中后的条目做结构化返回。如果本地知识库匹配到了就不调用模型匹配不到或置信度低再进入模型推理。这样做的好处是常见错误响应快几毫秒就能返回。团队内部经验能持续沉淀越用越准。模型不会在已知错误上重复犯错。4.3 输出格式和置信度判断如果知识库命中可以直接返回固定 JSON 结构。如果知识库没有命中模型接口返回的文本最好也转成同样的结构方便客户端后续自动化。一个推荐的输出结构是{ error_summary: 一句话概括, severity: low | medium | high | critical, possible_causes: [ {priority: 1, cause: 原因, action: 验证步骤} ], confidence: 0.8, source: local_knowledge_base | llm }confidence 字段很关键。它可以帮助使用者判断要不要直接相信这个结果。当来源是本地知识库、且错误码完全匹配时置信度可以设高一点当来源是大模型、且输入信息不完整时置信度要保守一些。这里有一个经验不要试图让模型自己输出置信度模型对自己的确信程度经常不准。更可靠的方式是从业务侧设置规则比如“是否命中已知错误码”“是否提供了完整堆栈”“是否包含上下文信息”。命中项目越多置信度就越高。5. 接入客户端落地到日常排查流程5.1 在 MCP 客户端里注册使用MCP server 本身不提供界面它需要配合支持 MCP 的客户端使用。常见的客户端配置方式是在配置文件中声明 server 名称、启动命令和参数。下面是一个和 stdin 传输方式匹配的示例{ mcpServers: { error-explain: { command: python, args: [/path/to/error_mcp_server.py], env: {} } } }具体配置项要看你使用的客户端和 MCP SDK 版本但核心逻辑一样客户端启动 server 进程通过协议发现工具在大模型对话中按需调用。第一次接入时先不要急着处理批量日志先用一条错误信息验证整个链路。5.2 从单条错误到日志文件批量分析单条工具调用跑通之后再考虑批量。批量场景是错误解析 MCP server 最有价值的地方也是最容易踩坑的地方。一个比较实用的做法是不直接让 MCP server 读超大日志文件而是先在外层用脚本把日志里疑似错误的部分提取出来再逐批调用 MCP server 的分析工具。输出侧要处理三件事每次分析的错误数量要限制比如一批 20 条防止模型上下文超长。输出命名要稳定建议按时间戳和日志文件来源生成结果文件。要设计失败重试某条分析失败时不要中断整个任务。如果输入材料里有maximum context length is 1048576 tokens这类错误你更会意识到上下文管理有多重要。MCP server 接收错误信息时应尽量只保留关键堆栈而不是把整段完整日志都塞给模型。5.3 给输出加一层人工确认机制错误解析 MCP server 可以给出分析但真正要执行修复动作时最好还是加一道人工确认。尤其是涉及生产环境、权限操作、配置变更、代码修改的场景直接自动化风险太高。我一般会在结果里额外输出“建议人工确认项”。比如“这个改动会影响线上连接池需要先在测试环境验证。”“权限调整需要管理员账号请确认合规流程。”“该错误可能和近期发布有关建议先回滚相关配置再观察。”不要觉得这一步多余。AI 辅助排查最怕的不是慢而是“看起来很有道理的错误结论”导致误操作。加一层确认其实是在保护你自己和你的团队。6. 运行中的常见问题与排查链路6.1 服务能启动但客户端连不上如果你看到 MCP server 进程已经启动但客户端始终提示connection failed先不要急着检查代码逻辑。按下面这个顺序排查确认启动命令里的路径是否正确。很多配置会挂在相对路径上客户端的工作目录和项目目录不一致时命令会找不到文件。确认传输方式一致。如果 server 默认监听 stdio客户端却用 SSE 或 HTTP 去连接自然连不上。查看 server 的标准错误输出。MCP 调试最方便的手段就是让 server 把日志写到 stderr然后从客户端查看启动日志。6.2 工具调用超时或返回空工具调用成功但结果为空或一直转圈通常不是协议问题而是 server 内部某个环节卡住了。排查顺序应该是先看模型服务是否可达。如果 server 调用本地模型可以先在终端直接 curl 一下模型接口。再看来回耗时。错误分析涉及模型调用经常要几十秒。客户端默认超时时间如果太短会出现“调用失败但 server 没报错”的假象。最后看输入内容。错误信息太长或格式不对可能导致模型拒绝返回或返回空字符串。6.3 错误信息被截断或乱码这条在真实场景里非常常见。日志里有中英文混排、Windows 和 Linux 路径分隔符不一致、特殊转义字符都会让解析结果变得很奇怪。处理建议是在进入 MCP server 之前先把原始错误文本做一次清洗。把不可见字符替换成普通空格限制单条错误长度尽量保留堆栈的最后若干行。如果错误信息包含二进制内容或编码异常先丢弃不要让模型强行分析。6.4 敏感信息泄露与脱敏错误日志里最容易出现的是访问密钥、IP、用户名、内部域名、请求 ID。如果 MCP server 会把错误信息发给远程模型服务或者写入结果文件必须先做脱敏。我常用的脱敏规则是替换sk-...、AK...等密钥前缀。正则替换邮箱和手机号。把内网 IP 替换成x.x.x.x。保留域名后缀但把子域名打码比如api.***.com。脱敏要放在调用模型之前而不是前后端传输之前。这样能确保模型拿到的只是清洗后的文本不会把敏感信息带进回答里。7. 使用边界与实践建议7.1 它能做什么不能做什么现在可以给这类错误解析 MCP server 做一个更清醒的定位。它能做的事情包括把一条看不懂的错误信息翻译成人类能理解的描述。结合本地知识库给出针对本项目的可能原因。提供按优先级排列的排查步骤。在批量日志中快速聚合错误减少人工翻阅时间。它不能做的事情包括不能保证解释一定准确因为错误信息本身可能不完整。不能直接访问你没授权给它的系统资源。不能替你做生产变更和代码修改。不能把所有问题都抽象成“配置问题”或“网络问题”那对排查没有意义。7.2 更适合作为“第二意见”而不是“自动驾驶”实际使用过程中我建议把它当作一个“第二意见”工具。你心里可以先有一个模糊判断然后让 MCP server 分析一遍看看结果能不能印证你的想法或者能不能补充你没想到的角度。它比较适合的工作流是报错出现先看日志上下文自己有个初步方向。把错误信息和上下文喂给 MCP server。对比输出结果和自己的判断。如果有分歧再回日志里验证。确认后再执行修复动作。这样既不会盲目相信 AI也不会让 MCP server 沦为摆设。排查链路里最贵的其实是人的注意力而错误解析 MCP server 能帮你把注意力集中在真正需要判断的地方。7.3 后续可以扩展的方向如果你已经在团队里用起来了后面可以考虑这些扩展方向错误知识库持续沉淀每分析一个有效错误就把“错误特征、原因、修复步骤”回写到知识库里积累多了以后大部分常见错误都能直接从本地命中。结合告警平台把 MCP server 接入到告警推送流程里告警触发时自动附上初步诊断信息减少人工翻日志的时间。多环境上下文识别在输入中带上项目名、环境、版本号让知识库按环境维度存储避免测试环境的结论误用在生产环境。自动化生成排查文档把一段时间内的高频错误和对应处理结果汇总成周报帮助团队发现系统性隐患。这些方向都不复杂核心还是先有一个跑得稳的最小版本再把经验源源不断地喂进去。最后留一个我一直保留的使用习惯先跑单条错误确认输出可靠再扩大到批量日志先看本地规则能否命中再考虑调用模型先脱敏再发送给远端服务。很多问题不是 MCP server 能力不够而是输入的错误信息没整理干净或者知识库还没沉淀到位。把这个基础打好错误解析 MCP server 会是一个越用越顺手的排错助手。