MeloPulse

Local coding playlists for MCP agents.

npx @melolab/melopulse recommend

MeloPulse reads safe Git metadata locally, recommends from a local catalogue, and opens playlists in MeloLab or your music app. Recommendation does not upload code or require an account.

What it does

MeloPulse is an offline-first playlist recommender for coding sessions. It includes a small local catalogue, lets you import HTTPS playlist links with local tags, and can explicitly synchronize MeloLab's public catalogue into a local cache. It returns playlist URLs; your browser or music app handles playback.

It does not generate music, store audio, authenticate users, use OAuth, control a player, monitor repositories in the background, send telemetry, or fetch provider metadata. The only network operation is an explicit sync request to MeloLab.

Install and use

The package is not published until a separate release action occurs. Until then, run from a local checkout with npm run build and node dist/cli/index.js <command>.

Once published, use the CLI with npx:

npx -y @melolab/melopulse recommend --activity debugging
npx -y @melolab/melopulse recommend --no-git --json

CLI commands

Command	Purpose
melopulse add <playlist-url>	Import an HTTPS playlist link into the local catalogue. Use --title, --activity, --mood, --energy, --focus, and --vocals to set local tags.
melopulse sync	Explicitly download MeloLab's public featured catalogue and update the local cache.
melopulse recommend	Return up to three local recommendations. Git context is enabled by default; use --no-git to disable it.
melopulse play <playlist-id>	Hand a selected playlist URL to the operating system's default browser or registered music app.
melopulse mcp	Start the MCP server over standard input/output.

recommend accepts --activity, --mood, --energy, --focus, --vocals, --limit, and --json. Recommendation uses the bundled catalogue, your local link imports, and any cached MeloLab sync; it does not query streaming providers.

MCP tools

The MCP server exposes exactly four tools:

Tool	Purpose
melopulse_recommend	Recommend from the local catalogue, optionally using safe Git context.
melopulse_add_playlist	Import and tag an HTTPS playlist link locally.
melopulse_list_playlists	List local catalogue entries, optionally filtered by source.
melopulse_sync_catalog	Explicitly synchronize MeloLab's public catalogue.

See MCP setup and copy the ready-made configurations in examples.

Supported playlist links

MeloPulse accepts HTTPS links and recognizes MeloLab, Spotify, Apple Music, and YouTube Music links. Other HTTPS playlist links are stored as generic. Link import only saves the URL and your local tags; it does not retrieve provider metadata or audio.

Local storage and privacy

The local catalogue is stored in the platform configuration directory, or in MELOPULSE_CONFIG_DIR when set. It contains playlists.json for local imports and melolab-catalog-cache.json for the last explicit MeloLab sync.

When Git context is enabled, MeloPulse reads only safe metadata from the chosen workspace. It never uploads repository contents, source code, file contents, remote URLs, credentials, or audio. Read the complete privacy boundary.

MeloLab relationship

MeloPulse is a local recommender that can hand off a MeloLab playlist URL to your browser or app. MeloLab sync is opt-in and happens only when you run melopulse sync or call melopulse_sync_catalog; there is no background synchronization, account connection, OAuth, or provider integration.

Development

npm ci
npm run verify
npm run smoke:pack
npm pack --dry-run

The packed-install smoke test builds an npm tarball, installs it in a temporary directory, runs recommend --no-git --json, verifies a recommendation is returned, and cleans up both locations.

Contributing and security

Please read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md before participating.

License

MIT © 2026 Tover0314