@upstash/context7-mcp 2.3.0 → 3.0.0

package/dist/index.js

@@ -7,8 +7,11 @@ import { formatSearchResults, extractClientInfoFromUserAgent } from "./lib/utils
 import { isJWT, validateJWT } from "./lib/jwt.js";
 import express from "express";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { Command } from "commander";
 import { AsyncLocalStorage } from "async_hooks";
+import { randomUUID } from "node:crypto";
+import { createSessionStore } from "./lib/sessionStore.js";
 import { SERVER_VERSION, RESOURCE_URL, AUTH_SERVER_URL, OPENAI_APPS_CHALLENGE_TOKEN, } from "./lib/constants.js";
 import { appendAuthPrompt } from "./lib/auth/auth-prompt.js";
 /** Default HTTP server port */
@@ -50,6 +53,8 @@ const requestContext = new AsyncLocalStorage();
 // Global state for stdio mode only
 let stdioApiKey;
 let stdioClientInfo;
+// One session ID per stdio process.
+let stdioSessionId;
 /**
  * Get the effective client context
  */
@@ -64,6 +69,7 @@ function getClientContext() {
         apiKey: stdioApiKey,
         clientInfo: stdioClientInfo,
         transport: "stdio",
+        sessionId: stdioSessionId,
     };
 }
 /**
@@ -297,10 +303,11 @@ async function main() {
                 extractHeaderValue(req.headers["context7_api_key"]) ||
                 extractHeaderValue(req.headers["x_api_key"]));
         };
+        const sessionStore = createSessionStore();
         const handleMcpRequest = async (req, res, requireAuth) => {
-            // Reject GET requests — this server is stateless and does not send server-initiated
-            // notifications, so SSE streams serve no purpose and cause mass NGINX timeouts.
-            // Returning 405 is spec-compliant per MCP StreamableHTTP (2025-03-26).
+            // Reject GET requests — sessions are tracked in Redis, but this server does not send
+            // server-initiated notifications, so SSE streams serve no purpose and cause mass NGINX
+            // timeouts. Returning 405 is spec-compliant per MCP StreamableHTTP (2025-03-26).
             if (req.method === "GET") {
                 return res.status(405).json({
                     jsonrpc: "2.0",
@@ -345,6 +352,51 @@ async function main() {
                     clientInfo: extractClientInfoFromUserAgent(req.headers["user-agent"]),
                     transport: "http",
                 };
+                const sessionId = extractHeaderValue(req.headers["mcp-session-id"]);
+                if (req.method === "DELETE") {
+                    if (!sessionId) {
+                        return res.status(400).json({
+                            jsonrpc: "2.0",
+                            error: { code: -32000, message: "Bad Request: No valid session ID provided" },
+                            id: null,
+                        });
+                    }
+                    await sessionStore.delete(sessionId);
+                    return res.status(200).end();
+                }
+                let effectiveSessionId;
+                if (!sessionId && req.method === "POST" && isInitializeRequest(req.body)) {
+                    effectiveSessionId = randomUUID();
+                    await sessionStore.create(effectiveSessionId);
+                    res.setHeader("mcp-session-id", effectiveSessionId);
+                }
+                else if (sessionId && req.method === "POST" && !isInitializeRequest(req.body)) {
+                    const sessionExists = await sessionStore.refresh(sessionId);
+                    if (!sessionExists) {
+                        // Per MCP Streamable HTTP spec: 404 signals to the client that the session
+                        // has been terminated/expired, so it should re-initialize with a fresh InitializeRequest.
+                        return res.status(404).json({
+                            jsonrpc: "2.0",
+                            error: {
+                                code: -32000,
+                                message: "Session not found or expired. Please re-initialize.",
+                            },
+                            id: null,
+                        });
+                    }
+                    effectiveSessionId = sessionId;
+                }
+                else {
+                    return res.status(400).json({
+                        jsonrpc: "2.0",
+                        error: { code: -32000, message: "Bad Request: No valid session ID provided" },
+                        id: null,
+                    });
+                }
+                context.sessionId = effectiveSessionId;
+                // sessionIdGenerator is undefined because session lifecycle (create/refresh/delete)
+                // is owned by the route handler above and persisted in Redis, not by the SDK transport.
+                //
                 // Use SSE responses for tool calls (enableJsonResponse: false). The SDK then
                 // flushes response headers immediately after parsing the request rather than
                 // buffering until the tool returns. This is required for long-running tools
@@ -359,9 +411,9 @@ async function main() {
                     transport.close();
                     server.close();
                 });
+                installTransportArgAliasing(transport);
+                await server.connect(transport);
                 await requestContext.run(context, async () => {
-                    installTransportArgAliasing(transport);
-                    await server.connect(transport);
                     await transport.handleRequest(req, res, req.body);
                 });
             }
@@ -456,6 +508,7 @@ async function main() {
     }
     else {
         stdioApiKey = cliOptions.apiKey || process.env.CONTEXT7_API_KEY;
+        stdioSessionId = randomUUID();
         process.stdin.on("end", () => process.exit(0));
         process.stdin.on("close", () => process.exit(0));
         process.on("SIGHUP", () => process.exit(0));

package/dist/lib/encryption.js

@@ -36,6 +36,9 @@ export function generateHeaders(context) {
     if (context.clientIp) {
         headers["mcp-client-ip"] = encryptClientIp(context.clientIp);
     }
+    if (context.sessionId) {
+        headers["mcp-session-id"] = context.sessionId;
+    }
     if (context.apiKey) {
         headers["Authorization"] = `Bearer ${context.apiKey}`;
     }

package/dist/lib/redis.js

@@ -0,0 +1,14 @@
+import { Redis } from "@upstash/redis";
+let cached;
+/**
+ * Returns the shared Upstash Redis client. Throws if credentials are missing.
+ */
+export function getRedis() {
+    if (cached)
+        return cached;
+    if (!process.env.UPSTASH_REDIS_REST_URL || !process.env.UPSTASH_REDIS_REST_TOKEN) {
+        throw new Error("Upstash Redis credentials are required. Set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.");
+    }
+    cached = Redis.fromEnv();
+    return cached;
+}

