{"_id":"@daniel-aquino/djai","_rev":"3-5cc31fe5665f01951eea6988da0b5a5a","name":"@daniel-aquino/djai","dist-tags":{"latest":"0.5.2"},"versions":{"0.5.0":{"name":"@daniel-aquino/djai","version":"0.5.0","keywords":["mcp","spotify","model-context-protocol","playlist","music","djai"],"license":"MIT","_id":"@daniel-aquino/djai@0.5.0","maintainers":[{"name":"daniel-aquino","email":"danielaquinosantiago04@gmail.com"}],"homepage":"https://github.com/DanielAquino2003/DJ.AI#readme","bugs":{"url":"https://github.com/DanielAquino2003/DJ.AI/issues"},"bin":{"djai":"dist/cli.js","djai-auth":"dist/auth.js"},"dist":{"shasum":"ee94c092790e148c0c250fe3d1c4b859826f1b02","tarball":"https://registry.npmjs.org/@daniel-aquino/djai/-/djai-0.5.0.tgz","fileCount":24,"integrity":"sha512-4kxSiKG4aWenA6RHW7RSyclDE28k01d5CluPBhFBjeVetAWT7INuT2Cz5KVJ6xgzPYF/X9LGKvXCoS0VeVbDeA==","signatures":[{"sig":"MEUCIQCSKbN9yU+j/XcJViuLpvh+8iBMaLKeS5gSoT1Qb/jJDgIgSToR0RvpyAxdfuzQfNG+mLWTtdasruyV+a4eekg44Ig=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":132168},"type":"module","engines":{"node":">=20"},"gitHead":"7804ed6efabefd95d8587e5c7b07a79d4042d9ed","scripts":{"dev":"tsx src/server.ts","auth":"tsx src/auth.ts","test":"npm run typecheck && tsx --test tests/*.test.ts","build":"tsc","start":"node dist/server.js","prepack":"npm run build","typecheck":"tsc --noEmit"},"_npmUser":{"name":"daniel-aquino","email":"danielaquinosantiago04@gmail.com"},"repository":{"url":"git+https://github.com/DanielAquino2003/DJ.AI.git","type":"git"},"_npmVersion":"11.11.1","description":"DJAI: Spotify MCP server for agent-controlled playback, playlist workflows, and prompt-based music curation.","directories":{},"_nodeVersion":"20.19.6","dependencies":{"zod":"^3.25.67","dotenv":"^17.4.2","@modelcontextprotocol/sdk":"^1.15.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","typescript":"^5.5.4","@types/node":"^20.14.10"},"_npmOperationalInternal":{"tmp":"tmp/djai_0.5.0_1782566853566_0.5537347622673343","host":"s3://npm-registry-packages-npm-production"}},"0.5.1":{"name":"@daniel-aquino/djai","version":"0.5.1","keywords":["mcp","spotify","model-context-protocol","playlist","music","djai"],"license":"MIT","_id":"@daniel-aquino/djai@0.5.1","maintainers":[{"name":"daniel-aquino","email":"danielaquinosantiago04@gmail.com"}],"homepage":"https://github.com/DanielAquino2003/DJ.AI#readme","bugs":{"url":"https://github.com/DanielAquino2003/DJ.AI/issues"},"bin":{"djai":"dist/cli.js","djai-auth":"dist/auth.js"},"dist":{"shasum":"4a464251e88abc0923a4e92cd500cbc6a2cd4c1b","tarball":"https://registry.npmjs.org/@daniel-aquino/djai/-/djai-0.5.1.tgz","fileCount":30,"integrity":"sha512-RUiItPlBpD7YIqkoejnmgCw9BCuASRNNreTkE3NU5uPqpzJNpl/PiHpggIU4lzq1D6WBiDVqnbYOZqV1nI0WDQ==","signatures":[{"sig":"MEQCICdKNqCo25nk2NJdPJVVe+qY1mwM0ZEgtVjdCPp1CjUdAiBz22Eo+ghMKakwMB9zRreGieP0Yw68zuc1FEPTe1B8+A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":135581},"type":"module","engines":{"node":">=20"},"gitHead":"ae9c06d4714aea13852c00bea69687cf3c262e7b","scripts":{"dev":"tsx src/server.ts","auth":"tsx src/auth.ts","test":"npm run typecheck && tsx --test tests/*.test.ts","build":"tsc","start":"node dist/server.js","prepack":"npm run build","typecheck":"tsc --noEmit","postinstall":"node dist/postinstall.js || true"},"_npmUser":{"name":"daniel-aquino","email":"danielaquinosantiago04@gmail.com"},"repository":{"url":"git+https://github.com/DanielAquino2003/DJ.AI.git","type":"git"},"_npmVersion":"11.11.1","description":"DJAI: Spotify MCP server for agent-controlled playback, playlist workflows, and prompt-based music curation.","directories":{},"_nodeVersion":"20.19.6","dependencies":{"zod":"^3.25.67","dotenv":"^17.4.2","@modelcontextprotocol/sdk":"^1.15.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","typescript":"^5.5.4","@types/node":"^20.14.10"},"_npmOperationalInternal":{"tmp":"tmp/djai_0.5.1_1782577501387_0.9383833388809413","host":"s3://npm-registry-packages-npm-production"}},"0.5.2":{"name":"@daniel-aquino/djai","version":"0.5.2","description":"DJAI: Spotify MCP server for agent-controlled playback, playlist workflows, and prompt-based music curation.","type":"module","bin":{"djai":"dist/cli.js","djai-auth":"dist/auth.js"},"scripts":{"build":"tsc","dev":"tsx src/server.ts","auth":"tsx src/auth.ts","start":"node dist/server.js","typecheck":"tsc --noEmit","test":"npm run typecheck && tsx --test tests/*.test.ts","prepack":"npm run build","postinstall":"node dist/postinstall.js || true"},"keywords":["mcp","spotify","model-context-protocol","playlist","music","djai"],"license":"MIT","dependencies":{"@daniel-aquino/djai":"^0.5.1","@modelcontextprotocol/sdk":"^1.15.0","dotenv":"^17.4.2","zod":"^3.25.67"},"devDependencies":{"@types/node":"^20.14.10","tsx":"^4.20.3","typescript":"^5.5.4"},"engines":{"node":">=20"},"homepage":"https://github.com/DanielAquino2003/DJ.AI#readme","repository":{"type":"git","url":"git+https://github.com/DanielAquino2003/DJ.AI.git"},"bugs":{"url":"https://github.com/DanielAquino2003/DJ.AI/issues"},"gitHead":"ef85f8e667ba1b9821e8aba5d47248709dc93a49","_id":"@daniel-aquino/djai@0.5.2","_nodeVersion":"20.19.6","_npmVersion":"11.11.1","dist":{"integrity":"sha512-3RQhFxfbup4/ooDgs+S4EsonKaRYoAWnvdBoE0Gf4t6vHbYhMGHkerIBjsR0UkRP3QKhtAWoM3+zDMUIeYzN/g==","shasum":"234e2a8c23d41c3b8385f84cd78248cfcc3c73de","tarball":"https://registry.npmjs.org/@daniel-aquino/djai/-/djai-0.5.2.tgz","fileCount":30,"unpackedSize":136437,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGqqo0hhxZyofEB5pL97WvH27/EBUOCIO6DvOeqM87fVAiAG0T8WSh6YwaM7W9OEDULKtofSK2CLMoB+c9xGBtlp8Q=="}]},"_npmUser":{"name":"daniel-aquino","email":"danielaquinosantiago04@gmail.com"},"directories":{},"maintainers":[{"name":"daniel-aquino","email":"danielaquinosantiago04@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/djai_0.5.2_1782579091296_0.2594751046520687"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-27T13:27:33.433Z","modified":"2026-06-27T16:51:31.552Z","0.5.0":"2026-06-27T13:27:33.716Z","0.5.1":"2026-06-27T16:25:01.531Z","0.5.2":"2026-06-27T16:51:31.426Z"},"bugs":{"url":"https://github.com/DanielAquino2003/DJ.AI/issues"},"license":"MIT","homepage":"https://github.com/DanielAquino2003/DJ.AI#readme","keywords":["mcp","spotify","model-context-protocol","playlist","music","djai"],"repository":{"type":"git","url":"git+https://github.com/DanielAquino2003/DJ.AI.git"},"description":"DJAI: Spotify MCP server for agent-controlled playback, playlist workflows, and prompt-based music curation.","maintainers":[{"name":"daniel-aquino","email":"danielaquinosantiago04@gmail.com"}],"readme":"# DJAI\n\nDJAI is a Spotify MCP server for AI coding agents and desktop MCP clients. It gives tools such as Codex, Claude Code, Cursor, and any stdio-compatible MCP client controlled access to Spotify playback, playlists, saved music, listening history, and prompt-based playlist creation.\n\nWith DJAI, an agent can answer requests like:\n\n```text\nPut on my R&B playlist.\nCreate a 60 minute techno workout playlist.\nFind duplicate tracks in this playlist.\nMake a private playlist from my recently played tracks.\nQueue this song next.\n```\n\nDJAI uses Spotify's supported Web API surfaces and OAuth PKCE. It does not require a Spotify client secret, and it avoids deprecated or restricted Spotify recommendation, audio-feature, and audio-analysis endpoints.\n\n## Features\n\n- Spotify playback control from an MCP client: play, pause, skip, queue, volume, shuffle, repeat, and device transfer.\n- Playlist workflows: list, search, inspect, export, duplicate, merge, deduplicate, and add tracks.\n- Playlist generation from natural-language prompts using Spotify text search and deduplication.\n- Taste and library access: saved tracks, recently played tracks, top tracks, top artists, and followed artists.\n- Auth diagnostics through `spotify_auth_status` and `spotify_doctor`.\n- Secure local OAuth token storage with owner-only file permissions.\n- Simple `npx` setup for Codex and standard stdio MCP configuration for other clients.\n\n## Requirements\n\n- Node.js 20 or newer.\n- A Spotify developer app.\n- Spotify Premium for playback-control actions such as play, pause, queue, skip, volume, shuffle, repeat, and device transfer.\n\nRead-only tools such as playlist inspection and search do not require an active playback device. Playback tools require Spotify Premium and at least one active Spotify device.\n\n## Spotify App Setup\n\nCreate a Spotify app at <https://developer.spotify.com/dashboard> and add this redirect URI exactly:\n\n```text\nhttp://127.0.0.1:8765/callback\n```\n\nCopy the app Client ID. DJAI uses OAuth PKCE, so no client secret is needed.\n\n## Authentication\n\nRun the auth wizard:\n\n```bash\nnpx --package @daniel-aquino/djai djai-auth\n```\n\nPaste your Spotify Client ID when prompted, open the authorization URL, and approve the requested scopes.\n\nYou can also run the wizard non-interactively:\n\n```bash\nnpx --package @daniel-aquino/djai djai-auth --client-id your-spotify-client-id\n```\n\nOr use a custom redirect URI if your Spotify app is configured for it:\n\n```bash\nnpx --package @daniel-aquino/djai djai-auth --client-id your-spotify-client-id --redirect-uri http://127.0.0.1:8765/callback\n```\n\nDJAI stores local files under `~/.djai`:\n\n- `~/.djai/config.json`: non-secret app configuration, including the Spotify Client ID and redirect URI.\n- `~/.djai/token.json`: OAuth access and refresh tokens.\n\nBoth files are written with owner-only permissions on POSIX systems.\n\n## Configure Codex\n\nRun:\n\n```bash\nnpx --package @daniel-aquino/djai djai setup codex\n```\n\nThis updates `~/.codex/config.toml` with:\n\n```toml\n[mcp_servers.djai]\ncommand = \"npx\"\nargs = [\"-y\", \"@daniel-aquino/djai\"]\nstartup_timeout_sec = 10\ntool_timeout_sec = 120\n```\n\nRestart Codex and run:\n\n```text\n/mcp\n```\n\nYou should see `djai` in the MCP server list.\n\n## Configure Other MCP Clients\n\nUse DJAI as a stdio MCP server:\n\n```json\n{\n  \"mcpServers\": {\n    \"djai\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@daniel-aquino/djai\"]\n    }\n  }\n}\n```\n\nIf your client supports longer-running tools, set a timeout of at least 120 seconds. Playlist generation and playlist-copy operations can require multiple Spotify API calls.\n\n## CLI Commands\n\n```bash\nnpx --package @daniel-aquino/djai djai\n```\n\nStarts the MCP server over stdio.\n\n```bash\nnpx --package @daniel-aquino/djai djai setup codex\n```\n\nAdds or updates the DJAI MCP server block in Codex config.\n\n```bash\nnpx --package @daniel-aquino/djai djai help\n```\n\nPrints CLI usage.\n\n```bash\nnpx --package @daniel-aquino/djai djai-auth\n```\n\nRuns the Spotify OAuth setup wizard.\n\n## MCP Tools\n\n### Diagnostics\n\n- `spotify_auth_status`: checks token path, expiry, granted scopes, missing scopes, and reauthorization guidance without exposing token values.\n- `spotify_doctor`: runs non-destructive checks for auth, profile, devices, playlists, top tracks, and recently played access.\n\n### Playback and Devices\n\n- `spotify_get_current_playback`: returns the currently playing track or playback state.\n- `spotify_get_playback_state`: returns device, shuffle, repeat, progress, and context details.\n- `spotify_get_devices`: lists available Spotify playback devices.\n- `spotify_play`: starts or resumes playback from tracks or a context URI.\n- `spotify_play_playlist_by_name`: finds one of your playlists by name and starts playback.\n- `spotify_pause`: pauses playback.\n- `spotify_next_track`: skips to the next track.\n- `spotify_previous_track`: skips to the previous track.\n- `spotify_add_to_queue`: adds a track URI to the playback queue.\n- `spotify_set_volume`: sets playback volume from 0 to 100.\n- `spotify_set_shuffle`: enables or disables shuffle.\n- `spotify_set_repeat`: sets repeat mode to `track`, `context`, or `off`.\n- `spotify_transfer_playback`: transfers playback to one or more device IDs.\n\n### Playlists\n\n- `spotify_list_my_playlists`: lists your playlists with IDs, names, owners, visibility, and track counts.\n- `spotify_search_my_playlists`: searches your playlists by name.\n- `spotify_get_playlist`: returns raw playlist details by playlist ID.\n- `spotify_get_playlist_tracks`: lists playlist tracks with pagination.\n- `spotify_analyze_playlist`: reports duration, duplicate groups, unique tracks, and frequent artists.\n- `spotify_export_playlist`: exports a playlist as markdown, CSV, or JSON text.\n- `spotify_create_playlist`: creates a playlist for the current user.\n- `spotify_add_tracks_to_playlist`: adds track URIs to a playlist.\n- `spotify_duplicate_playlist`: copies a playlist into your library.\n- `spotify_merge_playlists`: merges multiple playlists into a new deduplicated playlist.\n- `spotify_remove_duplicate_playlist_tracks`: removes duplicate playlist tracks, keeping the first occurrence.\n- `spotify_create_playlist_from_recently_played`: creates a playlist from recently played tracks.\n- `spotify_create_playlist_from_top_tracks`: creates a playlist from top tracks for short, medium, or long term.\n- `spotify_create_playlist_like_playlist`: creates a new playlist using text-search similarity to a source playlist.\n- `spotify_generate_playlist_from_prompt`: creates a playlist from a natural-language prompt.\n\n### Library and Taste\n\n- `spotify_search_tracks`: searches Spotify tracks by text query.\n- `spotify_get_saved_tracks`: lists saved or liked tracks.\n- `spotify_save_tracks`: saves tracks to your library.\n- `spotify_get_recently_played`: lists recently played tracks.\n- `spotify_get_top_tracks`: lists top tracks for `short_term`, `medium_term`, or `long_term`.\n- `spotify_get_top_artists`: lists top artists for `short_term`, `medium_term`, or `long_term`.\n- `spotify_get_followed_artists`: lists followed artists.\n\n## Prompt-Based Playlist Generation\n\n`spotify_generate_playlist_from_prompt` turns natural-language prompts into Spotify playlists. It infers activity, genre hints, duration, and search queries, then deduplicates tracks by Spotify track ID and artist-title pairs.\n\nExample prompts:\n\n```text\nGenerate a 45 minute drum and bass running playlist.\nCreate a private chill jazz focus playlist for 2 hours.\nMake a techno workout playlist and start playback.\n```\n\nThe generator uses Spotify text search. It does not use restricted recommendation, audio-feature, or audio-analysis endpoints.\n\n## Environment Variables\n\nDJAI works without environment variables after `djai-auth`, but these overrides are supported:\n\n- `SPOTIFY_CLIENT_ID`: Spotify app Client ID.\n- `SPOTIFY_REDIRECT_URI`: redirect URI configured in your Spotify app.\n- `DJAI_CONFIG_PATH`: path to DJAI config JSON. Defaults to `~/.djai/config.json`.\n- `DJAI_TOKEN_PATH`: path to DJAI token JSON. Defaults to `~/.djai/token.json`.\n- `SPO_MCP_TOKEN_PATH`: legacy token path override kept for compatibility.\n\n## Security and Privacy\n\nDJAI stores OAuth credentials locally and does not send them anywhere except Spotify's official OAuth and Web API endpoints. Tool responses intentionally avoid exposing raw token values.\n\nIf scopes change or Spotify reports insufficient scope, reauthorize:\n\n```bash\nrm ~/.djai/token.json\nnpx --package @daniel-aquino/djai djai-auth\n```\n\nIf you are developing from source, use:\n\n```bash\nrm ~/.djai/token.json\nnpm run auth\n```\n\n## Troubleshooting\n\nRun diagnostics from your MCP client:\n\n```text\nspotify_doctor\n```\n\nCommon issues:\n\n- `No active device found`: open Spotify on a desktop, phone, or web player, start any playback once, then retry or transfer playback to that device.\n- `Spotify Premium required`: playback control endpoints require a Premium account.\n- `Missing Spotify client ID`: run `npx --package @daniel-aquino/djai djai-auth` or set `SPOTIFY_CLIENT_ID`.\n- `Insufficient client scope`: remove `~/.djai/token.json`, run auth again, and restart your MCP client.\n- `Redirect URI mismatch`: make sure the Spotify app contains `http://127.0.0.1:8765/callback` exactly.\n\n## Development\n\nClone the repository and install dependencies:\n\n```bash\ngit clone https://github.com/DanielAquino2003/DJ.AI.git\ncd DJ.AI\nnpm install\n```\n\nRun auth from source:\n\n```bash\nnpm run auth\n```\n\nStart the MCP server from source:\n\n```bash\nnpm run dev\n```\n\nBuild and validate:\n\n```bash\nnpm test\nnpm run build\nnpm pack --dry-run\n```\n\nThe test suite covers config resolution, OAuth token storage, Codex config updates, required Spotify scopes, Spotify client request behavior, playback response handling, and missing-scope guidance.\n\n## Package Contents\n\nPublished packages include only:\n\n- `dist`\n- `README.md`\n- `LICENSE`\n\nSource files and tests stay out of the npm tarball.\n\n## Disclaimer\n\nDJAI is not affiliated with, endorsed by, or sponsored by Spotify. Spotify is a trademark of Spotify AB. Use of DJAI is subject to Spotify's developer terms and the permissions granted by your Spotify account.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}