mcp-qobuz copilot-instructions.md

Copilot Instructions — mcp-qobuz

Project context

@kud/mcp-qobuz is a TypeScript MCP server that exposes the Qobuz music service to AI assistants via the Model Context Protocol. It is one of four surfaces in the @kud/qobuz ecosystem; all share the @kud/qobuz core client library.

Stack:

• Runtime: Node.js >=20, ESM-only ("type": "module", NodeNext resolution)
• MCP layer: @modelcontextprotocol/sdk — tools registered with server.registerTool()
• Input validation: Zod v4 schemas passed directly to registerTool inputSchema
• Core client: @kud/qobuz (auth, API transport, types, deep-link helpers)
• Auth: macOS Keychain (createKeychainStore) or env vars (QOBUZ_TOKEN + QOBUZ_APP_ID)
• Tests: Vitest — unit tests mock @kud/qobuz via vi.fn(), export makeHandlers for testability
• Build: tsc → dist/, strict mode, no bundler

Key architectural invariants:

• All tool handlers live inside makeHandlers(client) and return ok(data) or err(message) — never throw out of a handler.
• Write tools (create-playlist, add-to-playlist, update-playlist-description) require confirm: true to execute; they return an err() message otherwise.
• now-playing is macOS-only and reads a local Qobuz desktop app state file; it must return a graceful err() on any other platform or when the file is absent.
• console.error is the correct logging channel (stdout is the MCP stdio transport).
• The convert-link tool is intentionally absent pending extraction of a shared @kud/song-match package. Do not copy the resolve logic into this repo.

---

Content rules

Flag these patterns:

1. Uncaught throws in tool handlers — every handler must catch its own errors and return err(msg). A throw propagating out of a handler crashes the MCP connection rather than returning a structured error to the client.

2. console.log in server code — only console.error is safe; console.log writes to stdout which is the MCP stdio transport and will corrupt the protocol stream.