# PT5 MCP Server

MCP (Model Context Protocol) server for parsing **Monsoon Power Monitor PT5** files.

Enables any MCP-compatible client (WorkBuddy, Claude Desktop, Cursor, etc.) to read, analyze, and export power measurement data from `.pt5` files captured by Monsoon Solutions' Power Tool software.

## Features

- **parse_pt5** — Parse a PT5 file and return summary statistics (avg/min/max current, voltage, power, energy)
- **get_pt5_channels** — List available measurement channels and field types from the captureDataMask
- **get_pt5_samples** — Retrieve sample data with time-range filtering and decimation
- **export_pt5_csv** — Export sample data to CSV file for external analysis
- **get_pt5_header** — Return raw header and status packet metadata (hardware info, calibration, scaling)
- **analyze_pt5_trend** — Analyze current trend: peak detection, periodicity (autocorrelation), trend segments, anomalies

## Quick Start

### Use with npx (no install needed)

Add to your MCP client configuration (e.g., `~/.workbuddy/mcp.json` or Claude Desktop `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "pt5": {
      "command": "npx",
      "args": ["pt5-mcp-server"]
    }
  }
}
```

### Install globally

```bash
npm install -g pt5-mcp-server
```

Then configure:

```json
{
  "mcpServers": {
    "pt5": {
      "command": "pt5-mcp-server"
    }
  }
}
```

### Local development

```bash
git clone https://github.com/YOUR_USERNAME/pt5-mcp-server.git
cd pt5-mcp-server
npm install
npm run build
```

Configure with local path:

```json
{
  "mcpServers": {
    "pt5": {
      "command": "node",
      "args": ["/path/to/pt5-mcp-server/build/index.js"]
    }
  }
}
```

## PT5 File Format

PT5 is the native binary format of Monsoon Solutions' Power Tool software. The file structure is:

| Section | Offset | Description |
|---------|--------|-------------|
| Header | 0 | 212-byte fixed header with capture metadata |
| Status Packet | 272 | Variable-length hardware status (calibration, scaling) |
| Sample Data | 1024 | Sequential current/voltage samples at 5 kHz |

Each sample contains:
- Main Current (signed Int32, µA) — if channel enabled
- USB Current (signed Int32, µA) — if channel enabled
- Aux Current (signed Int32, µA) — if channel enabled
- Voltage (unsigned UInt16, with marker bits) — always present

Voltage tick resolution depends on hardware revision:

| Hardware | Main | USB | Aux |
|----------|------|-----|-----|
| Rev A | 62.5 µV/tick | 62.5 µV/tick | 62.5 µV/tick |
| Rev B | 125 µV/tick | 125 µV/tick | 62.5 µV/tick |
| Rev C | 125 µV/tick | 125 µV/tick | 125 µV/tick |
| HVPM | 500 µV/tick | 125 µV/tick | 500 µV/tick |

## Tools Reference

### parse_pt5
Parse a PT5 file and return summary statistics.

**Parameters:**
- `file_path` (string, required): Absolute path to the .pt5 file

**Returns:** JSON with sample count, duration, avg/min/max current (mA), avg voltage (V), avg power (mW), total energy (mJ).

### get_pt5_channels
List available measurement channels and fields.

**Parameters:**
- `file_path` (string, required): Absolute path to the .pt5 file

**Returns:** Channels (Main/USB/Aux), fields (Min/Avg/Max Voltage/Current/Power), sample rate, hardware info.

### get_pt5_samples
Retrieve sample data with filtering options.

**Parameters:**
- `file_path` (string, required): Absolute path to the .pt5 file
- `start_time_sec` (number, optional): Start time in seconds (default: 0)
- `end_time_sec` (number, optional): End time in seconds (default: end of capture)
- `decimation` (number, optional): Return every Nth sample (default: 1)
- `max_samples` (number, optional): Max samples to return (default: 5000)

**Returns:** Array of sample objects with timestamp, current (mA), and voltage (V).

### export_pt5_csv
Export sample data to a CSV file.

**Parameters:**
- `input_path` (string, required): Absolute path to the input .pt5 file
- `output_path` (string, required): Absolute path for the output .csv file

**Returns:** Confirmation with file size and sample count.

### get_pt5_header
Return raw header and status packet metadata.

**Parameters:**
- `file_path` (string, required): Absolute path to the .pt5 file

**Returns:** Full header and status packet data, including voltage tick sizes per channel.

### analyze_pt5_trend
Analyze current trend in a PT5 file: detect periodic peaks, autocorrelation-based periodicity, trend direction, and anomalies.

**Parameters:**
- `file_path` (string, required): Absolute path to the .pt5 file
- `channel` (enum: "main" | "usb" | "aux", optional): Channel to analyze (default: "main")
- `peak_window_ms` (number, optional): Peak detection window in ms (default: 50)
- `min_peak_prominence_ma` (number, optional): Minimum peak prominence in mA (default: auto — 5% of mean current)
- `anomaly_threshold_std` (number, optional): Anomaly detection threshold in standard deviations (default: 3)
- `max_lag_sec` (number, optional): Maximum lag for autocorrelation in seconds (default: 10)

**Returns:**
- **Basic stats**: mean, std, CV, min, max current
- **Peak analysis**: total peaks, top peaks with time/current/prominence, average peak interval
- **Periodicity**: dominant period/frequency from autocorrelation, confidence score (0–1)
- **Trend**: overall direction (rising/falling/stable), slope, segment breakdown
- **Anomalies**: intervals where current deviates >N standard deviations from mean
- **Histogram**: current distribution bins

**Example output:**
```
=== Trend Analysis: air-mode.pt5 (channel: main) ===
Mean current: 131.854 mA, Std: 82.512 mA, CV: 0.6259

--- Peak Analysis ---
Total peaks detected: 4244
Average peak interval: 0.0531s (std: 0.0073s)
Top peaks: t=4.610s I=3783.4mA, t=4.709s I=2527.3mA ...

--- Periodicity (Autocorrelation) ---
Dominant period: 0.052s (19.2308Hz)
Confidence: 57.3%

--- Overall Trend ---
Trend: stable (slope: -0.0172 mA/s)
Segments: 80 rising, 60 falling, 84 stable (224 total)

--- Anomalies ---
Found 35 anomaly intervals
```

## License

MIT