musix-box 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# musix-box
+
+An MCP server giving an agent real Spotify Web API access — full paginated
+library, following, and search — instead of the capped, fuzzy first-party
+connector.
+
+## Why this exists
+
+The built-in Spotify connector's tools return at most 5 results per search
+call, with no pagination, and have no tool at all for listing your full
+liked-songs library, followed artists, saved albums, or playlists. Asking
+"what bands do I like" cannot be answered completely by a connector that
+can only return 5 results.
+
+`musix-box` calls the real Spotify Web API directly, with tools that page
+through complete lists rather than returning a capped snapshot.
+
+## Architecture
+
+Built on the same pattern as `other-memory`: a Cloudflare Worker running an
+MCP agent (`agents/mcp`), with `@cloudflare/workers-oauth-provider` as the
+outer OAuth layer between the MCP client and this server, and Spotify as
+the identity and data-access provider.
+
+The one structural difference from `other-memory`: GitHub there is used
+only to answer "who is this," against a token this server never stores or
+reuses. Spotify here is also the source every tool actually calls, so the
+tokens from the OAuth exchange are persisted (in `SPOTIFY_TOKENS`, a KV
+namespace) and refreshed on every call that needs one — see
+`src/providers/spotify/spotify_session.ts`.
+
+`src/providers/media_provider.ts` defines a provider-agnostic interface
+(`MediaProvider`) that `src/providers/spotify/` implements. Adding YouTube
+Music or Apple Music later is a matter of writing a new file under
+`providers/`, not touching the tools or the MCP wiring.
+
+## Tools
+
+- `search_media` — search tracks, artists, albums, playlists (up to 10 per
+  type per call, paginated)
+- `get_liked_tracks` — the user's full liked-songs library, paginated
+- `get_followed_artists` — every artist the user follows, paginated
+- `get_saved_albums` — the user's saved albums, paginated
+- `get_playlists` — playlists the user owns or follows, paginated
+- `get_playlist_tracks` — every track in one playlist, paginated
+
+## Setup
+
+1. Create a Spotify app at https://developer.spotify.com/dashboard to get a
+   `Client ID`. This flow uses PKCE, so no client secret is needed.
+2. Add `https://<your-worker>.workers.dev/callback` as a Redirect URI on
+   the app.
+3. `npx wrangler kv namespace create OAUTH_KV` and
+   `npx wrangler kv namespace create SPOTIFY_TOKENS`, then copy
+   `wrangler.example.jsonc` to `wrangler.jsonc` and fill in the returned
+   ids plus your Spotify user id.
+4. Set secrets:
+   ```sh
+   printf %s "$SPOTIFY_CLIENT_ID" | npx wrangler secret put SPOTIFY_CLIENT_ID
+   openssl rand -hex 32           | npx wrangler secret put COOKIE_ENCRYPTION_KEY
+   ```
+5. `npm run deploy`.
+
+## Testing
+
+```sh
+npm test              # worker + repository projects
+```
+
+No `integration` project yet — those would exercise the real Spotify API
+and need a test account and app configured, which this package does not
+have set up.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "musix-box",
+  "version": "0.1.0",
+  "description": "An MCP server giving an agent real Spotify Web API access — full paginated library, following, and search — instead of the capped, fuzzy first-party connector.",
+  "type": "module",
+  "author": "Idin K",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/idin/musix-box.git"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "test": "vitest run --project worker --project repository",
+    "test:integration": "vitest run --project integration",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@cloudflare/workers-oauth-provider": "^0.8.1",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "agents": "^0.17.1",
+    "hono": "^4.12.27",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.20.3",
+    "@cloudflare/workers-types": "^5.20260801.1",
+    "@types/node": "^26.2.0",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.10",
+    "wrangler": "^4.120.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,225 @@
+import { McpAgent } from "agents/mcp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { version as PACKAGE_VERSION } from "../package.json";
+
+import { SpotifyProvider } from "./providers/spotify/spotify_provider";
+import { getAccessToken } from "./providers/spotify/spotify_session";
+import type { SearchType } from "./providers/media_provider";
+import {
+  buildFailure,
+  consoleFailureSink,
+  reportingFailures,
+  type FailureSink,
+} from "./tool_errors";
+import type { Env, UserProps } from "./types";
+
+const SEARCH_TYPES = ["track", "artist", "album", "playlist"] as const satisfies readonly SearchType[];
+
+/**
+ * Every list tool shares the same two paging parameters, so the shape is
+ * declared once here rather than repeated per tool with a chance to drift.
+ */
+const PAGING_SCHEMA = {
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Items per page. Provider's own maximum applies if higher."),
+  cursor: z
+    .string()
+    .optional()
+    .describe("Cursor from a previous call's response, to fetch the next page."),
+};
+
+export class MusixBoxMCP extends McpAgent<Env, unknown, UserProps> {
+  server = new McpServer({
+    name: "musix-box",
+    title: "Musix Box",
+    version: PACKAGE_VERSION,
+  });
+
+  protected failureSink: FailureSink = consoleFailureSink;
+
+  private async provider(): Promise<SpotifyProvider> {
+    if (!this.props?.spotifyUserId) {
+      throw new Error("Not authenticated with Spotify.");
+    }
+    const accessToken = await getAccessToken(this.env.SPOTIFY_TOKENS, this.props.spotifyUserId, {
+      clientId: this.env.SPOTIFY_CLIENT_ID,
+      now: () => Date.now(),
+    });
+    return new SpotifyProvider(accessToken);
+  }
+
+  /**
+   * Register a tool whose failures are recorded rather than thrown.
+   *
+   * Same reasoning as `other-memory`'s equivalent wrapper: a tool
+   * registered the direct SDK way would still work, and would lose its
+   * failures silently — invisible until the day someone needed the log.
+   */
+  protected registerTool<InputSchema extends z.ZodRawShape>(
+    name: string,
+    definition: { description: string; inputSchema: InputSchema },
+    handler: (args: { [Key in keyof InputSchema]: z.infer<InputSchema[Key]> }) => Promise<unknown>,
+  ): void {
+    type Arguments = { [Key in keyof InputSchema]: z.infer<InputSchema[Key]> };
+    this.server.registerTool(
+      name,
+      definition as Parameters<McpServer["registerTool"]>[1],
+      (async (args: Arguments) =>
+        reportingFailures({
+          tool: name,
+          args,
+          spotifyUserId: this.props?.spotifyUserId ?? null,
+          sink: this.failureSink,
+          run: async () => handler(args),
+        })) as unknown as Parameters<McpServer["registerTool"]>[2],
+    );
+  }
+
+  async init() {
+    this.registerSearchTool();
+    this.registerLikedTracksTool();
+    this.registerFollowedArtistsTool();
+    this.registerSavedAlbumsTool();
+    this.registerPlaylistsTool();
+    this.registerPlaylistTracksTool();
+  }
+
+  private registerSearchTool() {
+    this.registerTool(
+      "search_media",
+      {
+        description:
+          "Search Spotify for tracks, artists, albums and playlists. Unlike " +
+          "the built-in Spotify connector's search (capped at 5 results " +
+          "total, one page, no way to ask for more), this returns up to 10 " +
+          "results per type per call and accepts a cursor to page further. " +
+          "Supports Spotify's field filters in the query, e.g. " +
+          '`artist:Radiohead track:Karma Police` or `year:2020`.',
+        inputSchema: {
+          query: z.string().describe("Free-text query, optionally using Spotify field filters."),
+          types: z
+            .array(z.enum(SEARCH_TYPES))
+            .optional()
+            .describe("Which kinds to search. All four when omitted."),
+          ...PAGING_SCHEMA,
+        },
+      },
+      async ({ query, types, limit, cursor }) => {
+        const provider = await this.provider();
+        const result = await provider.search(query, { types, limit, cursor });
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      },
+    );
+  }
+
+  private registerLikedTracksTool() {
+    this.registerTool(
+      "get_liked_tracks",
+      {
+        description:
+          "List the user's liked (saved) tracks on Spotify, one page at a " +
+          "time. Unlike the built-in connector, which has no tool for this " +
+          "at all — only a 5-result search — this pages through the full " +
+          "library via the real Spotify API. Pass the returned cursor back " +
+          "to fetch the next page; a null cursor means this was the last page.",
+        inputSchema: PAGING_SCHEMA,
+      },
+      async ({ limit, cursor }) => {
+        const provider = await this.provider();
+        const page = await provider.getLikedTracks({ limit, cursor });
+        return { content: [{ type: "text" as const, text: JSON.stringify(page, null, 2) }] };
+      },
+    );
+  }
+
+  private registerFollowedArtistsTool() {
+    this.registerTool(
+      "get_followed_artists",
+      {
+        description:
+          "List every artist the user follows on Spotify, one page at a " +
+          "time — this is what answers \"what bands do I like\" completely, " +
+          "which the built-in connector's 5-result search cannot. Pass the " +
+          "returned cursor back to fetch the next page.",
+        inputSchema: PAGING_SCHEMA,
+      },
+      async ({ limit, cursor }) => {
+        const provider = await this.provider();
+        const page = await provider.getFollowedArtists({ limit, cursor });
+        return { content: [{ type: "text" as const, text: JSON.stringify(page, null, 2) }] };
+      },
+    );
+  }
+
+  private registerSavedAlbumsTool() {
+    this.registerTool(
+      "get_saved_albums",
+      {
+        description:
+          "List the user's saved albums on Spotify, one page at a time.",
+        inputSchema: PAGING_SCHEMA,
+      },
+      async ({ limit, cursor }) => {
+        const provider = await this.provider();
+        const page = await provider.getSavedAlbums({ limit, cursor });
+        return { content: [{ type: "text" as const, text: JSON.stringify(page, null, 2) }] };
+      },
+    );
+  }
+
+  private registerPlaylistsTool() {
+    this.registerTool(
+      "get_playlists",
+      {
+        description:
+          "List the playlists the user owns or follows on Spotify, one " +
+          "page at a time.",
+        inputSchema: PAGING_SCHEMA,
+      },
+      async ({ limit, cursor }) => {
+        const provider = await this.provider();
+        const page = await provider.getPlaylists({ limit, cursor });
+        return { content: [{ type: "text" as const, text: JSON.stringify(page, null, 2) }] };
+      },
+    );
+  }
+
+  private registerPlaylistTracksTool() {
+    this.registerTool(
+      "get_playlist_tracks",
+      {
+        description:
+          "List every track in one Spotify playlist, one page at a time. " +
+          "Unlike the built-in connector's fetch_tracks, this is not " +
+          "limited to a playlist already shown in the current widget " +
+          "session — any playlist id works, and it pages through the full " +
+          "track list rather than returning it all at once uncapped.",
+        inputSchema: {
+          playlist_id: z.string().describe("The Spotify playlist id."),
+          ...PAGING_SCHEMA,
+        },
+      },
+      async ({ playlist_id, limit, cursor }) => {
+        const provider = await this.provider();
+        const page = await provider.getPlaylistTracks(playlist_id, { limit, cursor });
+        return { content: [{ type: "text" as const, text: JSON.stringify(page, null, 2) }] };
+      },
+    );
+  }
+}
+
+export { buildFailure };
+export type { Env, UserProps } from "./types";

