JamRelay v1.2.0

JamRelay v1.2.0

Multi-provider music automation, without making one provider the center of the system.

JamRelay v1.2.0 is the largest architectural release so far.
The project moves from a Spotify-first MCP server to a provider-neutral music automation platform with explicit provider connections, capability-aware operations, cross-provider playlist workflows, stronger authorization boundaries, and safer persistence.

---

✦ What changed

Area	v1.2.0
Providers	Spotify, SoundCloud, Apple Music, YouTube
Architecture	Provider Registry + capability model
Connections	Multiple provider connections with explicit targeting
Transfers	Cross-provider playlist planning and execution
Identity	Canonical tracks + provider-specific mappings
Security	Owner sessions, CSRF, MCP grants, encrypted provider credentials
Persistence	Provider-aware state, snapshots, rate limits, errors, history
Playlists	Import/export, chapters, safer automation
Startup	Zero-provider boot is supported
Health	Provider-neutral server health semantics

---

Multi-provider foundation

JamRelay is no longer architecturally tied to Spotify.

The new provider layer introduces:

• Provider Registry
• explicit provider connections
• stable connection IDs
• capability discovery
• multiple connections per provider
• provider-aware reads and writes
• canonical track identities
• provider-specific mappings

Write operations now fail closed when the destination is missing or ambiguous instead of silently selecting another provider.

A JamRelay instance can also boot and remain healthy with zero configured music providers.

---

Provider support

Spotify

Spotify remains fully supported, but it now lives behind the same provider abstraction as the rest of the platform.

Supported areas include:

• catalog access
• playlists
• library operations
• playback
• history-related workflows
• playlist writes
• provider-aware connection targeting

The canonical Spotify callback route is now:

/auth/providers/spotify/callback

Compatibility handling may still exist for the previous Spotify callback route where supported.

---

SoundCloud

Initial SoundCloud integration adds:

• OAuth authentication
• identity access
• catalog operations
• playlist operations

Capabilities are modeled explicitly, so JamRelay no longer assumes that every provider behaves like Spotify.

---

Apple Music

Apple Music uses a deliberately separate authentication model:

• Developer Token
• Media Services .p8 private key
• Music User Token

JamRelay keeps server-side developer credentials separate from user authorization.

This avoids pretending Apple Music is just another Spotify-style OAuth provider.

---

YouTube

YouTube support uses the official YouTube Data API.

JamRelay treats YouTube playlists as collections of videos and does not present the integration as an unofficial YouTube Music API.

---

TIDAL

TIDAL remains feasibility-only.

There is currently no runtime TIDAL provider.

---

Cross-provider playlist transfers

JamRelay can now plan and execute playlist transfers across supported providers.

The transfer system includes:

• source and destination connection selection
• canonical track matching
• provider-specific identity mapping
• unresolved-track reporting
• capability validation
• execution planning
• snapshots
• rollback-aware safety

A playlist transfer is no longer treated as “copy these Spotify IDs somewhere else”.

Instead, JamRelay resolves a provider-neutral identity and maps it to the destination service.

---

Canonical resolution

v1.2.0 introduces a provider-neutral canonical resolver.

The same logical track can now be represented by:

• one canonical identity
• multiple provider-specific identities
• persistent provider mappings

This architecture powers:

• cross-provider transfers
• provider-neutral import/export
• safer playlist automation
• connection-aware persistence
• future provider integrations

---

Playlist import & export

Import/export is now provider-neutral.

JamRelay can preserve portable playlist metadata while retaining provider-specific identifiers where useful.

This makes playlists easier to:

• move between services
• inspect
• archive
• restore
• reuse in automation workflows

---

Playlist chapters

Playlist chapters are now persisted as first-class state.

They allow large playlists to be divided into meaningful logical sections while keeping ordering and chapter metadata available across supported operations.

---

Playlist automation

Automation received a major safety pass.

Improvements include:

• stronger integrity verification
• provider-aware targeting
• snapshots before mutation
• rollback attempts
• durable job integration
• duration-based playlist extension
• safer handling of destructive operations

The core rule remains simple:

JamRelay should know how to recover before it changes something important.

---

Connection Hub

