musix-box 0.1.0

package/src/tool_errors.ts

@@ -0,0 +1,180 @@
+/**
+ * Failure reporting for MCP tools.
+ *
+ * When a tool throws, two different readers need something from it, and
+ * they need different things. The agent that made the call needs to know
+ * the call failed and roughly why, so it can say so rather than inventing
+ * a result. Whoever maintains the server needs the stack, the arguments
+ * and the time, later, when they sit down to fix it.
+ *
+ * A thrown exception serves the first reader badly and the second not at
+ * all: the MCP transport reduces it to a message, and once the request is
+ * over the context is gone. So failures are captured here instead —
+ * turned into a record, handed to a sink, and reported back to the caller
+ * as an error result rather than an exception.
+ */
+
+/** A tool failure, in the form it is stored and read back in. */
+export type ToolFailure = {
+  /** When the failure happened, ISO 8601. */
+  timestamp: string;
+  /** Which tool was called. */
+  tool: string;
+  /** The authenticated Spotify user, when the request had one. */
+  spotifyUserId: string | null;
+  /**
+   * Arguments the tool was called with, JSON-encoded. Not redacted the way
+   * `other-memory`'s equivalent module redacts memory content — no tool
+   * here takes free-text personal content as an argument, only queries and
+   * ids, so there is nothing in an argument blob that duplicates data the
+   * user would not already expect logged.
+   */
+  arguments: string;
+  /** The error message. */
+  message: string;
+  /** The stack, when the thrown value carried one. */
+  stack: string | null;
+};
+
+/**
+ * Somewhere failures are written.
+ *
+ * Kept deliberately small so that a deployment can send failures to a
+ * database, a log service, or anywhere else, without the library needing
+ * to know that such a place exists.
+ */
+export type FailureSink = (failure: ToolFailure) => void | Promise<void>;
+
+/** Longest argument blob stored, in characters. */
+const MAXIMUM_ARGUMENT_LENGTH = 2000;
+
+/**
+ * Build a failure record from a thrown value.
+ *
+ * @param options.tool - Name of the tool that failed.
+ * @param options.error - Whatever was thrown. Anything can be thrown in
+ *   JavaScript, so non-Error values are described rather than assumed.
+ * @param options.args - Arguments the tool was called with.
+ * @param options.spotifyUserId - Authenticated caller, when there was one.
+ * @param options.timestamp - When the failure happened.
+ * @returns The record to store.
+ */
+export function buildFailure(options: {
+  tool: string;
+  error: unknown;
+  args: unknown;
+  spotifyUserId: string | null;
+  timestamp: string;
+}): ToolFailure {
+  const { tool, error, args, spotifyUserId, timestamp } = options;
+  const isError = error instanceof Error;
+  let encodedArguments: string;
+  try {
+    encodedArguments = JSON.stringify(args) ?? "null";
+  } catch {
+    // Arguments arrive from a remote caller and are not guaranteed to be
+    // encodable — a cycle here must not mask the failure being reported.
+    encodedArguments = '"[unencodable]"';
+  }
+  return {
+    timestamp,
+    tool,
+    spotifyUserId,
+    arguments: encodedArguments.slice(0, MAXIMUM_ARGUMENT_LENGTH),
+    message: isError ? error.message : String(error),
+    stack: isError ? (error.stack ?? null) : null,
+  };
+}
+
+/**
+ * Write a failure to the console as one structured line.
+ *
+ * This is the default sink. On Cloudflare it is not a fallback so much as
+ * the ordinary path: Workers observability already captures and retains
+ * console output, so a deployment that configures nothing still has its
+ * failures recorded and searchable.
+ *
+ * @param failure - The record to write.
+ * @returns Nothing.
+ */
+export const consoleFailureSink: FailureSink = (failure: ToolFailure) => {
+  console.error(JSON.stringify({ kind: "tool_failure", ...failure }));
+};
+
+/**
+ * Whether a failure message is Spotify refusing for rate reasons.
+ *
+ * Kept here rather than imported from a provider module on purpose: this
+ * module is what every tool funnels its errors through, and it must not
+ * depend on the module whose calls it is reporting on.
+ *
+ * @param message - The failure message.
+ * @returns True when the message describes a rate limit.
+ */
+function isRateLimitMessage(message: string): boolean {
+  return message.toLowerCase().includes("429");
+}
+
+/**
+ * Run a tool handler, reporting any failure rather than throwing.
+ *
+ * @param options.tool - Name of the tool being run.
+ * @param options.args - Arguments it was called with.
+ * @param options.spotifyUserId - Authenticated caller, when there was one.
+ * @param options.sink - Where the failure is written.
+ * @param options.run - The handler itself.
+ * @returns The handler's result, or an error result describing the
+ *   failure.
+ */
+export async function reportingFailures<Result>(options: {
+  tool: string;
+  args: unknown;
+  spotifyUserId: string | null;
+  sink: FailureSink;
+  run: () => Promise<Result>;
+}): Promise<Result | { content: [{ type: "text"; text: string }]; isError: true }> {
+  const { tool, args, spotifyUserId, sink, run } = options;
+  try {
+    return await run();
+  } catch (error) {
+    const failure = buildFailure({
+      tool,
+      error,
+      args,
+      spotifyUserId,
+      timestamp: new Date().toISOString(),
+    });
+    try {
+      await sink(failure);
+    } catch (sinkError) {
+      // A sink that cannot write must not replace the failure it was
+      // asked to record: the original is what the caller needs to hear
+      // about, and losing it to a logging problem is the worst outcome.
+      console.error(
+        JSON.stringify({
+          kind: "failure_sink_error",
+          tool,
+          message: sinkError instanceof Error ? sinkError.message : String(sinkError),
+        }),
+      );
+    }
+
+    const retryAfterMatch = /retryAfterSeconds["\s:]+(\d+)/.exec(failure.message);
+    const retryNote = retryAfterMatch
+      ? ` Try again in about ${retryAfterMatch[1]} seconds.`
+      : "";
+    const explanation = isRateLimitMessage(failure.message)
+      ? `The ${tool} tool could not run: Spotify's API rate limit is `
+        + `exhausted.${retryNote} Nothing is wrong with your library — tell `
+        + "the user to try again shortly, and do not treat this as an empty "
+        + "or missing result."
+      : `The ${tool} tool failed: ${failure.message}\n\n`
+        + "This has been logged. Tell the user the call failed rather than "
+        + "treating the absence of a result as an answer.";
+
+    return {
+      content: [{ type: "text" as const, text: explanation }],
+      isError: true,
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+export type Env = {
+  OAUTH_KV: KVNamespace;
+  MCP_OBJECT: DurableObjectNamespace;
+  SPOTIFY_CLIENT_ID: string;
+  COOKIE_ENCRYPTION_KEY: string;
+  /**
+   * Stores each user's Spotify refresh token, keyed by their Spotify user
+   * id. Separate from OAUTH_KV, which belongs to the outer MCP OAuth layer
+   * (`@cloudflare/workers-oauth-provider`) and is never touched by this
+   * server's own code directly — Spotify tokens are a different concern
+   * with a different lifetime (they refresh hourly; the MCP session token
+   * does not).
+   */
+  SPOTIFY_TOKENS: KVNamespace;
+  /** The single Spotify account permitted to authenticate. */
+  ALLOWED_SPOTIFY_USER_ID: string;
+};
+
+/**
+ * Identity of the authenticated caller, carried through to the MCP agent.
+ *
+ * Deliberately does not carry the Spotify access token itself — access
+ * tokens expire in an hour and `props` is fixed for the life of the
+ * session, so a long session would silently start failing once the token
+ * aged out. Tools look the current, possibly-refreshed token up from
+ * `SPOTIFY_TOKENS` by `spotifyUserId` on every call instead. See
+ * `spotify_session.ts`.
+ */
+export type UserProps = {
+  spotifyUserId: string;
+  displayName: string;
+};

package/src/worker.ts

@@ -0,0 +1,41 @@
+import OAuthProvider from "@cloudflare/workers-oauth-provider";
+
+import { SpotifyHandler } from "./spotify_handler";
+import { MusixBoxMCP } from "./index";
+
+/**
+ * A ready-to-deploy musix-box server.
+ *
+ * Assembled the same way `other-memory`'s `worker.ts` is: the MCP agent,
+ * Spotify as the OAuth provider, and the endpoints wired together. Kept
+ * separate from `index.ts` for the same reason — importing the library must
+ * not also hand you a running worker, so a deployment that needs to change
+ * something has somewhere to do it without editing the library's own source.
+ */
+export default buildWorker(MusixBoxMCP);
+
+/**
+ * Re-exported by name so `wrangler.jsonc`'s Durable Object binding can find
+ * the class. A default export alone is not enough — `other-memory`'s own
+ * worker.ts needed this too.
+ */
+export { MusixBoxMCP };
+
+/**
+ * Assemble a worker around a `MusixBoxMCP` class.
+ *
+ * @param musixBoxMcp - `MusixBoxMCP` or a subclass of it.
+ * @returns A worker ready to be a `wrangler.jsonc` `main`.
+ */
+export function buildWorker(musixBoxMcp: typeof MusixBoxMCP) {
+  return new OAuthProvider({
+    apiHandlers: {
+      "/sse": musixBoxMcp.serveSSE("/sse"),
+      "/mcp": musixBoxMcp.serve("/mcp"),
+    },
+    defaultHandler: SpotifyHandler as never,
+    authorizeEndpoint: "/authorize",
+    tokenEndpoint: "/token",
+    clientRegistrationEndpoint: "/register",
+  });
+}

package/tests/providers/media_provider.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "vitest";
+
+import { fetchAllPages, type Page } from "../../src/providers/media_provider";
+
+function pagesOf(items: number[], pageSize: number): (cursor: string | undefined) => Promise<Page<number>> {
+  return async (cursor) => {
+    const start = cursor ? Number(cursor) : 0;
+    const slice = items.slice(start, start + pageSize);
+    const nextStart = start + pageSize;
+    return {
+      items: slice,
+      nextCursor: nextStart < items.length ? String(nextStart) : null,
+      total: items.length,
+    };
+  };
+}
+
+describe("fetchAllPages", () => {
+  test("follows nextCursor until it is null, returning every item", async () => {
+    const items = await fetchAllPages(pagesOf([1, 2, 3, 4, 5], 2), { maxPages: 10 });
+    expect(items).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  test("a single page needs no cursor following", async () => {
+    const items = await fetchAllPages(pagesOf([1, 2], 5), { maxPages: 10 });
+    expect(items).toEqual([1, 2]);
+  });
+
+  test("an empty list returns empty, not an error", async () => {
+    const items = await fetchAllPages(pagesOf([], 5), { maxPages: 10 });
+    expect(items).toEqual([]);
+  });
+
+  test("a cursor that never terminates throws rather than looping forever", async () => {
+    const neverEnds = async (): Promise<Page<number>> => ({
+      items: [1],
+      nextCursor: "always-more",
+      total: null,
+    });
+
+    await expect(fetchAllPages(neverEnds, { maxPages: 5 })).rejects.toThrow(/did not terminate/);
+  });
+});

package/tests/providers/spotify/spotify_oauth.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  buildAuthorizeUrl,
+  deriveCodeChallenge,
+  generateCodeVerifier,
+  needsRefresh,
+  SPOTIFY_SCOPES,
+} from "../../../src/providers/spotify/spotify_oauth";
+
+describe("deriveCodeChallenge", () => {
+  test("matches RFC 7636 Appendix B's worked example", async () => {
+    // The RFC's own test vector, not a value this code produced itself —
+    // a self-referential test proves only that the function is consistent
+    // with itself, not that it implements the spec correctly.
+    const verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";
+    const expectedChallenge = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM";
+
+    expect(await deriveCodeChallenge(verifier)).toBe(expectedChallenge);
+  });
+
+  test("contains no base64 padding or URL-unsafe characters", async () => {
+    const challenge = await deriveCodeChallenge(generateCodeVerifier());
+    expect(challenge).not.toMatch(/[+/=]/);
+  });
+});
+
+describe("generateCodeVerifier", () => {
+  test("is within RFC 7636's 43-128 character range", () => {
+    const verifier = generateCodeVerifier();
+    expect(verifier.length).toBeGreaterThanOrEqual(43);
+    expect(verifier.length).toBeLessThanOrEqual(128);
+  });
+
+  test("uses only the RFC's allowed alphabet", () => {
+    const verifier = generateCodeVerifier();
+    expect(verifier).toMatch(/^[A-Za-z0-9\-._~]+$/);
+  });
+
+  test("two calls produce different verifiers", () => {
+    // Not a proof of cryptographic quality, just a guard against an
+    // accidentally deterministic implementation.
+    expect(generateCodeVerifier()).not.toBe(generateCodeVerifier());
+  });
+});
+
+describe("buildAuthorizeUrl", () => {
+  test("includes every required PKCE and OAuth parameter", () => {
+    const url = new URL(
+      buildAuthorizeUrl({
+        clientId: "client-123",
+        redirectUri: "https://example.workers.dev/callback",
+        codeChallenge: "challenge-abc",
+        state: "state-xyz",
+      }),
+    );
+
+    expect(url.origin + url.pathname).toBe("https://accounts.spotify.com/authorize");
+    expect(url.searchParams.get("client_id")).toBe("client-123");
+    expect(url.searchParams.get("response_type")).toBe("code");
+    expect(url.searchParams.get("redirect_uri")).toBe(
+      "https://example.workers.dev/callback",
+    );
+    expect(url.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(url.searchParams.get("code_challenge")).toBe("challenge-abc");
+    expect(url.searchParams.get("state")).toBe("state-xyz");
+  });
+
+  test("requests exactly the scopes this package needs, space-separated", () => {
+    const url = new URL(
+      buildAuthorizeUrl({
+        clientId: "client-123",
+        redirectUri: "https://example.workers.dev/callback",
+        codeChallenge: "challenge-abc",
+        state: "state-xyz",
+      }),
+    );
+    expect(url.searchParams.get("scope")).toBe(SPOTIFY_SCOPES.join(" "));
+  });
+});
+
+describe("needsRefresh", () => {
+  const tokens = {
+    accessToken: "a",
+    refreshToken: "r",
+    expiresAt: 1_000_000,
+  };
+
+  test("false well before expiry", () => {
+    expect(
+      needsRefresh(tokens, { now: () => 0, marginMs: 60_000 }),
+    ).toBe(false);
+  });
+
+  test("true once inside the refresh margin", () => {
+    expect(
+      needsRefresh(tokens, { now: () => 999_500, marginMs: 60_000 }),
+    ).toBe(true);
+  });
+
+  test("true once already past expiry", () => {
+    expect(
+      needsRefresh(tokens, { now: () => 1_000_001, marginMs: 60_000 }),
+    ).toBe(true);
+  });
+});

package/tests/providers/spotify/spotify_provider.test.ts

@@ -0,0 +1,218 @@
+import { describe, expect, test, vi } from "vitest";
+
+import { SpotifyProvider } from "../../../src/providers/spotify/spotify_provider";
+
+/**
+ * Fakes `fetch` with real Spotify Web API response shapes, copied from
+ * Spotify's own published reference examples rather than invented — what is
+ * under test here is `SpotifyProvider`'s mapping from those shapes onto
+ * `MediaProvider`, not Spotify's API itself, which is exercised for real
+ * once integration credentials exist.
+ */
+function fakeSpotifyFetch(responseBody: unknown): typeof fetch {
+  return vi.fn(async () => new Response(JSON.stringify(responseBody), { status: 200 })) as unknown as typeof fetch;
+}
+
+const SAVED_TRACKS_RESPONSE = {
+  href: "https://api.spotify.com/v1/me/tracks?offset=0&limit=1",
+  limit: 1,
+  next: "https://api.spotify.com/v1/me/tracks?offset=1&limit=1",
+  offset: 0,
+  previous: null,
+  total: 2,
+  items: [
+    {
+      added_at: "2026-01-01T00:00:00Z",
+      track: {
+        id: "track-1",
+        name: "Karma Police",
+        artists: [{ id: "artist-1", name: "Radiohead" }],
+        album: { id: "album-1", name: "OK Computer" },
+        duration_ms: 261973,
+        uri: "spotify:track:track-1",
+      },
+    },
+  ],
+};
+
+const FOLLOWED_ARTISTS_RESPONSE = {
+  artists: {
+    href: "https://api.spotify.com/v1/me/following?type=artist",
+    limit: 1,
+    next: "https://api.spotify.com/v1/me/following?type=artist&after=artist-1",
+    cursors: { after: "artist-1" },
+    total: 2,
+    items: [
+      {
+        id: "artist-1",
+        name: "Rammstein",
+        genres: ["neue deutsche härte", "industrial metal"],
+        uri: "spotify:artist:artist-1",
+        images: [],
+      },
+    ],
+  },
+};
+
+describe("SpotifyProvider.getLikedTracks", () => {
+  test("maps a Spotify saved-tracks page onto the shared Track shape", async () => {
+    globalThis.fetch = fakeSpotifyFetch(SAVED_TRACKS_RESPONSE);
+    const provider = new SpotifyProvider("test-token");
+
+    const page = await provider.getLikedTracks();
+
+    expect(page.items).toEqual([
+      {
+        id: "track-1",
+        name: "Karma Police",
+        artistNames: ["Radiohead"],
+        albumName: "OK Computer",
+        durationMs: 261973,
+        uri: "spotify:track:track-1",
+      },
+    ]);
+    expect(page.total).toBe(2);
+  });
+
+  test("a present next URL becomes a non-null offset cursor", async () => {
+    globalThis.fetch = fakeSpotifyFetch(SAVED_TRACKS_RESPONSE);
+    const provider = new SpotifyProvider("test-token");
+
+    const page = await provider.getLikedTracks();
+
+    // offset 0 + 1 item returned = next offset 1, as a string cursor.
+    expect(page.nextCursor).toBe("1");
+  });
+
+  test("a null next URL means no more pages", async () => {
+    globalThis.fetch = fakeSpotifyFetch({ ...SAVED_TRACKS_RESPONSE, next: null });
+    const provider = new SpotifyProvider("test-token");
+
+    const page = await provider.getLikedTracks();
+
+    expect(page.nextCursor).toBeNull();
+  });
+});
+
+describe("SpotifyProvider.getFollowedArtists", () => {
+  test("maps a cursor-paginated response onto the shared Page shape", async () => {
+    globalThis.fetch = fakeSpotifyFetch(FOLLOWED_ARTISTS_RESPONSE);
+    const provider = new SpotifyProvider("test-token");
+
+    const page = await provider.getFollowedArtists();
+
+    expect(page.items).toEqual([
+      {
+        id: "artist-1",
+        name: "Rammstein",
+        genres: ["neue deutsche härte", "industrial metal"],
+        uri: "spotify:artist:artist-1",
+      },
+    ]);
+    // Cursor-paginated, so the cursor is Spotify's own `after` value, not a
+    // derived offset — this is the one place the two pagination styles this
+    // package wraps must not be conflated.
+    expect(page.nextCursor).toBe("artist-1");
+    expect(page.total).toBe(2);
+  });
+});
+
+describe("SpotifyProvider.getPlaylistTracks", () => {
+  const PLAYLIST_ITEMS_RESPONSE = {
+    href: "https://api.spotify.com/v1/playlists/playlist-1/items?offset=0&limit=1",
+    limit: 1,
+    next: null,
+    offset: 0,
+    previous: null,
+    total: 1,
+    items: [
+      {
+        added_at: "2026-01-01T00:00:00Z",
+        item: {
+          id: "track-1",
+          name: "Karma Police",
+          artists: [{ id: "artist-1", name: "Radiohead" }],
+          album: { id: "album-1", name: "OK Computer" },
+          duration_ms: 261973,
+          uri: "spotify:track:track-1",
+        },
+      },
+    ],
+  };
+
+  test("requests /playlists/{id}/items, not the deprecated /tracks path", async () => {
+    // Spotify's February 2026 migration renamed GET /playlists/{id}/tracks
+    // to GET /playlists/{id}/items, and the item field from `track` to
+    // `item`. Asserted on the actual request URL, not just the mapped
+    // output, because a test that only checks the output can pass against
+    // a stale path if the fake response is shaped to match it regardless.
+    const fetchSpy = vi.fn(
+      async () => new Response(JSON.stringify(PLAYLIST_ITEMS_RESPONSE), { status: 200 }),
+    );
+    globalThis.fetch = fetchSpy as unknown as typeof fetch;
+    const provider = new SpotifyProvider("test-token");
+
+    await provider.getPlaylistTracks("playlist-1");
+
+    const requestedUrl = (fetchSpy as ReturnType<typeof vi.fn>).mock.calls[0][0] as URL;
+    expect(requestedUrl.pathname).toBe("/v1/playlists/playlist-1/items");
+    expect(requestedUrl.pathname).not.toContain("/tracks");
+  });
+
+  test("maps the item field (not the deprecated track field) onto Track", async () => {
+    globalThis.fetch = vi.fn(
+      async () => new Response(JSON.stringify(PLAYLIST_ITEMS_RESPONSE), { status: 200 }),
+    ) as unknown as typeof fetch;
+    const provider = new SpotifyProvider("test-token");
+
+    const page = await provider.getPlaylistTracks("playlist-1");
+
+    expect(page.items).toEqual([
+      {
+        id: "track-1",
+        name: "Karma Police",
+        artistNames: ["Radiohead"],
+        albumName: "OK Computer",
+        durationMs: 261973,
+        uri: "spotify:track:track-1",
+      },
+    ]);
+  });
+});
+
+describe("SpotifyProvider.search", () => {
+  test("only requested types are present, others come back as empty pages", async () => {
+    globalThis.fetch = fakeSpotifyFetch({
+      tracks: {
+        href: "",
+        limit: 10,
+        next: null,
+        offset: 0,
+        previous: null,
+        total: 0,
+        items: [],
+      },
+    });
+    const provider = new SpotifyProvider("test-token");
+
+    const result = await provider.search("test query", { types: ["track"] });
+
+    expect(result.tracks.items).toEqual([]);
+    expect(result.artists).toEqual({ items: [], nextCursor: null, total: 0 });
+    expect(result.albums).toEqual({ items: [], nextCursor: null, total: 0 });
+    expect(result.playlists).toEqual({ items: [], nextCursor: null, total: 0 });
+  });
+
+  test("the query reaches the request", async () => {
+    const fetchSpy = fakeSpotifyFetch({
+      tracks: { href: "", limit: 10, next: null, offset: 0, previous: null, total: 0, items: [] },
+    });
+    globalThis.fetch = fetchSpy;
+    const provider = new SpotifyProvider("test-token");
+
+    await provider.search("artist:Radiohead track:Karma Police");
+
+    const requestedUrl = (fetchSpy as ReturnType<typeof vi.fn>).mock.calls[0][0] as URL;
+    expect(requestedUrl.searchParams.get("q")).toBe("artist:Radiohead track:Karma Police");
+  });
+});