Start a background BLE scan. Returns a scan_id immediately. The scan runs in the background for up to timeout_s seconds. Use ble.scan_get_results to check discovered devices and ble.scan_stop to end the scan early.

Non-blocking: return the devices discovered so far by a running (or finished) scan. Also returns whether the scan is still active. Call this to check progress or to decide whether to stop early.

Stop a running scan early and return the final list of discovered devices. Safe to call on an already-finished scan.

Connect to a BLE peripheral by address. Returns a connection_id, device identity (device_name, service_uuids from scan cache), and spec status (null if none attached). After connecting: 1) Use ble.spec.list to check for a matching protocol spec by device name or service UUIDs. If a match is found, attach it with ble.spec.attach. If no match, ask the user if they have a protocol spec for this device. 2) Use ble.plugin.list to check for a plugin whose name matches the device. If a matching plugin is loaded, its tools are available to use directly.

Disconnect a BLE peripheral by connection_id.

Check whether a connection is still alive. Returns connected (bool), address, and disconnect_ts if the device disconnected unexpectedly. Use this to verify a connection before a sequence of operations.

Discover services and characteristics on a connected device. Results are cached per connection.

Return the negotiated MTU (Maximum Transmission Unit) for a connection. The effective max write payload per packet is mtu - 3 bytes (ATT header). Useful for determining chunk sizes for large writes.

Read the value of a GATT characteristic.

Write a value to a GATT characteristic. Requires BLE_MCP_ALLOW_WRITES=true at server startup. Provide value as base64 (value_b64) or hex (value_hex).

Read a GATT descriptor by handle. Use ble.discover to find descriptor handles. Descriptors provide metadata about characteristics (e.g. CCCD, user description).

Write to a GATT descriptor by handle. Requires BLE_MCP_ALLOW_WRITES=true. Rarely needed directly — bleak handles CCCD for notify/indicate automatically.

Subscribe to notifications/indications on a characteristic.

Unsubscribe from a previously created subscription.

Block until the next single notification arrives on a subscription, or timeout. For bursty / bulk flows (e.g. downloading a dataset or log file) prefer ble.drain_notifications instead.

Non-blocking: return up to max_items buffered notifications immediately. Returns an empty list if the queue is empty. Also returns a dropped counter showing how many notifications were lost to queue overflow since subscription start.

Batch-collect notifications: waits up to timeout_s for the first notification, then keeps collecting until idle_timeout_s passes with no new data, max_items is reached, or the total timeout_s expires. Ideal for bursty flows like downloading a log file or dataset over BLE notifications.

List all tracked connections with their status, address, name, timestamps, and subscription count. Useful for recovering connection IDs after context loss.

List all active subscriptions with their status, queue depth, and dropped count. Optionally filter by connection_id. Useful for recovering subscription IDs.

List all tracked scans with their status, filters, timestamps, and device count. Useful for recovering scan IDs after context loss.

List all registered background tasks (from plugins) with their status. Shows task_id, name, running/stopped, start time, and any error.

Cancel a running background task by task_id.

Return a markdown template for a new BLE protocol spec. Optionally pre-fill with a device name.

Register a spec file in the index. Validates YAML front-matter (requires kind: ble-protocol and name). The file path can be absolute or relative to CWD.

List all registered specs with their metadata and matching hints.

Attach a registered spec to a connection session (in-memory only). The spec will be available via ble.spec.get for the duration of this connection. After attaching, check ble.plugin.list for a matching plugin, then present the user with their options: interact with the device using the spec (read/write characteristics, execute flows), use plugin shortcut tools if a plugin is loaded, extend an existing plugin with new tools, or create a new plugin using ble.plugin.template.

Get the attached spec for a connection (returns null if none attached).

Read full spec content, file path, and metadata by spec_id.

Full-text search over a spec's content. Returns matching snippets with line numbers and surrounding context.

Return tracing config and event count.

Return last N trace events (default 50).

List loaded plugins with their tool names and metadata. Each plugin may include a 'meta' dict with matching hints like service_uuids, device_name_contains, or description — use these to determine which plugin fits the connected device. Also returns whether plugins are enabled and the current policy. Plugins require BLE_MCP_PLUGINS env var — set to 'all' for all or 'name1,name2' to allow specific plugins. If disabled, tell the user to set this variable when adding the MCP server.

Hot-reload a plugin by name. Re-imports the module and refreshes tools. Requires BLE_MCP_PLUGINS env var to be set.

Return a Python plugin template. Use this when creating a new plugin. Optionally pre-fill with a device name. Save the result to .ble_mcp/plugins/.py, fill in the tools and handlers, then load with ble.plugin.load.

Load a new plugin from a file or directory path. Requires BLE_MCP_PLUGINS env var to be set.