JamRelay now includes an owner-facing control surface for provider and MCP access management.

It supports:

• provider connections
• connection status
• preferred connection roles
• authorized MCP clients
• connection-scoped grants
• system diagnostics
• provider onboarding

The Connection Hub is operational tooling, not a replacement for the MCP interface.

---

Authentication boundaries

v1.2.0 separates three different trust boundaries that previously risked being conflated:

1. MCP authentication

Controls which MCP clients can access JamRelay.

2. Owner authentication

Controls administrative access to JamRelay itself.

3. Provider authentication

Controls access to Spotify, SoundCloud, Apple Music, YouTube, and future providers.

These are now intentionally independent.

---

MCP authorization

MCP clients can now be restricted to specific provider connections and permissions.

This introduces:

• connection ACLs
• explicit grants
• read/write separation
• provider-scoped access
• safer destructive operations

Clients no longer implicitly gain access to every configured provider connection.

---

Provider-aware persistence

The database layer now understands providers and connections directly.

v1.2.0 adds migrations for:

• provider-aware application state
• provider-aware playlist snapshots
• generic resolver attempts
• connection-scoped rate limits
• connection-scoped provider API errors
• canonical listening history
• playlist chapters

Historical migrations remain immutable.

---

Encrypted credential storage

The old Spotify-only token storage model has been replaced by a shared encrypted provider credential store.

The primary runtime path is now:

PROVIDER_CREDENTIAL_STORE_PATH

Provider credentials are stored per connection and encrypted at rest using the existing JamRelay credential protection model.

---

Security improvements

This release strengthens the trust model across the project.

Highlights include:

• owner sessions
• CSRF protection
• MCP OAuth grants
• connection-scoped permissions
• encrypted provider credentials
• fail-closed write targeting
• stronger secret/token redaction
• explicit provider authentication boundaries

---

Health & deployment

Provider connectivity is no longer treated as application health.

JamRelay may be fully healthy even when:

• Spotify is disconnected
• another provider is disconnected
• no provider is configured

Health now reflects the state of the JamRelay server and its database instead of requiring one specific music service.

---

Breaking / behavioral changes

Please review these before upgrading:

• Spotify is no longer required at startup.
• Writes must resolve to an explicit or unique capable connection.
• Spotify IDs are no longer treated as universal music identifiers.
• Provider credentials now use the multi-provider credential store.
• Provider auth routes are organized under /auth/providers/....
• Provider capabilities are not assumed to be identical.
• Zero-provider startup is a valid supported state.

---

Upgrade notes

Before upgrading:

1. Back up the JamRelay database.
2. Back up provider credentials.
3. Back up MCP OAuth state.
4. Keep your encryption and owner secrets safe.
5. Update provider callback URLs where required.
6. Run the full validation suite before deployment.

Startup applies new forward-only migrations automatically.

There is no automatic down migration.

For Spotify, the production callback should use:

https://mcp.jamrelay.com/auth/providers/spotify/callback

---

Known limitations

Some functionality still depends on live third-party provider behavior and credentials.

Notable limitations:

• provider API quotas still apply
• provider capability parity is not guaranteed
• Apple Music requires its separate token model
• third-party MCP client behavior may vary
• TIDAL is not implemented

---

Release summary

JamRelay v1.2.0 turns the project into a real multi-provider foundation.

Spotify remains important, but it is no longer the architecture itself.

The new model gives JamRelay a cleaner path toward additional services, safer automation, cross-provider interoperability, and finer-grained client permissions without sacrificing self-hosting or explicit control.

---

Full Changelog:
v1.1.0...v1.2.0

JamRelay v1.1.0 — Stateful Music Automation

JamRelay v1.1.0 — Stateful Music Automation

JamRelay v1.1.0 is the largest update since the initial public release.

This release moves JamRelay well beyond being a thin MCP wrapper around Spotify. It introduces a persistent local state layer, database-first track resolution, durable background jobs, rate-limit awareness, reversible playlist operations, rules and recipes, playlist analysis and optimization, local listening history, personalization, rotations, stronger deployment tooling, and a significantly expanded MCP surface.

The runtime now exposes 103 MCP tools across Spotify access, playlist automation, state management, diagnostics, personalization, and higher-level music workflows.

