LINK：把 Intiface 设备接给手机里的角色和 Grok

一个人用的远程控制链路：手机里的角色（或 Grok）调一个 MCP 工具，你电脑上的 Intiface 设备就动。 MCP 放在服务器上，电脑只留一个很薄的中继；手机只填一串地址。

这份文档按"照着做就能复现"写。每一步都有命令和验证方法；踩过的坑单独成章； 最后有一段可以直接贴给 AI 助手（比如 Claude Code）让它代你施工的指令。

目录

1. 它是什么、为什么这样搭

2. 你需要准备什么

3. 十个工具

4. 搭建步骤（照着做）

5. 手机和 Grok 怎么填

6. 验证清单

7. 日常使用

8. 掌机面板怎么看

9. 文件和配置项

10. 安全须知

11. 常见问题和踩过的坑

12. 一套可复用的做事流程

13. 给 AI 助手的施工指令

Related MCP server: lovense-mcp

1. 它是什么、为什么这样搭

手机里的角色 / Grok
   │  一串地址（钥匙写在地址里，或者地址 + 钥匙两个框）
   ▼
服务器上的 MCP（linkmcp.py，十个工具）        ← 一直开着，开机自启
   │  WebSocket（电脑主动连出来，电脑不用开任何入站端口）
   ▼
电脑上的中继（linkrelay.py，只搬运）
   ▼
本机桥（bridge.py，Buttplug ⇄ MCP，限幅、自动归零）
   ▼
Intiface Central ──蓝牙──▶ 设备

另外：本机掌机面板（mediator.py + web/）= 一块有屏幕的小机器，
      看得见谁在什么时候让设备动了；只给你自己看，不说话、不思考。

几条设计原则（也是后面所有决定的依据）：

适用：Windows 电脑（启动脚本是 PowerShell）、一台能装 Python 的 Linux 服务器（可选有域名）。 桥、中继、中介本身是纯 Python，别的系统也能跑，只是一键启动脚本要自己改。

2. 你需要准备什么

3. 十个工具

服务器端（linkmcp.py）和本机桥（bridge.py）的工具名、参数、说明完全一致。

• val 一律 0-100，0 是归零；sec 到点自动归零，不写就一直保持。

• val 可以写小数或字符串（"40"），桥会容错；MAX_STRENGTH 能给上限加一道保险。

• 想改工具：两边一起改（bridge.py 和 linkmcp.py），否则列出来的和真能执行的不一致。

4. 搭建步骤（照着做）

4.0 先决定：有没有域名

• 有域名（推荐）：走 Caddy 反代，得到 https://你的域名/link/…

• 没域名：服务直接监听 0.0.0.0:端口，得到 http://服务器IP:端口/…（要在云控制台放行端口）

4.1 拿到代码，装依赖（电脑）

git clone <你的仓库地址> link-toy-bridge
cd link-toy-bridge
python -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt

装好后把 .venv\Scripts\python.exe 的完整路径记下来，等下写进 .env 的 LINK_PY。 （不写也行，启动脚本会去 PATH 里找 python.exe，但那个多半没装依赖。建议写。）

4.2 生成密钥

python tools/gen_secrets.py

它会打印三类密钥：电脑用的 BRIDGE_TOKEN、电脑和服务器共用的 RELAY_TOKEN（电脑那边叫 LINK_RELAY_TOKEN）、服务器用的 LINK_TOKEN。 RELAY_TOKEN 和 LINK_TOKEN 必须不一样，程序会拒绝启动。别把它们发到聊天里、别提交到 git。

4.3 服务器部署

① 写服务器的环境文件（权限要收紧）：

sudo tee /etc/link-mcp.env >/dev/null <<'EOF'
LINK_TOKEN=（gen_secrets 的 LINK_TOKEN）
RELAY_TOKEN=（gen_secrets 的 RELAY_TOKEN）
LINK_HOST=127.0.0.1      # 前面有 Caddy 时；没有反代、直接对外就写 0.0.0.0
LINK_PORT=8802           # 直接对外的话常用 8801，记得云防火墙放行
EOF
sudo chmod 640 /etc/link-mcp.env

⚠️ 不要用 Windows PowerShell 的管道（"..." | ssh ...）去写这个文件：它会在文件开头加一个看不见的 BOM，第一个变量名被污染，服务会报"必须设置 LINK_TOKEN"。用 printf/tee 在服务器上写，或用 Git Bash。

② 传文件并安装（在电脑上，仓库根目录）：

