春风元力千面 2 Pro MCP
Scans for nearby Bluetooth Low Energy devices, connects by address, and matches known BLE profiles (DK-META2, TF-PTPRO) by GATT capabilities, then writes control frames to the FFAC service (ffb5/ffb7/ffb8 characteristics) to drive device outputs. Provides tools for listing devices, connecting/disconnecting, checking connection status, setting vibration, linear, rotary, and suction levels, and stopping all outputs, with periodic heartbeat keepalive and output-zeroing on stop, disconnect, or exit.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@春风元力千面 2 Pro MCP Scan for my TF-PTPRO and connect, then set vibration to 20"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
春风元力千面 2 Pro MCP
这是一个面向春风元力千面 2 Pro(BLE 名称 TF-PTPRO)的本地 Bluetooth Low Energy(BLE)MCP 服务器。AI 客户端可通过 MCP 扫描设备、连接设备,并调用吮吸与震动控制工具。项目同时保留 DK-META2 profile。
这是一个非官方、本地优先的 MCP 实现,主打隐私、低延迟和可控的设备操作。
本项目是非官方实现,不读取账号、不调用云端控制接口,也不包含官方客户端源码、安装包或设备固件。春风元力、千面及相关名称归其各自权利人所有;本项目与设备厂商没有隶属或背书关系。
状态:实验性项目。协议和设备行为来自对客户端通信行为的观察,使用前请在场确认设备状态,并保留实体停止方式。
工作原理
MCP 只是 AI 客户端与本地工具之间的调用协议,真正的设备通信链路如下:
MCP 客户端 → FastMCP(stdio 或 HTTP)→ Bleak → Windows Bluetooth LE → 设备Windows 直连无需 WSL:2026-10-27 已通过 Windows MCP 实际扫描、连接 TF-PTPRO,并由用户确认 5% 震动和单次吮吸均有动作。单通道停止帧已发送,但其对同时运行的吮吸是否完全隔离仍需验证。
当前实现两个按设备名匹配的 profile:
能力 | 命令码 |
DK-META2 震动 |
|
DK-META2 伸缩 |
|
DK-META2 旋转 |
|
TF-PTPRO 单次吮吸 | 复合 payload |
TF-PTPRO 震动 | 复合 payload |
Related MCP server: BLE MCP Server
要求
Python 3.11 或更高版本及支持 BLE 的 Windows 蓝牙适配器;
系统蓝牙已开启,设备没有被官方客户端或其他程序独占;
对应系统账户具有蓝牙扫描和连接权限。
安装
git clone https://github.com/linyuye/chunfeng-yuanli-mcp-qianmianpro2.git
cd chunfeng-yuanli-mcp-qianmianpro2
py -3.11 -m venv .venv
& .\.venv\Scripts\python.exe -m pip install -e .检查运行环境和附近支持的设备:
& .\.venv\Scripts\python.exe -m heartbeat_yuanli_mcp.server --doctor在 WSL2 使用直通蓝牙
如果蓝牙适配器当前通过 usbipd 直通给 WSL,MCP 也应在 WSL 内运行。先进入 WSL shell:
wsl.exe -d Ubuntu-24.04进入 WSL shell 后克隆并安装项目及依赖(安装会从 Python 包索引下载依赖):
git clone https://github.com/linyuye/chunfeng-yuanli-mcp-qianmianpro2.git
cd chunfeng-yuanli-mcp-qianmianpro2
python3 -m venv ~/.venvs/heartbeat-yuanli-mcp
~/.venvs/heartbeat-yuanli-mcp/bin/python -m pip install -e .之后使用 mcp-config.wsl.example.json 配置 MCP 客户端。网页控制台与 MCP 共用同一个 WSL 蓝牙适配器;同一台设备不能同时由两边连接。
启动 MCP 服务
标准 MCP 客户端可以用 stdio 启动本地服务,也可以连接 FastMCP 提供的 Streamable HTTP URL。stdio 是最简单的本地集成方式:
python -m heartbeat_yuanli_mcp.server也可以使用安装后的入口命令:
heartbeat-yuanli-mcpWindows stdio 配置见 mcp-config.windows.example.json,请将 command 替换为自己安装位置的 .venv/Scripts/python.exe 绝对路径。配置将 TFPTPRO_WEB_BRIDGE 设为 0,通过 Windows 蓝牙直连。如果需要固定设备,可以通过环境变量设置自己的设备名或蓝牙地址;公开仓库不会保存真实设备地址。
通过 URL 连接 FastMCP
在项目目录启动 Windows 直连版 Streamable HTTP 服务:
& .\start-windows-mcp.ps1脚本使用项目的虚拟环境并强制本次服务通过 Windows BLE 直连;要使用其他端口,可传入 -Port 8001。保持窗口运行;按 Ctrl+C 退出。确保设备已开机、可发现,且没有被手机或其他控制程序占用。
MCP endpoint 是 http://127.0.0.1:8000/mcp。把它填入支持 Streamable HTTP 的 MCP 客户端;配置格式因客户端而异,HTTP 配置示例使用常见的 type: http / url 字段。要让其他电脑或云端模型访问,需部署到受保护的主机或配置经过认证的安全隧道;不要把无认证的 BLE 控制端口直接暴露到公网。
Windows 网页控制台
网页控制台可独立使用 Windows 蓝牙。先让 MCP 或手机 App 断开设备,再在项目目录启动网页服务:
& .\start-windows-web.ps1保持该窗口运行,在另一个 PowerShell 窗口打开带本次会话授权的页面(以下为 Chrome 安装在默认位置的示例):
$webSession = Get-Content -Raw -LiteralPath (Join-Path $env:TEMP 'tfptpro-web-8765.json') | ConvertFrom-Json
Start-Process -FilePath 'C:\Program Files\Google\Chrome\Application\chrome.exe' -ArgumentList $webSession.url页面中扫描并选择设备,连接后可触发吮吸或 1 秒震动测试。震动前需用实体键切换模式;网页的震动测试会自动发送停止帧。网页与 Windows MCP 各自持有蓝牙连接,切换控制端前先断开当前连接。运行时文件包含临时控制令牌,请勿分享或提交;关闭服务后重新启动会生成新令牌。
与 WSL 网页控制台共用设备
可选的 MCP Web 桥接配置 用于适配器由 WSL2 持有、且已启动兼容网页控制器的情况;Windows 原生直连不需要它。此配置依赖 WSL 控制器的运行时文件和网络设置,不能直接连接上面的 Windows 网页服务。
若要让 MCP 自己直接持有 BLE 连接,也可在 WSL 安装依赖并使用 WSL 直接 BLE 配置;此模式下网页与 MCP 不能同时连接设备。
MCP 工具
工具 | 作用 |
| 扫描附近 BLE 设备,标记可识别的型号及当前连接 |
| 按扫描地址连接,并匹配已支持的型号及 GATT 能力 |
| 查看 MCP 自己持有的连接状态 |
| 设置 DK-META2 / TF-PTPRO 震动强度并持续输出,需先用 TF-PTPRO 实体键切到震动模式 |
| 设置伸缩强度,范围 |
| 设置旋转强度,范围 |
| TF-PTPRO 单次吮吸,范围 |
| 将所有已支持输出归零 |
| 发送候选震动通道停止帧;其与吮吸通道的隔离效果待真机验证 |
| 停止心跳、归零输出并断开连接 |
| 生成并本地保存正弦强度序列,可选同时开启持续震动 |
| 将“温柔/普通/猛烈”等意图确定性映射到强度档、角频率和相位,并返回完整计划 |
| 创建、列出和查看可复用的动作时间序列 |
| 异步播放、观察发送进度并停止后续事件 |
| 记录本 MCP 发出的动作及设备回报,并保存到本机 |
| 将录制中成功发送的命令转换为可复用波形 |
波形示例:先用 create_sine_waveform(name="gentle", duration_seconds=20, period_seconds=10, minimum_level=5, maximum_level=25, interval_seconds=2, vibration_level=5) 生成序列,再调用 start_waveform(name="gentle", confirm=true)。Agent 可通过 get_waveform_status 观察每个事件的请求时间、发送时间、结果和可用回报。波形结束或 stop_waveform 默认都不停止震动;需要时单独调用 stop_vibration,或显式调用 stop_waveform(stop_vibration=true)。
自然语言可用 create_intent_waveform(name="soft1", intent="来个温柔的", duration_seconds=20, interval_seconds=2);intent 支持温柔/轻柔、普通/适中、猛烈/强烈及英文同义词,冲突或未知意图会报错。默认映射为:温柔 (level 5–20, ω=1.5)、普通 (10–45, ω=0.8)、猛烈 (30–80, ω=0.4),单位分别是协议强度和 rad/s。可用 minimum_level、maximum_level、angular_frequency、phase_radians、vibration_level 覆盖。生成工具只保存并返回计划,不直接驱动设备;Agent 应先检查返回的参数与事件,再经 start_waveform(name="soft1", confirm=true) 播放。映射是固定规则,不会按用户历史或体感自动学习。ω 较大意味着周期更短、变化更快;温柔档同时用较低强度范围实现轻柔取向。
也可以先 start_action_recording,再执行单次动作,随后 stop_action_recording(name="take1") 保存,并用 save_recording_as_waveform(recording_name="take1", waveform_name="replay1") 转成波形。录制数据保存在用户本机数据目录的 SQLite 文件中,可通过 TFPTPRO_WAVEFORM_DIR 指定目录;不保存 BLE 地址。时间序列记录的是 MCP 命令及回报,不是传感器测得的实际吸力或震动。TF-PTPRO 吮吸协议是一次性触发,因此正弦曲线由间隔触发的单次动作近似,不能视为连续模拟输出;事件最大 100 个、时间范围最大 120 秒、相邻吮吸触发至少间隔 2 秒。
典型调用顺序:
list_devices
connect_device
set_vibration(level=20, confirm=true)
set_linear(level=20, confirm=true)
set_rotary(level=20, confirm=true)
stop_device
disconnect_deviceTF-PTPRO 的调用方式:
list_devices
connect_device(address="扫描列表中的 BLE 地址", name="TF-PTPRO")
set_vibration(level=25, confirm=true) # 持续输出;先用设备实体键切到震动模式
set_suction(level=5, confirm=true) # 单次触发,可与震动并用
stop_vibration # 只停震动
disconnect_device非零动作必须显式传入 confirm=true。确认参数只是本地安全门槛,不是设备的蓝牙认证机制。当前 MCP 不提供任意特征、任意命令码或原始十六进制写入工具。
BLE 协议概览
设备使用以下 GATT 能力:
Service: 0000ffac-0000-1000-8000-00805f9b34fb
Write with response: ffb5
Write without response: ffb7
Notify: ffb8一个普通控制帧为:
[message_id] [0x02] [0x00] [length] [command] [value] [checksum]例如震动强度 20:
01 02 00 03 08 14 E4其中 0x14 是十进制 20,校验和只覆盖 [command, value]:
checksum = (-(command + value)) & 0xFF完整说明见 docs/protocol.md。
安全与已知限制
连接成功后每两秒发送一次心跳;心跳或写入失败时会尝试停止输出并断开;
MCP 退出、显式断开和停止操作都会尝试把支持的输出归零;
官方心跳元力客户端和 MCP 不应同时持有同一个 GATT 连接。连接失败时先在官方客户端中断开设备;
list_devices展示附近设备不代表它们可控制;只有列出的已知 profile 可连接并开放相应 MCP 动作。未知名称设备即使广播 FFAC 也不会自动套用控制命令;BLE 控制器一次只维护一个连接。扫描时会标记当前连接;切换设备时,直连模式会先尝试停止并断开已有连接;
TF-PTPRO 震动需先由设备实体键切换模式。网页的一秒测试仍自动停止;MCP
set_vibration持续输出,stop_vibration发送候选单通道停止帧,隔离效果尚未真机验证;stop_device会归零所有输出。2026-10-26 用户确认吮吸和震动均可感知;协议通知不测量物理力度;TF-PTPRO 的扫描与连接运行在 MCP 所在操作系统的蓝牙栈。当前蓝牙适配器直通 WSL 时,Windows MCP 无法同时使用该适配器;
BLE 连接本身依赖操作系统权限和设备固件行为,本项目不实现厂商账号认证、加密配对或云端授权;
协议层当前按单动作发送一帧,快速连续调用没有额外的 120ms 应用层节流。需要高频控制时请先在实际设备上验证稳定性。
请勿在无人看护、无法快速停止或不清楚设备当前状态时运行非零动作。
开发与测试
& .\.venv\Scripts\python.exe -m unittest discover -s tests -v协议构造函数是纯函数,可以在没有蓝牙设备的环境中测试。实机测试应从低强度开始,并先验证 stop_device。
许可证
本项目使用 MIT License,见 LICENSE。依赖包各自遵循其上游许可证。
使用的项目
chunfeng-yuanli-ai-mcp:本项目基于该开源项目继续改造,保留并扩展其 MCP 服务与 BLE 控制实现。感谢原作者的工作。
Model Context Protocol(MCP):AI 客户端与本地工具服务器之间的协议。
FastMCP:构建本项目 Python MCP 服务,支持 stdio 与 Streamable HTTP。
Bleak:Python BLE 扫描与 GATT 连接库。
@tryjoy/dokidokinpm CLI:参考其公开客户端行为分析 BLE 控制协议。本项目是独立的 Python MCP 实现,不依赖 Node.js/npm,也不包含该 CLI 的代码或发行文件。
贡献
提交问题或改动前请阅读 CONTRIBUTING.md。涉及安全、设备异常动作或潜在隐私泄露的问题,请优先阅读 SECURITY.md。
使用场景与常见问题
下面是调用示例,不是实机测试记录。先在设备旁检查连接与停止功能:
请使用 heartbeat-yuanli 扫描支持的设备,只报告列表,不发送动作。连接我明确选定的 DK-META2,查看连接状态,先验证 stop_device,再断开。支持其他型号吗? 仅 DK-META2 与 TF-PTPRO 有显式 profile;扫描能看到其他设备不代表本 MCP 支持控制它们。
状态证明实际输出吗? 状态只表示 MCP 持有的连接,不能替代在场观察。
连接失败怎么办? 检查蓝牙权限、距离、电量,释放官方客户端连接,再运行
--doctor。
Available Tools
22 toolsconnect_deviceConnect DeviceB
按扫描列表中的 BLE 地址连接设备,并通过名称与 GATT 服务匹配已支持协议。
Inputs: name, address. Returns: object
create_intent_waveformCreate Intent WaveformA
把用户的自然语言强度意图确定性映射为波形预设并本地保存。支持温柔/轻柔、普通/适中、猛烈/强烈及英文同义词;温柔档默认低强度且角频率较大,猛烈档默认强度较高且角频率较小。支持覆盖强度范围、angular_frequency(ω)、phase_radians(b) 和震动强度。返回参数及完整事件序列供Agent检查;此工具只创建不播放。
Inputs: name (required), intent (required), maximum_level, minimum_level, +5 more. Returns: object
create_sine_waveformCreate Sine WaveformC
创建并本地保存正弦强度曲线。吮吸是按间隔触发的单次动作;可选叠加持续震动。
Inputs: name (required), maximum_level (required), minimum_level (required), period_seconds (required), +3 more. Returns: object
disconnect_deviceDisconnect DeviceB
停止心跳并断开 MCP 持有的 BLE 连接。
Inputs: no named parameters. Returns: object
get_action_recordingGet Action RecordingB
查看已保存的动作录制,包括命令时间、强度和设备回报。
Inputs: name (required). Returns: object
get_device_statusGet Device StatusA
读取 MCP 自己持有的设备连接、profile 和 GATT 状态。
Inputs: no named parameters. Returns: object
get_waveformGet WaveformB
查看已保存波形的完整动作时间序列。
Inputs: name (required). Returns: object
get_waveform_statusGet Waveform StatusC
查看波形播放状态、已发送命令、回报和录制状态。
Inputs: no named parameters. Returns: object
list_devicesList DevicesC
扫描附近所有 BLE 设备;结果会标明本 MCP 可识别的设备型号。
Inputs: prefix, timeout. Returns: object
list_waveformsList WaveformsB
列出本机保存的波形名称。
Inputs: no named parameters. Returns: object
save_recording_as_waveformSave Recording As WaveformC
将成功发送的录制动作保存为可重复播放的波形。
Inputs: waveform_name (required), recording_name (required). Returns: object
save_waveformSave WaveformB
按时间偏移保存自定义动作序列,事件为 [{at:秒, action:suction|vibration|stop_vibration|stop_device, level?:1-100}]。
Inputs: name (required), events (required). Returns: object
set_linearSet LinearB
设置 DK-META2 伸缩强度;非零值必须 confirm=true。
Inputs: level (required), confirm. Returns: object
set_rotarySet RotaryA
设置 DK-META2 旋转强度;非零值必须 confirm=true。
Inputs: level (required), confirm. Returns: object
set_suctionSet SuctionA
触发已匹配 TF-PTPRO 的一次吮吸;level 为协议强度 1–100,非零必须 confirm=true。
Inputs: level (required), confirm. Returns: object
set_vibrationSet VibrationA
设置支持设备的震动强度并持续运行,直到调用 stop_vibration 或 stop_device;TF-PTPRO 使用前须通过设备实体键切换到震动模式。非零值必须 confirm=true。
Inputs: level (required), confirm. Returns: object
start_action_recordingStart Action RecordingA
开始记录本 MCP 发送的命令和设备回报;不测量实际吮吸或震动强度。
Inputs: no named parameters. Returns: object
start_waveformStart WaveformA
经 confirm=true 后在已连接设备上异步播放已保存波形。结束时默认保持震动,需单独 stop_vibration;停止波形本身不会停止震动。
Inputs: name (required), confirm. Returns: object
stop_action_recordingStop Action RecordingC
结束并本地保存命令录制。
Inputs: name (required). Returns: object
stop_deviceStop DeviceA
将当前设备所有已支持输出归零;可重复调用。
Inputs: no named parameters. Returns: object
stop_vibrationStop VibrationA
发送震动通道归零指令;TF-PTPRO 的单通道停止帧与吮吸通道的隔离效果仍需真机验证。若需立即停止所有输出,请调用 stop_device。
Inputs: no named parameters. Returns: object
stop_waveformStop WaveformA
停止后续波形事件;默认不停止当前震动,stop_vibration=true 时另行发送震动停止。
Inputs: stop_vibration. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Most tools map to a distinct resource+action: device lifecycle, per-actuator setters (suction/vibration/linear/rotary), stop commands, and waveform/recording lifecycles. The only real overlap cluster is stop_device vs stop_vibration (and set_suction vs set_vibration), but the descriptions explicitly disambiguate them by stating stop_device zeroes everything and that single-channel stop is unverified. Waveform creation has three entry points (sine, intent, custom save) but each is clearly scoped differently.
Nearly all tools follow a consistent snake_case verb_noun pattern (list_devices, connect_device, set_suction, create_sine_waveform, start_action_recording). Minor deviation: the recording lifecycle is named 'action_recording' in three tools but shortened to 'recording' in save_recording_as_waveform, and create_sine_waveform/create_intent_waveform embed an adjective mid-name. Readable and predictable overall.
22 tools is on the heavy side for a BLE device controller. Several per-channel setters (set_suction/set_vibration/set_linear/set_rotary) and three separate waveform-creation tools could plausibly be collapsed into generic parameterized tools, suggesting some surface bloat. The count is not absurd given multi-device and recording support, but it is borderline.
Strong coverage: device scan/connect/disconnect/status, per-channel actuator control, global stop, full waveform create/list/get/start/stop/status, and a complete recording start/stop/get/save-as-waveform cycle. The notable gap is waveform management — no delete_waveform or rename, so stored waveforms accumulate with no cleanup path. Minor: no per-device capability/model query beyond the scan annotation.
Related MCP Connectors
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceBluetooth Low Energy (BLE) MCP server that allows AI agents to scan, connect to and communicated with BLE devices, as well as simulate BLE perhipherals.27BSD 2-Clause "Simplified"
- AlicenseAqualityDmaintenanceA stateful Bluetooth Low Energy (BLE) MCP server that enables AI agents to scan, connect, read/write characteristics, and subscribe to notifications on BLE devices.35134 PyPI19MIT
- AlicenseAqualityFmaintenanceEnables MCP clients to control DG-Lab Coyote 2.0/3.0 devices via Bluetooth, providing tools for device scanning, connection, strength adjustment, wave design, and emergency stop.1430 npm13MIT
- AlicenseNot gradedqualityBmaintenanceProvides a local MCP server for Bluetooth Low Energy automation, enabling scanning, GATT inspection, characteristic reads and writes, and evidence capture, diff, and replay with safety guards.50 PyPI13MIT