Highlights

Smart playlist automation

JamRelay now includes a dedicated playlist automation layer capable of analyzing, planning, previewing, executing, verifying, and reversing complex playlist transformations.

New playlist capabilities include:

• playlist health analysis
• deterministic smart shuffle
• artist balancing and spacing
• artist-share limits
• semantic duplicate detection
• playlist optimization
• smart insertion
• playlist filtering
• duration-aware trimming and extension
• partial playlist replacement
• playlist freshening
• smart merge and balanced split
• playlist cloning and synchronization
• artist extraction, movement, removal, and replacement
• bulk playlist editing
• operation cost estimation
• playlist comparison and integrity verification

Many mutating operations support dry-run-first execution, allowing an AI client to inspect the intended result before changing Spotify.

Safe and reversible mutations

Playlist writes now have a real safety model instead of being treated as isolated Spotify API calls.

JamRelay can:

• create playlist snapshots before mutation
• store operation plans
• preserve before/after state
• verify playlist integrity after execution
• restore saved snapshots
• undo supported previous operations
• detect mismatches between the expected and actual result

The intended lifecycle for higher-level playlist operations is now:

analyze → plan → dry run → snapshot → execute → verify

This gives AI clients significantly more freedom to perform complex playlist work without blindly applying destructive transformations.

Playlist rules and recipes

JamRelay now supports reusable playlist automation logic.

Rules can express deterministic constraints around playlist structure, while recipes provide persistent reusable configurations for applying those rules and transformations repeatedly.

This makes workflows such as:

• maintain artist spacing
• cap artist concentration
• apply consistent cleanup rules
• reuse a preferred playlist layout
• perform repeatable playlist transformations

possible without rebuilding the operation from scratch every time.

Recipes are persisted in the JamRelay state database and versioned independently of Spotify.

Database-first track resolution

Track resolution has been redesigned around a persistent local resolver.

Instead of immediately calling Spotify Search for every title/artist query, JamRelay now follows a database-first flow:

normalize query → local alias lookup → canonical track lookup → Spotify Search only on miss

Successful matches are persisted for future requests.

The resolver supports:

• normalized track aliases
• canonical Spotify track records
• deterministic matching
• ambiguity detection
• resolver diagnostics
• hit tracking
• passive cache warming from canonical Spotify responses
• alternate resolver fallback when configured
• canonical Spotify validation before accepting external candidates

This significantly reduces repeated Spotify Search usage and allows JamRelay to keep working more effectively when Spotify search limits become restrictive.

Persistent SQLite state database

v1.1.0 introduces JamRelay's first persistent application state database.

SQLite now stores durable state for:

• canonical tracks
• track aliases
• resolver attempts
• normalized Spotify API errors
• rate-limit state
• durable jobs
• job items
• playlist snapshots
• playlist operations
• playlist recipes
• listening events
• rotation definitions

The database runs in WAL mode with foreign-key enforcement and a bounded busy timeout.

Production deployments store it inside the persistent JamRelay data volume rather than the container filesystem.

Forward-only database migrations

JamRelay now includes a proper migration system.

v1.1.0 ships four schema migrations:

• 0001_state_db.sql
• 0002_playlist_engine.sql
• 0003_playlist_recipes.sql
• 0004_personalization_history.sql

Migrations are:

• applied automatically on startup
• ordered deterministically
• executed transactionally
• recorded in schema_migrations
• protected by SHA-256 checksums
• verified again on future startups
• rejected if applied migration files are modified or disappear

The runtime distinguishes database states as:

• current
• ahead
• behind

The migration policy is forward-only and follows an expand/deploy/contract model rather than attempting automatic DOWN migrations.

Durable jobs

Large or deferred operations can now use persisted jobs instead of depending entirely on a single MCP request remaining alive.

JamRelay can:

• create jobs
• persist per-item progress
• resume eligible work after restart
• wait for rate limits without losing state
• commit resolved work explicitly
• cancel jobs without deleting history
• track retry attempts separately from normal progress
• surface jobs requiring manual review

Interrupted resolution can resume safely.

An operation interrupted during an uncertain external Spotify write is not blindly repeated, reducing the risk of duplicate mutations.

