企业官网建设流程全解析

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 步：

1. 网络配置：用"初始化MCP服务"积木块填入 WiFi 名称、密码和小智后台的 MCP 接入地址（形如wss://xiaozhi.cn/mcp）
2. 定义工具函数：用"定义工具函数"+"获取调用参数"积木写出工具逻辑
3. 注册工具：用"添加工具"积木描述工具名称、回调函数、参数 schema，再用"添加到服务中"完成注册
4. 启动服务：最后放置"启动源师兄MCP服务"积木，进入消息监听循环

💡 下面的 10 个坑，本质都是这四步中某一步配错了。想对照实物排查，可以直接查看仓库里的完整示例工程 mcptext.ohc（含屏幕显示、RGB 灯、机顶盒控制 3 个工具）。

第一部分：MCP Server 连接失败——先排查这3个坑

坑1：WiFi SSID 或密码填错，设备根本上不了网

⚠️ "初始化MCP服务"积木块要求填写 WiFi 名称和密码，与路由器不一致时，后续所有环节都不可能通。

• 解决方法：严格按路由器实际名称填写，注意大小写和特殊字符；仍连不上时，确认路由器开启了 2.4G WiFi（多数设备只支持 2.4G），然后重新上传代码。

坑2：WSS 接入地址不对或 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。

坑6：schema 参数名与"获取调用参数"里取的名字不一致

参数描述积木里写的"参数名"，要和函数体里"获取调用参数"积木取的值完全一致。schema 里叫action、函数里却取state，取到的永远是空。

• 解决方法：全局统一命名；关键取值建议利用"获取调用参数"积木的第三个字段"数据为空则返回"填一个默认值兜底（积木定义见 blocksdef.js#L192-L219）。

坑7：required 参数或"是否允许其他参数"设置过严

必填参数 AI 没传时调用会被拒绝；而"是否允许其他参数"选了"否"后，AI 一旦自作主张多传一个参数，整个调用就会失败。

• 解决方法："必要参数"只填真正必须的值；对可能变化的参数，把"是否允许其他参数"放宽为"是"。

坑8：忘记放"工具调用成功,返回"积木

函数明明执行了，小智端却收不到任何反馈——十有八九是没返回结果。

• 解决方法：在每个函数分支的末尾都补上"工具调用成功,返回"积木，并填写用户能听懂的话（如"灯已打开"）。该积木会按 MCP 标准格式构造返回内容（见 blocksdef.js#L221-L241）。

第三部分：服务起不来、执行结果诡异——还有2个坑

坑9：忘记放"启动源师兄MCP服务"，或没放在最末尾

服务积木启动后会进入无限循环监听消息。如果漏放，工具永远不会被触发；如果它后面还跟着别的积木，后面的代码也永远执行不到。

• 解决方法：把"启动源师兄MCP服务"作为主流程的最后一个积木，定义见 blocksdef.js#L610-L626。

坑10：连续操作之间没有加延时

比如"关闭机顶盒"需要连发两条红外命令（先"确定"再"电源开关"），紧接着发第二条经常失败。

• 解决方法：两条操作之间用"等待X毫秒"积木留出间隔，示例工程中等待了 1000 毫秒（积木定义见 blocksdef.js#L244-L266）。

关键文件速查：遇到问题去哪里找答案

如果想在本地完整跑一遍示例对照排查，直接克隆仓库即可：git clone https://gitcode.com/yuanshixiong/mcp-server

写在最后

✅ 记住一句话：MCP 服务的问题，90% 出在"连接四要素"（WiFi、接入地址、注册、返回）上。按本文"先查连接、再查注册、后查执行"的顺序排查，绝大多数连接失败与工具无响应都能在 5 分钟内定位解决。

【免费下载链接】mcp-server源师兄扩展项目: mcp_server | 由源师兄组织创建项目地址: https://gitcode.com/yuanshixiong/mcp-server