mcp-server常见问题与解决方案清单连接失败到工具无响应的10个坑一次讲透【免费下载链接】mcp-server源师兄扩展项目: mcp_server | 由源师兄组织创建项目地址: https://gitcode.com/yuanshixiong/mcp-server源师兄 mcp-server 是一个用可视化积木块定义 MCP 工具、并接入小智后台的扩展项目。如果你使用中遇到 MCP server 连接失败、MCP 工具无响应等常见问题本文按连接→注册→执行→返回的完整链路把 10 个高频坑位一次讲透每个坑都给出直接的解决方法。30秒看懂 MCP 工具的运行链路连接→注册→执行→返回排查问题前先建立整体认知。项目在 OHCode 可视化编程环境中提供了一整套MCP-TOOL 积木库一个能正常工作的 MCP 服务必须走完 4 步网络配置用初始化MCP服务积木块填入 WiFi 名称、密码和小智后台的 MCP 接入地址形如wss://xiaozhi.cn/mcp定义工具函数用定义工具函数获取调用参数积木写出工具逻辑注册工具用添加工具积木描述工具名称、回调函数、参数 schema再用添加到服务中完成注册启动服务最后放置启动源师兄MCP服务积木进入消息监听循环 下面的 10 个坑本质都是这四步中某一步配错了。想对照实物排查可以直接查看仓库里的完整示例工程 mcptext.ohc含屏幕显示、RGB 灯、机顶盒控制 3 个工具。第一部分MCP Server 连接失败——先排查这3个坑坑1WiFi SSID 或密码填错设备根本上不了网⚠️ 初始化MCP服务积木块要求填写 WiFi 名称和密码与路由器不一致时后续所有环节都不可能通。解决方法严格按路由器实际名称填写注意大小写和特殊字符仍连不上时确认路由器开启了 2.4G WiFi多数设备只支持 2.4G然后重新上传代码。坑2WSS 接入地址不对或 token 已过期接入地址是小智后台的 MCP 服务地址示例工程中用的是带 token 的长地址wss://api.xiaozhi.me/mcp/?token...。解决方法检查地址是否以wss://开头、有无多余空格token 有有效期过期后需到小智后台重新获取并整串替换。坑3初始化MCP服务没有放在主流程里有人把初始化积木放进了工具函数内部导致工具被调用时才去建连接——连接都还没建立自然失败。解决方法把初始化MCP服务放在主流程启动服务之前积木定义见 blocksdef.js#L270-L299摆放方式可参考 mcptext.ohc 主流程。第二部分MCP 工具调用后无响应——按顺序排查这5个坑坑4只写了工具函数忘记注册工具⚠️ 最经典的坑。写了定义工具函数并不等于工具可用必须再用添加工具描述它并用添加到服务中积木完成注册。解决方法为每个工具函数检查是否都有对应的注册积木它生成的就是add_tool注册调用见 blocksdef.js#L587-L608。坑5回调函数名和实际函数名不一致添加工具里的工具函数字段必须与工具函数名称一字不差。差一个字母就找不到函数。解决方法逐字符核对两边名称建议统一用英文小写下划线风格如control_rgb_func。坑6schema 参数名与获取调用参数里取的名字不一致参数描述积木里写的参数名要和函数体里获取调用参数积木取的值完全一致。schema 里叫action、函数里却取state取到的永远是空。解决方法全局统一命名关键取值建议利用获取调用参数积木的第三个字段数据为空则返回填一个默认值兜底积木定义见 blocksdef.js#L192-L219。坑7required 参数或是否允许其他参数设置过严必填参数 AI 没传时调用会被拒绝而是否允许其他参数选了否后AI 一旦自作主张多传一个参数整个调用就会失败。解决方法必要参数只填真正必须的值对可能变化的参数把是否允许其他参数放宽为是。坑8忘记放工具调用成功,返回积木函数明明执行了小智端却收不到任何反馈——十有八九是没返回结果。解决方法在每个函数分支的末尾都补上工具调用成功,返回积木并填写用户能听懂的话如灯已打开。该积木会按 MCP 标准格式构造返回内容见 blocksdef.js#L221-L241。第三部分服务起不来、执行结果诡异——还有2个坑坑9忘记放启动源师兄MCP服务或没放在最末尾服务积木启动后会进入无限循环监听消息。如果漏放工具永远不会被触发如果它后面还跟着别的积木后面的代码也永远执行不到。解决方法把启动源师兄MCP服务作为主流程的最后一个积木定义见 blocksdef.js#L610-L626。坑10连续操作之间没有加延时比如关闭机顶盒需要连发两条红外命令先确定再电源开关紧接着发第二条经常失败。解决方法两条操作之间用等待X毫秒积木留出间隔示例工程中等待了 1000 毫秒积木定义见 blocksdef.js#L244-L266。关键文件速查遇到问题去哪里找答案文件作用config.json项目配置声明这是一个 MCP 工具MCP_TOOL项目category.jsonMCP-TOOL 积木库所有可用积木及默认值blocksdef.js积木定义与 Python 代码生成规则mcptext.ohc完整可运行示例屏幕显示、RGB灯、机顶盒控制 3 个工具如果想在本地完整跑一遍示例对照排查直接克隆仓库即可git clone https://gitcode.com/yuanshixiong/mcp-server写在最后✅ 记住一句话MCP 服务的问题90% 出在连接四要素WiFi、接入地址、注册、返回上。按本文先查连接、再查注册、后查执行的顺序排查绝大多数连接失败与工具无响应都能在 5 分钟内定位解决。【免费下载链接】mcp-server源师兄扩展项目: mcp_server | 由源师兄组织创建项目地址: https://gitcode.com/yuanshixiong/mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考