小智MCP桥接器配置指南

工作原理

小智的MCP架构采用反向连接模式：

┌─────────┐     ┌─────────────────┐     ┌─────────┐
│  小智   │ ←── │  小智平台       │ ←── │   MBE   │
│  设备   │     │ api.xiaozhi.me  │     │ 桥接器  │
└─────────┘     └─────────────────┘     └─────────┘
               WebSocket长连接

关键点：不是小智连接MBE，而是MBE主动连接小智平台！

快速开始

1. 获取MCP接入点

登录小智控制台
进入 智能体 > MCP接入点
创建新接入点或选择现有接入点
复制接入点地址（格式：wss://api.xiaozhi.me/mcp/?token=xxx）

2. 配置环境变量

在 .env 文件中添加：

XIAOZHI_MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=你的token

3. 启动方式

方式A: Docker Compose（推荐）

cd mises-behavior-engine

# 启动所有服务（包含桥接器）
docker-compose -f docker-compose.tunnel.yml up -d

# 查看桥接器日志
docker logs mbe-xiaozhi-bridge -f

方式B: 本地运行

cd mises-behavior-engine

# 方式1: 使用启动脚本（交互式）
.\start_xiaozhi_bridge.ps1

# 方式2: 直接运行（需先设置环境变量）
python -m src.mcp.xiaozhi_bridge

验证连接

启动后，你应该看到以下日志：

🔌 XiaozhiBridge initialized
   Endpoint: wss://api.xiaozhi.me/mcp/?token=xxx...
   Tools count: 6
🔗 正在连接小智平台...
✅ 已连接到小智平台
📝 已注册 6 个工具到小智平台

然后在小智控制台的MCP接入点页面点击刷新，状态应变为已连接。

工具列表

桥接器会向小智注册以下MBE工具：

工具名	功能
`ask_expert`	咨询行为经济学专家
`get_expert_list`	获取可用专家列表
`analyze_decision`	分析决策和偏好
`get_economic_insight`	获取经济学洞察
`check_user_status`	查询用户注册状态
`user_feedback`	提交用户反馈

常见问题

Q: 连接失败

检查：

接入点地址是否正确
Token是否过期（在小智控制台重新生成）
网络是否可以访问 api.xiaozhi.me

Q: 工具调用失败

检查：

MBE API服务是否正常运行
数据库是否已初始化
LLM API Key是否配置正确

Q: 如何查看通信日志

# Docker方式
docker logs mbe-xiaozhi-bridge -f --tail 100

# 本地方式
# 日志会直接输出到终端

架构说明

xiaozhi_bridge.py
       │
       ├── WebSocket连接到小智平台
       │
       ├── 接收小智平台的消息
       │     ├── tools/list → 返回工具列表
       │     ├── tools/call → 调用MCPServer处理
       │     └── ping → 返回pong保持连接
       │
       └── 调用MCPServer处理工具请求
             └── 返回结果给小智平台

注意事项

保持长连接：桥接器需要持续运行，断开后会自动重连
Token安全：不要泄露MCP接入点Token
单实例运行：一个Token只能有一个桥接器连接
日志监控：建议监控桥接器日志排查问题