scp linkmcp.py requirements-server.txt deploy/link-mcp.service 你@服务器:/tmp/
ssh 你@服务器 'bash -s' < deploy/deploy-server.sh

脚本会：建一个专用低权限用户 linkmcp、装 venv 和依赖、装 systemd 服务并开机自启。成功时最后会打印 active 和 {"ok":true,"pc_online":false,...}。

③a 有域名：加一段反代（先备份！）：

sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.bak-$(date +%Y%m%d%H%M)
# 把 deploy/Caddyfile.snippet 的内容加进你站点块里，然后：
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl https://你的域名/link/health        # 应该看到 {"ok":true,"pc_online":false,...}

③b 没域名：直连端口

把 /etc/link-mcp.env 里改成 LINK_HOST=0.0.0.0、LINK_PORT=8801，重启服务；然后在云控制台防火墙加入站规则：TCP 8801，来源全部 IPv4。 验证（在另一台机器上，别用你电脑——代理软件可能吃掉连接）：curl http://服务器IP:8801/health。

4.4 电脑端配置

copy .env.example .env      # 然后编辑 .env

必改的几项：

BRIDGE_HOST=127.0.0.1
BRIDGE_TOKEN=（gen_secrets 的 BRIDGE_TOKEN）
LINK_SERVERS=wss://你的域名/link              # 没域名：ws://服务器IP:8801 ；多台逗号隔开
LINK_RELAY_TOKEN=（和服务器 RELAY_TOKEN 同一串）
LINK_PY=C:\...\link-toy-bridge\.venv\Scripts\python.exe

4.5 启动

1. 打开 Intiface Central，点 Start Server；到 Devices 页点 Start Scanning，把设备开机，等它出现。（这一步别人替不了，蓝牙和设备都在它手里）

2. 双击仓库里的 Start LINK.bat。后台静默起：桥 → 中介 → 中继 → 保活，然后弹出掌机窗口。

3. 掌机顶上四盏灯（桥 / Intiface / 玩具 / 服务器）都亮、写着「一切就绪 ✓」就好了。

5. 手机和 Grok 怎么填

钥匙就是服务器的 LINK_TOKEN。 两种写法服务器都认：

• 小手机「经站里转发」选关。

• 钥匙错或没带 → 返回 404（不是 401），当作这个地址不存在。

6. 验证清单

按顺序，哪一条不对就停在那一条查。

# ① 服务器活着（pc_online 在电脑没开时是 false，正常）
curl https://你的域名/link/health

# ② 钥匙对，能列出 10 个工具（Bearer 写法）
curl -s -X POST https://你的域名/link/mcp \
  -H "Authorization: Bearer <LINK_TOKEN>" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# ③ 钥匙错应该是 404
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://你的域名/link/mcp \
  -H "Authorization: Bearer wrong" -H "Content-Type: application/json" -d '{}'

电脑 Start LINK.bat 之后：

• 再 curl .../link/health → "pc_online":true

• 调 link_status → 返回 JSON（upstream_connected 应为 true）

• Intiface 里扫到设备后调 channel_list → 能看到设备

• 调 output_a（val=10，sec=2）→ 设备轻轻动 2 秒后停

• 调 output_stop → 立刻停

急停有三层，记住最快的： ① Intiface 里把滑块拖到 0；② 设备本体关机；③ 双击 Stop LINK.bat。

7. 日常使用

电脑睡眠或关机后链路会断：保活脚本会让 Windows 在空闲时不睡眠、屏幕常亮（不改你的电源设置），但合盖或手动点睡眠仍然会睡。 玩具如果自己断了蓝牙，要在 Intiface 里重新 Scan，桥和中继会自己重连。

8. 掌机面板怎么看

窗口顶上四盏灯，下面一句话告诉你哪里没通、该干嘛：

下面是四个通道的值条和事件流（红边 = 角色调的，绿边 = 你在面板上按的），再往下是手动按键：选通道、调值和秒、发送、归零、扫通道。 「更多」里有保持唤醒、刷新。有两套外观，右上角「外观」切换。

9. 文件和配置项

电脑 .env

服务器 /etc/link-mcp.env

10. 安全须知

这是一条能远程驱动你身体上设备的链路，请按最保守的来：

1. 密钥只有你知道。 LINK_TOKEN、BRIDGE_TOKEN、RELAY_TOKEN 都不要发聊天、不要截图、不要提交 git（.gitignore 已挡 .env）。怀疑泄露就重新生成、改完重启服务和电脑端。

2. 地址就是钥匙。 带钥匙的长网址等于密码，只填进你自己信任的客户端。

