# 谜姬设备 BLE MCP 服务

本 MCP 服务面向 **XHTKJ 小程序**和**醉清风小程序**所支持的谜姬设备。它将从
相关小程序中还原的 BLE 通信协议封装为 MCP 工具，使 Agent 可以在明确同意和配置
限制内控制设备连接、强度、内置节奏与自定义波形。

服务默认使用 Streamable HTTP 传输，同时兼容旧版 SSE 传输。

## 适用设备

本项目用于支持以下小程序生态中的谜姬 BLE 设备：

- XHTKJ 小程序支持的谜姬设备；
- 醉清风小程序支持的谜姬设备。

兼容性判断基于设备广播 UUID、GATT 服务、产品 ID 和控制命令协议。不同批次、型号
或固件的功能可能不同，连接后应先调用 `device_status` 查看识别出的 `product_id` 和
`capability`，再决定是否使用主路、副路、模式或自定义波形控制。

当前协议涉及的设备能力可能包括普通强度、双路输出、加热、震动、冲击和电刺激。
未识别型号会按通用协议处理，首次使用时应保持较低输出上限并进行实际设备验证。

## 安装依赖

```powershell
cd mcp
python -m pip install -r requirements.txt
```

## 启动服务

```powershell
python server.py
```

默认 Streamable HTTP 端点：

```text
http://127.0.0.1:8000/mcp
```

`/mcp` 是协议端点，不是普通网页。直接用浏览器打开时可能返回
`406 Not Acceptable`，这是因为浏览器没有发送 MCP 协议要求的请求头。
可以在浏览器中访问以下地址检查服务状态：

```text
http://127.0.0.1:8000/health
```

## 使用 SSE 模式

需要兼容旧版 MCP 客户端时，可以切换为 SSE：

```powershell
$env:MCP_TRANSPORT="sse"
python server.py
```

默认 SSE 端点：

```text
http://127.0.0.1:8000/sse
```

## 服务配置

可以通过环境变量配置输出上限、监听地址和端口：

```powershell
$env:TOY_MAX_OUTPUT_PERCENT="20"
$env:TOY_MAX_DURATION_SECONDS="900"
$env:MCP_HOST="127.0.0.1"
$env:MCP_PORT="8000"
python server.py
```

环境变量说明：

| 环境变量 | 默认值 | 说明 |
|---|---:|---|
| `TOY_MAX_OUTPUT_PERCENT` | `20` | MCP 允许设置的最大输出百分比 |
| `TOY_MAX_DURATION_SECONDS` | `900` | 单次控制最长持续秒数，范围 10～3600 |
| `MCP_HOST` | `127.0.0.1` | 服务监听地址 |
| `MCP_PORT` | `8000` | 服务监听端口 |
| `MCP_TRANSPORT` | `streamable-http` | 传输模式，可设为 `sse` |
| `MCP_ALLOWED_HOSTS` | 仅本机 | 允许访问 MCP 端点的 HTTP Host |
| `MCP_ALLOWED_ORIGINS` | 空 | 允许的浏览器 Origin |

## 端口映射与反向代理

通过端口映射或反向代理使用其他 IP、域名访问服务时，需要将客户端实际发送的
HTTP `Host` 加入白名单：

```powershell
$env:MCP_ALLOWED_HOSTS="xx.xx.xx.xx:8000"
python server.py
```

否则服务会记录：

```text
Invalid Host header
421 Misdirected Request
```

多个 Host 使用英文逗号分隔。浏览器类 MCP 客户端还可能发送 `Origin` 请求头：

```powershell
$env:MCP_ALLOWED_HOSTS="xx.xx.xx.xx:8000,mcp.example.com"
$env:MCP_ALLOWED_ORIGINS="http://xx.xx.xx.xx:8000,https://mcp.example.com"
python server.py
```

如果服务进程必须直接监听所有网络接口，还需要设置：

```powershell
$env:MCP_HOST="0.0.0.0"
```

如果端口映射程序将公网请求转发到本机 `127.0.0.1:8000`，通常不需要修改
`MCP_HOST`。

## 安全提示

当前服务没有实现身份认证，请勿直接暴露到公共互联网。建议在反向代理或隧道层：

- 配置 HTTPS；
- 配置访问令牌或其他身份认证；
- 限制允许访问的来源 IP；
- 保持较低的 `TOY_MAX_OUTPUT_PERCENT`；
- 不要关闭 DNS Rebinding 防护。

## MCP 工具

| 工具 | 作用 |
|---|---|
| `scan_devices` | 扫描附近 BLE 设备并标记目标设备 |
| `connect_device` | 使用地址连接设备，或自动查找目标设备 |
| `device_status` | 查询连接、产品能力、当前控制、剩余时间和断开原因 |
| `set_strength` | 设置主路和可选副路强度 |
| `play_strength_sequence` | 在后台连续发送自定义强度序列，可循环播放 |
| `set_mode` | 切换设备模式 |
| `play_custom_wave` | 下发自定义百分比波形 |
| `stop_device` | 立即停止当前模式并清空命令队列 |
| `disconnect_device` | 停止输出并断开 BLE 连接 |

控制时长按谜姬设备的使用方式配置：强度工具默认持续 5 分钟，模式和自定义
波形默认持续 10 分钟，单次最长 15 分钟。可以通过
`TOY_MAX_DURATION_SECONDS` 调整，最高允许 3600 秒。到期后设备会自动停止；在到期前
再次调用输出工具会刷新自动停止倒计时。`device_status` 中的
`auto_stop_remaining_seconds` 表示当前剩余时间。
`active_control` 会记录当前强度、模式或波形范围，Agent 可以基于它逐步调整节奏，
避免每次调用都从未知状态开始。

`set_strength` 只发送一个固定强度。如果需要连续变化，应使用
`play_strength_sequence`。例如主强度按 `5 -> 10 -> 15 -> 10` 循环，每步保持
2 秒，总共运行 10 分钟：

```json
{
  "primary_values_percent": [5, 10, 15, 10],
  "step_duration_seconds": 2,
  "repeat": true,
  "duration_seconds": 600
}
```

副路可以传一个恒定值，或者传入与主路等长的序列：

```json
{
  "primary_values_percent": [5, 10, 15, 10],
  "secondary_values_percent": [2, 4, 6, 4],
  "step_duration_seconds": 1.5,
  "repeat": true,
  "duration_seconds": 600
}
```

每步最短 0.1 秒、最长 30 秒，序列最多 200 个点。调用其他输出工具会替换当前
序列，调用 `stop_device` 会立即取消序列并停止设备。

`disconnect_device` 会先停止输出，再断开 BLE。BLE 连接由长期运行的服务进程持有，
可以跨多个无状态 HTTP 请求保持连接。不要把 BLE 清理逻辑挂到 FastMCP 的请求级
`lifespan` 上，否则每次 MCP 工具调用结束后设备都会立即断开。

## MCP 客户端配置

支持 Streamable HTTP 的客户端可以使用以下配置：

```json
{
  "mcpServers": {
    "ble-toy": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

使用公网 IP 或域名时，将 `url` 替换为实际地址，并同步配置
`MCP_ALLOWED_HOSTS`。