# xiaozhi-mcp-mpy

**Repository Path**: anipython/xiaozhi-mcp-mpy

## Basic Information

- **Project Name**: xiaozhi-mcp-mpy
- **Description**: xiaozhi mcp micropython 代码
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-13
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xiaozhi-mcp-micropython

MicroPython 移植版本 - 小智 MCP 客户端库，运行在 ESP32 上。

原始 Arduino/C++ 项目：[toddpan/xiaozhi-esp32-mcp](https://github.com/toddpan/xiaozhi-esp32-mcp)  
小智 MCP 协议文档：[mcp-protocol.md](https://github.com/78/xiaozhi-esp32/blob/main/docs/mcp-protocol.md)

---

## 功能特性（100% 对应 Arduino 版本）

| 功能 | Arduino 版 | MicroPython 版 |
|------|-----------|---------------|
| WebSocket (ws://) 连接 | ✅ | ✅ |
| WebSocket Secure (wss://) | ✅ | ✅ |
| 自动重连机制 | ✅ | ✅ |
| JSON-RPC 2.0 协议 | ✅ | ✅ |
| `initialize` 请求处理 | ✅ | ✅ |
| `tools/list` 请求处理 | ✅ | ✅ |
| `tools/call` 工具调用 | ✅ | ✅ |
| 完整工具注册 (`registerTool`) | ✅ | ✅ |
| 简化工具注册 (`registerSimpleTool`) | ✅ | ✅ |
| 工具注销 (`unregisterTool`) | ✅ | ✅ |
| 清除所有工具 (`clearTools`) | ✅ | ✅ |
| 连接状态回调 | ✅ | ✅ |
| ToolParams 参数解析 | ✅ | ✅ |
| ToolResponse 响应封装 | ✅ | ✅ |
| 设备主动通知 (Notification) | ✅ | ✅ |
| 保活 Ping | ✅ | ✅ |
| session_id 支持 | ✅ | ✅ |
| 同步 loop() 模式 | ✅ | ✅ |
| 异步 asyncio 模式 | ❌ | ✅（额外） |

---

## 文件结构

```
xiaozhi_mcp_micropython/
├── websocket_mcp.py          # 主库文件（对应 WebSocketMCP.h / .cpp）
├── wifi_helper.py            # WiFi 连接工具
├── config.py                 # 用户配置（WiFi、MCP 地址、引脚）
├── examples/
│   ├── basic_example/
│   │   └── main.py           # 基础示例（LED 控制 + say_hello）
│   └── smart_switch_example/
│       └── main.py           # 智能开关示例（多路输出 + 物理按钮通知）
└── README.md
```

---

## 快速开始

### 1. 安装依赖

在 ESP32 的 MicroPython REPL 中执行：

```python
import mip
mip.install("uwebsockets")
```

或通过 mpremote：

```bash
mpremote mip install uwebsockets
```

### 2. 上传文件

```bash
mpremote cp websocket_mcp.py :websocket_mcp.py
mpremote cp wifi_helper.py   :wifi_helper.py
mpremote cp config.py        :config.py
mpremote cp examples/basic_example/main.py :main.py
```

### 3. 修改 config.py

```python
WIFI_SSID     = "你的WiFi名称"
WIFI_PASSWORD = "你的WiFi密码"
MCP_ENDPOINT  = "ws://你的小智服务器:端口/路径"
LED_PIN       = 2   # 板载 LED 引脚，大多数 ESP32 是 2
```

### 4. 运行

重启 ESP32，串口输出如下即为成功：

```
[WiFi] Connecting to 'MyWifi' ..........
[WiFi] Connected! IP=192.168.1.100
[MCP] Initialised. Endpoint: ws://192.168.1.1:8080/mcp
[MCP] WebSocket connected
[MCP] Server hello received, session_id=xxx
[App] MCP connected - registering tools
[MCP] Tool registered: led_control
[MCP] Tool registered: say_hello
[App] Entering main loop
```

唤醒小智，说「小智，帮我打开 ESP32 的 LED」，LED 亮起！

---

## API 参考

### `WebSocketMCP` 类

#### 初始化

```python
mcp = WebSocketMCP()
ok = mcp.begin("ws://host:port/path", on_connected_callback)
```

- `on_connected_callback(connected: bool)` 在连接/断开时被调用。

#### 主循环（同步模式）

```python
while True:
    mcp.loop()
    time.sleep_ms(10)
```

#### 异步模式

```python
import uasyncio as asyncio

async def main():
    await mcp.begin_async("ws://host:port/path", on_cb)
    asyncio.create_task(mcp.run_forever())
    # ... 其他 tasks

asyncio.run(main())
```

#### 工具注册

```python
# 完整注册
mcp.register_tool(
    name="my_tool",
    description="工具说明",
    input_schema={
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "参数说明"}
        },
        "required": ["param1"]
    },
    callback=my_callback
)

# 简化注册（单参数）
mcp.register_simple_tool(
    name="my_tool",
    description="工具说明",
    param_name="param1",
    param_desc="参数说明",
    param_type="string",   # "string" | "integer" | "boolean" | "number"
    callback=my_callback
)
```

#### 工具管理

```python
mcp.unregister_tool("tool_name")
mcp.clear_tools()
count = mcp.get_tool_count()
connected = mcp.is_connected()
mcp.disconnect()
```

#### 发送自定义消息

```python
ok = mcp.send_message('{"type":"mcp","payload":{...}}')
```

#### 发送通知

```python
mcp.send_notification(
    method="notifications/state_changed",
    params={"state": "idle"}
)
```

### `ToolParams` 类

```python
def my_tool(params_str):
    p = ToolParams(params_str)
    if not p.is_valid():
        return ToolResponse(True, "参数无效")

    s = p.get_string("key", default="")
    i = p.get_int("num", default=0)
    b = p.get_bool("flag", default=False)
    f = p.get_float("val", default=0.0)
    raw = p.get_raw("obj")          # 返回原始 Python 对象

    return ToolResponse(False, "成功")
```

### `ToolResponse` 类

```python
# 文本响应
ToolResponse(is_error=False, message="操作成功")
ToolResponse(is_error=True,  message="发生错误")

# JSON 内容响应
ToolResponse.from_json({"key": "value"}, is_error=False)
ToolResponse.from_json([{"type": "text", "text": "hello"}])
```

---

## 协议说明

本库实现了小智 MCP 协议（设备侧 MCP 服务器角色）：

```
ESP32 (MCP Server)          小智后台 (MCP Client)
        │                           │
        │── hello (features.mcp=true) ──▶│
        │                           │
        │◀── MCP: initialize ────────│
        │─── MCP: initialize 响应 ──▶│
        │                           │
        │◀── MCP: tools/list ────────│
        │─── MCP: tools/list 响应 ──▶│
        │                           │
        │◀── MCP: tools/call ────────│
        │─── MCP: tools/call 响应 ──▶│
        │                           │
        │── MCP: notifications/... ─▶│  (设备主动通知)
```

所有 MCP 消息封装格式：

```json
{
  "session_id": "xxx",
  "type": "mcp",
  "payload": {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": { "name": "led_control", "arguments": {"state": "on"} },
    "id": 3
  }
}
```

---

## 许可证

GNU General Public License v3.0 (GPLv3) - 与原始 Arduino 版本保持一致。