mr-magic-mcp-server 0.1.21 → 0.1.23

package/.env.example

@@ -119,6 +119,7 @@ MR_MAGIC_TOOL_ARG_CHUNK_SIZE=400  # Chunk size in chars (only used when LOG_TOOL
 # Streamable HTTP MCP transport diagnostics
 MR_MAGIC_MCP_HTTP_DIAGNOSTICS=0  # Set to 1 to log enriched request diagnostics at transport ingress
 MR_MAGIC_ALLOWED_HOSTS=           # Optional. Comma-separated extra allowed hostnames for DNS rebinding protection when binding to 0.0.0.0 (e.g. custom domains). RENDER_EXTERNAL_HOSTNAME is auto-included on Render.
+MR_MAGIC_SESSIONLESS=0            # Set to 1 to force sessionless mode (each request handled by a fresh server/transport, no in-memory session). Auto-enabled on Render. Set manually on ECS, Fly.io, Railway, etc.
 
 # SDK repro harness verbose HTTP logging
 MR_MAGIC_SDK_REPRO_HTTP_DEBUG=0  # Set to 1 for verbose HTTP previews in the SDK repro harness script

package/README.md

@@ -103,6 +103,7 @@ grouped below by purpose.
 | `MR_MAGIC_ROOT`            | _(project root)_ | Override the project root used for `.env` and `.cache` path resolution.                                                                                                                         |
 | `MR_MAGIC_ENV_PATH`        | _(auto)_         | Point to a specific `.env` file instead of `<project root>/.env`.                                                                                                                               |
 | `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. |
+| `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). |
 
 ### Genius credentials
 
@@ -315,6 +316,25 @@ Recommended Render service settings:
 > your Render environment so the DNS rebinding protection accepts requests with
 > those `Host` headers.
 
+#### Sessionless mode on Render (automatic)
+
+When `RENDER=true` is detected, the MCP Streamable HTTP server automatically operates
+in **sessionless mode**. This is essential for multi-instance deployments where Render
+routes requests across several processes:
+
+- An `initialize` request served by **Instance A** would store the session in A's
+  in-memory `Map`. A follow-up `tools/list` call routed to **Instance B** cannot
+  find that session and returns `{"error": "Session not found. …"}`.
+- In sessionless mode, every request — `initialize`, `tools/list`, `tools/call`, etc.
+  — is handled by a fresh, short-lived `Server + StreamableHTTPServerTransport` pair.
+  No `Mcp-Session-Id` header is issued and no session state is stored. Each request
+  is fully self-contained and works correctly regardless of which instance handles it.
+
+You do **not** need to set `MR_MAGIC_SESSIONLESS=1` manually on Render — it is
+auto-enabled via the platform-injected `RENDER` env var. Set `MR_MAGIC_SESSIONLESS=1`
+explicitly on other multi-instance platforms (ECS, Fly.io, Railway, etc.) where
+a similar load-balanced, stateless deployment is used.
+
 ### Transport selection
 
 | Transport            | Command                   | Use case                            |

package/package.json

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

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

@@ -87,7 +87,15 @@ function createMcpServer() {
 export async function startMcpHttpServer(options = {}) {
   const logger = createLogger('mcp-http-server');
   const httpDiagnostics = process.env.MR_MAGIC_MCP_HTTP_DIAGNOSTICS === '1';
-  const configuredSessionless = Boolean(options.sessionless);
+  // Sessionless mode: skip persistent in-memory session tracking so every
+  // request is handled independently.  This is required on platforms like
+  // Render.com that run multiple instances (a session created on instance A is
+  // invisible to instance B).  Auto-enable when the RENDER env var is present,
+  // or when MR_MAGIC_SESSIONLESS=1 is set explicitly.
+  const configuredSessionless =
+    Boolean(options.sessionless) ||
+    Boolean(process.env.MR_MAGIC_SESSIONLESS) ||
+    Boolean(process.env.RENDER);
   const host = options.remote
     ? '0.0.0.0'
     : options.host || process.env.HOST || (process.env.RENDER ? '0.0.0.0' : '127.0.0.1');