package/dist/lib/sessionStore.js

@@ -0,0 +1,47 @@
+import { getRedis } from "./redis.js";
+const SESSION_TTL_SECONDS = 7 * 24 * 60 * 60; // 7 days
+const REFRESH_THRESHOLD_SECONDS = 24 * 60 * 60; // 1 day — only extend TTL when below this
+const SESSION_KEY_PREFIX = "#mcp#session#";
+// Fail-open: log Redis errors and proceed. The session ID isn't an auth/authz
+// primitive — only an opaque identifier for log correlation and spec compliance —
+// so an unreachable Redis shouldn't block clients. Ghost sessions self-heal on
+// the next refresh (returns false → client gets 404 → re-inits).
+export function createSessionStore() {
+    const redis = getRedis();
+    const getSessionKey = (sessionId) => `${SESSION_KEY_PREFIX}${sessionId}`;
+    return {
+        async create(sessionId) {
+            try {
+                await redis.set(getSessionKey(sessionId), "1", { ex: SESSION_TTL_SECONDS });
+            }
+            catch (err) {
+                console.error(`Error creating Redis session record ${sessionId}:`, err);
+            }
+        },
+        async refresh(sessionId) {
+            try {
+                // One TTL call tells us both whether the key exists AND how much time it has left.
+                // Only issue an EXPIRE write when the key is approaching expiry
+                const ttl = await redis.ttl(getSessionKey(sessionId));
+                if (ttl < 0)
+                    return false;
+                if (ttl < REFRESH_THRESHOLD_SECONDS) {
+                    await redis.expire(getSessionKey(sessionId), SESSION_TTL_SECONDS);
+                }
+                return true;
+            }
+            catch (err) {
+                console.error(`Error refreshing Redis session record ${sessionId}:`, err);
+                return true;
+            }
+        },
+        async delete(sessionId) {
+            try {
+                await redis.del(getSessionKey(sessionId));
+            }
+            catch (err) {
+                console.error(`Error deleting Redis session record ${sessionId}:`, err);
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upstash/context7-mcp",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "mcpName": "io.github.upstash/context7",
   "description": "MCP server for Context7",
   "repository": {
@@ -35,6 +35,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@types/express": "^5.0.4",
+    "@upstash/redis": "^1.38.0",
     "commander": "^14.0.0",
     "express": "^5.1.0",
     "jose": "^6.1.3",