simpleaible 0.14.1.dev77__tar.gz → 0.14.1.dev79__tar.gz

{simpleaible-0.14.1.dev77 → simpleaible-0.14.1.dev79}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simpleaible
-Version: 0.14.1.dev77
+Version: 0.14.1.dev79
 Summary: SimpleAIBLE is an AI-friendly BLE toolkit (MCP server & REST API) powered by SimplePyBLE.
 Author-email: Kevin Dewald <kevin@simpleble.org>
 Project-URL: Homepage, https://github.com/simpleble/simpleble
@@ -85,7 +85,12 @@ See the `HTTP Server docs`_ for the full API reference.
 Agent Skills
 ------------
 
-Install the SimpleAIBLE skill to give your AI agent built-in knowledge of BLE workflows: ::
+Install the SimpleAIBLE skill to give your AI agent built-in knowledge of BLE workflows.
+The bundled installer detects Claude Code and Codex automatically: ::
+
+   simpleaible install
+
+Run ``simpleaible uninstall`` to remove the skill again. For other agents, use the ``skills`` CLI: ::
 
    npx skills add https://github.com/simpleble/simpleble --skill simpleaible
 

{simpleaible-0.14.1.dev77 → simpleaible-0.14.1.dev79}/README.rst

@@ -58,7 +58,12 @@ See the `HTTP Server docs`_ for the full API reference.
 Agent Skills
 ------------
 
-Install the SimpleAIBLE skill to give your AI agent built-in knowledge of BLE workflows: ::
+Install the SimpleAIBLE skill to give your AI agent built-in knowledge of BLE workflows.
+The bundled installer detects Claude Code and Codex automatically: ::
+
+   simpleaible install
+
+Run ``simpleaible uninstall`` to remove the skill again. For other agents, use the ``skills`` CLI: ::
 
    npx skills add https://github.com/simpleble/simpleble --skill simpleaible
 

{simpleaible-0.14.1.dev77 → simpleaible-0.14.1.dev79}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simpleaible"
-version = "0.14.1-dev77"
+version = "0.14.1-dev79"
 description = "SimpleAIBLE is an AI-friendly BLE toolkit (MCP server & REST API) powered by SimplePyBLE."
 readme = "README.rst"
 requires-python = ">=3.10"
