@upstash/context7-mcp 2.3.0 → 3.1.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/jwt.js

@@ -1,17 +1,71 @@
 import * as jose from "jose";
-import { CLERK_DOMAIN } from "./constants.js";
-const JWKS_URL = `https://${CLERK_DOMAIN}/.well-known/jwks.json`;
-const ISSUER = `https://${CLERK_DOMAIN}`;
-const jwks = jose.createRemoteJWKSet(new URL(JWKS_URL));
+import { CLERK_DOMAIN, CONTEXT7_API_BASE_URL } from "./constants.js";
+const CLERK_ISSUER = `https://${CLERK_DOMAIN}`;
+const clerkJwks = jose.createRemoteJWKSet(new URL(`https://${CLERK_DOMAIN}/.well-known/jwks.json`));
+const ENTRA_V2_ISSUER_RE = /^https:\/\/login\.microsoftonline\.com\/[0-9a-f-]{36}\/v2\.0$/;
+const jwksByTenant = new Map();
+function entraJwks(tenantId) {
+    let jwks = jwksByTenant.get(tenantId);
+    if (!jwks) {
+        jwks = jose.createRemoteJWKSet(new URL(`https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`));
+        jwksByTenant.set(tenantId, jwks);
+    }
+    return jwks;
+}
+const CONFIG_TTL_MS = 5 * 60 * 1000;
+const configByAudience = new Map();
+async function fetchEntraConfig(audience) {
+    const now = Date.now();
+    const cached = configByAudience.get(audience);
+    if (cached && cached.expiresAt > now)
+        return cached.value;
+    try {
+        const res = await fetch(`${CONTEXT7_API_BASE_URL}/v2/entra/config/${encodeURIComponent(audience)}`);
+        if (res.ok) {
+            const value = (await res.json());
+            configByAudience.set(audience, { value, expiresAt: now + CONFIG_TTL_MS });
+            return value;
+        }
+        if (res.status === 404) {
+            // Authoritative "not configured" response — safe to cache the miss so we
+            // don't hammer the app on every token verification.
+            configByAudience.set(audience, { value: null, expiresAt: now + CONFIG_TTL_MS });
+            return null;
+        }
+    }
+    catch {
+        // Network or JSON parse error: transient. Fall through without caching so
+        // the next request retries.
+    }
+    return null;
+}
 export function isJWT(token) {
-    const parts = token.split(".");
-    return parts.length === 3;
+    return token.split(".").length === 3;
 }
 export async function validateJWT(token) {
     try {
-        await jose.jwtVerify(token, jwks, {
-            issuer: ISSUER,
-        });
+        const decoded = jose.decodeJwt(token);
+        const iss = typeof decoded.iss === "string" ? decoded.iss : "";
+        if (ENTRA_V2_ISSUER_RE.test(iss)) {
+            const audience = typeof decoded.aud === "string" ? decoded.aud : "";
+            if (!audience)
+                return { valid: false, error: "Missing audience" };
+            const config = await fetchEntraConfig(audience);
+            if (!config)
+                return { valid: false, error: "Unknown audience" };
+            const { payload } = await jose.jwtVerify(token, entraJwks(config.tenantId), {
+                issuer: `https://login.microsoftonline.com/${config.tenantId}/v2.0`,
+                audience,
+            });
+            if (config.requiredScope) {
+                const scopes = String(payload.scp ?? "").split(" ");
+                if (!scopes.includes(config.requiredScope)) {
+                    return { valid: false, error: "Missing required scope" };
+                }
+            }
+            return { valid: true };
+        }
+        await jose.jwtVerify(token, clerkJwks, { issuer: CLERK_ISSUER });
         return { valid: true };
     }
     catch (error) {

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.1.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",