
这个工具解决什么问题
在 Claude Desktop 或 Cursor 里加一个 MCP 服务器,实际要做的事就是把一段 JSON 贴进配置文件,再重启客户端。贴完一看,工具列表里什么都没多出来。配置文件本身没被标红,客户端也没有报错弹窗,重启三次还是空的。这时候只能靠猜:是括号少了?逗号多了?args 到底是数组还是字符串?那个 npx 我这台机器装了没有?网上教程的配置能跑,自己照着改过之后就不行——差别在哪一行?没有人告诉你。改到最后往往是把整份配置删掉重新抄一遍,运气好就通了,运气不好还是不知道错在哪。
- 原来的做法:打开配置文件逐字符比对、把配置删了重抄、上网搜「MCP 配置不生效」,最后靠反复重启客户端试错,一次要折腾十几分钟到半小时
- 用这个工具:粘进窗口就有结果:错误在第 8 行第 18 列、args 必须是数组、C:/tools/mcp-report/server.exe 这个路径在本机不存在;双击问题行直接跳到配置里对应的位置
- 省下来的:从「猜 + 重抄 + 反复重启」压到「粘进去看一眼」;常见配置几秒钟出结果,改完再粘一次就能确认,不用靠重启客户端试探
技术实现
这类工具的技术难点不在界面,而在「怎么在不猜错的前提下把错误指到行列」。两个选择定了实现路径:解析器自己写,命令一个都不执行。自己写解析器,是因为 .NET 自带的 JSON 反序列化只给字符偏移量和「无效的 JSON 基元」,用户拿这个信息无法定位;自己写还能在报错之后继续解析,一次把所有问题摊开,而不是逼用户改一个再报下一个。不执行命令,是因为检查工具不能有副作用——npx 一跑就会联网下载包,既慢又会往缓存里写东西,而判断命令在不在其实只需要看文件系统。所以程序切成三层:Json.cs 只负责把文本变成带坐标的树,Rules.cs 只做纯函数判定(含 PATH 查找),MainForm.cs 只做渲染。前两层不引用任何界面类型,44 条自测可以在没有窗口的情况下全部跑完——这一点很关键,本机沙箱不允许向窗口注入鼠标事件,靠点按钮做自测这条路走不通。
- 手写递归下降解析器,每个节点带行列号:JsonParser 逐字符推进,同时维护行列号:每消费一个字符就记账,因此每条 Issue 都能给出「第 8 行第 18 列」。不用 JavaScriptSerializer 的原因很具体——它只报字符偏移量与「无效的 JSON 基元」,用户拿这个信息没法定位,也看不出是少了逗号还是多了引号。
- 出错不中断:就地恢复后继续往下解析:对象与数组的每轮循环先记下当前位置,出错后跳过非法字符继续解析;若一轮下来位置没有推进就强制前进,并把循环上限设为 50000 次,避免括号未闭合时解析器一路吞到文件结尾。效果是一份配置里的五处错误能一次全列出来。
- 五类高频笔误各有专门分支:尾逗号、// 与 注释、单引号字符串、键名不带引号、中文全角标点,都由专门分支识别并给出针对性改法;另有一条「同一对象里重名键」提醒——JSON 只认后面那个,前面那次等于白写,这是「我明明改了却不生效」的常见原因。
- 专抓「不报错但坏掉」的路径转义:Windows 路径写在 JSON 里时,反斜杠是转义符:\t 会被静默解码成制表符,解析不报错、客户端也不报错,但拿到的路径是坏的。解析字符串时标记是否解码出控制字符(小于 0x20),命中即提醒改用正斜杠或双反斜杠。这类问题比语法错误更难查,因为两边都不吭声。
- 命令可达性按 PATH + PATHEXT 查文件,不执行:ResolveCommand() 对带分隔符的按 GetFullPath + File.Exists 判定;对纯命令名则遍历 PATH 的每个目录、拼上 PATHEXT 里的每个扩展名再 File.Exists。整个过程不调 Process.Start:既避免执行来路不明的命令,也避免 npx 触发联网下载。
- WinForms 手工 DPI 折算 + 表格列宽收缩:SetProcessDPIAware 让文字清晰,代价是所有尺寸要自己乘缩放比(P(x) = x × DpiX / 96),同时把 AutoScaleMode 设为 None 防止系统再缩一次。ListView 的横向滚动范围不会随列变窄而立刻收缩,FitColumns() 用「设定 → 加一 → 还原」抖一次,强制它重算,去掉那条什么都没得滚的横条。
技术栈:C# 5、.NET Framework 4.8、WinForms 窗体、手写递归下降 JSON 解析器(带行列号与错误恢复)、PATH + PATHEXT 命令查找、UTF-8 / UTF-16 / GB18030 编码判定
已知局限:只做静态检查:读配置文本与本机文件系统,不启动服务器、不联网、不探测远程地址能否连通,因此「配置全对但服务器本身起不来」这类问题查不出来。不做 JSON Schema 全字段校验,只覆盖 MCP 配置里高频出错的字段与结构。命令查找按当前进程的 PATH 判定,与客户端实际使用的环境变量可能有差异(从桌面双击启动和从版本管理器的会话里启动,环境变量并不完全一致)。
同类软件对照
下面几款都是公开可查的同类软件,定位各不相同。这里只说明各自的定位,以及本工具在其中的位置,方便你判断哪一类更契合自己的用法。
| 软件 | 它的定位 | 本工具的定位 |
|---|---|---|
| 客户端自带的日志与报错 | Claude Desktop、Cursor 等客户端在配置出错时会写日志文件,个别版本还会在界面上给一句提示 | 本工具把这一步提前到编辑阶段:粘进窗口就能看到第几行第几列,不用再去 %APPDATA% 下翻日志文件,也不用重启客户端确认 |
| JSONLint、JSON.cn 一类通用校验工具 | 通用 JSON 语法校验,能指出语法错误的位置 | 本工具在语法之外还按 MCP 配置的结构做检查:args 是不是数组、command 和 url 有没有冲突、命令在本机能不能找到——这些在通用校验器里全都是合法 JSON |
| VS Code 的 JSON Schema 校验 | 编辑器内置能力,按 schema 提示字段类型与拼写错误 | 需要先准备好可用的 schema 并绑到文件上,且不会检查本机是否存在该命令、也看不出 Windows 路径转义被吃掉;本工具是独立 exe,双击即用,不需要编辑器 |
| MCP Inspector 等官方调试工具 | 面向开发者的调试工具,能真正连上服务器查看握手过程与工具列表 | 它关心的是连上之后能做什么,本工具关心的是连之前配置对不对;两者阶段不同,常常是先用本工具把配置改对,再用调试工具看能力 |
以上仅作定位对照,各软件的可用性、授权方式与功能范围请以其官方页面为准。
操作教程
- 解压后双击「MCP配置体检.exe」
不需要安装任何运行库(Win10/11 自带 .NET Framework 4.8)。打开即载入一份示例配置并自动检查,不用点任何按钮。
预期结果:窗口打开,左侧看到示例 JSON,右侧显示 3 个服务器、2 个错误、1 个提醒 - 把自己的配置整段粘到左边
直接 Ctrl+V 即可,也可以用「打开配置文件…」选文件(会自动识别 UTF-8 / UTF-16 / GB18030 与 BOM)。输入停顿约 0.3 秒后自动重新检查。
预期结果:右侧三个数字与问题清单立刻刷新,状态栏显示当前是粘贴内容还是某个文件 - 从上往下看问题清单
清单按错误、提醒、提示、通过排序:红色是会导致加载失败的,橙色是不影响加载但值得改的,绿色是已经确认没问题的。
预期结果:每条都带行号;双击任意一行,左侧光标会跳到对应位置并选中那一行 - 看下面的「说明与建议」
选中一行后,下面写清楚两件事:为什么会这样、具体怎么改。比如路径不存在时会提示常见原因(换电脑没同步、盘符变了、反斜杠被转义吃掉)。
预期结果:说明文字与选中的问题对应,能照着改 - 改完再粘回来复查
按说明改完,把配置重新粘进窗口(或直接改左边的文本),检查会自动重跑。
预期结果:错误数变成 0,结论变为结构完整、没有发现问题 - 需要留档就点「复制报告」
报告是纯文本,含检查时间、每一条问题的行号与说明、以及服务器清单,可以直接粘到记事本里对着改,或者发给同事。
预期结果:状态栏提示已复制,粘到记事本里能看到完整报告
常见问题
技术实现与后续维护
本工具由我们自行开发并持续维护。判定规则全部写成纯函数并配了断言,改一条规则立刻能知道有没有把别的规则带坏;界面与判定分离,新增一条规则不需要动窗口代码。下面说明它的技术构成与可扩展方向。
技术构成:
src/Program.cs—— 程序入口:DPI 声明、未处理异常兜底、--selftest 隐藏开关src/Model.cs—— Issue / ServerInfo / CheckResult 三个数据模型与统计、排序src/Json.cs—— 带行列号与错误恢复的递归下降 JSON 解析器src/Rules.cs—— MCP 配置结构与字段规则、PATH + PATHEXT 命令查找src/Report.cs—— 把检查结果导出成纯文本报告src/Samples.cs—— 内置示例配置与最小模板src/MainForm.cs—— 主窗口:布局、DPI 折算、事件、跳行、复制报告src/SelfTest.cs—— 44 项无界面自测
可扩展方向:
- 支持 .vscode/mcp.json 的 inputs 变量占位符,做取值与引用一致性检查
- 批量模式:选一个目录,一次检查里面所有 .json 配置并汇总成一张表
- 把检查结果导出成 Markdown,方便贴进工单或团队文档
- 增加配置迁移:把 mcpServers 写法一键转成 servers 写法,或反过来
- 记住上次打开的目录与窗口大小,减少重复操作
本工具免费提供使用,功能完整、不设限制。如果你需要在本工具基础上做功能调整、对接内部系统或长期维护,可以联系我们做二次开发。
需要其它功能?可以定制
这个工具只做一件事:MCP 客户端配置写错一个字符就不加载,却不给任何提示,只能一行行瞎试。如果你的场景还需要别的处理,可以联系我们做二次开发,按你的实际数据格式和流程定制。
常见的定制需求:
- 公司内部统一分发一套 MCP 配置,需要先批量校验再下发给同事
- 给团队写配置模板,希望检查时顺带确认所有人机器上的 npx 路径都一致
- 把检查结果接进内部工单系统,作为配置自检的一个环节
- 联系方式:邮箱/微信见站内「联系我们」页面,或在本文下方留言
- 定制说明:请附上你的数据样例(脱敏即可)和期望结果,方便快速评估工作量
- 交付形式:定制项目交付可执行程序,支持后续版本迭代与长期维护
使用说明与免责声明
- 本工具在本地运行,不联网、不上传任何数据到服务器。
- 涉及文件改写的功能,请在使用前备份原始文件。
- 软件完全免费,可自由使用与转发,请勿用于倒卖。
- 因误操作造成的数据问题请自行承担。
关于检查结果:本工具只依据配置文本的结构、字段类型与本机文件系统给出判断,不代表被检查的 MCP 服务器本身安全可信。配置里出现 API Key 之类的凭据时请自行判断要不要粘进任何窗口——本程序不联网,但截图、录屏、共享屏幕仍可能泄露。远程地址只做格式校验,不探测连通性、不验证凭据是否有效。

