# @cassette.diy/mcp

MCP server for **Cassette** (music releases) and **Cassette for Creators** (short-form clips). Lets AI assistants in Cursor, Claude Desktop, and other MCP clients manage your Cassette account via personal access tokens.

**npm:** https://www.npmjs.com/package/@cassette.diy/mcp  
**Docs:** https://cassette.diy/docs/mcp

## Install

Published on npm. No separate install step when using Cursor — `npx` downloads the package on first run:

```bash
npx -y @cassette.diy/mcp
```

1. A Cassette or Creator account with **Google Drive linked** (required for uploads).
2. A **personal access token** from the web app:
   - Music app: **Settings → API / AI access**
   - Creator app: **Settings → API / AI access**

## Cursor setup

Add to your Cursor MCP config (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "cassette": {
      "command": "npx",
      "args": ["-y", "@cassette.diy/mcp"],
      "env": {
        "CASSETTE_API_URL": "https://api.cassette.diy",
        "CASSETTE_API_TOKEN": "ct_live_YOUR_TOKEN_HERE",
        "CASSETTE_PRODUCT": "both"
      }
    }
  }
}
```

You can copy a ready-made snippet from Settings after creating a token.

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CASSETTE_API_URL` | No | Backend URL (default: `http://localhost:8080`) |
| `CASSETTE_API_TOKEN` | Yes | Personal access token (`ct_live_…`) |
| `CASSETTE_PRODUCT` | No | `music`, `creator`, or `both` (default: `both`) — controls which tools are registered |

## Local development

From the monorepo:

```bash
cd cassette-mcp
npm install
npm run build
```

Point Cursor at the local package:

```json
{
  "mcpServers": {
    "cassette": {
      "command": "node",
      "args": ["/absolute/path/to/Cassette/cassette-mcp/dist/index.js"],
      "env": {
        "CASSETTE_API_URL": "http://localhost:8080",
        "CASSETTE_API_TOKEN": "ct_live_...",
        "CASSETTE_PRODUCT": "both"
      }
    }
  }
}
```

## Tool catalog

Set `CASSETTE_PRODUCT` to `music`, `creator`, or `both` (default: `both`).

### Shared

| Tool | Description |
|------|-------------|
| `cassette_get_account` | Profile, Drive link status, tiers |
| `cassette_start_gdrive_link` | OAuth URL to link Google Drive |
| `cassette_search_users` | Find users for invites (creator mode only) |

### Music — track creation workflow

Focused tools for musicians: create a release end-to-end (no delete, collaboration, or Drive sync).

| Tool | Description |
|------|-------------|
| `cassette_create_track` | Create track (name, artist, release date) |
| `cassette_upload_track_file` | Upload artwork, audio, promo, footages, vertical videos |
| `cassette_update_track_metadata` | Metadata, Spotify pitch, notes |
| `cassette_list_track_files` | List uploaded files by category |
| `cassette_get_track` | Get full track after creation |

### Creators

Full clip workflow (unchanged):

| Tool | Description |
|------|-------------|
| `cassette_get_creator_billing` | Tier, limits, clip count |
| `cassette_list_clips` | List clips |
| `cassette_get_clip` / `create_clip` / `update_clip` / `delete_clip` | Clip CRUD |
| `cassette_update_scenario` | Scenario time blocks |
| `cassette_update_clip_notes` | Freeform notes |
| `cassette_list_trends` / `create_trend` / `delete_trend` | Trend library |
| `cassette_start_clip_from_trend` | New clip from trend |
| `cassette_list_footages` / `upload_footage` / `review_footage` / `delete_footage` | Footages |
| `cassette_get_final` / `upload_final` / `update_post_links` | Final video & links |
| `cassette_manage_clip_shares` | Collaboration |

## Uploads

Upload tools read files from **`local_path`** on the machine running the MCP server (your computer when using stdio in Cursor).

- **< 10 MB** — direct multipart upload
- **10–20 MB** — async upload + task polling
- **> 20 MB** (tracks) — chunked upload + task polling

If Drive is not linked, upload tools fail; use `cassette_start_gdrive_link` first.

## Token scopes

| Scope | Access |
|-------|--------|
| `music:read` | GET on `/tracks/*` |
| `music:write` | Mutations on `/tracks/*` |
| `creator:read` | GET on `/creator/*` |
| `creator:write` | Mutations on `/creator/*` |

Tokens cannot access admin, Stripe checkout, analytics, or token management endpoints.

## Publish checklist

- [ ] Deploy backend with `api_tokens` collection and routes
- [ ] Verify token create/list/revoke in staging Settings UI
- [ ] Smoke-test MCP tools against staging API
- [x] Publish `@cassette.diy/mcp` to npm (v0.1.0)
- [ ] Set production `CASSETTE_API_URL` in docs
- [ ] Optional: track `mcp_token_created` analytics event

## License

UNLICENSED — internal Cassette package.