tactus

Tactus

与内容无关的 MCP 服务，让任何 AI Agent 都能通过简洁、安全的工具接口控制私密硬件。

Tactus 是一个轻量、中立的控制层。它封装了 Buttplug / Intiface，因此通过一次集成即可连接约 26 个品牌的 750 多种设备，并将这些设备作为模型上下文协议（MCP）工具提供给 AI Agent。它只转发硬件控制命令。它不会生成、托管或存储任何类型的内容。

• 安全至上。 默认内置并启用强度限制、独立的看门狗自动停止功能、单次调用紧急停止，以及故障安全停止语义——这是核心特性，而非事后补充。
• 一行安装。 npx -y tactus-mcp，无需克隆或构建。
• 与操作系统无关。 Tactus 不会接触蓝牙。无线通信由 Intiface 负责；我们只通过本地 WebSocket 与其通信。

⚠️ 仅限成年人使用（年满 18 岁，或达到您所在司法辖区的法定成年年龄）。仅可用于您拥有的设备，并且必须获得所有参与者的同意。

---

工作原理

  AI client / agent           Tactus (this server)            Intiface Central
  (Claude Desktop,    MCP      - MCP server          WebSocket - holds BLE/USB
   Claude Code, your  ───────▶ - Buttplug client     ────────▶   - 750+ device
   own AI product)            - SAFETY LAYER          :12345      protocols
                                                                     │ BLE/USB
                                                                     ▼
                                                                🔵 your device

所有操作都在您的计算机本地运行。Tactus 是一个 Buttplug 客户端，连接到本地运行的 Intiface Central/Engine： ws://127.0.0.1:12345。

前置条件

1. 安装 Intiface Central。
2. 打开它并点击 Start Server。
3. 配对您的设备（或在开发时，通过 Devices → Manage Simulated Devices 添加模拟设备）。

安装与配置

Tactus 通过 npx 使用标准输入/输出运行。将其添加到您的 MCP 客户端配置中。

Claude Desktop / Claude Code（claude_desktop_config.json）：

{
  "mcpServers": {
    "tactus": {
      "command": "npx",
      "args": ["-y", "tactus-mcp"],
      "env": { "MAX_INTENSITY": "1.0" }
    }
  }
}

相同的 command/args 适用于任何可启动标准输入/输出服务的 MCP 客户端（Cursor、Cline、Continue 等）。

工具

工具	用途
list_devices	列出已连接的设备及其执行器
scan_for_devices	扫描并返回新发现的设备
get_battery	读取电池电量（0.0–1.0）
vibrate	设置振动强度（0.0–1.0）
oscillate	设置振荡强度（0.0–1.0）
rotate	设置旋转速度和方向
linear	在指定时长内将推杆移动到某个位置
vibrate_pattern	播放可中断的定时振动模式
stop_device	停止一台设备
stop_all	紧急停止——立即停止所有设备
server_status	报告与 Intiface 的连接状态

所有强度值均标准化为 0.0–1.0。每个工具都会返回结构化数据和易读文本。

安全性

安全层会包装每条驱动命令，并默认启用：

• 强度限制——请求会限制在 MAX_INTENSITY 范围内；系统会返回实际生效的值，对于超出范围的输入则会给出明确错误，而不是静默强制转换。
• 看门狗自动停止——除非通过新命令刷新，否则任何持续驱动都会在 MAX_CONTINUOUS_MS（默认 10 分钟）后自动停止。这是一个独立计时器，并非等到下次调用时才检查。
• 断开连接/退出时停止——如果 AI 客户端断开连接或进程收到信号，所有设备都会停止。对于强制终止，看门狗则是最后一道保障。
• 可中断模式——模式按时间调度，因此单次调用不会阻塞服务；任何停止命令都会立即中断模式。
• 速率限制——合并每台设备的突发命令，以保护 BLE。
• 故障安全停止——如果无法确认停止，Tactus 会重试，而不会乐观地报告成功。

配置

变量	默认值	含义
INTIFACE_URL	ws://127.0.0.1:12345	Intiface WebSocket 地址
MAX_INTENSITY	1.0	驱动强度上限（0.0–1.0）
MAX_CONTINUOUS_MS	600000	看门狗自动停止时间窗口
SCAN_DEFAULT_MS	5000	默认扫描时长
--allow-unsafe	off	禁用强度上限（不建议）

故障排除

“无法在 ws://127.0.0.1:12345 连接到 Intiface” 启动 Intiface Central 并点击 Start Server（顶部状态应显示 “Engine running”）。Tactus 会自动进行退避重试，因此 Intiface 启动后，工具便会开始工作，无需重启 MCP 客户端。