3. 没域名走 http 是明文，钥匙在网络上是裸的。能用 https 就用 https。

4. 留一个最快的急停（见第 6 节），并确认你随时够得着。

5. 给角色用的时候，MAX_STRENGTH 调到你能接受的上限；先从 val=10、sec=2 开始试。

6. 小手机里的「一小时内默认同意」会让角色这段时间调工具不再问你，不在场也一样；用之前想清楚。

7. 本仓库已去掉面板里原来会把带钥匙地址发给第三方二维码网站的功能。如果你自己加回来，别发密钥。

8. 服务端用专用低权限用户、NoNewPrivileges、ProtectSystem=strict 跑；不要改成 root。

11. 常见问题和踩过的坑

12. 一套可复用的做事流程

做这套东西（以及以后任何类似的"改动 → 上线"）用的是同一个节奏，值得原样照搬：

1. 先讲方案，再动手。 动代码之前先说清：要改哪些文件、运行逻辑是什么、有哪些我拿主意的点。等一句"可以"。

2. 改动尽量小，一块一块来。 别一次生成一大堆；每块改完就能单独验证。

3. 改在本机，先测。 单元测试 + 类型检查 + 端到端（能起一份临时服务就起一份，端口用 18xxx、密钥用临时的，测完关掉）。

4. 能看到的界面要亲眼看一眼。 用预览开手机宽度截图，别只看"类型检查过了"。

5. 列清单再上线。 清单写四样：会发出去什么、确认没带上什么、怎么回滚、影响谁。等明确的"可以"，不要把"我觉得你会同意"当成同意。

6. 上线前备份，上线后验证。 改配置先备份；上线后从公网测一遍，不要只看本机。

7. 留回滚。 旧版本留在旁边一份（例如 pwa.old、Caddyfile.bak-…）。

8. 写发布记录，再提交。 记录里写：改了什么、没改什么、没亲眼验证的地方、入口哈希/版本、上一版在哪。

9. 密钥永远不进聊天、不进 git。 要给用户看密钥时，写进他们本机的文件，让他们自己去拿。

10. 谁的东西谁点头。 蓝牙、设备、Intiface 的开关只有用户能点；对外发布（GitHub、服务器配置）先问。

13. 给 AI 助手的施工指令

把下面整段贴给 Claude Code（或别的能操作终端的 AI），再把你的服务器和电脑信息补进去。它会按本文第 4–6 节施工。

任务：照着仓库根目录的 README.md 搭建 LINK（第 4 节），并按第 6 节逐条验证。

背景信息（我来填）：
- 电脑：Windows，仓库已 clone 在：<路径>
- 服务器：<ssh 别名或 user@ip>，系统：<Ubuntu 版本>，有没有域名：<域名 / 没有>
- 反代：<Caddy / Nginx / 没有>；没域名时我会自己去云控制台放行端口

规矩（务必遵守）：
1. 动手前先把你要做的步骤列给我，等我说"可以"。
2. 密钥用 tools/gen_secrets.py 生成；不要把任何密钥打印到聊天里，要给我看就写进我本机的文件并告诉我路径。
3. 服务器环境文件用 printf/tee 在服务器上写，不要用 Windows PowerShell 的管道（会带 BOM）。
4. 远程命令写成脚本文件再 `ssh host 'bash -s' < 脚本`，不要在 PowerShell 里拼带引号的命令。
5. 改 Caddy/Nginx 前先备份，validate 通过再 reload；不要动我服务器上已有的其他站点和服务。
6. 验证要从公网测（第 6 节），没域名时在另一台机器上测端口。
7. Intiface Central 的 Start Server / Start Scanning 和设备开机只有我能做，轮到这一步时停下来告诉我。
8. 每做完一大步汇报一次：做了什么、验证结果、还差什么。最后给我一份"手机/Grok 要填什么"（写进本机文件，不贴密钥）。

许可与说明

• 许可：个人使用，禁止再分发（见根目录 LICENSE）。你可以自己用、自己改； 不可以把它（原版或修改版）再发给别人、传到任何地方、商用或冒用。这不是开源许可证（不是 MIT）。 GitHub 的 fork 只用于查看和提交修改建议。想做许可里禁止的事，先到 Issues 联系作者。

• 只能用在知情、同意的成年人身上，并且要保证对方随时能停下（第 10 节）。

• 依赖：Intiface Central / Buttplug、mcp Python SDK、Starlette、Uvicorn、websockets，各自有各自的许可。

• 这是个人自用工具的整理版，不提供任何担保。使用风险自负，尤其是第 10 节。