TuneTidy

Hosted ChatGPT ↔ Spotify control — a small Connect website + MCP server so ChatGPT can act on your Spotify account.

Spotify stays the music app. TuneTidy is the middle layer: link once, then control playlists, playback (including exact-cue seek), and optional offline ZIP export from chat.

Not a Spotify clone. Not a self-host Docker product for end users. You (operator) deploy once; everyone else just Connects.

What it does

Capabilities (Milestone A)

• Connect site — Spotify OAuth (Authorization Code), encrypted token storage

• Playlist control — list, create, add/remove tracks, update details

• Playback — play / pause / seek / now-playing; exact-cue (beat-drop seek with confirmation)

• Offline export — Spotify metadata → match on JioSaavn/Gaana APIs → ZIP download
  (not Spotify stream ripping)

• Safety — write tools need confirmationToken + idempotencyKey; AES-256-GCM for tokens

Related MCP server: spotify-mcp-server

Architecture

Browser  ──►  apps/web   (Next.js Connect + OAuth)
ChatGPT  ──►  apps/mcp   (Fastify JSON-RPC MCP @ POST /mcp)
                 │
                 ▼
           packages/core  (use cases)
                 │
     ┌───────────┼───────────┐
     ▼           ▼           ▼
 packages/   packages/   packages/
  spotify       db        saavn
     │           │           │
 Spotify API  Postgres   Saavn/Gaana APIs

MCP tools (17)

Endpoint: POST /mcp (JSON-RPC). Also: GET /mcp, GET /tools.

Full contracts: docs/MCP_TOOL_CATALOG.md.

Quick start (local)

Requirements: Node ≥ 22, pnpm 9, Postgres (Docker optional).

# 1. Install
pnpm install

# 2. Env
cp .env.example .env
# Generate encryption key:
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
# Set TOKEN_ENCRYPTION_KEY_CURRENT and DATABASE_URL

# 3. Database
docker compose up -d          # optional local Postgres
pnpm db:migrate
# pnpm db:seed               # optional

# 4. Run
pnpm dev:web                  # http://127.0.0.1:3000
pnpm dev:mcp                  # http://127.0.0.1:3100

Minimum env for local Connect + MCP

Auth0 vars are required for production-style login; dev bypass skips MCP Bearer checks.

See .env.example for the full list (Saavn URLs, cover storage, classifier stubs, etc.).

Smoke MCP (dev bypass)

curl -s -X POST http://127.0.0.1:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Deploy — free multi-user (recommended)

Don’t use paid Render Postgres. Use Convex free for encrypted Spotify tokens:

1. npx convex dev / npx convex deploy (see docs/CONVEX_FREE_MULTIUSER.md)

2. Render 2 free Web Services: tunetidy-web + tunetidy-mcp (no Postgres service)

3. Env: STORAGE_BACKEND=convex, CONVEX_URL, CONVEX_SERVER_KEY, encryption key, Spotify app

4. Users open Connect → Link Spotify once → ChatGPT uses MCP

Scripts

Security & compliance

• Spotify refresh/access tokens are encrypted at rest; tools never return them.

• Destructive writes are confirmation + idempotency gated.

• Offline export uses third-party catalog APIs (Saavn-compatible / Gaana). Not official Spotify Offline. Operators are responsible for ToS/legal fit in their region.

• Never commit .env — only .env.example.

More: docs/SECURITY.md.

Docs

Planning source (optional): .planning/, archive PRDs under all_raw_infos/.

Status

License

Private / unlicensed unless you add a license file. Spotify, JioSaavn, Gaana, Auth0, and ChatGPT are trademarks of their respective owners; this project is an independent companion stack.