# lms-mcp-server

MCP server for [Lyrion Music Server](https://lyrion.org) (LMS). Lets Claude query the music library ("what John Coltrane albums do I have?", "which albums did I add this month?") and control players ("play the latest Mali Sheard album in the office").

Runs as a streamable HTTP MCP server. Also records play history by polling player status, since LMS does not store last-played dates - "what have I played this week?" works from the day the server starts. Play counts are whole-album listening sessions (not tracks heard), and each play records the release year and the date the album was added to the library, so "this year's releases, ordered by how much I've played them" is answerable from history alone.

This is an opinionated server, and the opinion is that music comes in albums:

- **The album is the default unit.** "Play Vamala by Champs" plays the whole album. Single tracks are for when you ask for one explicitly ("play the song Vamala") - the tool descriptions steer the model the same way.
- **Artists mean album artists.** "Albums by John Coltrane" returns the albums he made, not every tribute album he has a guest solo on. Artist queries use LMS's `ALBUMARTIST` role, matching the "Album Artists" browse view.
- **Local files beat streaming copies.** If an album (or track) exists both as local files and as a synced online-library copy (e.g. Qobuz favourites), only the local version is surfaced. Online-only albums still appear.

> Code and docs are 100% Claude

## Tools

| Tool | |
|---|---|
| `list_players` | Players/rooms with power and playing state |
| `search_albums` | Albums by free text and/or album artist; sort by newest or random |
| `search_tracks` | Individual tracks, for explicit single-song requests |
| `get_recently_added_albums` | Albums added in the last N days, with added dates |
| `get_recently_played_albums` | Albums played in the last N days, from the server's own history |
| `play_album` | Play or queue a whole album on a player (fuzzy-matched name) |
| `play_track` | Play or queue one track |
| `control_player` | Pause, resume, stop, volume |

## Configuration

| Env var | Default | |
|---|---|---|
| `LMS_URL` | _required_ | LMS base URL (no auth), e.g. `http://lms.local:9000` |
| `PORT` | `3000` | HTTP listen port |
| `HISTORY_FILE` | `./data/history.jsonl` | Play-history store |
| `POLL_INTERVAL_MS` | `30000` | Player status poll interval |

Malformed values fail at startup rather than silently misbehaving.

## Run locally

```sh
npm install
npm test        # unit + transport integration tests (vitest)
npm run bdd     # BDD scenarios (cucumber) - full stack against a stub LMS, no real server needed
LMS_URL=http://<lms-host>:9000 npm run smoke   # read-only checks against the real LMS
LMS_URL=http://<lms-host>:9000 npm run dev
claude mcp add --transport http lms http://localhost:3000/mcp
```

The BDD suite in `features/` is the end-to-end check: real MCP client, real HTTP transport, real play recorder, against the stateful stub in `test/stub/lms-stub.ts`. Nothing there touches the real server, so playback scenarios are safe to run any time. `npm run smoke` is the only thing that talks to the real LMS, and it never sends playback commands.

## Docker

```sh
docker compose up --build
```

CI (GitHub Actions) runs the test suites and pushes `ghcr.io/sixeyed/lms-mcp-server` with `latest` and `sha-*` tags on every push to main. No registry secrets needed - it authenticates with the workflow's `GITHUB_TOKEN`.

## Deployment

Notes for running on Kubernetes (or any orchestrator):

- Image: `ghcr.io/sixeyed/lms-mcp-server` (public package).
- `LMS_URL` must be set - the server refuses to start without it.
- Single replica (`strategy: Recreate`) - the play-history poller must not run twice or plays are double-recorded.
- RWO persistent volume mounted at `/data` for the history file.
- Probes: liveness `GET /healthz`, readiness `GET /readyz`.

## Clients

- **Claude Code** (LAN): `claude mcp add --transport http lms http://<host>:3000/mcp`; if you serve it over HTTPS with a private CA, set `NODE_EXTRA_CA_CERTS`.
- **Claude Desktop**: custom connectors are proxied through Anthropic's cloud so a LAN-only server is unreachable - use a local stdio bridge in `claude_desktop_config.json`:
  ```json
  { "mcpServers": { "lms": { "command": "npx", "args": ["mcp-remote", "http://<host>:3000/mcp", "--allow-http"] } } }
  ```
- **Claude iPhone app**: not supported - would need public HTTPS exposure, and this server has no auth.