bluespy-mcp 1.2.0__tar.gz

bluespy_mcp-1.2.0/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "bluespy"
+  ],
+  "permissions": {
+    "allow": [
+      "mcp__bluespy__list_captures"
+    ]
+  }
+}

bluespy_mcp-1.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.pcapng
+!tests/fixtures/*.pcapng
+.DS_Store

bluespy_mcp-1.2.0/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "bluespy": {
+      "command": "/Users/mafaneh/Projects/bluespy-mcp/.venv/bin/python",
+      "args": ["-m", "bluespy_mcp"],
+      "env": {
+        "BLUESPY_LIBRARY_PATH": "/Applications/blueSPY.app/Contents/Frameworks/libblueSPY.dylib",
+        "BLE_CAPTURES_DIR": "/Users/mafaneh/Projects/bluespy-captures"
+      }
+    }
+  }
+}

bluespy_mcp-1.2.0/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+## What This Is
+
+Open-source MCP server for the BlueSPY Bluetooth LE protocol analyzer. Lets AI assistants load and analyze .pcapng capture files.
+
+## Architecture
+
+Flat Python package:
+
+- `server.py` — FastMCP server, 16 tools + 2 resources + 3 prompts
+- `capture.py` — CaptureManager wrapping BlueSPY's global file state
+- `analyzer.py` — Packet classification, filtering, summarization
+- `hardware.py` — HardwareManager: subprocess isolation, file lock, state machine
+- `worker.py` — Worker subprocess: executes bluespy hardware commands
+- `loader.py` — Auto-discovers bluespy.py (installed > bundled fallback)
+- `_vendor/bluespy.py` — Bundled fallback BlueSPY API
+
+## Development
+
+```bash
+# Setup
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+
+# Run tests (no hardware needed)
+python -m pytest tests/ -v
+
+# Run integration tests (needs BlueSPY hardware + dylib)
+python -m pytest tests/ -v -m hardware
+
+# Run server locally
+bluespy-mcp
+# or
+python -m bluespy_mcp
+```
+
+## Key Patterns
+
+- **Lazy loading**: BlueSPY module loaded on first use, not at import time
+- **One file at a time**: BlueSPY uses global state. CaptureManager wraps this.
+- **Defensive queries**: Every packet attribute access wrapped in try/except
+- **JSON responses**: All tools return JSON. Errors are `{"error": "message"}`.
+- **50K packet cap**: Summary operations cap iteration to prevent hanging on huge captures.
+- **Subprocess isolation**: All hardware calls run in a child process. If ctypes hangs, the subprocess is killed — MCP server stays responsive.
+- **File lock**: `~/.bluespy-mcp.lock` ensures single-client hardware access.
+- **Reboot on connect**: Every connect_hardware() reboots the device first to avoid stale state.
+
+## Adding New Tools
+
+1. Add analysis function to `analyzer.py`
+2. Add `@mcp.tool` function to `server.py` (follows the pattern of existing tools)
+3. Add tests to the corresponding test file
+4. Update README.md tool table

bluespy_mcp-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Novel Bits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bluespy_mcp-1.2.0/PKG-INFO

@@ -0,0 +1,390 @@
+Metadata-Version: 2.4
+Name: bluespy-mcp
+Version: 1.2.0
+Summary: MCP server for BlueSPY Bluetooth LE protocol analyzer
+Project-URL: Homepage, https://github.com/novelbits/bluespy-mcp
+Project-URL: Repository, https://github.com/novelbits/bluespy-mcp
+Project-URL: Issues, https://github.com/novelbits/bluespy-mcp/issues
+Author-email: Mohammad Afaneh <mafaneh@novelbits.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ble,bluespy,bluetooth,mcp,protocol-analyzer,sniffer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.0.0
+Provides-Extra: e2e
+Requires-Dist: claude-code-sdk; extra == 'e2e'
+Requires-Dist: pytest-asyncio; extra == 'e2e'
+Description-Content-Type: text/markdown
+
+# BlueSPY MCP Server
+
+MCP server for the [BlueSPY](https://rfcreations.com) Bluetooth LE protocol analyzer. Gives AI assistants direct access to .pcapng capture analysis — turn packet captures into conversations instead of writing scripts or scrolling through Wireshark.
+
+Works with Claude Desktop, Claude Code, and Cursor.
+
+## What It Does
+
+Instead of writing Python scripts or manually filtering packets, just ask:
+
+> "Load this capture and tell me what's going on."
+
+The AI loads your capture file, classifies 54,000+ packets, identifies 219 devices, maps 25 connections, and gives you a structured breakdown — in seconds.
+
+### Example: Analyzing a Restaurant Bluetooth LE Environment
+
+```
+You: Load the First Watch capture and summarize it.
+
+Claude: Loaded First Watch Carmel.pcapng — 54,195 packets over 32 seconds.
+
+  219 devices detected, 25 active connections.
+
+  Packet breakdown:
+  → 11,671 ADV_IND (connectable advertisements)
+  → 4,738 ADV_NONCONN_IND (beacons)
+  → 6,554 LE_DATA (active data transfer)
+  → 5,642 SCAN_REQ / 5,014 SCAN_RSP
+  → 113 CRC errors from RF congestion
+  → 33 new connections initiated
+
+You: Show me the advertising for the first device.
+
+Claude: Device BC:57:29:01:00:42 — 34 advertisements found.
+  Channels: 37, 38, 39
+  RSSI: min -82, max -48, avg -65.2
+
+You: Find all the errors.
+
+Claude: 113 errors found — all CRC failures on advertising channels,
+  consistent with a congested RF environment (219 devices in range).
+```
+
+No scripts. No manual filtering. Just a conversation.
+
+## Prerequisites
+
+- **Python 3.10+**
+- **BlueSPY application** (free) — provides the native `libblueSPY` library required for packet parsing
+
+Download BlueSPY for your platform from [rfcreations.com/bluespy-software](https://www.rfcreations.com/bluespy-software):
+
+| Platform | Download |
+|----------|----------|
+| macOS 11.0+ | [blueSPY-Darwin.pkg](https://private.rfcreations.com/bin/latest?q=blueSPY-~-Darwin.pkg) |
+| Windows 7+ | [blueSPY-win64.msi](https://private.rfcreations.com/bin/latest?q=blueSPY-~-win64.msi) |
+| Windows 7+ (Portable) | [blueSPY-win64.7z](https://private.rfcreations.com/bin/latest?q=blueSPY-~-win64.7z) |
+| Linux (glibc 2.27+) | [blueSPY-Linux.7z](https://private.rfcreations.com/bin/latest?q=blueSPY-~-Linux.7z) |
+| Linux (arm64) | [blueSPY-Linux-arm64.7z](https://private.rfcreations.com/bin/latest?q=blueSPY-~-Linux-arm64.7z) |
+| Linux (Headless) | [blueSPY-Linux-Headless.7z](https://private.rfcreations.com/bin/latest?q=blueSPY-~-Linux-Headless.7z) |
+
+No hardware needed to get started — download the [example captures](https://www.rfcreations.com/bluespy-software) from the same page and use them with the file analysis tools.
+
+## Installation
+
+```bash
+pip install bluespy-mcp
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/novelbits/bluespy-mcp.git
+cd bluespy-mcp
+pip install .
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "bluespy": {
+      "command": "bluespy-mcp",
+      "env": {
+        "BLUESPY_LIBRARY_PATH": "/Applications/blueSPY.app/Contents/Frameworks/libblueSPY.dylib"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add bluespy -- bluespy-mcp
+```
+
+Or add to your `.mcp.json`:
+
+```json
+{
+  "bluespy": {
+    "command": "bluespy-mcp",
+    "env": {
+      "BLUESPY_LIBRARY_PATH": "/Applications/blueSPY.app/Contents/Frameworks/libblueSPY.dylib"
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your MCP server configuration:
+
+```json
+{
+  "bluespy": {
+    "command": "bluespy-mcp",
+    "env": {
+      "BLUESPY_LIBRARY_PATH": "/Applications/blueSPY.app/Contents/Frameworks/libblueSPY.dylib"
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `BLUESPY_LIBRARY_PATH` | Path to `libblueSPY.dylib` / `.so` / `.dll` | Yes |
+| `BLUESPY_API_PATH` | Path to directory containing `bluespy.py` (auto-discovered if not set) | No |
+| `BLE_CAPTURES_DIR` | Default directory for capture files (default: `captures/`) | No |
+
+### Platform-Specific Library Paths
+
+| Platform | Path |
+|----------|------|
+| macOS | `/Applications/blueSPY.app/Contents/Frameworks/libblueSPY.dylib` |
+| Windows | `C:\Program Files\blueSPY\libblueSPY.dll` |
+| Linux | `/usr/local/lib/libblueSPY.so` |
+
+## Tools
+
+### File Management
+
+| Tool | Description |
+|------|-------------|
+| `load_capture(file_path)` | Load a .pcapng capture file for analysis |
+| `close_capture()` | Close the currently loaded file |
+| `list_captures(directory?)` | List .pcapng files in a directory |
+
+### Discovery
+
+| Tool | Description |
+|------|-------------|
+| `capture_summary()` | Packet counts by type, duration, device/connection counts |
+| `list_devices()` | All Bluetooth devices with addresses and names |
+| `list_connections()` | All connections with parameters |
+
+### Analysis
+
+| Tool | Description |
+|------|-------------|
+| `search_packets(summary_contains?, packet_type?, channel?, max_results?)` | Filter packets by criteria |
+| `inspect_connection(connection_index)` | Deep-dive connection analysis with packet breakdown |
+| `inspect_advertising(device_index)` | Per-device advertising analysis with RSSI and channel stats |
+| `inspect_all_devices()` | Batch advertising analysis for ALL devices in a single pass (much faster than per-device calls) |
+| `inspect_all_connections()` | Batch connection analysis for ALL connections in a single pass (much faster than per-connection calls) |
+| `find_capture_errors(max_results?)` | Error, failure, disconnect, and timeout packets |
+
+### Live Hardware
+
+| Tool | Description |
+|------|-------------|
+| `connect_hardware(serial, force)` | Connect to first available device (or specify serial) |
+| `disconnect_hardware()` | Disconnect from hardware |
+| `start_capture(filename, duration_seconds, LE, CL, QHS, wifi, CS)` | Start live capture |
+| `stop_capture()` | Stop active capture |
+| `hardware_status()` | Get current hardware state |
+
+### Resources
+
+| Resource | Description |
+|----------|-------------|
+| `capture://status` | Current loaded file metadata (JSON) |
+| `bluespy://hardware` | Current hardware connection state (JSON) |
+| `bluespy://capture` | Current live capture state (JSON) |
+
+### Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `analyze-capture` | Guided workflow to load and analyze a capture file |
+| `quick-capture` | Quick-start workflow for live hardware capture |
+| `debug-connection` | Troubleshoot hardware connection issues |
+
+## Try It Without Hardware
+
+Download the [example captures](https://www.rfcreations.com/bluespy-software) from RFcreations (free) and try these prompts. No sniffer needed — just the BlueSPY application installed.
+
+### Example Captures
+
+| File | Packets | Devices | Connections | What's inside |
+|------|---------|---------|-------------|---------------|
+| `LE_Phone_Alert_Status_Profile.pcapng` | 2,359 | 16 | 2 | Simple Bluetooth LE GATT profile with scanning and data exchange |
+| `Encrypted Advertising Data.pcapng` | 1,547 | 13 | 0 | Advertising only — no connections, good for device discovery analysis |
+| `AVDTP_and_eSCO.pcapng` | — | — | — | Bluetooth Classic audio (A2DP streaming + voice calls) |
+| `BIS.pcapng` | — | — | — | LE Audio Broadcast Isochronous Stream |
+| `CIS_and_AVDTP_and_HCI.pcapng` | — | — | — | Mixed: LE Audio CIS + Classic audio + HCI commands |
+| `audiopod_LE_Audio_CIG.pcapng` | 53,887 | 186 | 14 | Dense LE Audio capture — NRF5340 devices, CRC errors, encrypted traffic |
+
+### Start here: simple Bluetooth LE profile
+
+```
+Load LE_Phone_Alert_Status_Profile.pcapng and tell me what's going on.
+```
+
+```
+Inspect all connections. What protocols are being used?
+```
+
+### Advertising-only analysis
+
+```
+Load Encrypted Advertising Data.pcapng. How many devices are advertising? Inspect all of them.
+```
+
+```
+Search for SCAN_REQ packets. Which devices are being actively scanned?
+```
+
+### Stress test: large LE Audio capture
+
+```
+Load audiopod_LE_Audio_CIG.pcapng and summarize it.
+```
+
+```
+Inspect all 14 connections at once. Which ones have the most data packets?
+```
+
+```
+Find all errors. What's causing the CRC failures?
+```
+
+```
+Look at connection 9 — that's the NRF5340_AUDIO device. What's it doing?
+```
+
+Or use the built-in `analyze-capture` prompt for a guided walkthrough of any file.
+
+## Live Hardware Capture
+
+If you have a BlueSPY sniffer connected via USB, the MCP server can control it directly — connect, start/stop captures, and analyze results in real time.
+
+```
+You: Connect to my sniffer and capture Bluetooth LE traffic for 10 seconds.
+
+Claude: Connected to Moreph serial 2411001234.
+  Capturing Bluetooth LE packets for 10 seconds...
+  Capture complete — saved to ble_capture_20260228.pcapng (12,847 packets).
+
+You: Summarize what you captured.
+
+Claude: 12,847 packets over 10 seconds.
+  87 devices detected, 12 active connections.
+  → 4,231 ADV_IND (connectable advertisements)
+  → 1,892 ADV_NONCONN_IND (beacons)
+  → 3,104 LE_DATA (active data transfer)
+```
+
+Hardware access is subprocess-isolated — if a hardware call hangs, the MCP server kills the worker process and stays responsive. A file lock (`~/.bluespy-mcp.lock`) ensures only one client controls the hardware at a time.
+
+## Model Recommendations
+
+This MCP server works with any LLM that supports tool use. The built-in prompt templates (`analyze-capture`, `quick-capture`, `debug-connection`) guide even smaller models through the correct multi-step workflows.
+
+| Tier | Models | Best For |
+|------|--------|----------|
+| **Minimum** | Haiku 4.5, GPT-4o mini, Gemini Flash | Loading captures, running guided workflows, basic summaries. Handles the full tool chain reliably. |
+| **Recommended** | Sonnet 4.5, GPT-4o, Gemini Pro | Deeper protocol analysis — correlating error patterns across connections, interpreting RSSI trends, diagnosing RF interference, generating actionable recommendations. |
+| **Advanced** | Opus, o3, Gemini Ultra | Multi-capture comparison, cross-referencing against Bluetooth spec, complex protocol-level debugging. Rarely needed. |
+
+**Key factors for good results:**
+- **Use the prompt templates.** They walk any model through load → summarize → analyze → inspect in the right order.
+- **Tool-use reliability matters more than model size.** A mid-tier model that follows tool sequences correctly will outperform a large model that skips steps.
+- **Domain knowledge helps but isn't required.** The server returns structured JSON with classified packet types, so the model doesn't need to know Bluetooth LE internals to report useful findings.
+
+## Development
+
+```bash
+git clone https://github.com/novelbits/bluespy-mcp.git
+cd bluespy-mcp
+pip install -e .
+pytest
+```
+
+To run the full test suite including end-to-end and hardware tests (requires a BlueSPY sniffer connected via USB):
+
+```bash
+pip install -e ".[e2e]"
+bash scripts/test.sh all
+```
+
+## Troubleshooting
+
+### "BlueSPY library not found"
+
+Ensure `BLUESPY_LIBRARY_PATH` points to the correct native library for your platform. The BlueSPY application must be installed from [rfcreations.com](https://rfcreations.com).
+
+### "No capture file loaded"
+
+Use `load_capture()` with a path to your .pcapng file before calling analysis tools.
+
+### Claude Desktop crashes on startup
+
+If you're using FastMCP v3.0.2+, ensure the server runs with `show_banner=False` (this is the default in bluespy-mcp). The FastMCP banner corrupts the MCP stdio protocol.
+
+### Hardware: "bluespy_init failed"
+
+The MCP server retries automatically when this happens, but if it persists:
+
+1. **Connect directly to your computer** — do not use a USB hub. The Moreph sniffer requires a direct USB connection for reliable communication.
+2. **Close the BlueSPY desktop app** if it's open. Only one application can control the hardware at a time. Check the device LED: green means it's in use, blue means it's available.
+3. **Unplug and replug** the device, then try again.
+
+### Hardware: "in use by another session"
+
+This means the file lock (`~/.bluespy-mcp.lock`) is held by another MCP session. If no other session is actually running (e.g., a previous session crashed), use the `force` parameter:
+
+```
+connect_hardware(force=True)
+```
+
+This removes the stale lock file and proceeds with the connection.
+
+### Hardware: Python crash on exit
+
+You may see a macOS crash report (`Python quit unexpectedly`) after using hardware tools. This is a known issue with the BlueSPY native library's cleanup routine (`bluespy_deinit`) and does not affect capture data or MCP server operation. The crash occurs during process exit and can be safely dismissed.
+
+### Module not found errors
+
+Ensure you're using Python 3.10+ and have installed the package:
+
+```bash
+python --version  # Should be 3.10+
+pip install bluespy-mcp
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Links
+
+- [BlueSPY by RFcreations](https://rfcreations.com)
+- [MCP Protocol](https://modelcontextprotocol.io)
+- [Issues](https://github.com/novelbits/bluespy-mcp/issues)