# BLE Toy MCP Starter

一套面向普通用户与 AI 编程助手的开源教程和安全代码骨架：从本人持有的 iPhone BLE
玩具出发，用官方 App 产生样本、在 Mac 上分析与短时回放，再封装成 MCP，并通过
OpenAI Secure MCP Tunnel 连接到 ChatGPT。

它不内置任何厂商协议，不使用品牌 Logo，也不自动扫描或控制附近设备。每个研究者都
必须从自己的合法设备与自己的抓包重新确认广播名、GATT 字段、最低档测试帧和停止帧。

## 架构

```text
iPhone 官方 App ──产生单变量样本──> PacketLogger / Mac
                                         ↓ 独立分析
iPhone / ChatGPT <──Secure MCP Tunnel── Mac stdio MCP ──BLE──> 自有设备
```

iPhone 不直接运行 Python MCP。最终控制由 Mac 负责蓝牙；iPhone/ChatGPT 通过官方
隧道间接调用。LightBlue 适合枚举 GATT 和低风险手动回放，PacketLogger 才负责观察
官方 App 实际写入。

## 阅读顺序

1. [把本仓库交给你的 AI](AI_HANDOFF.md)
2. [Mac + iPhone + BLE 玩具到 MCP 全教程](docs/通用BLE到MCP.md)
3. [本地 MCP 连接到 OpenAI 官方产品](docs/OpenAI连接.md)
4. [安全边界](SECURITY.md)

本仓库不会列出或链接任何设备专属研究，也不会把某一品牌的帧当作通用标准。

## 安装与 dry-run

```bash
python3 --version  # 必须是 3.10 或更新版本
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
BLE_DRY_RUN=1 .venv/bin/ble-toy-mcp
```

macOS 自带的 `python3` 可能仍是 3.9；版本不足时，先用 Python.org、Homebrew 或你信任
的 Python 管理器安装 3.10+。

## 真实设备登记

先设置自己观察到的广播名，再由设备所有者在电脑前选择单台设备：

```bash
export BLE_DEVICE_NAME='<NAME_OBSERVED_ON_YOUR_DEVICE>'
.venv/bin/ble-toy-enroll
```

登记命令只显示本机 CoreBluetooth identifier，不自动保存。把它与本人独立抓到的
`BLE_WRITE_UUID`、`BLE_TEST_FRAME`、`BLE_STOP_FRAMES` 放入本地私密环境，绝不能
提交到 GitHub。格式见 [.env.example](.env.example)。

MCP 默认只暴露：

- `ble_status`：查找用户登记的那台设备，不改变状态。
- `ble_short_test`：运行本地配置的最低档测试帧，硬上限 5 秒，随后重复停止。
- `ble_stop`：重复发送所有本地配置的停止帧。

没有批量控制、按名称自动选择第一台设备或无限时长动作。

## 公开资料

- [Apple Bluetooth 开发者页面（PacketLogger）](https://developer.apple.com/bluetooth/)
- [MCP 官方 Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [OpenAI Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
- [ChatGPT developer mode 与 MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta)

## License

[MIT License](LICENSE)