# 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
