谜姬设备 BLE MCP 服务

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

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

适用设备

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

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

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

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

安装依赖

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

启动服务

python server.py

默认 Streamable HTTP 端点：

http://127.0.0.1:8000/mcp

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

http://127.0.0.1:8000/health

使用 SSE 模式

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

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

默认 SSE 端点：

http://127.0.0.1:8000/sse

服务配置

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

$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 加入白名单：

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

否则服务会记录：

Invalid Host header
421 Misdirected Request

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

$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

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

$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 分钟：

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

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

{
  "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 的客户端可以使用以下配置：

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

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