Rate-limit awareness

Spotify rate limits are now persisted and exposed as application state.

A 429 response can be recorded with:

• provider
• operation scope
• retry information
• first/last occurrence
• occurrence count
• normalized error information

JamRelay performs rate-limit preflight checks before unnecessary network calls.

Rate limits are scoped rather than treated as one global Spotify lock. For example, Spotify Search being blocked does not automatically prevent unrelated playlist operations from proceeding.

The state survives application restarts.

API diagnostics and structured errors

HTTP and Spotify errors now have significantly stronger normalization and diagnostics.

JamRelay adds:

• request IDs
• normalized API errors
• persisted API-error fingerprints
• occurrence counters
• rate-limit metadata
• bounded diagnostic history
• state diagnostics MCP tools

Raw authorization headers, tokens, full response bodies, and other secret material are not stored as diagnostic data.

Local listening history

JamRelay can now maintain its own local listening-event history from events it actually observes.

The history model records provenance instead of pretending JamRelay knows more about the user than it really does.

Stored events can include:

• track identity
• artist
• album
• occurrence time
• source
• event type
• playback progress
• duration
• session information
• supporting evidence

This state forms the basis for local-first personalization features without requiring JamRelay to claim access to Spotify's private recommendation internals.

Personalization and affinity

v1.1.0 introduces deterministic local personalization capabilities built from data JamRelay can actually observe.

New workflows include:

• ranking playlist tracks by local affinity
• sorting by personal affinity
• playlist personalization
• avoiding recently played tracks
• rediscovering older tracks
• deep-cuts selection
• identifying missing favorites
• completing artist collections
• skip-pattern analysis
• playlist cleanup using locally observed skip evidence

JamRelay keeps observed events separate from derived scoring so clients can distinguish factual history from inference.

Session and queue planning

New tools can construct deterministic listening sessions from existing playlists.

Capabilities include:

• bounded session generation
• duration targets
• artist spacing
• seeded ordering
• playlist-based queue planning
• smart-next selection

Where Spotify does not expose a safe or supported direct capability, JamRelay returns a local execution plan instead of pretending the external action occurred.

Daily mixes and rotations

JamRelay now includes higher-level recurring playlist concepts.

The release adds tooling for:

• daily mixes
• weekly rotations
• persistent rotation definitions
• rotation state
• manual/daily/weekly cadence metadata
• target playlist tracking
• last/next execution state

Rotation state is persisted locally so playlist automation can evolve beyond one-shot requests.

Library workflows

The release expands higher-level interactions between Spotify library state and playlists.

This includes workflows such as:

• liked-track synchronization
• inbox-style playlist handling
• playlist archival
• playlist versioning
• comparison with locally known listening state

These operations build on the same state, planner, and safety infrastructure as the rest of the playlist engine.

Spotify resolver fallback

JamRelay now supports an optional alternate track resolver.

When Spotify Search is unavailable or rate-limited, a configured external resolver may provide candidate Spotify IDs or URLs.

External results are never treated as authoritative metadata.

JamRelay validates accepted candidates against Spotify before storing them as canonical tracks.

The alternate resolver is disabled unless expl...

JamRelay v1.0.0

JamRelay v1.0.0

Initial public release of JamRelay — an open-source MCP server for Spotify.

Highlights

• Spotify search, library, playlists and playback controls
• OAuth 2.0 Authorization Code + PKCE
• Static OAuth client configuration
• Multi-client OAuth registry
• Dynamic Client Registration support
• ChatGPT integration verified
• Documentation for Claude, Gemini CLI, Cursor, VS Code, Windsurf and MCP Inspector
• Docker and Docker Compose deployment
• Cloudflare Tunnel support
• Multi-language VitePress documentation
• Automated documentation generation and validation
• Persistent SQLite state and rate-limit handling

Requirements

• Node.js 22+
• Spotify Developer application
• Docker optional

Documentation

See the repository documentation for installation, OAuth configuration, supported MCP clients and deployment options.

Notes

This is the first public release of JamRelay.

JamRelay is an independent open-source project and is not affiliated with Spotify, OpenAI, Anthropic, Google, Microsoft, Cursor or Windsurf.