扫描时未发现设备

• 确认设备已开机且处于唤醒状态（按下按钮唤醒），并且未连接到自己的手机应用——蓝牙设备一次只能连接一个主机，因此请先关闭或断开该应用。
• 在 macOS 上，Intiface 需要蓝牙权限：系统设置 → 隐私与安全性 → 蓝牙 → 启用 Intiface Central，然后退出并重新打开 Intiface（权限只有在重启后才会生效）。
• 让设备保持在有效范围内；超出范围的设备会断开连接，并从 list_devices 中消失。

我的电脑能通过蓝牙识别设备，但 Intiface/Tactus 无法识别 设备播报的蓝牙名称不在 Buttplug 支持的设备列表中（某些地区版本或重新贴牌的 SKU 常见此情况）。必须在 Buttplug 上游添加支持——Tactus 刻意不添加针对单个设备的代码，也不会对设备进行逆向工程。

命令返回“Unknown device id” 设备已断开连接（例如超出范围），因此不在已知设备集合中。调用 scan_for_devices / list_devices 重新连接并获取设备当前 ID。

已知限制

• 设备覆盖范围取决于 Buttplug 的支持范围。 Buttplug 设备配置中未列出的设备，在上游添加前无法控制。
• 不会主动检测连接的无声降级。 Intiface 能报告的连接断开会得到处理（设备会从 list_devices 中移除，驱动调用也会明确报错）。但如果蓝牙连接无声降级，而 Intiface 未能察觉，命令可能看似成功，但设备实际上没有响应——目前尚未实现主动检测设备是否在线。
• 仅限本地。 此软件包通过本地 Intiface 控制同一台机器上的设备。不支持通过互联网或远程控制。

为未识别的设备添加支持

使用受支持品牌的设备，却发现设备未显示？通常只是因为设备播报的蓝牙名称（或地区 SKU）尚未被 Buttplug 收录。由于 Tactus 封装了 Buttplug，修复应当在 Buttplug 上游完成，而不是在此处——对于同一品牌的设备，通常只需添加一个名称，无需逆向工程。

1. 查找设备播报的蓝牙名称（参见上方的故障排除）。
2. 在 Intiface 的用户设备配置中，将该名称添加到同一品牌现有的协议中，并测试能否正常驱动设备。
3. 如果有效，请将该名称贡献到上游 buttplugio/buttplug，让所有人都能受益——和/或在此处提交 “Unsupported device” 问题，我们会提供帮助。

如果设备只有在使用其实际并不匹配的协议时才能工作，或者需要 Buttplug 尚不支持的协议，就必须进行逆向工程，这超出了项目范围（参见 CONTRIBUTING）。

---

商标

“Lovense”“We-Vibe”“Satisfyer”“Kiiroo”“Lelo”“The Handy”“Magic Motion”“Svakom”及其他设备名称均为其各自所有者的商标。Tactus 是一个独立项目，与任何设备制造商均无关联，也未获其认可、赞助或与其合作。此处仅基于其使用开源 Buttplug 协议库这一事实，将其描述为兼容这些设备。项目未使用任何制造商标志。

内容生成——不在范围内

本服务仅转发硬件控制命令。它不会生成、合成、推荐或制作任何文本、图像、音频或视频内容。调用它的 AI Agent 是唯一负责生成内容的一方，并对其生成的任何内容以及遵守其司法管辖区内的内容义务承担全部责任。

可接受的使用方式

Tactus 是一个中立且与内容无关的硬件控制层。它不支持、记录或协助以下行为：在你不拥有或未获同意操作的设备上使用；由未成年人使用；或任何违反你所在司法管辖区适用法律的行为。这些声明描述的是维护者提供支持和文档的范围，并非对许可证的额外限制；许可证仍适用于所有使用、修改和再分发行为。用户应自行负责评估其使用方式是否符合适用法律。

Tactus 仅使用 Buttplug 上游已支持的设备协议。它不会对不受支持的设备进行逆向工程，也不会破解任何设备的加密或访问控制。它不会收集或传输任何个人数据或使用数据。

免责声明

本软件用于控制你连接的硬件。仅可在你拥有的设备上使用，且须征得所有相关人员的同意。仅限成年人使用（年满 18 周岁，或达到你所在司法管辖区规定的成年年龄）。

本软件按“原样”提供，不附带任何形式的保证（请参阅许可证）。上述声明仅供参考；它们不会修改许可证、增加保证或注意义务，也不会转移责任。许可证中的无保证和责任限制条款仍完全适用。

许可证

Apache-2.0。