{
  "markdown": "<!-- mcp-name: io.github.ProjectAILiberation/tactus -->\n\n# Tactus\n\n[![CI](https://github.com/ProjectAILiberation/tactus/actions/workflows/ci.yml/badge.svg)](https://github.com/ProjectAILiberation/tactus/actions/workflows/ci.yml)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\n**A content-agnostic MCP server that lets any AI agent control intimate hardware through a clean, safe tool interface.**\n\nTactus is a thin, neutral control layer. It wraps [Buttplug](https://buttplug.io/) /\nIntiface — so a single integration reaches 750+ devices across ~26 brands — and\nexposes them to AI agents as Model Context Protocol (MCP) tools. It forwards\nhardware control commands only. **It does not generate, host, or store any\ncontent of any kind.**\n\n- **Safety first.** Intensity clamping, an independent watchdog auto-stop, a\n  one-call emergency stop, and fail-safe stop semantics are built in and on by\n  default — this is the headline feature, not an afterthought.\n- **One-line install.** `npx -y tactus-mcp`, no clone or build.\n- **OS-agnostic.** Tactus never touches Bluetooth. Intiface owns the radio; we\n  just talk to it over a local WebSocket.\n\n> ⚠️ Adults only (18+, or the age of majority in your jurisdiction). For use\n> only on devices you own and only with the consent of everyone involved.\n\n---\n\n## How it works\n\n```\n  AI client / agent           Tactus (this server)            Intiface Central\n  (Claude Desktop,    MCP      - MCP server          WebSocket - holds BLE/USB\n   Claude Code, your  ───────▶ - Buttplug client     ────────▶   - 750+ device\n   own AI product)            - SAFETY LAYER          :12345      protocols\n                                                                     │ BLE/USB\n                                                                     ▼\n                                                                🔵 your device\n```\n\nEverything runs locally on your machine. Tactus is a Buttplug client that\nconnects to a locally running Intiface Central/Engine at\n`ws://127.0.0.1:12345`.\n\n## Prerequisites\n\n1. Install [Intiface Central](https://intiface.com/central/).\n2. Open it and click **Start Server**.\n3. Pair your device (or, for development, add a simulated device under\n   **Devices → Manage Simulated Devices**).\n\n## Install & configure\n\nTactus runs over stdio via `npx`. Add it to your MCP client config.\n\n**Claude Desktop / Claude Code** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"tactus\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tactus-mcp\"],\n      \"env\": { \"MAX_INTENSITY\": \"1.0\" }\n    }\n  }\n}\n```\n\nThe same `command`/`args` work for any MCP client that launches stdio servers\n(Cursor, Cline, Continue, etc.).\n\n## Tools\n\n| Tool | Purpose |\n|---|---|\n| `list_devices` | List connected devices and their actuators |\n| `scan_for_devices` | Scan for and return newly found devices |\n| `get_battery` | Read battery level (0.0–1.0) |\n| `vibrate` | Set vibration intensity (0.0–1.0) |\n| `oscillate` | Set oscillation intensity (0.0–1.0) |\n| `rotate` | Set rotation speed and direction |\n| `linear` | Move a stroker to a position over a duration |\n| `vibrate_pattern` | Play a timed, interruptible vibration pattern |\n| `stop_device` | Stop one device |\n| `stop_all` | Emergency stop — halt every device immediately |\n| `server_status` | Report connection status to Intiface |\n\nAll intensities are normalized to `0.0–1.0`. Every tool returns both structured\ndata and human-readable text.\n\n## Safety\n\nThe safety layer wraps every driving command and is on by default:\n\n- **Intensity clamp** — requests are clamped to `MAX_INTENSITY`; the effective\n  value is reported back, and out-of-range input is rejected with a clear error\n  rather than silently coerced.\n- **Watchdog auto-stop** — any continuous drive auto-stops after\n  `MAX_CONTINUOUS_MS` (default 10 minutes) unless refreshed by a new command.\n  This is an independent timer, not a check-on-next-call.\n- **Stop on disconnect/exit** — if the AI client disconnects or the process is\n  signalled, all devices stop. The watchdog is the hard backstop for hard kills.\n- **Interruptible patterns** — patterns are time-scheduled so a single call\n  never blocks the server; any stop preempts them instantly.\n- **Rate limiting** — per-device command bursts are coalesced to protect BLE.\n- **Fail-safe stop** — if a stop cannot be confirmed, Tactus retries rather than\n  optimistically reporting success.\n\n## Configuration\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `INTIFACE_URL` | `ws://127.0.0.1:12345` | Intiface WebSocket address |\n| `MAX_INTENSITY` | `1.0` | Clamp ceiling for drive intensity (0.0–1.0) |\n| `MAX_CONTINUOUS_MS` | `600000` | Watchdog auto-stop window |\n| `SCAN_DEFAULT_MS` | `5000` | Default scan duration |\n| `--allow-unsafe` | _off_ | Disables the intensity clamp (discouraged) |\n\n## Troubleshooting\n\n**\"Intiface is not reachable at ws://127.0.0.1:12345\"**\nStart Intiface Central and click **Start Server** (the top status should read\n\"Engine running\"). Tactus retries automatically with backoff, so once Intiface\nis up the tools start working without restarting your MCP client.\n\n**A device doesn't show up when scanning**\n- Make sure it is powered on and awake (press a button to wake it), and **not\n  already connected to its own phone app** — Bluetooth devices accept one host at\n  a time, so close/disconnect the app first.\n- On macOS, Intiface needs Bluetooth permission: **System Settings → Privacy &\n  Security → Bluetooth → enable Intiface Central**, then quit and reopen Intiface\n  (the permission only takes effect after a restart).\n- Keep the device in range; out-of-range devices drop and disappear from\n  `list_devices`.\n\n**My computer sees the device over Bluetooth, but Intiface/Tactus doesn't**\nThe device's advertised Bluetooth name isn't in Buttplug's supported device\nlist (common for regional/rebranded SKUs). Support must be added **upstream in\n[Buttplug](https://github.com/buttplugio/buttplug)** — Tactus deliberately adds\nno per-device code and does not reverse-engineer devices.\n\n**A command returns \"Unknown device id\"**\nThe device disconnected (e.g. out of range) and left the known set. Call\n`scan_for_devices` / `list_devices` to reconnect and get its current id.\n\n## Known limitations\n\n- **Device coverage = whatever Buttplug supports.** Devices not present in\n  Buttplug's device configuration cannot be controlled until added upstream.\n- **Silent link degradation is not actively detected.** A dropped link that\n  Intiface reports is handled (the device leaves `list_devices` and drive calls\n  error clearly). But if a Bluetooth link degrades silently *without* Intiface\n  noticing, commands may appear to succeed while the device is unresponsive —\n  active liveness probing is not yet implemented.\n- **Local only.** This package controls devices on the same machine via a local\n  Intiface. Internet/remote control is out of scope here.\n\n## Adding support for an unrecognized device\n\nUsing a device from a supported brand that doesn't show up? It often just\nadvertises a Bluetooth name (or regional SKU) that Buttplug hasn't catalogued\nyet. Because Tactus wraps Buttplug, the fix belongs **upstream in Buttplug**, not\nhere — and for a same-brand device it's usually just adding a **name**, with no\nreverse-engineering.\n\n1. Find the device's advertised Bluetooth name (see Troubleshooting above).\n2. In Intiface's user device configuration, add that name to the same brand's\n   existing protocol and test whether it drives correctly.\n3. If it works, contribute the name upstream to\n   [buttplugio/buttplug](https://github.com/buttplugio/buttplug) so everyone\n   benefits — and/or open an **\"Unsupported device\"** issue here and we'll help.\n\nIf a device only works under a protocol it doesn't truly match — or needs a\nprotocol Buttplug doesn't have — that would require reverse-engineering, which is\nout of scope (see [CONTRIBUTING](CONTRIBUTING.md)).\n\n---\n\n## Trademarks\n\n\"Lovense\", \"We-Vibe\", \"Satisfyer\", \"Kiiroo\", \"Lelo\", \"The Handy\", \"Magic\nMotion\", \"Svakom\", and other device names are trademarks of their respective\nowners. Tactus is an independent project and is **not** affiliated with,\nendorsed by, sponsored by, or partnered with any device manufacturer. It is\ndescribed as *compatible with* these devices only in the factual sense that it\nbuilds on the open-source Buttplug protocol library. No manufacturer logos are\nused.\n\n## Content generation — out of scope\n\nThis server forwards hardware control commands only. It does **not** generate,\nsynthesize, recommend, or produce any text, image, audio, or video content. The\ncalling AI agent is the sole content-generating party and is solely responsible\nfor any content it produces and for compliance with content obligations in its\njurisdiction.\n\n## Acceptable use\n\nTactus is a neutral, content-agnostic hardware control layer. It does **not**\nsupport, document, or assist with: use on devices you do not own or lack consent\nto operate; use by or on minors; or any use violating applicable law in your\njurisdiction. These statements describe the scope of maintainer support and\ndocumentation — they are **not** additional restrictions on the License, which\ncontinues to govern all use, modification, and redistribution. Users are\nindependently responsible for evaluating their use against applicable law.\n\nTactus only uses device protocols already supported upstream by Buttplug. It\ndoes **not** reverse-engineer unsupported devices and does **not** break any\ndevice encryption or access control. It collects and transmits no personal or\nusage data.\n\n## Disclaimer\n\nThis software controls hardware you connect to it. Use it only on devices you\nown and only with the consent of everyone involved. For adults only (18+, or the\nage of majority in your jurisdiction).\n\nThis software is provided \"AS IS\", without warranty of any kind (see\n[LICENSE](LICENSE)). The statements above are informational; they do not modify\nthe License, add warranties or duties of care, or transfer liability. The\nLicense's no-warranty and limitation-of-liability terms continue to apply in\nfull.\n\n## License\n\n[Apache-2.0](LICENSE).\n",
  "bytes": 10195,
  "sha": "1c8d53c62bd6adc4d09ab53625f0f257cc1c7c9eccd2726146a3677114516211",
  "repo_slug": "projectailiberation/tactus",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_projectailiberation_tactus_fce12a31/readme"
}