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 explicitly configured.

Deployment system overhaul

The deployment workflow has been substantially rebuilt.

The new VPS deployment tooling includes:

• local build validation
• optional full lint and test checks
• deployment archive creation
• source upload
• differential asset synchronization
• Docker Compose validation
• image building
• container replacement
• health-gated rollout
• schema-version verification
• public endpoint verification
• rollback image preservation
• automatic application rollback after failed deployment
• deployment locking
• persistent external data volumes
• internal Docker networking
• Cloudflare Tunnel lifecycle handling

A release is not considered healthy merely because the container starts.

The deployment health gate verifies that:

• the application is healthy
• Spotify authorization is available
• the state database is ready
• the running schema version matches the migration set shipped by the release

Container and persistence improvements

The production container now ships database migrations alongside the compiled application.

Persistent application state lives under /data, backed by the external jamrelay_data Docker volume.

The container remains intentionally constrained with:

• non-root execution
• read-only root filesystem
• dropped Linux capabilities
• no-new-privileges
• temporary writable /tmp
• explicit internal networking

Recreating the application container does not recreate the persistent JamRelay state volume.

OAuth and authentication improvements

MCP OAuth remains fully supported and received additional hardening and product work.

v1.1.0 includes:

• improved OAuth handling
• branded JamRelay authorization UI
• JamRelay-native OAuth assets
• continued PKCE support
• static and dynamically registered client support
• multi-client compatibility
• stronger consistency across OAuth configuration and documentation

Spotify OAuth and MCP-client authentication remain separate trust boundaries.

JamRelay branding

The project now has a complete JamRelay visual identity and reusable asset set.

The repository includes:

• primary JamRelay logos
• icons
• dark/light variants
• web-optimized WebP exports
• social/Open Graph artwork
• X card artwork
• ChatGPT plugin artwork
• browser favicons
• PWA icons
• service-specific assets

Brand assets are documented and reusable without having to regenerate them manually for each integration.

Documentation improvements

Documentation has been updated to reflect the substantially larger runtime.

Notable additions include documentation for:

• persistent state database
• database-first resolution
• playlist automation
• playlist safety
• playlist rules
• personalization
• new errors and diagnostics
• expanded MCP tool reference

The generated MCP reference now reflects the live runtime registry and currently documents 103 MCP tools.

Documentation generation remains derived from project sources so fast-changing technical reference information does not need to be maintained manually in several places.

Development and release quality

The development workflow received additional safeguards.

v1.1.0 adds or expands:

• database tests
• migration integrity tests
• duplicate migration-prefix validation
• job regression tests
• state-runtime tests
• MCP integration tests
• OAuth tests
• Spotify response/error handling tests
• pre-push validation
• cross-platform documentation checks
• full release checks

The production release was validated with:

• ESLint
• TypeScript build
• 93 passing automated tests
• Docker production build
• deployment health checks
• public endpoint health verification
• migration checksum verification
• production schema verification

Licensing

JamRelay is now licensed under GNU Affero General Public License v3.0 only (AGPL-3.0-only).

The repository also includes expanded licensing and contribution documentation.

This is an important change for users redistributing, modifying, or operating modified network-accessible versions of JamRelay. Review LICENSE, LICENSING.md, and CONTRIBUTING.md before redistributing modified builds.

Database upgrade notes

Existing installations upgrading to v1.1.0 do not need to manually execute SQL migrations.

On startup JamRelay automatically:

1. discovers migration files,
2. validates migration metadata,
3. verifies previously applied checksums,
4. applies missing migrations transactionally,
5. records the resulting schema version.

Production deployments should ensure that /data is persistent.

After upgrade, /health should report the latest expected schema with:

schemaState: "current"

Do not edit migration files after they have been applied to shared or production storage.

Compatibility notes

Core Spotify search, playlist, library, and playback tools from v1.0.0 remain available.

The project configuration and runtime naming have been consolidated under JamRelay, and deprecated naming aliases have been removed where appropriate.

Operators upgrading older deployments should review:

• environment variable names
• persistent data paths
• Docker Compose configuration
• public base URL
• OAuth client configuration

before replacing an existing production installation.

What changed architecturally

v1.0.0 was primarily:

AI client → MCP → Spotify API

v1.1.0 introduces a much richer execution model:

AI client
→ MCP tool layer
→ JamRelay domain logic
→ planner / rules / personalization / jobs
→ persistent local state
→ Spotify client
→ Spotify API

This means JamRelay can now perform higher-level operations that would otherwise require an AI client to manually coordinate dozens or hundreds of low-level Spotify API actions.

The long-term direction is no longer simply "expose Spotify through MCP."

JamRelay is becoming a self-hosted music automation layer where MCP is one interface to a growing set of deterministic, stateful music capabilities.

---

Thank you for using, testing, and building with JamRelay.

This release represents a major expansion of what the project can do while keeping the core principles intact:

self-hosted, explicit, inspectable, reversible where possible, and under the user's control.