soundcloud-mcp CLAUDE.md

CLAUDE.md

Working notes for agents in this repo. See PLAN.md for status and the full API audit.

Layout

One package, pnpm, Node 22+. Two servers over one shared core:

• src/client.ts, tools.ts, types.ts, server.ts, icon.ts — shared. Runtime-neutral: no Node APIs, no Workers APIs. A tool change belongs here and lands in both servers at once.
• src/index.ts + src/stdio/ — the stdio server. pnpm build first; clients run the compiled build/index.js, not the TS.
• src/worker.ts + src/worker/ — the Cloudflare Workers server.

Two tsconfigs, because Node and Workers disagree about fetch/Request even though they share source files. pnpm typecheck runs both; tsconfig.build.json must keep excluding the worker paths, since exclude replaces rather than extends the base.

Relative imports need .js extensions everywhere — the Node build is NodeNext and requires them. Wrangler's bundler resolves them to .ts fine.

Verify stdio changes against the live API with pnpm verify, which exercises every read tool plus a create/read/delete playlist round-trip, checks the resources and templates, and cleans up after itself. For the worker, at minimum pnpm exec wrangler deploy --dry-run proves it still bundles.

SoundCloud API rules

Authoritative sources, in order: the OpenAPI spec at https://github.com/soundcloud/api (openapi/api.yaml), SoundCloud's Agents.md in that same repo, then https://developers.soundcloud.com/docs/api/guide. Check the spec before adding an endpoint — several plausible-looking ones were removed from the public API and now return 405 (see PLAN.md).

• Two hosts. https://api.soundcloud.com for the API, https://secure.soundcloud.com for /authorize and /oauth/token. The legacy api.soundcloud.com/oauth2/token is explicitly deprecated.
• Authorization: OAuth <token> — not Bearer. This fails silently-ish (401) if you copy a Spotify-shaped client.
• URNs, not numeric ids. Paths take soundcloud:tracks:123. Numeric ids still resolve today but are deprecated; normalize at the client boundary.
• Refresh tokens are single-use. Every refresh returns a new one. Persist it or the next refresh fails permanently and the user has to re-auth.
• PKCE is mandatory (OAuth 2.1). The verifier must survive the redirect — in the worker it lives in KV keyed by the OAuth state token.
• Client-credentials tokens are rate limited hard: 50 per 12h per app, 30 per hour per IP. Cache them; never mint one per request.
• Pagination is cursor-based. Pass linked_partitioning=true and follow next_href, which is an absolute URL — fetch it as-is, do not re-base it onto the API root. Default page 50, max 200.
• Playlist writes replace the whole tracklist — there is no append endpoint. Read, concatenate, PUT. Track ids above int32 (2147483647) must be sent as URN strings or the API returns 422 with no useful message.
• access is playable | preview | blocked. Blocked tracks have no stream. /tracks/{urn}/streams returns time-limited URLs; the older /stream endpoint is deprecated.