package/src/providers/media_provider.ts

@@ -0,0 +1,152 @@
+/**
+ * The contract every media provider implements.
+ *
+ * Tools call this interface, never a provider's own client directly — that is
+ * what makes adding YouTube Music or Apple Music later a matter of writing a
+ * new file under `providers/`, not touching every tool.
+ *
+ * Every list method is paginated and exhaustive by construction: none of them
+ * return a capped top-N. The gap this whole package exists to close is a
+ * connector whose search and library tools return at most five results with
+ * no way to ask for more — every method here is shaped so that limitation
+ * cannot recur.
+ */
+
+export type Track = {
+  id: string;
+  name: string;
+  artistNames: string[];
+  albumName: string;
+  durationMs: number;
+  uri: string;
+};
+
+export type Artist = {
+  id: string;
+  name: string;
+  genres: string[];
+  uri: string;
+};
+
+export type Album = {
+  id: string;
+  name: string;
+  artistNames: string[];
+  releaseDate: string;
+  uri: string;
+};
+
+export type Playlist = {
+  id: string;
+  name: string;
+  ownerName: string;
+  trackCount: number;
+  uri: string;
+};
+
+export type SearchResults = {
+  tracks: Track[];
+  artists: Artist[];
+  albums: Album[];
+  playlists: Playlist[];
+};
+
+/** What kinds of thing a search may be restricted to. */
+export type SearchType = "track" | "artist" | "album" | "playlist";
+
+/**
+ * A single page of a paginated list, plus what is needed to fetch the next
+ * one.
+ *
+ * `cursor` is provider-shaped on purpose — Spotify pages saved tracks by
+ * numeric offset and followed artists by an artist-id cursor, and forcing
+ * both into one shape would either lose information or invent a fake offset
+ * for a cursor-based endpoint. Callers pass the cursor back unexamined.
+ */
+export type Page<Item> = {
+  items: Item[];
+  /** Present when more items exist; absent when this is the last page. */
+  nextCursor: string | null;
+  /** Total item count, when the provider reports one. */
+  total: number | null;
+};
+
+export interface MediaProvider {
+  /** The provider's own name, e.g. "spotify". Used to tag results and errors. */
+  readonly name: string;
+
+  /**
+   * Search for content, across one or more types.
+   *
+   * @param query - Free-text query.
+   * @param options.types - Which kinds to search. All four when omitted.
+   * @param options.limit - Items per type, per page.
+   * @param options.cursor - Page cursor from a previous call.
+   */
+  search(
+    query: string,
+    options?: { types?: SearchType[]; limit?: number; cursor?: string },
+  ): Promise<{
+    tracks: Page<Track>;
+    artists: Page<Artist>;
+    albums: Page<Album>;
+    playlists: Page<Playlist>;
+  }>;
+
+  /** One page of the user's liked/saved tracks. */
+  getLikedTracks(options?: { limit?: number; cursor?: string }): Promise<Page<Track>>;
+
+  /** One page of the artists the user follows. */
+  getFollowedArtists(options?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<Page<Artist>>;
+
+  /** One page of the user's saved albums. */
+  getSavedAlbums(options?: { limit?: number; cursor?: string }): Promise<Page<Album>>;
+
+  /** One page of the playlists the user owns or follows. */
+  getPlaylists(options?: { limit?: number; cursor?: string }): Promise<Page<Playlist>>;
+
+  /** Every track in one playlist, in order. */
+  getPlaylistTracks(
+    playlistId: string,
+    options?: { limit?: number; cursor?: string },
+  ): Promise<Page<Track>>;
+}
+
+/**
+ * Fetch every page of a paginated call, following `nextCursor` until it is
+ * null.
+ *
+ * The interface returns one page at a time because a Worker has a bounded
+ * subrequest budget per invocation — see `other-memory`'s own
+ * `FILES_INDEXED_PER_SEARCH` for the shape of that constraint recurring.
+ * This helper is for callers who know the total is small enough (a personal
+ * library, not an open-ended catalogue) to fetch in full within one call.
+ *
+ * @param fetchPage - Fetches one page, given the previous cursor or none.
+ * @param options.maxPages - Hard ceiling, so a provider bug returning a
+ *   cursor that never terminates cannot loop forever.
+ * @returns Every item across every page.
+ */
+export async function fetchAllPages<Item>(
+  fetchPage: (cursor: string | undefined) => Promise<Page<Item>>,
+  options: { maxPages: number },
+): Promise<Item[]> {
+  const items: Item[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < options.maxPages; page += 1) {
+    const result = await fetchPage(cursor);
+    items.push(...result.items);
+    if (result.nextCursor === null) {
+      return items;
+    }
+    cursor = result.nextCursor;
+  }
+  throw new Error(
+    `fetchAllPages did not terminate within ${options.maxPages} pages. `
+      + "Either raise maxPages for a genuinely large list, or the provider's "
+      + "cursor is not advancing.",
+  );
+}

package/src/providers/spotify/spotify_api_client.ts

@@ -0,0 +1,220 @@
+/**
+ * Raw HTTP calls against the Spotify Web API.
+ *
+ * Kept separate from `SpotifyProvider` (which maps these responses onto the
+ * shared `MediaProvider` shape) so the two concerns — "what Spotify's API
+ * actually returns" and "what this package promises callers" — can each be
+ * read and tested on their own.
+ */
+
+const SPOTIFY_API_BASE = "https://api.spotify.com/v1";
+
+/** The maximum `limit` Spotify's search endpoint accepts, per item type. */
+export const SEARCH_MAX_LIMIT = 10;
+
+/** The maximum `limit` Spotify's library-listing endpoints accept. */
+export const LIBRARY_MAX_LIMIT = 50;
+
+/** One page of a Spotify "paging object" response, generic over item shape. */
+export type SpotifyPagingObject<Item> = {
+  href: string;
+  limit: number;
+  next: string | null;
+  offset: number;
+  previous: string | null;
+  total: number;
+  items: Item[];
+};
+
+/** One page of a Spotify cursor-paginated response (used for followed artists). */
+export type SpotifyCursorPage<Item> = {
+  href: string;
+  limit: number;
+  next: string | null;
+  cursors: { after: string | null; before?: string };
+  total: number;
+  items: Item[];
+};
+
+export type SpotifyImage = { url: string; height: number | null; width: number | null };
+
+export type SpotifyArtist = {
+  id: string;
+  name: string;
+  genres: string[];
+  uri: string;
+  images: SpotifyImage[];
+};
+
+export type SpotifyAlbum = {
+  id: string;
+  name: string;
+  artists: { id: string; name: string }[];
+  release_date: string;
+  uri: string;
+  images: SpotifyImage[];
+};
+
+export type SpotifyTrack = {
+  id: string;
+  name: string;
+  artists: { id: string; name: string }[];
+  album: { id: string; name: string };
+  duration_ms: number;
+  uri: string;
+};
+
+export type SpotifyPlaylist = {
+  id: string;
+  name: string;
+  owner: { id: string; display_name: string | null };
+  tracks: { total: number };
+  uri: string;
+};
+
+/** Thrown when Spotify's API returns a non-2xx response. */
+export class SpotifyApiError extends Error {
+  readonly status: number;
+  readonly retryAfterSeconds: number | null;
+
+  constructor(options: { status: number; body: string; retryAfterSeconds: number | null }) {
+    super(`Spotify API returned ${options.status}: ${options.body}`);
+    this.name = "SpotifyApiError";
+    this.status = options.status;
+    this.retryAfterSeconds = options.retryAfterSeconds;
+  }
+}
+
+/** Whether an error means Spotify is rate-limiting rather than rejecting the request. */
+export function isSpotifyRateLimited(error: unknown): boolean {
+  return error instanceof SpotifyApiError && error.status === 429;
+}
+
+/**
+ * A thin client for the Spotify Web API, authenticated with one access
+ * token.
+ *
+ * Holds no OAuth state of its own — refreshing the token and constructing a
+ * new client with the fresh one is the caller's job, kept in
+ * `spotify_oauth.ts` so this file only ever has to reason about the Web API
+ * itself.
+ */
+export class SpotifyApiClient {
+  private readonly accessToken: string;
+
+  constructor(accessToken: string) {
+    this.accessToken = accessToken;
+  }
+
+  private async get<Result>(path: string, params: Record<string, string | number | undefined>): Promise<Result> {
+    const url = new URL(`${SPOTIFY_API_BASE}${path}`);
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${this.accessToken}` },
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      const retryAfterHeader = response.headers.get("Retry-After");
+      throw new SpotifyApiError({
+        status: response.status,
+        body,
+        retryAfterSeconds: retryAfterHeader ? Number(retryAfterHeader) : null,
+      });
+    }
+
+    return (await response.json()) as Result;
+  }
+
+  /**
+   * GET /v1/search.
+   *
+   * @param query - Free-text query, or one using Spotify's field filters
+   *   (`artist:`, `track:`, `album:`, `year:`, `genre:`).
+   * @param types - Which item types to search. Spotify allows more types
+   *   than this package models; only the four `MediaProvider` covers are
+   *   accepted here.
+   * @param options.limit - Per-type result count. Spotify's own ceiling is
+   *   {@link SEARCH_MAX_LIMIT} — much lower than the library endpoints.
+   * @param options.offset - Starting index, for paging past the limit.
+   */
+  async search(
+    query: string,
+    types: Array<"track" | "artist" | "album" | "playlist">,
+    options: { limit?: number; offset?: number } = {},
+  ): Promise<{
+    tracks?: SpotifyPagingObject<SpotifyTrack>;
+    artists?: SpotifyPagingObject<SpotifyArtist>;
+    albums?: SpotifyPagingObject<SpotifyAlbum>;
+    playlists?: SpotifyPagingObject<SpotifyPlaylist>;
+  }> {
+    return this.get("/search", {
+      q: query,
+      type: types.join(","),
+      limit: options.limit,
+      offset: options.offset,
+    });
+  }
+
+  /** GET /v1/me/tracks — the user's liked songs. Scope: user-library-read. */
+  async getSavedTracks(
+    options: { limit?: number; offset?: number } = {},
+  ): Promise<SpotifyPagingObject<{ added_at: string; track: SpotifyTrack }>> {
+    return this.get("/me/tracks", { limit: options.limit, offset: options.offset });
+  }
+
+  /** GET /v1/me/albums — the user's saved albums. Scope: user-library-read. */
+  async getSavedAlbums(
+    options: { limit?: number; offset?: number } = {},
+  ): Promise<SpotifyPagingObject<{ added_at: string; album: SpotifyAlbum }>> {
+    return this.get("/me/albums", { limit: options.limit, offset: options.offset });
+  }
+
+  /**
+   * GET /v1/me/following?type=artist — the artists the user follows.
+   * Scope: user-follow-read. Cursor-paginated, not offset-paginated — see
+   * {@link SpotifyCursorPage}.
+   */
+  async getFollowedArtists(
+    options: { limit?: number; after?: string } = {},
+  ): Promise<{ artists: SpotifyCursorPage<SpotifyArtist> }> {
+    return this.get("/me/following", {
+      type: "artist",
+      limit: options.limit,
+      after: options.after,
+    });
+  }
+
+  /** GET /v1/me/playlists — playlists the user owns or follows. Scope: playlist-read-private. */
+  async getPlaylists(
+    options: { limit?: number; offset?: number } = {},
+  ): Promise<SpotifyPagingObject<SpotifyPlaylist>> {
+    return this.get("/me/playlists", { limit: options.limit, offset: options.offset });
+  }
+
+  /**
+   * GET /v1/playlists/{id}/items — every track in one playlist.
+   * Scope: playlist-read-private.
+   *
+   * `/tracks` is the deprecated form of this endpoint as of Spotify's
+   * February 2026 migration: the path became `/items`, and the item's field
+   * holding the track object was renamed from `track` to `item`. Verified
+   * directly against Spotify's own reference page
+   * (get-playlists-items) before writing this, not assumed from the older
+   * form still used elsewhere.
+   */
+  async getPlaylistTracks(
+    playlistId: string,
+    options: { limit?: number; offset?: number } = {},
+  ): Promise<SpotifyPagingObject<{ item: SpotifyTrack }>> {
+    return this.get(`/playlists/${playlistId}/items`, {
+      limit: options.limit,
+      offset: options.offset,
+    });
+  }
+}