@@ -36,6 +36,14 @@ dependencies = [
 [project.scripts]
 simpleaible-mcp = "simpleaible.mcp:main"
 simpleaible-http = "simpleaible.http:main"
+simpleaible = "simpleaible.cli:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.setuptools.package-data]
+simpleaible = [
+    "py.typed",
+    "skills/*/SKILL.md",
+    "skills/*/references/*.md",
+]

simpleaible-0.14.1.dev79/src/simpleaible/cli.py

@@ -0,0 +1,125 @@
+"""Command-line entry point for SimpleAIBLE.
+
+Running ``simpleaible`` with no subcommand starts the MCP server (stdio
+transport by default), so the bare command remains a valid MCP server
+invocation for agent configurations. The ``install`` and ``uninstall``
+subcommands manage the bundled agent skill for locally detected agents.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import List
+
+SKILL_NAME = "simpleaible"
+
+
+@dataclass(frozen=True)
+class Agent:
+    key: str
+    display_name: str
+    executable: str
+    config_dir: Path
+
+    @property
+    def skill_dir(self) -> Path:
+        return self.config_dir / "skills" / SKILL_NAME
+
+    def detected(self) -> bool:
+        return self.config_dir.is_dir() or shutil.which(self.executable) is not None
+
+
+def _known_agents() -> List[Agent]:
+    home = Path.home()
+    return [
+        Agent(key="claude", display_name="Claude Code", executable="claude", config_dir=home / ".claude"),
+        Agent(key="codex", display_name="Codex", executable="codex", config_dir=home / ".codex"),
+    ]
+
+
+def _select_agents(requested: List[str]) -> List[Agent]:
+    agents = _known_agents()
+    if requested:
+        # Explicitly requested agents are used even if not auto-detected.
+        return [agent for agent in agents if agent.key in requested]
+    return [agent for agent in agents if agent.detected()]
+
+
+def _bundled_skill_path() -> Path:
+    skill = resources.files(__package__) / "skills" / SKILL_NAME
+    path = Path(str(skill))
+    if not (path / "SKILL.md").is_file():
+        raise FileNotFoundError(f"Bundled skill not found at {path}")
+    return path
+
+
+def install_skills(requested: List[str]) -> int:
+    agents = _select_agents(requested)
+    if not agents:
+        print("No supported agents detected (looked for Claude Code and Codex).")
+        print("Use --agent to target one explicitly, or install manually:")
+        print("  npx skills add https://github.com/simpleble/simpleble --skill simpleaible")
+        return 1
+
+    source = _bundled_skill_path()
+    for agent in agents:
+        target = agent.skill_dir
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(source, target, dirs_exist_ok=True)
+        print(f"Installed '{SKILL_NAME}' skill for {agent.display_name} at {target}")
+    return 0
+
+
+def uninstall_skills(requested: List[str]) -> int:
+    agents = _select_agents(requested)
+    removed = False
+    for agent in agents:
+        target = agent.skill_dir
+        if not target.is_dir():
+            continue
+        if not (target / "SKILL.md").is_file():
+            # Refuse to delete a directory that doesn't look like an installed skill.
+            print(f"Skipping {target}: no SKILL.md found, not removing.")
+            continue
+        shutil.rmtree(target)
+        removed = True
+        print(f"Removed '{SKILL_NAME}' skill for {agent.display_name} from {target}")
+
+    if not removed:
+        print(f"No installed '{SKILL_NAME}' skill found.")
+    return 0
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+
+    if argv and argv[0] in ("install", "uninstall"):
+        parser = argparse.ArgumentParser(
+            prog=f"simpleaible {argv[0]}",
+            description=f"{argv[0].capitalize()} the SimpleAIBLE agent skill for detected agents.",
+        )
+        parser.add_argument(
+            "--agent",
+            action="append",
+            choices=[agent.key for agent in _known_agents()],
+            default=[],
+            help="Target a specific agent (repeatable). Defaults to all detected agents.",
+        )
+        args = parser.parse_args(argv[1:])
+        handler = install_skills if argv[0] == "install" else uninstall_skills
+        sys.exit(handler(args.agent))
+
+    # Default: run the MCP server. Imported lazily so skill management works
+    # in environments where the BLE backend is unavailable.
+    from . import mcp
+
+    mcp.main()
+
+
+if __name__ == "__main__":
+    main()

simpleaible-0.14.1.dev79/src/simpleaible/skills/simpleaible/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: simpleaible
+description: Use the SimpleAIBLE MCP server to scan, connect, and interact with Bluetooth devices. This skill provides guidance on the recommended flow (scan -> connect -> services -> read/notify) and handles platform-specific differences like UUIDs on macOS vs MAC addresses on Linux. Use when the user wants to interact with BLE hardware or debug Bluetooth connections.
+---
+
+# SimpleAIBLE
+
+SimpleAIBLE is an AI-friendly BLE toolkit powered by SimpleBLE. This skill provides instructions for using the SimpleAIBLE MCP server to interact with Bluetooth Low Energy (BLE) devices directly from the host machine.
+
+## Quick Start Flow
+
+Always follow this sequence for BLE interactions:
+
+1. **Scanning**: Call `scan_for` (default 5s) to find nearby peripherals.
+2. **Connection**: Call `connect` using the `address` from the scan results.
+3. **Exploration**: Call `services` to list available GATT services and characteristics.
+4. **Interaction**: Use `read` for one-time values, `write_request`/`write_command` to send data, or `notify`/`indicate` + `get_notifications` + `unsubscribe` for streaming data.
+5. **Cleanup**: Always call `disconnect` when finished to release the device.
+
+## Core Instructions
+
+- **Scanning**: Prefer scanning immediately before connecting to ensure the device is in the internal cache.
+- **Addressing**: Be aware that macOS/iOS uses UUIDs for addresses, while Linux/Windows uses MAC addresses.
+- **Data Handling**: Binary data is returned as `data_hex` (always reliable) and `data_utf8` (convenience field). If the data is not valid UTF-8, invalid bytes are skipped, so `data_utf8` may be incomplete or empty. Use `data_hex` for protocol analysis and `data_utf8` for human-readable strings.
+- **Notifications/Indications**: Use `notify` or `indicate` to subscribe, `get_notifications` to retrieve buffered data, and `unsubscribe` when done.
+- **Bluetooth Status**: Assume Bluetooth is enabled by default. Only check `bluetooth_enabled` when an operation fails.
+
+## Additional Resources
+
+- For detailed tool documentation and platform notes, see [the reference guide](references/REFERENCE.md).
+- For concrete usage examples, see [examples.md](references/examples.md).
+- For troubleshooting common issues, see [troubleshooting.md](references/troubleshooting.md).

simpleaible-0.14.1.dev79/src/simpleaible/skills/simpleaible/references/REFERENCE.md

@@ -0,0 +1,46 @@
+# SimpleAIBLE Reference
+
+## Tool Catalog
+
+### Adapter Management
+
+- `get_adapters`: Lists all Bluetooth adapters. Returns `identifier` and `address`.
+- `scan_for(timeout_ms)`: Scans for devices using the first available adapter. Returns `identifier`, `address`, `rssi`, `connectable`, and `manufacturer_data`.
+
+### Connection Management
+
+- `connect(address)`: Establishes a connection.
+- `disconnect(address)`: Terminates the connection.
+
+### GATT Operations
+
+- `services(address)`: Discovers services and characteristics. Returns a list of services with their UUIDs and associated characteristic UUIDs.
+- `read(address, service_uuid, char_uuid)`: Reads a single value. Returns `data_hex` and `data_utf8`. If the data is not valid UTF-8, invalid bytes are skipped in `data_utf8`.
+- `write_request(address, service_uuid, char_uuid, data)`: Writes data (hex string) to a characteristic with response.
+- `write_command(address, service_uuid, char_uuid, data)`: Writes data (hex string) to a characteristic without response.
+- `notify(address, service_uuid, char_uuid)`: Subscribes to notifications. Data is buffered in the background.
+- `indicate(address, service_uuid, char_uuid)`: Subscribes to indications. Data is buffered in the background.
+- `get_notifications(address)`: Retrieves and clears all buffered notifications/indications.
+- `unsubscribe(address, service_uuid, char_uuid)`: Unsubscribes from notifications or indications.
+
+## Platform-Specific Behavior
+
+### macOS / iOS
+
+- **Addresses**: Uses randomized UUIDs (e.g., `5E2A...`) instead of hardware MAC addresses. These UUIDs are temporary and may change between sessions or device restarts.
+- **Permissions**: Requires Bluetooth permissions. If the MCP server fails to start or scan, check System Settings.
+
+### Linux (BlueZ)
+
+- **Addresses**: Uses standard MAC addresses (e.g., `AA:BB:CC:DD:EE:FF`).
+- **Dependencies**: Works on any Linux OS that uses BlueZ.
+
+### Windows
+
+- **Addresses**: Uses standard MAC addresses (e.g., `AA:BB:CC:DD:EE:FF`).
+
+## Data Encoding
+
+- **`data_hex`**: Always reliable. Lowercase hex string without `0x` prefix.
+- **`data_utf8`**: Convenience field. If the data is not valid UTF-8, invalid bytes are silently skipped, so it may be incomplete or empty for binary data.
+

simpleaible-0.14.1.dev79/src/simpleaible/skills/simpleaible/references/examples.md

@@ -0,0 +1,77 @@
+# SimpleAIBLE Examples
+
+## Example 1: Listing Bluetooth Adapters
+
+**User**: "What Bluetooth adapters are available on this machine?"
+
+**Agent Workflow**:
+1. Call `get_adapters` to list all available Bluetooth adapters.
+2. Display the adapter identifiers and addresses to the user.
+
+## Example 2: Basic Device Discovery
+
+**User**: "Find any BLE devices nearby."
+
+**Agent Workflow**:
+1. Call `scan_for(timeout_ms=5000)` to search for devices. 
+2. Display the list of found devices (Identifier, Address, RSSI).
+
+## Example 3: Reading Device Information
+
+**User**: "Read the firmware version from the device at address AA:BB:CC:DD:EE:FF."
+
+**Agent Workflow**:
+1. Call `scan_for` to ensure the device is in cache. 
+2. Call `connect("AA:BB:CC:DD:EE:FF")`.
+3. Call `services("AA:BB:CC:DD:EE:FF")` to find the Device Information Service (usually `0000180a-...`).
+4. Identify the Firmware Revision String characteristic (usually `00002a26-...`).
+5. Call `read("AA:BB:CC:DD:EE:FF", "180a", "2a26")`.
+6. Display the `data_utf8` result.
+7. Call `disconnect("AA:BB:CC:DD:EE:FF")`.
+
+## Example 4: Debugging a Connection Issue
+
+**User**: "I'm debugging my peripheral, please ensure it is connectable and I can read some data."
+
+**Agent Workflow**:
+1. Call `scan_for` to see if the device appears in the scan results. 
+2. Check the `connectable` field in the scan results.
+3. If connectable, call `connect(address)`.
+4. Call `services(address)` to explore available GATT characteristics.
+5. Attempt a `read` from a known characteristic (e.g., Device Name or Battery Level) to verify data access.
+6. Report the status of each step to the user to help pinpoint where it fails.
+
+## Example 5: Writing to a Characteristic
+
+**User**: "Send the command 0x01 to the control characteristic on my device at AA:BB:CC:DD:EE:FF."
+
+**Agent Workflow**:
+1. Call `scan_for` to ensure the device is in cache. 
+2. Call `connect("AA:BB:CC:DD:EE:FF")`.
+3. Call `services("AA:BB:CC:DD:EE:FF")` to find the relevant service and characteristic.
+4. Call `write_request("AA:BB:CC:DD:EE:FF", "service-uuid", "char-uuid", "01")` for a write with response, or `write_command(...)` for a write without response.
+5. Call `disconnect("AA:BB:CC:DD:EE:FF")`.
+
+## Example 6: Streaming Notification Data
+
+**User**: "Subscribe to heart rate notifications from my device at AA:BB:CC:DD:EE:FF."
+
+**Agent Workflow**:
+1. Call `scan_for` to ensure the device is in cache. 
+2. Call `connect("AA:BB:CC:DD:EE:FF")`.
+3. Call `services("AA:BB:CC:DD:EE:FF")` to find the Heart Rate Service (usually `0000180d-...`).
+4. Identify the Heart Rate Measurement characteristic (usually `00002a37-...`).
+5. Call `notify("AA:BB:CC:DD:EE:FF", "180d", "2a37")` to subscribe.
+6. Wait, then call `get_notifications("AA:BB:CC:DD:EE:FF")` to retrieve buffered samples.
+7. Repeat `get_notifications` as needed to collect more data.
+8. Call `unsubscribe("AA:BB:CC:DD:EE:FF", "180d", "2a37")` when done.
+9. Call `disconnect("AA:BB:CC:DD:EE:FF")`.
+
+## Example 7: Troubleshooting Discovery
+
+**User**: "I've made this Bluetooth integration but I'm not finding any device, please see if you can find any BLE device."
+
+**Agent Workflow**:
+1. Call `scan_for(timeout_ms=10000)` with a longer timeout to give devices more time to advertise. 
+2. Analyze the results: if no devices are found, suggest checking physical proximity or if the device is already paired/connected to another host.
+3. If devices are found but not the specific one, list the found identifiers to see if it's appearing with a different name.

simpleaible-0.14.1.dev79/src/simpleaible/skills/simpleaible/references/troubleshooting.md

@@ -0,0 +1,33 @@
+# Troubleshooting SimpleAIBLE MCP Operations
+
+## Bluetooth Not Enabled
+
+If any MCP operation fails (scanning, connecting, reading, etc.), the first diagnostic step is to check if Bluetooth is enabled on the host system.
+
+### Diagnostic Steps
+
+1. **When an operation fails, call `bluetooth_enabled` tool** to check the Bluetooth status:
+   ```python
+   result = bluetooth_enabled()
+   # Returns: {"enabled": true} or {"enabled": false}
+   ```
+
+2. **If Bluetooth is disabled (`enabled: false`)**:
+   - Prompt the user: "Bluetooth appears to be disabled on your system. Please enable Bluetooth in your system settings and try again."
+   - Wait for the user to confirm they've enabled Bluetooth
+   - Call `bluetooth_enabled` again to verify it's now enabled
+   - Retry the original operation
+
+3. **If Bluetooth is enabled (`enabled: true`) but operations still fail**:
+   - The issue is likely something else (permissions, device not in range, hardware issue, etc.)
+   - Proceed with other troubleshooting steps:
+     - Check if adapters are available with `get_adapters`
+     - Verify device proximity and advertising status
+     - Check system permissions (especially on macOS/iOS)
+
+### Important Notes
+
+- **Assume Bluetooth is enabled by default** - do not check `bluetooth_enabled` proactively
+- **Only call `bluetooth_enabled` when an operation fails** to diagnose the issue
+- Bluetooth must be enabled for **all** BLE operations to work
+- The `bluetooth_enabled` check is fast and idempotent - safe to call multiple times

{simpleaible-0.14.1.dev77 → simpleaible-0.14.1.dev79}/src/simpleaible.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simpleaible
-Version: 0.14.1.dev77
+Version: 0.14.1.dev79
 Summary: SimpleAIBLE is an AI-friendly BLE toolkit (MCP server & REST API) powered by SimplePyBLE.
 Author-email: Kevin Dewald <kevin@simpleble.org>
 Project-URL: Homepage, https://github.com/simpleble/simpleble
@@ -85,7 +85,12 @@ See the `HTTP Server docs`_ for the full API reference.
 Agent Skills
 ------------
 
-Install the SimpleAIBLE skill to give your AI agent built-in knowledge of BLE workflows: ::
+Install the SimpleAIBLE skill to give your AI agent built-in knowledge of BLE workflows.
+The bundled installer detects Claude Code and Codex automatically: ::
+
+   simpleaible install
+
+Run ``simpleaible uninstall`` to remove the skill again. For other agents, use the ``skills`` CLI: ::
 
    npx skills add https://github.com/simpleble/simpleble --skill simpleaible
 

{simpleaible-0.14.1.dev77 → simpleaible-0.14.1.dev79}/src/simpleaible.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 README.rst
 pyproject.toml
 src/simpleaible/__init__.py
+src/simpleaible/cli.py
 src/simpleaible/http.py
 src/simpleaible/mcp.py
 src/simpleaible/py.typed
@@ -9,4 +10,8 @@ src/simpleaible.egg-info/SOURCES.txt
 src/simpleaible.egg-info/dependency_links.txt
 src/simpleaible.egg-info/entry_points.txt
 src/simpleaible.egg-info/requires.txt
-src/simpleaible.egg-info/top_level.txt
+src/simpleaible.egg-info/top_level.txt
+src/simpleaible/skills/simpleaible/SKILL.md
+src/simpleaible/skills/simpleaible/references/REFERENCE.md
+src/simpleaible/skills/simpleaible/references/examples.md
+src/simpleaible/skills/simpleaible/references/troubleshooting.md

{simpleaible-0.14.1.dev77 → simpleaible-0.14.1.dev79}/src/simpleaible.egg-info/entry_points.txt

@@ -1,3 +1,4 @@
 [console_scripts]
+simpleaible = simpleaible.cli:main
 simpleaible-http = simpleaible.http:main
 simpleaible-mcp = simpleaible.mcp:main