<p align="center">
  <img src="docs/demo.svg" alt="AUX demo — rainy 2am drive" width="920" />
</p>

<h1 align="center">AUX</h1>
<p align="center"><strong>Spotify, for your AI.</strong><br/>Not a remote. A DJ that talks back.</p>

<p align="center">
  <a href="https://github.com/brian-mwirigi/aux-mcp"><img alt="GitHub" src="https://img.shields.io/badge/github-brian--mwirigi%2Faux--mcp-1DB954?style=flat-square" /></a>
  <img alt="npm" src="https://img.shields.io/badge/npx-spotify--aux-111?style=flat-square" />
  <img alt="hooks" src="https://img.shields.io/badge/hooks-peak-ff2d55?style=flat-square" />
</p>

```bash
npx -y spotify-aux demo
npx -y spotify-aux login
```

Then in Cursor: *“rainy 2am drive”* · *“roast my top tracks”* · *“start auto DJ”*

---

## 60-second setup

1. [Spotify Dashboard](https://developer.spotify.com/dashboard) → create app  
2. Redirect URI (exact):

```
http://127.0.0.1:7654/callback
```

(Optional roast site later: also add `http://127.0.0.1:7656/`)

3. Install & login:

```bash
npm i -g spotify-aux
# or: git clone … && npm i && npm run build
export SPOTIFY_CLIENT_ID=…
export SPOTIFY_CLIENT_SECRET=…
npx -y spotify-aux login
```

4. Cursor MCP config:

```json
{
  "mcpServers": {
    "aux": {
      "command": "npx",
      "args": ["-y", "spotify-aux"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_id",
        "SPOTIFY_CLIENT_SECRET": "your_secret"
      }
    }
  }
}
```

From a local clone, point `command`/`args` at `node` + `dist/server.js` instead.

---

## Peak hooks

| Say this | What happens |
|----------|----------------|
| *rainy 2am drive* | `vibe` — LLM invents searches, catalog DJ |
| *music Spotify won’t show me* | `vibe` + `anti_algorithm` |
| *DJ for right now* | `context_vibe` — time + weather |
| *keep it going* | `auto_dj_start` → `npx spotify-aux autodj` |
| *roast my week* | `weekly_report` |
| *party room* | `party_room_create` + friend relay |
| *roast this playlist* (no Cursor) | `npx spotify-aux web` |

Every hook can drop an **ASCII card** made for screenshots.

### Party with friends

```bash
# host machine
npx -y spotify-aux party-host
# tunnel it, e.g. cloudflared tunnel --url http://127.0.0.1:7655

# everyone
export AUX_PARTY_RELAY=https://your-tunnel.example
```

Then `party_room_create` → share the **code** → friends `party_room_add` / `party_room_vote`.

### Roast site (no MCP)

```bash
npx -y spotify-aux web
# open http://127.0.0.1:7656
```

---

## Full tool map

See [Architecture](docs/architecture.md) for the tool-module, Spotify endpoint,
authentication, and vibe-pipeline map.

<details>
<summary><strong>Peak / viral</strong></summary>

`vibe` · `context_vibe` · `weekly_report` · `auto_dj_start` · `auto_dj_tick` · `auto_dj_stop` · `auto_dj_status` · `party_room_create` · `party_room_join` · `party_room_add` · `party_room_vote` · `party_room_play_winner` · `set_mood` · `adjust_playlist_vibe` · `roast_my_playlist` · `playlist_dna` · `aux_battle` · `blend_tastes` · `music_compatibility` · `whats_playing_story` · `party_*` · `record_taste_feedback` · `get_taste_memory` · `auth_status`
</details>

<details>
<summary><strong>Spotify coverage</strong></summary>

Search, browse, playback, playlists, library, personalization — full Web API surface so the agent never stalls mid-task.
</details>

---

## CLI

```bash
npx -y spotify-aux              # MCP server
npx -y spotify-aux login
npx -y spotify-aux status
npx -y spotify-aux autodj       # refill loop
npx -y spotify-aux party-host   # friend relay :7655
npx -y spotify-aux web          # roast site :7656
npx -y spotify-aux demo
```

After `npm i -g spotify-aux`, binaries: `spotify-aux` and `aux-mcp`.

---

## Auth

| Flow | Unlocks |
|------|---------|
| Client ID + Secret | Search / catalog |
| `npx spotify-aux login` | Playback, library, hooks, Auto-DJ |

Tokens → `~/.aux-mcp/`. Premium + open Spotify app for playback.

---

## OpenClaw

Register AUX as an OpenClaw-managed MCP server + install the skill:

```bash
npx -y spotify-aux openclaw

openclaw mcp add aux \
  --command npx \
  --arg -y \
  --arg spotify-aux \
  --env SPOTIFY_CLIENT_ID="$SPOTIFY_CLIENT_ID" \
  --env SPOTIFY_CLIENT_SECRET="$SPOTIFY_CLIENT_SECRET"

openclaw mcp doctor aux --probe
```

ClawHub: [`@brian-mwirigi/aux-mcp`](https://clawhub.ai/brian-mwirigi/aux-mcp) · skill: [`skills/aux-mcp/SKILL.md`](./skills/aux-mcp/SKILL.md) · [docs/openclaw.md](./docs/openclaw.md)

## Contributing

PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) and open [`good first issue`](https://github.com/brian-mwirigi/aux-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)s.

Site: [brianmunene.me/aux-mcp](https://brianmunene.me/aux-mcp)

## Star it. Pass the aux.

[github.com/brian-mwirigi/aux-mcp](https://github.com/brian-mwirigi/aux-mcp)

MIT