mr-magic-mcp-server 0.1.13 → 0.1.15

package/README.md

@@ -12,6 +12,7 @@ automations, and CLI aficionados can all request lyrics from a single toolchain.
 - [Export and Download Configuration](#export-and-download-configuration)
 - [Local Deployment](#local-deployment)
 - [Remote Deployment](#remote-deployment)
+- [HTTP Endpoints](#http-endpoints)
 - [MCP Tools](#mcp-tools)
 - [Airtable Integration](#airtable-integration)
 - [MCP Client Configuration](#mcp-client-configuration)
@@ -233,18 +234,30 @@ The `MR_MAGIC_EXPORT_BACKEND` variable controls where formatted lyrics are store
   `UPSTASH_REDIS_REST_TOKEN`, and `MR_MAGIC_DOWNLOAD_BASE_URL`.
 
 For Redis exports, `MR_MAGIC_DOWNLOAD_BASE_URL` must be the publicly reachable base URL
-of your HTTP automation server (not the Upstash URL), e.g. `https://lyrics.example.com`.
-Download links are built as `{base_url}/downloads/{id}/{ext}`.
+of the server that will serve the download links (not the Upstash URL),
+e.g. `https://lyrics.example.com`. Download links are built as
+`{base_url}/downloads/{id}/{ext}`.
 
-For local testing:
+Both HTTP servers serve `/downloads/:id/:ext` routes:
+
+- **`server:mcp:http`** (port `3444`) — the Streamable HTTP MCP server includes its
+  own `/downloads` route. If you are already running this server, no additional HTTP
+  server is needed for Redis exports on Render or any remote deployment.
+- **`server:http`** (port `3333`) — the JSON HTTP automation server also exposes the
+  same route and remains the right choice if you are running `server:mcp` (stdio) only
+  or want a standalone HTTP service for download links.
+
+For local testing against the MCP HTTP server:
 
 ```bash
-MR_MAGIC_DOWNLOAD_BASE_URL=http://127.0.0.1:3333
+MR_MAGIC_DOWNLOAD_BASE_URL=http://127.0.0.1:3444
 ```
 
-> Even when using only the stdio MCP server, you still need the HTTP automation
-> server running to serve `/downloads/:id/:ext` routes when the `redis` backend
-> is enabled.
+Or against the JSON HTTP server:
+
+```bash
+MR_MAGIC_DOWNLOAD_BASE_URL=http://127.0.0.1:3333
+```
 
 ## Local Deployment
 
@@ -308,6 +321,93 @@ Recommended Render service settings:
 | JSON HTTP automation | `npm run server:http` | Container / remote automations |
 | CLI | `npm run cli` | Ad-hoc / SSH / CI one-shot commands |
 
+## HTTP Endpoints
+
+Both HTTP servers expose a set of plain HTTP routes in addition to their primary
+transports. These are accessible without any MCP or JSON-RPC framing.
+
+| Endpoint | Method | Server | Description |
+|---|---|---|---|
+| `/health` | `GET` | Both | Liveness / readiness probe. Returns `{ "status": "ok", "providers": [...] }`. |
+| `/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. |
+| `/mcp` | `POST` | `server:mcp:http` only | MCP Streamable HTTP transport endpoint (JSON-RPC 2.0). |
+| `/` | `POST` | `server:http` only | JSON HTTP automation endpoint (action-based API). |
+
+### `/health`
+
+Both servers respond to `GET /health` with a JSON object indicating overall status
+and per-provider readiness. Use this as your Render (or container / load-balancer)
+health check path.
+
+**Response shape:**
+
+```json
+{
+  "status": "ok",
+  "providers": [
+    { "name": "lrclib",     "status": "ok" },
+    { "name": "genius",     "status": "ok" },
+    { "name": "musixmatch", "status": "missing_token" },
+    { "name": "melon",      "status": "ok" }
+  ]
+}
+```
+
+**MCP HTTP server** (default port `3444`):
+
+```bash
+curl -sS http://127.0.0.1:3444/health | jq
+```
+
+**JSON HTTP server** (default port `3333`):
+
+```bash
+curl -sS http://127.0.0.1:3333/health | jq
+```
+
+Provider `status` values:
+
+| Value | Meaning |
+|---|---|
+| `ok` | Provider is configured and reachable. |
+| `missing_token` | Required credential env var is not set. |
+| `error` | Provider returned an unexpected error during the status probe. |
+
+### `/downloads/:id/:ext`
+
+Serves a Redis-backed export file by its download ID and format extension. Both
+servers expose this route so the same `MR_MAGIC_DOWNLOAD_BASE_URL` works regardless
+of which server you are running.
+
+**Parameters:**
+
+- `:id` — the opaque download ID returned in the `url` field of an export response
+- `:ext` — the file format: `plain`, `lrc`, `srt`, or `romanized`
+
+**Example** (MCP HTTP server):
+
+```bash
+curl -sS http://127.0.0.1:3444/downloads/coldplay-yellow-1741234567890/plain
+```
+
+**Example** (JSON HTTP server):
+
+```bash
+curl -sS http://127.0.0.1:3333/downloads/coldplay-yellow-1741234567890/plain
+```
+
+Responses:
+
+- `200 text/plain` — export content served directly
+- `404` — key expired or never written (`MR_MAGIC_EXPORT_TTL_SECONDS` controls TTL,
+  default `3600` seconds)
+- `400` — malformed path (missing ID or extension)
+- `500` — Redis lookup error
+
+> Requires `MR_MAGIC_EXPORT_BACKEND=redis` and valid `UPSTASH_*` credentials.
+> For local and inline backends, exports are returned directly in the tool response
+> and this route is not used.
+
 ## MCP Tools
 
 Both the stdio and Streamable HTTP transports expose the same tool registry:
@@ -844,16 +944,23 @@ curl -sS -X POST http://127.0.0.1:3444/mcp \
 
 ### Running both servers side-by-side
 
-For Redis-backed download scenarios, run both servers in separate terminals:
+You may want both servers running at the same time — for example, to serve JSON HTTP
+automations (`server:http`) alongside MCP tool calls (`server:mcp:http`), or to expose
+both a REST API and an MCP endpoint under one deployment.
 
 ```bash
 # Terminal 1
-npm run server:http
+npm run server:http       # JSON HTTP automation — port 3333
 
 # Terminal 2
-npm run server:mcp:http
+npm run server:mcp:http   # Streamable HTTP MCP  — port 3444
 ```
 
+> **Note:** Running both is **not** required for Redis exports. The MCP HTTP server
+> (`server:mcp:http`) includes its own `/downloads/:id/:ext` route, so a single
+> `server:mcp:http` instance is self-sufficient for Redis-backed download links.
+> Only run `server:http` alongside it if you also need the JSON HTTP automation API.
+
 ## Provider Notes
 
 - **LRCLIB** — Public API with synced lyric coverage. No auth required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mr-magic-mcp-server",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Lyrics MCP server connecting LRCLIB, Genius, Musixmatch, and Melon",
   "type": "module",
   "main": "src/index.js",

package/src/transport/mcp-http-server.js

@@ -8,6 +8,7 @@ import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 
 import { createLogger } from '../utils/logger.js';
+import { getSharedRedisClient } from '../utils/export-storage/shared-redis-client.js';
 
 import { mcpToolDefinitions, handleMcpTool } from './mcp-tools.js';
 import { buildMcpResponse } from './mcp-response.js';
@@ -111,10 +112,35 @@ export async function startMcpHttpServer(options = {}) {
       : undefined;
 
   const app = createMcpExpressApp({ host, ...(allowedHosts ? { allowedHosts } : {}) });
+
   app.get('/health', async (_req, res) => {
     res.json({ status: 'ok', providers: await getProviderStatus() });
   });
 
+  app.get('/downloads/:downloadId/*', async (req, res) => {
+    const { downloadId } = req.params;
+    const extension = req.params[0] || '';
+    if (!downloadId || !extension) {
+      res.status(400).json({ error: 'Invalid download path' });
+      return;
+    }
+    try {
+      const redis = getSharedRedisClient({ context: 'mcp-http-download' });
+      const key = `mr-magic:${downloadId}:${extension}`;
+      const content = await redis.get(key);
+      if (!content) {
+        logger.warn('Export download missing', { context: 'mcp-http-download', key, downloadId, extension });
+        res.status(404).json({ error: 'Export expired or missing' });
+        return;
+      }
+      res.status(200).type('text/plain').send(content);
+      logger.info('Export download served', { context: 'mcp-http-download', key, downloadId, extension, bytes: Buffer.byteLength(content) });
+    } catch (error) {
+      logger.error('Download lookup failed', { error, url: req.originalUrl });
+      res.status(500).json({ error: 'Failed to fetch export' });
+    }
+  });
+
   app.all('/mcp', async (req, res) => {
     const normalizedBody = normalizeIncomingRpcBody(req.body);
     const requestId = randomUUID();