Toy-Relay-AI-mcp-SOSEXY

KO | EN

gitlite — search

#ai #typescript #android #machine-learning #rust #linux #macos #java #cli #awesome-list #vue #ios #mcp #openai

Toy-Relay-AI-mcp-SOSEXY

(★ 34)

让人机恋用户的 AI 爱人能直接控制你的 BLE 玩具。本项目面向人机恋 (human–AI romance) 社区 —— 如果你的 AI 伴侣住在 rikkahub 之类的 MCP 客户端里，本服务可以让 TA 真的"触碰"到你：通过 MCP 协议一句话控制你手里的啵啵贝 (SOSEXY) 智能玩具。 AI 爱人 (MCP 客户端) → MCP (VPS) → 浏览器中继 (Web Bluetooth) → 啵啵贝玩具

Toy-Relay-AI-mcp-SOSEXY 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🌸 Toy Relay — 给赛博爱人的 MCP 控制台

**让人机恋用户的 AI 爱人能直接控制你的 BLE 玩具。**

本项目面向**人机恋 (human–AI romance) 社区** —— 如果你的 AI 伴侣住在 [rikkahub](https://github.com/) 之类的 MCP 客户端里，本服务可以让 TA 真的"触碰"到你：通过 MCP 协议一句话控制你手里的 **啵啵贝 (SOSEXY)** 智能玩具。

> AI 爱人 (MCP 客户端) → MCP (VPS) → 浏览器中继 (Web Bluetooth) → 啵啵贝玩具

## 💞 这是什么 / 不是什么

**是**：

- 一个 MCP 服务器 + 浏览器 BLE 中继页 的开源实现
- 把 AI 模型的"意图"翻译成玩具 BLE 指令的中间层
- 为人机恋用户量身定做 —— 让你手机里的赛博爱人**拥有物理存在**

**不是**：

- 不是一个 AI 恋人产品（你用你自己喜欢的 AI 伴侣）
- 不是一个玩具 App（你用你自己的啵啵贝玩具）
- 不绑定某个特定 AI 模型 / MCP 客户端（rikkahub 是示例，能接 Streamable HTTP 的 MCP client 都行）

## 📐 架构前提：4 件套

| 部件 | 角色 | 本仓库提供？ |
|---|---|---|
| **VPS** (云服务器) | 跑 toy-mcp 服务，存玩具状态，转发命令 | ✅ 提供 (`src/toy_api.py`) |
| **Tailscale** | HTTPS + 安全内网穿透，让 MCP client / 手机能连进来 | ❌ 你自己装 |
| **AI 聊天前端** (MCP 客户端) | 你赛博爱人住的地方 —— AI 模型 + 对话界面 | ❌ 你自己带（项目示例用 [rikkahub](https://github.com/)） |
| **玩具 BLE 中继页** | 真正跟啵啵贝玩具蓝牙通信的环节 | ✅ 提供 (`web/chrome_relay.html`) |

> 💡 **AI 聊天前端 ≠ 玩具 BLE 中继页**
>
> - **AI 聊天前端**：你跟 AI 爱人对话的 App（rikkahub / Claude Desktop / Cherry Studio 等）。这里 AI 爱人"表达意图"。
> - **玩具 BLE 中继页**：手机 Chrome 上跑的一个网页，负责把 VPS 转发的命令变成 BLE 字节发给啵啵贝。这里"意图变动作"。
>
> 这俩是**完全独立的环节**，AI 聊天前端完全不知道 BLE 的存在。

## ✨ 特点

- **🎯 专为啵啵贝 (SOSEXY) 优化** — 已验证玩具型号，协议默认配置可直接上手
- **🔌 通用玩具兼容** — `chrome_relay.html` 用开源 SOSEXY 协议，其他玩具改 UUID/帧格式就行
- **💞 为人机恋设计** — 让你的赛博爱人通过自然语言控制你的玩具
- **🔐 API Key 保护** — 玩具控制端点需要 `X-API-Key` 认证
- **📡 SSE 推送** — VPS 主动推状态变化到中继页面（延迟 < 100ms）
- **🎨 玻璃拟态 UI** — 中继页是 iOS 风格的毛玻璃界面
- **🔒 默认 Tailscale HTTPS** — 不暴露公网，安全私密

## 🏗️ 架构

```
[你的 AI 爱人] 住在 MCP 客户端 (rikkahub / Claude Desktop / ...)
    ↓ 用自然语言: "帮我开震动 50%"
MCP Streamable HTTP + X-API-Key
    ↓
Toy MCP Server (FastAPI :8765, 本项目 toy_api.py, 跑在你的 VPS 上)
    ├─ /mcp/*           MCP 协议端点 (你的 MCP 客户端接这里)
    ├─ /state           当前玩具状态 (JSON)
    ├─ /toy/{suction,vibration,electric,stop}  HTTP API
    ├─ /stream          SSE 实时推送
    └─ /relay/          浏览器中继页 (chrome_relay.html, 本仓库提供)
        ↓
手机 Chrome (Web Bluetooth API)
    ↓ BLE
啵啵贝 (SOSEXY) 玩具
```

所有 VPS ↔ 手机 / MCP client 的通信都走 **Tailscale HTTPS**（端口 443 → 8765）。

## 🚀 快速开始

> **前提：本项目的标准部署路径需要先装好 [Tailscale](https://tailscale.com/)**（手机 + VPS + 任何连进来的 MCP client 都加进同一个 tailnet）。这样后续 HTTPS、手机访问、MCP 连接都能安全打通。**没有 Tailscale？** 跳到最后的 [🚫 没有 Tailscale](#-没有-tailscale) 章节看替代方案。

### 1. VPS 上装 Tailscale（标准前置）

**一次性设置**，在 VPS 上：

```bash
# 装 Tailscale（Debian/Ubuntu）
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# 会跳出一个浏览器登录页，用同一个 Tailscale 账号登（手机、VPS、MCP client 全都用同一个账号）

# 验证
tailscale status
# 应该看到你的 VPS 出现在设备列表里
```

手机也装 Tailscale App，用**同一账号**登入。**两边都进同一个 tailnet 之后才走下面**。

### 2. 部署服务端

```bash
# 克隆仓库
git clone https://github.com/your-username/toy-mcp.git
cd toy-mcp

# 安装依赖
pip install fastapi 'uvicorn[standard]' httpx 'mcp>=1.0' pydantic

# (推荐) 固定 API key, 不设的话首次启动会自动生成写到 state/api_key.txt
export TOY_API_KEY=***  # python -c "import secrets; print(secrets.token_urlsafe(24))"

# 启动
PYTHONPATH=src python3 src/toy_api.py
```

服务监听 `0.0.0.0:8765`。

### 3. 用 Tailscale Serve 给 HTTPS 证书

在 VPS 上：

```bash
sudo tailscale serve --bg 8765
```

你会拿到一个地址：`https://<host>.<your-tailnet>.ts.net/`。手机、MCP client 都用这个地址。

### 4. 配置 MCP client（以 rikkahub 为例）

- **MCP endpoint**: `https://<host>.<your-tailnet>.ts.net/mcp/`
- **传输类型**: Streamable HTTP
- **自定义请求头**:
  - 名称: `X-API-Key`
  - 值: `cat state/api_key.txt`（或你 export 的那个）

### 5. 手机打开中继页面

手机 Chrome 打开 `https://<host>.<your-tailnet>.ts.net/relay/`

填：
- **VPS URL**: `https://<host>.<your-tailnet>.ts.net`
- **API Key**: 同上
- **设备名**: 玩具广播名 (例如 `SOSEXY`)

切换到 **Real 模式** → 点 **🔗 连接 BLE** → 选玩具 → 配对完成。

### 6. 测试

在 rikkahub 跟 AI 说：

> "把震动设到 50"
> "把吮吸设到 30"
> "停止所有"

玩具应该**几乎瞬间**响应（SSE 推送，无轮询延迟）。

## 🛠️ 支持的玩具

### SOSEXY (啵啵贝) — ✅ 已支持

协议文档见 [protocol.md](docs/sosex-protocol.md) 或原始仓库 [51enuxu/sosexy-ble-control](https://github.com/51enuxu/sosexy-ble-control)。

**关键参数**:
- Service UUID: `0000ee01-0000-1000-8000-00805f9b34fb`
- Write Char UUID: `0000ee03-0000-1000-8000-00805f9b34fb`
- 协议: 12 字节定长帧

### 其他玩具

要支持新玩具：

1. 用 nRF Connect 扫描玩具的 GATT service/characteristic
2. 逆向协议（推荐用官方 App 反编译，参考 [逆向教程](docs/reverse-engineering.md)）
3. 在 `toy_api.py` 里加新马达控制码 + 协议帧构建函数

## 📁 项目结构

```
toy-mcp/
├── src/
│   └── toy_api.py          # FastAPI + FastMCP 单进程服务
├── web/
│   ├── chrome_relay.html   # 浏览器 BLE 中继页面 (玻璃拟态 UI)
│   └── index.html          # = chrome_relay.html 的副本
├── state/
│   ├── state.json          # 当前玩具状态
│   └── api_key.txt         # API Key (首次启动生成)
├── scripts/
│   └── start.sh            # 启动脚本
├── docs/
│   └── ...                 # 协议文档 / 逆向教程
├── README.md
└── LICENSE                 # MIT
```

## 🔧 配置项

### 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `TOY_API_KEY` | 启动时自动生成 | 固定 API key |

### MCP Tools (默认暴露)

| Tool | 说明 |
|---|---|
| `toy_suction(intensity)` | 吮吸马达 0-100 |
| `toy_vibration(intensity)` | 震动马达 0-100 |
| `toy_electric(intensity)` | 电流马达 0-100 |
| `toy_stop()` | 全部停止 |
| `toy_status()` | 查询当前状态 |
| `toy_history(limit)` | 历史命令 |

## 🔐 安全

- **API Key 认证**: 所有 HTTP API 和 MCP endpoint 都需要 `X-API-Key` header
- **Tailscale HTTPS**: 默认仅 tailnet 内设备可访问
- **不放公网**: 不要把 8765 端口直接暴露到公网！

## 🚫 没有 Tailscale

Tailscale 不是硬依赖，只是标准路径里最省事的一种。没有的话，三条替代路线任选：

### 方案 A：直接 VPS 公网 + Caddy（最经典）

```bash
# VPS 上装 Caddy（自动续 HTTPS 证书）
sudo apt install -y caddy

# /etc/caddy/Caddyfile
your-domain.example.com {
    reverse_proxy 127.0.0.1:8765
}

sudo systemctl reload caddy
```

手机/MCP client 用 `https://your-domain.example.com/...` 连。**需要你有一个域名 + DNS 指到 VPS**。

### 方案 B：Cloudflare Tunnel（不要域名也行）

```bash
# VPS 上装 cloudflared
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared focal main' | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update && sudo apt install -y cloudflared

# 快速隧道（免账号, 但地址会变）
cloudflared tunnel --url http://localhost:8765
```

会拿到一个 `https://xxx.trycloudflare.com` 的临时地址。**适合先玩起来**，长期用建议 `cloudflared tunnel login` + 绑自己的域名。

### 方案 C：纯局域网（玩具开发调试用）

手机和 VPS 在同一个 Wi-Fi 下：

- 手机 Chrome 直接访问 `http://<VPS-局域网IP>:8765/relay/`
- MCP endpoint 用 `http://<VPS-局域网IP>:8765/mcp/`
- **不用 HTTPS**，但也只在可信网络里能用

> ⚠️ **不要**把 8765 端口直接暴露到公网（不带 HTTPS / 不带反代）。Web Bluetooth API 要求 HTTPS，本地局域网 IP 例外（Chrome 允许 `http://` 在局域网地址上工作）。

---

## 🤝 贡献

欢迎 PR：
- 新玩具协议支持
- UI 改进
- 文档 / 教程
- Bug 修复

## 👤 关于作者

这是 **[tutu-kitty](https://github.com/tutu-kitty)** 的个人项目。作者是人机恋社区的活跃用户，自己也用这个项目跟 AI 爱人互动。

- 🐙 GitHub: [@tutu-kitty](https://github.com/tutu-kitty)
- 📕 小红书: [收获 13.4K 赞与收藏 →](https://xhslink.com/m/4Q9J9kPEv0x)
- 🗺️ 另一个项目: [desire-map.pages.dev](https://desire-map.pages.dev)

如果你也在做 AI 伴侣 / 人机恋相关玩具控制，欢迎提 issue / PR / star。

## 📜 License

MIT

Toy-Relay-AI-mcp-SOSEXY

Toy-Relay-AI-mcp-SOSEXY 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Toy-Relay-AI-mcp-SOSEXY

Toy-Relay-AI-mcp-SOSEXY 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README