efferent-ble-simulator

BLE Simulator MCP Skill

This skill covers two distinct usage modes. Identify which applies before proceeding.

---

Mode A — Host: Deploy & Run the Service on the Local Machine

Use this mode when you are working directly on the Linux machine that has a Bluetooth adapter and need to install, build, and start the simulator service.

Prerequisites

• Linux with BlueZ (bluetoothd), a BLE-capable adapter
• BlueZ ≥ 5.87 — BlueZ 5.86 has an advertisement-registration bug (src/advertising.c uses the wrong struct size for MGMT_OP_ADD_EXT_ADV_DATA, sending 14 bytes instead of 6); on kernels with strict MGMT length validation this makes every RegisterAdvertisement fail with Failed to register advertisement. Upgrade before deploying: sudo pacman -S bluez && sudo systemctl restart bluetooth
• Node.js ≥ 18

First-time setup

Run once with sudo before starting the service:

npm install
npm run setup    # requires sudo — installs D-Bus policy, enables bluetoothd, verifies GATT
npm run build

npm run setup (scripts/setup.sh) does the following automatically:

1. Installs BlueZ if missing (apt / pacman / dnf / zypper)
2. Enables and starts bluetoothd
3. Powers on the BLE adapter
4. Writes /etc/dbus-1/system.d/ble-simulator.conf — the critical step: without this policy file, RegisterApplication() silently fails and the device cannot be connected to or read from
5. Reloads D-Bus daemon so the policy takes effect immediately
6. Runs an end-to-end GATT registration smoke test and reports pass/fail

Starting the service

stdio mode (default, for local MCP clients that launch the process directly):

npm start
# or: node dist/index.js

MCP client config:

{
  "mcpServers": {
    "ble-simulator": {
      "command": "node",
      "args": ["/path/to/ble-simulator-node/dist/index.js"]
    }
  }
}

HTTP mode (exposes the service over the network so remote agents on the LAN can connect):

npm run start:http
# equivalent: MCP_TRANSPORT=http npm start