# musicolet-mcp

Local tools for extracting listening metrics from Musicolet backup files, building a static dashboard, and exposing the same workflow through an optional MCP server.

This project is designed for power users who want their own music listening analytics without sending their library or listening history to a hosted service.

## Features

- Decode Musicolet backup ZIP files that contain encrypted app data.
- Extract song, play-count, recent listening, artist, album, month, week, and year metrics.
- Generate CSV files plus `summary.json`.
- Build a static, local HTML dashboard.
- Run as a CLI or optional MCP server for agent workflows.

## Quick Start

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev,mcp]"

musicolet-mcp extract C:\path\to\musicolet_backup.zip --out-dir outputs\latest
musicolet-mcp dashboard outputs\latest --out outputs\latest\dashboard.html
```

Open `outputs\latest\dashboard.html` in a browser.

For a recurring Syncthing or USB drop folder:

```powershell
musicolet-mcp update-latest data\incoming --out-dir outputs\latest
```

## MCP Server

```powershell
musicolet-mcp-server
```

Tools exposed by the server:

- `extract_musicolet_metrics`
- `build_musicolet_dashboard`
- `read_musicolet_summary`
- `update_from_latest_musicolet_backup`

## Background

The extraction logic is based on local inspection of Musicolet backups. Backup internals are not an official public API and may change. The project aims to fail gracefully if a future Musicolet version changes its schema.