mr-magic-mcp-server 0.2.6 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +53 -24
- package/README.md +439 -143
- package/package.json +4 -2
- package/src/providers/genius.js +1 -1
- package/src/providers/musixmatch.js +2 -3
- package/src/scripts/fetch_genius_token.mjs +21 -4
- package/src/scripts/fetch_musixmatch_token.mjs +169 -23
- package/src/scripts/push_musixmatch_token.mjs +133 -0
- package/src/transport/mcp-tools.js +2 -3
- package/src/transport/token-startup-log.js +4 -5
- package/src/utils/config.js +1 -1
- package/src/utils/kv-store.js +157 -0
- package/src/utils/tokens/genius-token-manager.js +97 -22
- package/src/utils/tokens/musixmatch-token-manager.js +77 -36
package/README.md
CHANGED
|
@@ -35,116 +35,288 @@ automations, and CLI aficionados can all request lyrics from a single toolchain.
|
|
|
35
35
|
|
|
36
36
|
## Installation
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
Mr. Magic publishes four named binaries through npm:
|
|
39
39
|
|
|
40
|
-
|
|
41
|
-
|
|
40
|
+
| Binary | Transport | Default port |
|
|
41
|
+
| ----------------- | -------------------------------------- | ------------ |
|
|
42
|
+
| `mcp-server` | MCP stdio | n/a (stdio) |
|
|
43
|
+
| `mcp-http-server` | MCP Streamable HTTP & SSE + legacy SSE | `3444` |
|
|
44
|
+
| `http-server` | JSON HTTP automation | `3333` |
|
|
45
|
+
| `mrmagic-cli` | CLI | n/a |
|
|
46
|
+
|
|
47
|
+
Choose the option that matches how you'll use Mr. Magic.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
### Option 1 — Local clone (recommended for persistent use)
|
|
52
|
+
|
|
53
|
+
Cloning the repo is the **simplest setup for local MCP clients** (Cline, Claude Desktop, etc.)
|
|
54
|
+
and for anyone who wants to use all features without extra ceremony.
|
|
55
|
+
Credentials live in a local `.env` file — no need to inject every variable through an MCP client
|
|
56
|
+
config. Token fetch scripts, the Playwright workflow, and local export storage all work out of the box.
|
|
57
|
+
|
|
58
|
+
1. Clone and install:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
git clone https://github.com/mrnajiboy/mr-magic-mcp-server.git
|
|
62
|
+
cd mr-magic-mcp-server
|
|
63
|
+
npm install
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
2. Create a `.env` file (copy `.env.example` as a starting point) and fill in your credentials.
|
|
67
|
+
See [Environment Variables](#environment-variables) for the full list.
|
|
68
|
+
|
|
69
|
+
3. Run the desired entrypoint:
|
|
70
|
+
|
|
71
|
+
| What you want | Command |
|
|
72
|
+
| ---------------------------------- | --------------------------------- |
|
|
73
|
+
| MCP stdio (local MCP clients) | `node src/bin/mcp-server.js` |
|
|
74
|
+
| MCP Streamable HTTP & SSE (remote) | `node src/bin/mcp-http-server.js` |
|
|
75
|
+
| JSON HTTP automation | `node src/bin/http-server.js` |
|
|
76
|
+
| CLI | `node src/bin/cli.js --help` |
|
|
77
|
+
|
|
78
|
+
Or use the npm scripts:
|
|
79
|
+
```bash
|
|
80
|
+
npm run server:mcp # MCP stdio
|
|
81
|
+
npm run server:mcp:http # MCP Streamable HTTP & SSE — 127.0.0.1:3444
|
|
82
|
+
npm run server:http # JSON HTTP — 127.0.0.1:3333
|
|
83
|
+
npm run cli -- --help # CLI
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
> ⚠️ **Stdio MCP clients:** Do not use `npm run server:mcp` in your MCP client config.
|
|
87
|
+
> Use `node src/bin/mcp-server.js` directly. The npm script preamble is written to stdout
|
|
88
|
+
> before Node starts and causes `"Unexpected token '>'"` JSON-RPC errors on every connection.
|
|
89
|
+
|
|
90
|
+
See [MCP Client Configuration → Local repo](#local-repo--cline) for the client config snippets.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
### Option 2 — npx (no clone, ephemeral or CI use)
|
|
95
|
+
|
|
96
|
+
`npx` is useful for quick one-off runs or CI contexts, but has an important limitation:
|
|
97
|
+
**the spawned process cannot read a local `.env` file** — every credential must be passed
|
|
98
|
+
as an environment variable in the shell or in your MCP client's `env` block.
|
|
99
|
+
|
|
100
|
+
This package publishes **multiple binaries**, so you must always specify which one you want
|
|
101
|
+
using `--package` and then the binary name. `npx -y mr-magic-mcp-server` is **not valid**
|
|
102
|
+
for this package — it would error because no binary named `mr-magic-mcp-server` exists.
|
|
103
|
+
|
|
104
|
+
#### MCP stdio server (for MCP client config)
|
|
42
105
|
|
|
43
106
|
```bash
|
|
44
|
-
|
|
107
|
+
# Shell (test only — real credentials come from MCP client env block)
|
|
108
|
+
MR_MAGIC_QUIET_STDIO=1 \
|
|
109
|
+
GENIUS_CLIENT_ID=your_id \
|
|
110
|
+
GENIUS_CLIENT_SECRET=your_secret \
|
|
111
|
+
MUSIXMATCH_DIRECT_TOKEN='...' \
|
|
112
|
+
npx -y --package mr-magic-mcp-server mcp-server
|
|
45
113
|
```
|
|
46
114
|
|
|
47
|
-
|
|
115
|
+
For MCP clients (Cline, Claude Desktop, etc.), put credentials in the `env` block of your
|
|
116
|
+
config — see [MCP Client Configuration → npx](#npx-no-clone-required).
|
|
117
|
+
|
|
118
|
+
#### MCP Streamable HTTP & SSE server (for remote / browser-based MCP clients)
|
|
48
119
|
|
|
49
120
|
```bash
|
|
50
|
-
|
|
121
|
+
# Streamable HTTP & SSE — listens on port 3444, endpoint: /mcp
|
|
122
|
+
GENIUS_CLIENT_ID=your_id \
|
|
123
|
+
GENIUS_CLIENT_SECRET=your_secret \
|
|
124
|
+
MUSIXMATCH_DIRECT_TOKEN='...' \
|
|
125
|
+
npx -y --package mr-magic-mcp-server mcp-http-server
|
|
51
126
|
```
|
|
52
127
|
|
|
53
|
-
|
|
128
|
+
Connect your client to `http://localhost:3444/mcp` (or your public URL + `/mcp`).
|
|
129
|
+
|
|
130
|
+
The same server exposes the **legacy SSE** endpoints for older clients:
|
|
131
|
+
|
|
132
|
+
- `GET /sse` — opens the event stream
|
|
133
|
+
- `POST /messages?sessionId=...` — sends JSON-RPC messages
|
|
134
|
+
|
|
135
|
+
Both protocols run on the same port simultaneously — no extra config needed.
|
|
136
|
+
|
|
137
|
+
#### JSON HTTP automation server
|
|
54
138
|
|
|
55
139
|
```bash
|
|
56
|
-
|
|
57
|
-
|
|
140
|
+
# JSON HTTP — listens on port 3333, endpoint: POST /
|
|
141
|
+
GENIUS_CLIENT_ID=your_id \
|
|
142
|
+
GENIUS_CLIENT_SECRET=your_secret \
|
|
143
|
+
MUSIXMATCH_DIRECT_TOKEN='...' \
|
|
144
|
+
npx -y --package mr-magic-mcp-server http-server
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
#### CLI
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
# Run a one-off CLI command
|
|
151
|
+
GENIUS_CLIENT_ID=your_id \
|
|
152
|
+
npx -y --package mr-magic-mcp-server mrmagic-cli find --artist "Coldplay" --title "Yellow"
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
#### npx reference — all entrypoints
|
|
156
|
+
|
|
157
|
+
| What you want | Command |
|
|
158
|
+
| -------------------------------- | ---------------------------------------------------------- |
|
|
159
|
+
| MCP stdio | `npx -y --package mr-magic-mcp-server mcp-server` |
|
|
160
|
+
| MCP Streamable HTTP & SSE (+SSE) | `npx -y --package mr-magic-mcp-server mcp-http-server` |
|
|
161
|
+
| JSON HTTP automation | `npx -y --package mr-magic-mcp-server http-server` |
|
|
162
|
+
| CLI | `npx -y --package mr-magic-mcp-server mrmagic-cli --help` |
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
### Option 3 — Global install (binaries always on PATH)
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
npm install -g mr-magic-mcp-server
|
|
170
|
+
|
|
171
|
+
mcp-server # MCP stdio server
|
|
172
|
+
mcp-http-server # Streamable HTTP & SSE MCP server (+ legacy SSE on same port)
|
|
58
173
|
http-server # JSON HTTP automation server
|
|
59
174
|
mrmagic-cli --help # CLI
|
|
60
175
|
```
|
|
61
176
|
|
|
62
|
-
|
|
177
|
+
When the binary is launched by an MCP client, it does **not** automatically read a `.env` file
|
|
178
|
+
unless you point to one via `MR_MAGIC_ENV_PATH`. Either pass credentials through the client
|
|
179
|
+
`env` block or set them as system/user environment variables.
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
### Musixmatch token for npx / ephemeral / headless installs
|
|
63
184
|
|
|
64
|
-
|
|
185
|
+
When running via `npx`, on Render free tier, or on any server without a browser or
|
|
186
|
+
persistent filesystem, the Musixmatch token cannot be captured via Playwright there.
|
|
187
|
+
The workflow is:
|
|
188
|
+
|
|
189
|
+
1. **Capture the token locally** (one-time on any machine with a browser):
|
|
65
190
|
|
|
66
191
|
```bash
|
|
67
192
|
git clone https://github.com/mrnajiboy/mr-magic-mcp-server.git
|
|
68
|
-
cd mr-magic-mcp-server
|
|
193
|
+
cd mr-magic-mcp-server && npm install
|
|
194
|
+
npm run fetch:musixmatch-token
|
|
69
195
|
```
|
|
70
196
|
|
|
71
|
-
|
|
197
|
+
After signing in, the script prints the full token JSON payload.
|
|
198
|
+
Copy the entire printed JSON object (the `MUSIXMATCH_DIRECT_TOKEN=...` line).
|
|
199
|
+
|
|
200
|
+
2. **Push to KV** so the server can read it on every cold start.
|
|
201
|
+
Set up Upstash Redis (free tier at [console.upstash.com](https://console.upstash.com/redis))
|
|
202
|
+
and run the push script with KV credentials. No browser needed:
|
|
72
203
|
|
|
73
204
|
```bash
|
|
74
|
-
|
|
205
|
+
UPSTASH_REDIS_REST_URL=https://xxx.upstash.io \
|
|
206
|
+
UPSTASH_REDIS_REST_TOKEN=your_upstash_token \
|
|
207
|
+
MUSIXMATCH_DIRECT_TOKEN='<paste token JSON here>' \
|
|
208
|
+
npm run push:musixmatch-token
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
3. **Start the server** with the same Upstash credentials — it reads the token from
|
|
212
|
+
KV on every cold start (no `MUSIXMATCH_DIRECT_TOKEN` needed when KV is configured):
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
GENIUS_DIRECT_TOKEN=... \
|
|
216
|
+
UPSTASH_REDIS_REST_URL=https://xxx.upstash.io \
|
|
217
|
+
UPSTASH_REDIS_REST_TOKEN=your_upstash_token \
|
|
218
|
+
npx -y --package mr-magic-mcp-server mcp-http-server
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
4. Re-run steps 1–2 only when the Musixmatch token expires (typically ~30 days).
|
|
222
|
+
|
|
223
|
+
#### Musixmatch on Render (headless, no SSH)
|
|
224
|
+
|
|
225
|
+
On Render free tier you cannot SSH in or open a browser. The recommended pattern is:
|
|
226
|
+
|
|
227
|
+
1. Run `npm run fetch:musixmatch-token` locally, copy the token JSON from the output.
|
|
228
|
+
|
|
229
|
+
2. In the Render Dashboard → **Environment** tab, set:
|
|
230
|
+
- `MUSIXMATCH_DIRECT_TOKEN` = `<your token JSON>` _(used as both push source and runtime override)_
|
|
231
|
+
- `UPSTASH_REDIS_REST_URL` = your Upstash endpoint
|
|
232
|
+
- `UPSTASH_REDIS_REST_TOKEN` = your Upstash token
|
|
233
|
+
|
|
234
|
+
3. Set the Render **Start Command** to:
|
|
235
|
+
|
|
236
|
+
```
|
|
237
|
+
npm run push:musixmatch-token && npm run server:mcp:http
|
|
75
238
|
```
|
|
76
239
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
> Run `npm link` (dev symlink) or install globally to get `mrmagic-cli` on `PATH`.
|
|
240
|
+
On every (re)start, the token is pushed to Upstash then the server reads it
|
|
241
|
+
from KV. If `MUSIXMATCH_DIRECT_TOKEN` is unset the push step is a silent no-op.
|
|
80
242
|
|
|
81
|
-
|
|
82
|
-
|
|
243
|
+
4. When the token expires: update `MUSIXMATCH_DIRECT_TOKEN` from a fresh local
|
|
244
|
+
`fetch:musixmatch-token` run, trigger a redeploy on Render. Done.
|
|
83
245
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
- CLI: `npm run cli -- --help`
|
|
246
|
+
> **Genius on ephemeral hosts:** Genius does not need this flow.
|
|
247
|
+
> Set `GENIUS_CLIENT_ID` + `GENIUS_CLIENT_SECRET` instead — the server calls the
|
|
248
|
+
> Genius OAuth `client_credentials` endpoint at runtime, auto-refreshes the token
|
|
249
|
+
> in memory, and never needs a browser, a KV store, or a captured session token.
|
|
89
250
|
|
|
90
251
|
## Environment Variables
|
|
91
252
|
|
|
92
253
|
Copy `.env.example` to `.env` (or inject via your platform dashboard). Variables are
|
|
93
254
|
grouped below by purpose.
|
|
94
255
|
|
|
95
|
-
### Server and runtime
|
|
96
|
-
|
|
97
|
-
| Variable | Default | Description |
|
|
98
|
-
| -------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
99
|
-
| `PORT` | `3444` / `3333` | Override server port. On Render this is set automatically (default `10000`). |
|
|
100
|
-
| `LOG_LEVEL` | `info` | Verbosity: `error` \| `warn` \| `info` \| `debug`. |
|
|
101
|
-
| `MR_MAGIC_QUIET_STDIO` | `0` | Set to `1` to suppress non-error stdout logs (forces `LOG_LEVEL=error`). Recommended under stdio MCP clients. |
|
|
102
|
-
| `MR_MAGIC_HTTP_TIMEOUT_MS` | `10000` | Global outbound HTTP timeout in milliseconds. |
|
|
103
|
-
| `MR_MAGIC_ROOT` | _(project root)_ | Override the project root used for `.env` and `.cache` path resolution. |
|
|
104
|
-
| `MR_MAGIC_ENV_PATH` | _(auto)_ | Point to a specific `.env` file instead of `<project root>/.env`. |
|
|
105
|
-
| `MR_MAGIC_ALLOWED_HOSTS` | _(empty)_ | Comma-separated extra hostnames allowed for DNS rebinding protection when binding to `0.0.0.0`. `RENDER_EXTERNAL_HOSTNAME` is included automatically on Render. Only needed for custom domains. |
|
|
106
|
-
| `MR_MAGIC_SESSIONLESS` | `0` | Set to `1` to force **sessionless mode** on the MCP Streamable HTTP server — each request is handled by a fresh, temporary server/transport with no in-memory session state. Auto-enabled on Render (see below). |
|
|
107
|
-
|
|
108
256
|
### Genius credentials
|
|
109
257
|
|
|
110
|
-
| Variable | Description
|
|
111
|
-
| ---------------------- |
|
|
258
|
+
| Variable | Description |
|
|
259
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
112
260
|
| `GENIUS_CLIENT_ID` | OAuth client ID for auto-refresh (recommended). Get from [genius.com/api-clients](https://genius.com/api-clients). |
|
|
113
|
-
| `GENIUS_CLIENT_SECRET` | OAuth client secret for auto-refresh (recommended).
|
|
114
|
-
| `
|
|
261
|
+
| `GENIUS_CLIENT_SECRET` | OAuth client secret for auto-refresh (recommended). |
|
|
262
|
+
| `GENIUS_DIRECT_TOKEN` | Static direct bearer token. Used when client credentials are unavailable. |
|
|
115
263
|
|
|
116
264
|
Token resolution order (first match wins):
|
|
117
265
|
|
|
118
266
|
1. In-memory runtime cache
|
|
119
267
|
2. Auto-refresh via `GENIUS_CLIENT_ID` + `GENIUS_CLIENT_SECRET` ← **recommended**
|
|
120
|
-
3. `
|
|
121
|
-
4.
|
|
268
|
+
3. `GENIUS_DIRECT_TOKEN` env var (static, no auto-refresh)
|
|
269
|
+
4. KV store — Upstash Redis or Cloudflare KV (written automatically by auto-refresh)
|
|
270
|
+
5. On-disk `.cache/genius-token.json` (local dev only)
|
|
122
271
|
|
|
123
272
|
### Musixmatch credentials
|
|
124
273
|
|
|
125
|
-
| Variable
|
|
126
|
-
|
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
274
|
+
| Variable | Description |
|
|
275
|
+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
276
|
+
| `MUSIXMATCH_DIRECT_TOKEN` | Static bearer token. Recommended for production / ephemeral hosts. Also used as push source by `push:musixmatch-token`. |
|
|
277
|
+
| `MUSIXMATCH_TOKEN_KV_KEY` | KV key name for the token store. Default: `mr-magic:musixmatch-token`. |
|
|
278
|
+
| `MUSIXMATCH_TOKEN_KV_TTL_SECONDS` | Token TTL in the KV store (seconds). Default: `2592000` (30 days). |
|
|
279
|
+
| `MUSIXMATCH_TOKEN_CACHE` | Path to the on-disk cache file. Default: `.cache/musixmatch-token.json`. |
|
|
280
|
+
| `MUSIXMATCH_AUTO_FETCH` | Set to `1` to attempt headless token re-fetch when no token is found. |
|
|
281
|
+
|
|
282
|
+
Token resolution order (first match wins):
|
|
283
|
+
|
|
284
|
+
1. **Env var** — `MUSIXMATCH_DIRECT_TOKEN`
|
|
285
|
+
2. **KV store** — Upstash Redis (priority 1) or Cloudflare KV (priority 2)
|
|
286
|
+
3. **On-disk cache** — `.cache/musixmatch-token.json` (local dev / persistent servers)
|
|
131
287
|
|
|
132
288
|
### Export and storage
|
|
133
289
|
|
|
134
|
-
| Variable | Default | Description
|
|
135
|
-
| ----------------------------------- | ---------- |
|
|
290
|
+
| Variable | Default | Description |
|
|
291
|
+
| ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
136
292
|
| `MR_MAGIC_EXPORT_BACKEND` | `local` | Storage backend: `local` \| `inline` \| `redis`. |
|
|
137
|
-
| `MR_MAGIC_EXPORT_DIR` | `exports/` | Absolute path for local exports. Required when backend is `local`.
|
|
138
|
-
| `MR_MAGIC_EXPORT_TTL_SECONDS` | `3600` | TTL for `local` and `redis` backends (ignored for `inline`).
|
|
139
|
-
| `MR_MAGIC_DOWNLOAD_BASE_URL` | _(none)_ | Public base URL for download links, e.g. `https://lyrics.example.com`.
|
|
293
|
+
| `MR_MAGIC_EXPORT_DIR` | `exports/` | Absolute path for local exports. Required when backend is `local`. |
|
|
294
|
+
| `MR_MAGIC_EXPORT_TTL_SECONDS` | `3600` | TTL for `local` and `redis` backends (ignored for `inline`). |
|
|
295
|
+
| `MR_MAGIC_DOWNLOAD_BASE_URL` | _(none)_ | Public base URL for download links, e.g. `https://lyrics.example.com`. |
|
|
140
296
|
| `MR_MAGIC_INLINE_PAYLOAD_MAX_CHARS` | `1500` | Character threshold at which `build_catalog_payload` auto-promotes to `reference` transport when `omitInlineLyrics` is `true`. |
|
|
141
|
-
| `UPSTASH_REDIS_REST_URL` |
|
|
142
|
-
| `UPSTASH_REDIS_REST_TOKEN` |
|
|
297
|
+
| `UPSTASH_REDIS_REST_URL` | — | Upstash Redis KV backend URL. Also used by the export backend when `MR_MAGIC_EXPORT_BACKEND=redis` — set once, used for both. |
|
|
298
|
+
| `UPSTASH_REDIS_REST_TOKEN` | — | Upstash Redis KV bearer token. Takes precedence over Cloudflare KV when both are set. |
|
|
299
|
+
| `CF_API_TOKEN` | — | Cloudflare API token with `KV:Edit` permission (Cloudflare KV backend). |
|
|
300
|
+
| `CF_ACCOUNT_ID` | — | Cloudflare account ID (Cloudflare KV backend). |
|
|
301
|
+
| `CF_KV_NAMESPACE_ID` | — | Cloudflare KV namespace ID (Cloudflare KV backend). |
|
|
302
|
+
|
|
303
|
+
### Server and runtime
|
|
304
|
+
|
|
305
|
+
| Variable | Default | Description |
|
|
306
|
+
| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
307
|
+
| `PORT` | `3444` / `3333` | Override server port. On Render this is set automatically (default `10000`). |
|
|
308
|
+
| `LOG_LEVEL` | `info` | Verbosity: `error` \| `warn` \| `info` \| `debug`. |
|
|
309
|
+
| `MR_MAGIC_QUIET_STDIO` | `0` | Set to `1` to suppress non-error stdout logs (forces `LOG_LEVEL=error`). Recommended under stdio MCP clients. |
|
|
310
|
+
| `MR_MAGIC_HTTP_TIMEOUT_MS` | `10000` | Global outbound HTTP timeout in milliseconds. |
|
|
311
|
+
| `MR_MAGIC_ROOT` | _(project root)_ | Override the project root used for `.env` and `.cache` path resolution. |
|
|
312
|
+
| `MR_MAGIC_ENV_PATH` | _(auto)_ | Point to a specific `.env` file instead of `<project root>/.env`. |
|
|
313
|
+
| `MR_MAGIC_ALLOWED_HOSTS` | _(empty)_ | Comma-separated extra hostnames allowed for DNS rebinding protection when binding to `0.0.0.0`. `RENDER_EXTERNAL_HOSTNAME` is included automatically on Render. Only needed for custom domains. |
|
|
314
|
+
| `MR_MAGIC_SESSIONLESS` | `0` | Set to `1` to force **sessionless mode** on the MCP Streamable HTTP & SSE server — each request is handled by a fresh, temporary server/transport with no in-memory session state. Auto-enabled on Render (see below). |
|
|
143
315
|
|
|
144
316
|
### Airtable
|
|
145
317
|
|
|
146
|
-
| Variable | Description
|
|
147
|
-
| -------------------------------- |
|
|
318
|
+
| Variable | Description |
|
|
319
|
+
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
148
320
|
| `AIRTABLE_PERSONAL_ACCESS_TOKEN` | Required for `push_catalog_to_airtable`. Generate at [airtable.com/create/tokens](https://airtable.com/create/tokens) with `data.records:write` scope. |
|
|
149
321
|
|
|
150
322
|
### Melon
|
|
@@ -155,12 +327,12 @@ Token resolution order (first match wins):
|
|
|
155
327
|
|
|
156
328
|
### Diagnostics and debugging
|
|
157
329
|
|
|
158
|
-
| Variable | Default | Description
|
|
159
|
-
| ------------------------------- | ------- |
|
|
160
|
-
| `MR_MAGIC_MCP_HTTP_DIAGNOSTICS` | `0` | Set to `1` to log enriched request metadata at the Streamable HTTP transport boundary. |
|
|
161
|
-
| `MR_MAGIC_LOG_TOOL_ARGS_CHUNKS` | `0` | Set to `1` to emit chunk-by-chunk MCP tool argument previews for truncation debugging.
|
|
162
|
-
| `MR_MAGIC_TOOL_ARG_CHUNK_SIZE` | `400` | Chunk size (chars) used when chunk logging is enabled.
|
|
163
|
-
| `MR_MAGIC_SDK_REPRO_HTTP_DEBUG` | `0` | Set to `1` for verbose HTTP traces in the SDK repro harness script.
|
|
330
|
+
| Variable | Default | Description |
|
|
331
|
+
| ------------------------------- | ------- | -------------------------------------------------------------------------------------------- |
|
|
332
|
+
| `MR_MAGIC_MCP_HTTP_DIAGNOSTICS` | `0` | Set to `1` to log enriched request metadata at the Streamable HTTP & SSE transport boundary. |
|
|
333
|
+
| `MR_MAGIC_LOG_TOOL_ARGS_CHUNKS` | `0` | Set to `1` to emit chunk-by-chunk MCP tool argument previews for truncation debugging. |
|
|
334
|
+
| `MR_MAGIC_TOOL_ARG_CHUNK_SIZE` | `400` | Chunk size (chars) used when chunk logging is enabled. |
|
|
335
|
+
| `MR_MAGIC_SDK_REPRO_HTTP_DEBUG` | `0` | Set to `1` for verbose HTTP traces in the SDK repro harness script. |
|
|
164
336
|
|
|
165
337
|
## Provider Credentials
|
|
166
338
|
|
|
@@ -173,7 +345,7 @@ Genius credentials are resolved in this order — the first available source win
|
|
|
173
345
|
refreshed in memory. **Recommended for all deployments**, including Render and
|
|
174
346
|
ephemeral hosts. No disk, no scripts, no manual token copying.
|
|
175
347
|
|
|
176
|
-
2. **
|
|
348
|
+
2. **Direct token** (`GENIUS_DIRECT_TOKEN`) — a static bearer token. Works
|
|
177
349
|
everywhere but does not auto-refresh. Update by redeploying with a new value.
|
|
178
350
|
|
|
179
351
|
3. **Cache token** (`.cache/genius-token.json`) — written by `npm run fetch:genius-token`.
|
|
@@ -185,9 +357,8 @@ Musixmatch uses a captured browser session token. There is no OAuth callback.
|
|
|
185
357
|
|
|
186
358
|
**For production / ephemeral hosts (Render, containers):**
|
|
187
359
|
|
|
188
|
-
Set `
|
|
189
|
-
|
|
190
|
-
when the filesystem may be wiped between restarts.
|
|
360
|
+
Set `MUSIXMATCH_DIRECT_TOKEN` directly in your environment. This is the highest-priority
|
|
361
|
+
env var option and the only reliable one when the filesystem may be wiped between restarts.
|
|
191
362
|
|
|
192
363
|
**For local development:**
|
|
193
364
|
|
|
@@ -205,11 +376,11 @@ The workflow:
|
|
|
205
376
|
3. After the redirect to `https://www.musixmatch.com/discover`, the script prints
|
|
206
377
|
the captured token and writes the cache file.
|
|
207
378
|
4. **For remote deployments:** copy the `token` value from the printed JSON and set
|
|
208
|
-
it as `
|
|
379
|
+
it as `MUSIXMATCH_DIRECT_TOKEN` in your platform environment. Do **not** rely on
|
|
209
380
|
the cache file surviving restarts on ephemeral hosts.
|
|
210
381
|
|
|
211
382
|
> **Developer accounts:** Get API access from [developer.musixmatch.com](https://developer.musixmatch.com)
|
|
212
|
-
> and set the resulting token as `
|
|
383
|
+
> and set the resulting token as `MUSIXMATCH_DIRECT_TOKEN`.
|
|
213
384
|
>
|
|
214
385
|
> **Public accounts:** Visit [auth.musixmatch.com](https://auth.musixmatch.com), sign in,
|
|
215
386
|
> and capture the token using the script above.
|
|
@@ -244,7 +415,7 @@ e.g. `https://lyrics.example.com`. Download links are built as
|
|
|
244
415
|
|
|
245
416
|
Both HTTP servers serve `/downloads/:id/:ext` routes:
|
|
246
417
|
|
|
247
|
-
- **`server:mcp:http`** (port `3444`) — the Streamable HTTP MCP server includes its
|
|
418
|
+
- **`server:mcp:http`** (port `3444`) — the Streamable HTTP & SSE MCP server includes its
|
|
248
419
|
own `/downloads` route. If you are already running this server, no additional HTTP
|
|
249
420
|
server is needed for Redis exports on Render or any remote deployment.
|
|
250
421
|
- **`server:http`** (port `3333`) — the JSON HTTP automation server also exposes the
|
|
@@ -270,11 +441,11 @@ Run whichever entrypoint you need via npm scripts:
|
|
|
270
441
|
```bash
|
|
271
442
|
npm run server:http # JSON HTTP automation — 127.0.0.1:3333 by default
|
|
272
443
|
npm run server:mcp # MCP stdio transport — ideal for local MCP clients
|
|
273
|
-
npm run server:mcp:http # Streamable HTTP MCP — 127.0.0.1:3444 by default
|
|
444
|
+
npm run server:mcp:http # Streamable HTTP & SSE MCP — 127.0.0.1:3444 by default
|
|
274
445
|
npm run cli -- --help # CLI entrypoint
|
|
275
446
|
```
|
|
276
447
|
|
|
277
|
-
Set provider tokens via `.env` before running. `dotenv` is for local convenience only —
|
|
448
|
+
Set provider tokens via `.env` before running. `dotenv` dependency is for local convenience only —
|
|
278
449
|
production environments should inject vars directly.
|
|
279
450
|
|
|
280
451
|
## Remote Deployment
|
|
@@ -309,7 +480,7 @@ Recommended Render service settings:
|
|
|
309
480
|
|
|
310
481
|
- **Start Command:** `npm run server:mcp:http`
|
|
311
482
|
- **Environment:** set provider credentials (`GENIUS_CLIENT_ID`, `GENIUS_CLIENT_SECRET`,
|
|
312
|
-
`
|
|
483
|
+
`MUSIXMATCH_DIRECT_TOKEN`, etc.) in the Render Dashboard → Environment tab
|
|
313
484
|
- **Health Check Path:** `/health` (returns `{ "status": "ok", "providers": [...] }`)
|
|
314
485
|
|
|
315
486
|
> For custom domains, add them to `MR_MAGIC_ALLOWED_HOSTS` (comma-separated) in
|
|
@@ -318,7 +489,7 @@ Recommended Render service settings:
|
|
|
318
489
|
|
|
319
490
|
#### Sessionless mode on Render (automatic)
|
|
320
491
|
|
|
321
|
-
When `RENDER=true` is detected, the MCP Streamable HTTP server automatically operates
|
|
492
|
+
When `RENDER=true` is detected, the MCP Streamable HTTP & SSE server automatically operates
|
|
322
493
|
in **sessionless mode**. This is essential for multi-instance deployments where Render
|
|
323
494
|
routes requests across several processes:
|
|
324
495
|
|
|
@@ -337,12 +508,12 @@ a similar load-balanced, stateless deployment is used.
|
|
|
337
508
|
|
|
338
509
|
### Transport selection
|
|
339
510
|
|
|
340
|
-
| Transport
|
|
341
|
-
|
|
|
342
|
-
| MCP stdio
|
|
343
|
-
| MCP Streamable HTTP | `npm run server:mcp:http` | Remote MCP clients |
|
|
344
|
-
| JSON HTTP automation
|
|
345
|
-
| CLI
|
|
511
|
+
| Transport | Command | Use case |
|
|
512
|
+
| -------------------------- | ------------------------- | ----------------------------------- |
|
|
513
|
+
| MCP stdio | `npm run server:mcp` | Local MCP clients that speak stdio |
|
|
514
|
+
| MCP Streamable HTTP & SSE | `npm run server:mcp:http` | Remote MCP clients |
|
|
515
|
+
| JSON HTTP automation | `npm run server:http` | Container / remote automations |
|
|
516
|
+
| CLI | `npm run cli` | Ad-hoc / SSH / CI one-shot commands |
|
|
346
517
|
|
|
347
518
|
## HTTP Endpoints
|
|
348
519
|
|
|
@@ -353,8 +524,8 @@ transports. These are accessible without any MCP or JSON-RPC framing.
|
|
|
353
524
|
| --------------------- | ----------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
354
525
|
| `/health` | `GET` | Both | Liveness / readiness probe. Returns `{ "status": "ok", "providers": [...] }`. |
|
|
355
526
|
| `/downloads/:id/:ext` | `GET` | Both | Serve a Redis-backed export by ID and file extension (e.g. `plain`, `lrc`, `srt`). Returns `200 text/plain` on hit, `404` when the key is expired or missing. |
|
|
356
|
-
| `/mcp` | `POST/GET/DELETE` | `server:mcp:http` only | MCP **Streamable HTTP** transport endpoint (JSON-RPC 2.0). Each `initialize` request creates an independent session — reconnects work correctly.
|
|
357
|
-
| `/sse` | `GET` | `server:mcp:http` only | MCP **legacy SSE** transport. Opens a server-sent event stream. For MCP clients that use the pre-Streamable HTTP protocol.
|
|
527
|
+
| `/mcp` | `POST/GET/DELETE` | `server:mcp:http` only | MCP **Streamable HTTP & SSE** transport endpoint (JSON-RPC 2.0). Each `initialize` request creates an independent session — reconnects work correctly. |
|
|
528
|
+
| `/sse` | `GET` | `server:mcp:http` only | MCP **legacy SSE** transport. Opens a server-sent event stream. For MCP clients that use the pre-Streamable HTTP & SSE protocol. |
|
|
358
529
|
| `/messages` | `POST` | `server:mcp:http` only | Companion to `/sse`. Routes JSON-RPC messages to the correct SSE session via `?sessionId=` query param. |
|
|
359
530
|
| `/` | `POST` | `server:http` only | JSON HTTP automation endpoint (action-based API). |
|
|
360
531
|
|
|
@@ -435,7 +606,7 @@ Responses:
|
|
|
435
606
|
|
|
436
607
|
## MCP Tools
|
|
437
608
|
|
|
438
|
-
Both the stdio and Streamable HTTP transports expose the same tool registry:
|
|
609
|
+
Both the stdio and Streamable HTTP & SSE transports expose the same tool registry:
|
|
439
610
|
|
|
440
611
|
| Tool | Purpose |
|
|
441
612
|
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -490,7 +661,7 @@ this forces a two-step create → PATCH so the full payload is never sent in one
|
|
|
490
661
|
|
|
491
662
|
### Bundled prompt template
|
|
492
663
|
|
|
493
|
-
`prompts/airtable-song-importer.md` (shipped in the
|
|
664
|
+
`prompts/airtable-song-importer.md` (shipped in the source package) is a ready-to-use
|
|
494
665
|
system prompt for MCP assistants that bulk-import songs into Airtable. It covers:
|
|
495
666
|
|
|
496
667
|
- Phased execution: resolve → bulk create → write lyrics → SRT export
|
|
@@ -590,10 +761,63 @@ Recommended presets:
|
|
|
590
761
|
|
|
591
762
|
Mr. Magic supports two connection modes depending on where the MCP client runs:
|
|
592
763
|
|
|
593
|
-
| Mode
|
|
594
|
-
|
|
|
595
|
-
| **Local (stdio)**
|
|
596
|
-
| **Remote (Streamable HTTP)** | `POST https://your-server.com/mcp` | TypingMind, browser-based clients, and any client connecting to a deployed server |
|
|
764
|
+
| Mode | Transport | When to use |
|
|
765
|
+
| ---------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------- |
|
|
766
|
+
| **Local (stdio)** | `mcp-server` binary via stdin/stdout | Cline, Claude Desktop, and any client that runs locally on the same machine |
|
|
767
|
+
| **Remote (Streamable HTTP & SSE)** | `POST https://your-server.com/mcp` | TypingMind, browser-based clients, and any client connecting to a deployed server |
|
|
768
|
+
|
|
769
|
+
### Configuration modes at a glance
|
|
770
|
+
|
|
771
|
+
The right way to supply environment variables depends on how the server is launched:
|
|
772
|
+
|
|
773
|
+
| Config mode | How it starts | How to pass env vars | `.env` file read? |
|
|
774
|
+
| ---------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------- |
|
|
775
|
+
| **Local source** | `node src/bin/mcp-server.js` or `npm run server:mcp` | `.env` in project root, or shell exports | ✅ yes |
|
|
776
|
+
| **Local npx** | `npx --package mr-magic-mcp-server mcp-server` via MCP client | `env` block in MCP client config (see below) | ❌ no |
|
|
777
|
+
| **Persistent server** (VPS, global install, Docker with persistent FS) | `mcp-server` binary or `npm run server:mcp:http` | `.env` file **or** platform environment variables | ✅ if present |
|
|
778
|
+
| **Ephemeral server** (Render free tier, containers, serverless) | `npx` or process started fresh each time | Platform environment variables (Render Dashboard, Docker `--env`) | ❌ no |
|
|
779
|
+
|
|
780
|
+
> **`npx` and MCP clients:** When a local MCP client (Cline, Claude Desktop, etc.) starts the
|
|
781
|
+
> server via `npx`, the spawned process has **no access to your `.env` file** — your
|
|
782
|
+
> project root and shell environment are not inherited. Every required variable must be
|
|
783
|
+
> provided in the `env` block of your MCP client config. See the npx snippet below.
|
|
784
|
+
|
|
785
|
+
### Required variables by deployment type
|
|
786
|
+
|
|
787
|
+
#### Ephemeral / npx / stateless hosts (no persistent filesystem)
|
|
788
|
+
|
|
789
|
+
These variables should be passed explicitly — the server cannot fall back to `.env` or on-disk caches:
|
|
790
|
+
|
|
791
|
+
| Variable | Purpose | Required when |
|
|
792
|
+
| --------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
793
|
+
| `GENIUS_CLIENT_ID` + `GENIUS_CLIENT_SECRET` | Genius auto-refresh (recommended) | Using Genius |
|
|
794
|
+
| `GENIUS_DIRECT_TOKEN` | Static Genius token (alternative) | Using Genius without OAuth credentials |
|
|
795
|
+
| `MUSIXMATCH_DIRECT_TOKEN` | Musixmatch token (highest priority) | Using Musixmatch |
|
|
796
|
+
| `UPSTASH_REDIS_REST_URL` + `UPSTASH_REDIS_REST_TOKEN` | KV store for Musixmatch token + Redis export backend | Musixmatch via KV **or** `MR_MAGIC_EXPORT_BACKEND=redis` |
|
|
797
|
+
| `MR_MAGIC_EXPORT_BACKEND` | Storage backend for exports (`inline` or `redis`) | Exporting lyrics; use `inline` if no Redis |
|
|
798
|
+
| `MR_MAGIC_DOWNLOAD_BASE_URL` | Base URL for download links | `MR_MAGIC_EXPORT_BACKEND=redis` only |
|
|
799
|
+
| `AIRTABLE_PERSONAL_ACCESS_TOKEN` | Airtable push tool | Using `push_catalog_to_airtable` |
|
|
800
|
+
| `MR_MAGIC_QUIET_STDIO` | Suppress non-error stdout (set to `1`) | stdio MCP clients — avoids JSON-RPC parse errors |
|
|
801
|
+
|
|
802
|
+
> 💡 **Musixmatch on ephemeral hosts:** The on-disk token cache (`.cache/musixmatch-token.json`)
|
|
803
|
+
> is **not** available when running via `npx` or on ephemeral servers. Use `MUSIXMATCH_DIRECT_TOKEN`
|
|
804
|
+
> directly, or configure Upstash Redis (`UPSTASH_REDIS_REST_URL` + `UPSTASH_REDIS_REST_TOKEN`) and
|
|
805
|
+
> run `push:musixmatch-token` once to store the token in KV. See
|
|
806
|
+
> [Musixmatch token for npx / ephemeral / headless installs](#musixmatch-token-for-npx--ephemeral--headless-installs).
|
|
807
|
+
|
|
808
|
+
#### Local source / persistent servers (writable filesystem present)
|
|
809
|
+
|
|
810
|
+
In addition to the provider credentials above, local and persistent deployments can also use:
|
|
811
|
+
|
|
812
|
+
| Variable | Purpose |
|
|
813
|
+
| ------------------------------------- | --------------------------------------------------------------------- |
|
|
814
|
+
| `MR_MAGIC_EXPORT_BACKEND=local` | Write export files to disk (default; not usable on ephemeral hosts) |
|
|
815
|
+
| `MR_MAGIC_EXPORT_DIR` | Directory to write local exports into |
|
|
816
|
+
| `MR_MAGIC_ROOT` / `MR_MAGIC_ENV_PATH` | Override project root / `.env` path resolution |
|
|
817
|
+
| `MUSIXMATCH_AUTO_FETCH` | Auto re-run the Playwright fetch script when no token found (requires browser) |
|
|
818
|
+
|
|
819
|
+
On-disk token caches (`.cache/genius-token.json`, `.cache/musixmatch-token.json`) are also
|
|
820
|
+
read automatically when a persistent filesystem is available and the above env vars are not set.
|
|
597
821
|
|
|
598
822
|
---
|
|
599
823
|
|
|
@@ -604,19 +828,35 @@ Mr. Magic supports two connection modes depending on where the MCP client runs:
|
|
|
604
828
|
> written to stdout before Node starts, and stdio MCP clients try to parse every stdout
|
|
605
829
|
> line as JSON-RPC, causing "Unexpected token '>'" errors on every connection.
|
|
606
830
|
|
|
607
|
-
#### npx (
|
|
831
|
+
#### npx (no clone required)
|
|
608
832
|
|
|
609
|
-
Works with any local MCP client that supports `command` / `args
|
|
833
|
+
Works with any local MCP client that supports `command` / `args`. Because this package
|
|
834
|
+
publishes multiple binaries, you must use `--package` to name the package and then
|
|
835
|
+
explicitly name the `mcp-server` binary. This is the correct form — do not use
|
|
836
|
+
`npx -y mr-magic-mcp-server` (no binary by that name exists).
|
|
837
|
+
|
|
838
|
+
> ⚠️ **`npx` does not read your local `.env` file.** The process is spawned by the MCP
|
|
839
|
+
> client and has no access to your project directory or shell environment. All credentials
|
|
840
|
+
> and configuration must be provided in the `env` block below. For a simpler setup,
|
|
841
|
+
> prefer [Local repo — Cline](#local-repo--cline) which reads `.env` automatically.
|
|
610
842
|
|
|
611
843
|
```json
|
|
612
844
|
{
|
|
613
845
|
"mcpServers": {
|
|
614
846
|
"Mr. Magic": {
|
|
615
847
|
"command": "npx",
|
|
616
|
-
"args": ["-y", "mr-magic-mcp-server"],
|
|
848
|
+
"args": ["-y", "--package", "mr-magic-mcp-server", "mcp-server"],
|
|
617
849
|
"env": {
|
|
618
|
-
"
|
|
619
|
-
|
|
850
|
+
"MR_MAGIC_QUIET_STDIO": "1",
|
|
851
|
+
|
|
852
|
+
"GENIUS_CLIENT_ID": "...",
|
|
853
|
+
"GENIUS_CLIENT_SECRET": "...",
|
|
854
|
+
|
|
855
|
+
"MUSIXMATCH_DIRECT_TOKEN": "...",
|
|
856
|
+
|
|
857
|
+
"UPSTASH_REDIS_REST_URL": "https://xxx.upstash.io",
|
|
858
|
+
"UPSTASH_REDIS_REST_TOKEN": "...",
|
|
859
|
+
|
|
620
860
|
"AIRTABLE_PERSONAL_ACCESS_TOKEN": "..."
|
|
621
861
|
}
|
|
622
862
|
}
|
|
@@ -624,15 +864,75 @@ Works with any local MCP client that supports `command` / `args`:
|
|
|
624
864
|
}
|
|
625
865
|
```
|
|
626
866
|
|
|
867
|
+
Variable notes:
|
|
868
|
+
|
|
869
|
+
- `MR_MAGIC_QUIET_STDIO=1` — **always set this for stdio clients**. Suppresses non-error
|
|
870
|
+
stdout so the MCP client doesn't see log lines as JSON-RPC noise.
|
|
871
|
+
- `GENIUS_CLIENT_ID` + `GENIUS_CLIENT_SECRET` — recommended for auto-refresh. Use
|
|
872
|
+
`GENIUS_DIRECT_TOKEN` instead for a static token (no auto-refresh).
|
|
873
|
+
- `MUSIXMATCH_DIRECT_TOKEN` — required if using Musixmatch. Must be the full token
|
|
874
|
+
JSON payload (from `npm run fetch:musixmatch-token`). Omit only if you've already
|
|
875
|
+
pushed the token to a KV store via `push:musixmatch-token` (then supply `UPSTASH_*`
|
|
876
|
+
and the KV lookup handles it at runtime).
|
|
877
|
+
- `UPSTASH_REDIS_REST_URL` + `UPSTASH_REDIS_REST_TOKEN` — optional but recommended:
|
|
878
|
+
enables KV-backed Musixmatch token storage (so you can refresh the token without
|
|
879
|
+
updating the client config) and unlocks the `redis` export backend.
|
|
880
|
+
- `AIRTABLE_PERSONAL_ACCESS_TOKEN` — only required if using `push_catalog_to_airtable`.
|
|
881
|
+
|
|
882
|
+
Minimal config (Genius + Musixmatch, no Airtable, no Redis):
|
|
883
|
+
|
|
884
|
+
```json
|
|
885
|
+
{
|
|
886
|
+
"mcpServers": {
|
|
887
|
+
"Mr. Magic": {
|
|
888
|
+
"command": "npx",
|
|
889
|
+
"args": ["-y", "--package", "mr-magic-mcp-server", "mcp-server"],
|
|
890
|
+
"env": {
|
|
891
|
+
"MR_MAGIC_QUIET_STDIO": "1",
|
|
892
|
+
"GENIUS_CLIENT_ID": "...",
|
|
893
|
+
"GENIUS_CLIENT_SECRET": "...",
|
|
894
|
+
"MUSIXMATCH_DIRECT_TOKEN": "..."
|
|
895
|
+
}
|
|
896
|
+
}
|
|
897
|
+
}
|
|
898
|
+
}
|
|
899
|
+
```
|
|
900
|
+
|
|
627
901
|
#### Global install
|
|
628
902
|
|
|
629
|
-
After `npm install -g mr-magic-mcp-server`, the `mcp-server` binary is on `PATH
|
|
903
|
+
After `npm install -g mr-magic-mcp-server`, the `mcp-server` binary is on `PATH`.
|
|
904
|
+
When launched by an MCP client, the global binary **can** read a `.env` file if
|
|
905
|
+
`MR_MAGIC_ENV_PATH` points to one — otherwise pass credentials via the `env` block
|
|
906
|
+
just like the `npx` config above, or set them as system/user-level environment
|
|
907
|
+
variables so they're available to all spawned processes.
|
|
630
908
|
|
|
631
909
|
```json
|
|
632
910
|
{
|
|
633
911
|
"mcpServers": {
|
|
634
912
|
"Mr. Magic": {
|
|
635
|
-
"command": "mcp-server"
|
|
913
|
+
"command": "mcp-server",
|
|
914
|
+
"env": {
|
|
915
|
+
"MR_MAGIC_QUIET_STDIO": "1",
|
|
916
|
+
"GENIUS_CLIENT_ID": "...",
|
|
917
|
+
"GENIUS_CLIENT_SECRET": "...",
|
|
918
|
+
"MUSIXMATCH_DIRECT_TOKEN": "..."
|
|
919
|
+
}
|
|
920
|
+
}
|
|
921
|
+
}
|
|
922
|
+
}
|
|
923
|
+
```
|
|
924
|
+
|
|
925
|
+
Or, if you keep a `.env` file somewhere on disk:
|
|
926
|
+
|
|
927
|
+
```json
|
|
928
|
+
{
|
|
929
|
+
"mcpServers": {
|
|
930
|
+
"Mr. Magic": {
|
|
931
|
+
"command": "mcp-server",
|
|
932
|
+
"env": {
|
|
933
|
+
"MR_MAGIC_QUIET_STDIO": "1",
|
|
934
|
+
"MR_MAGIC_ENV_PATH": "/Users/you/.config/mr-magic/.env"
|
|
935
|
+
}
|
|
636
936
|
}
|
|
637
937
|
}
|
|
638
938
|
}
|
|
@@ -640,7 +940,9 @@ After `npm install -g mr-magic-mcp-server`, the `mcp-server` binary is on `PATH`
|
|
|
640
940
|
|
|
641
941
|
#### Local repo — Cline
|
|
642
942
|
|
|
643
|
-
Cline supports `cwd`, so you can invoke `node` directly
|
|
943
|
+
Cline supports `cwd`, so you can invoke `node` directly. The server reads `.env`
|
|
944
|
+
from the project root automatically — no `env` block needed for credentials you've
|
|
945
|
+
already set there (though you may still want `MR_MAGIC_QUIET_STDIO`):
|
|
644
946
|
|
|
645
947
|
```json
|
|
646
948
|
{
|
|
@@ -651,7 +953,10 @@ Cline supports `cwd`, so you can invoke `node` directly:
|
|
|
651
953
|
"type": "stdio",
|
|
652
954
|
"command": "node",
|
|
653
955
|
"args": ["src/bin/mcp-server.js"],
|
|
654
|
-
"cwd": "/Users/you/Documents/Code/MCP/mr-magic-mcp-server"
|
|
956
|
+
"cwd": "/Users/you/Documents/Code/MCP/mr-magic-mcp-server",
|
|
957
|
+
"env": {
|
|
958
|
+
"MR_MAGIC_QUIET_STDIO": "1"
|
|
959
|
+
}
|
|
655
960
|
}
|
|
656
961
|
}
|
|
657
962
|
}
|
|
@@ -659,14 +964,18 @@ Cline supports `cwd`, so you can invoke `node` directly:
|
|
|
659
964
|
|
|
660
965
|
#### Local repo — clients without `cwd` support
|
|
661
966
|
|
|
662
|
-
For local clients that don't support a working-directory option, use a shell wrapper
|
|
967
|
+
For local clients that don't support a working-directory option, use a shell wrapper.
|
|
968
|
+
The `cd` sets the project root so `.env` is found automatically:
|
|
663
969
|
|
|
664
970
|
```json
|
|
665
971
|
{
|
|
666
972
|
"mcpServers": {
|
|
667
973
|
"Mr. Magic": {
|
|
668
974
|
"command": "/bin/sh",
|
|
669
|
-
"args": ["-c", "cd /Users/you/Code/mr-magic-mcp-server && node src/bin/mcp-server.js"]
|
|
975
|
+
"args": ["-c", "cd /Users/you/Code/mr-magic-mcp-server && node src/bin/mcp-server.js"],
|
|
976
|
+
"env": {
|
|
977
|
+
"MR_MAGIC_QUIET_STDIO": "1"
|
|
978
|
+
}
|
|
670
979
|
}
|
|
671
980
|
}
|
|
672
981
|
}
|
|
@@ -674,12 +983,33 @@ For local clients that don't support a working-directory option, use a shell wra
|
|
|
674
983
|
|
|
675
984
|
---
|
|
676
985
|
|
|
677
|
-
### Remote clients (Streamable HTTP)
|
|
986
|
+
### Remote clients (Streamable HTTP & SSE)
|
|
678
987
|
|
|
679
988
|
When Mr. Magic is deployed on a remote host (Render, VPS, etc.), connect via the
|
|
680
|
-
Streamable HTTP MCP endpoint (`/mcp`). Credentials are configured server-side via
|
|
989
|
+
Streamable HTTP & SSE MCP endpoint (`/mcp`). Credentials are configured server-side via
|
|
681
990
|
environment variables — no `env` block is needed in the client config.
|
|
682
991
|
|
|
992
|
+
#### Generic remote client (URL-based config)
|
|
993
|
+
|
|
994
|
+
Any client that accepts a plain MCP endpoint URL:
|
|
995
|
+
|
|
996
|
+
```
|
|
997
|
+
https://your-server.com/mcp
|
|
998
|
+
```
|
|
999
|
+
|
|
1000
|
+
|
|
1001
|
+
#### Legacy SSE clients
|
|
1002
|
+
|
|
1003
|
+
Some older MCP clients use the pre-Streamable HTTP & SSE SSE protocol instead of `POST /mcp`.
|
|
1004
|
+
For those, use the legacy SSE endpoint:
|
|
1005
|
+
|
|
1006
|
+
```
|
|
1007
|
+
GET https://your-server.com/sse ← opens the event stream
|
|
1008
|
+
POST https://your-server.com/messages ← sends JSON-RPC messages
|
|
1009
|
+
```
|
|
1010
|
+
|
|
1011
|
+
The server supports both protocols simultaneously — no restart or reconfiguration needed.
|
|
1012
|
+
|
|
683
1013
|
#### TypingMind
|
|
684
1014
|
|
|
685
1015
|
TypingMind connects to remote MCP servers through its **MCP Connector** browser
|
|
@@ -703,26 +1033,6 @@ extension (Chrome / Edge). Once your server is deployed:
|
|
|
703
1033
|
> Extensions settings). If the message persists, update the extension from the Chrome /
|
|
704
1034
|
> Edge Web Store. No changes to Mr. Magic or your server configuration are required.
|
|
705
1035
|
|
|
706
|
-
#### Legacy SSE clients
|
|
707
|
-
|
|
708
|
-
Some older MCP clients use the pre-Streamable HTTP SSE protocol instead of `POST /mcp`.
|
|
709
|
-
For those, use the legacy SSE endpoint:
|
|
710
|
-
|
|
711
|
-
```
|
|
712
|
-
GET https://your-server.com/sse ← opens the event stream
|
|
713
|
-
POST https://your-server.com/messages ← sends JSON-RPC messages
|
|
714
|
-
```
|
|
715
|
-
|
|
716
|
-
The server supports both protocols simultaneously — no restart or reconfiguration needed.
|
|
717
|
-
|
|
718
|
-
#### Generic remote client (URL-based config)
|
|
719
|
-
|
|
720
|
-
Any client that accepts a plain MCP endpoint URL:
|
|
721
|
-
|
|
722
|
-
```
|
|
723
|
-
https://your-server.com/mcp
|
|
724
|
-
```
|
|
725
|
-
|
|
726
1036
|
## CLI
|
|
727
1037
|
|
|
728
1038
|
A single CLI entrypoint (`mrmagic-cli`) is published with the package. Inside the
|
|
@@ -738,7 +1048,7 @@ installed globally.
|
|
|
738
1048
|
| `mrmagic-cli select` | Pick first match from a prioritized provider list. | `--providers`, `--artist`, `--title`, `--require-synced` |
|
|
739
1049
|
| `mrmagic-cli server` | Start the JSON automation API. | `--host`, `--port`, `--remote` |
|
|
740
1050
|
| `mrmagic-cli server:mcp` | Start the MCP stdio server. | — |
|
|
741
|
-
| `mrmagic-cli server:mcp:http` | Start the Streamable HTTP MCP server.
|
|
1051
|
+
| `mrmagic-cli server:mcp:http` | Start the Streamable HTTP & SSE MCP server. | `--host`, `--port`, `--remote`, `--sessionless` |
|
|
742
1052
|
| `mrmagic-cli search-provider` | Query a single provider only. | `--provider`, `--artist`, `--title` |
|
|
743
1053
|
| `mrmagic-cli status` | Print provider readiness. | — |
|
|
744
1054
|
|
|
@@ -774,10 +1084,10 @@ For direct binary usage: `mrmagic-cli search --artist "K/DA" --title "I'll Show
|
|
|
774
1084
|
Automated checks:
|
|
775
1085
|
|
|
776
1086
|
```bash
|
|
777
|
-
npm run test
|
|
778
|
-
node src/tests/mcp-tools.test.js
|
|
779
|
-
npm run repro:mcp:arg-boundary
|
|
780
|
-
npm run repro:mcp:arg-boundary:sdk
|
|
1087
|
+
npm run test # full bundled test runner
|
|
1088
|
+
node src/tests/mcp-tools.test.js # raw MCP integration harness
|
|
1089
|
+
npm run repro:mcp:arg-boundary # JSON-RPC argument boundary repro
|
|
1090
|
+
npm run repro:mcp:arg-boundary:sdk # SDK client transport repro
|
|
781
1091
|
npm run lint
|
|
782
1092
|
npm run format:check
|
|
783
1093
|
```
|
|
@@ -852,7 +1162,7 @@ EXPORT_URL=$(curl -sS -X POST http://127.0.0.1:3333 \
|
|
|
852
1162
|
curl -sS "$EXPORT_URL" | head -n 10
|
|
853
1163
|
```
|
|
854
1164
|
|
|
855
|
-
### MCP Streamable HTTP server (`server:mcp:http`)
|
|
1165
|
+
### MCP Streamable HTTP & SSE server (`server:mcp:http`)
|
|
856
1166
|
|
|
857
1167
|
Start the server:
|
|
858
1168
|
|
|
@@ -1043,27 +1353,13 @@ both a REST API and an MCP endpoint under one deployment.
|
|
|
1043
1353
|
npm run server:http # JSON HTTP automation — port 3333
|
|
1044
1354
|
|
|
1045
1355
|
# Terminal 2
|
|
1046
|
-
npm run server:mcp:http # Streamable HTTP MCP — port 3444
|
|
1356
|
+
npm run server:mcp:http # Streamable HTTP & SSE MCP — port 3444
|
|
1047
1357
|
```
|
|
1048
|
-
|
|
1049
1358
|
> **Note:** Running both is **not** required for Redis exports. The MCP HTTP server
|
|
1050
1359
|
> (`server:mcp:http`) includes its own `/downloads/:id/:ext` route, so a single
|
|
1051
1360
|
> `server:mcp:http` instance is self-sufficient for Redis-backed download links.
|
|
1052
1361
|
> Only run `server:http` alongside it if you also need the JSON HTTP automation API.
|
|
1053
1362
|
|
|
1054
|
-
## Provider Notes
|
|
1055
|
-
|
|
1056
|
-
- **LRCLIB** — Public API with synced lyric coverage. No auth required.
|
|
1057
|
-
- **Genius** — Requires `GENIUS_CLIENT_ID` + `GENIUS_CLIENT_SECRET` (auto-refresh,
|
|
1058
|
-
recommended) or `GENIUS_ACCESS_TOKEN` (static fallback token).
|
|
1059
|
-
- **Musixmatch** — Requires a token. Use `MUSIXMATCH_FALLBACK_TOKEN` for production /
|
|
1060
|
-
ephemeral hosts; use the on-disk cache token (`npm run fetch:musixmatch-token`) for
|
|
1061
|
-
local dev. See [Musixmatch](#musixmatch) for the full workflow.
|
|
1062
|
-
- **Melon** — Works anonymously. Set `MELON_COOKIE` for pinned / reproducible sessions.
|
|
1063
|
-
|
|
1064
|
-
Providers are queried concurrently and results are normalized into a shared schema
|
|
1065
|
-
exposed via the CLI, HTTP API, and MCP tools.
|
|
1066
|
-
|
|
1067
1363
|
## Changelog
|
|
1068
1364
|
|
|
1069
1365
|
See [`CHANGELOG.md`](CHANGELOG.md) for a full history of changes.
|