@upstash/context7-mcp 2.2.5 → 3.0.0

package/dist/index.js

@@ -7,9 +7,13 @@ 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 */
 const DEFAULT_PORT = 3000;
 // Parse CLI arguments using commander
@@ -49,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
  */
@@ -63,6 +69,7 @@ function getClientContext() {
         apiKey: stdioApiKey,
         clientInfo: stdioClientInfo,
         transport: "stdio",
+        sessionId: stdioSessionId,
     };
 }
 /**
@@ -156,28 +163,26 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f
             idempotentHint: true,
         },
     }, async ({ query, libraryName }) => {
-        const searchResponse = await searchLibraries(query, libraryName, getClientContext());
+        const ctx = getClientContext();
+        const searchResponse = await searchLibraries(query, libraryName, ctx);
         if (!searchResponse.results || searchResponse.results.length === 0) {
+            const text = searchResponse.error ?? "No libraries found matching the provided name.";
             return {
                 content: [
                     {
                         type: "text",
-                        text: searchResponse.error
-                            ? searchResponse.error
-                            : "No libraries found matching the provided name.",
+                        text: appendAuthPrompt(text, ctx),
                     },
                 ],
             };
         }
         const resultsText = formatSearchResults(searchResponse);
-        const responseText = `Available Libraries:
-
-${resultsText}`;
+        const responseText = `Available Libraries:\n\n${resultsText}`;
         return {
             content: [
                 {
                     type: "text",
-                    text: responseText,
+                    text: appendAuthPrompt(responseText, ctx),
                 },
             ],
         };
@@ -204,12 +209,13 @@ Do not call this tool more than 3 times per question.`,
             idempotentHint: true,
         },
     }, async ({ query, libraryId }) => {
-        const response = await fetchLibraryContext({ query, libraryId }, getClientContext());
+        const ctx = getClientContext();
+        const response = await fetchLibraryContext({ query, libraryId }, ctx);
         return {
             content: [
                 {
                     type: "text",
-                    text: response.data,
+                    text: appendAuthPrompt(response.data, ctx),
                 },
             ],
         };
@@ -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/api.js

@@ -81,6 +81,11 @@ else if (CUSTOM_CA_CERTS) {
         }
     }
 }
+function readPromptSignal(response, context) {
+    if (response.headers.get("X-Context7-Auth-Prompt") === "1") {
+        context.shouldPrompt = true;
+    }
+}
 /**
  * Searches for libraries matching the given query
  * @param query The user's question or task (used for LLM relevance ranking)
@@ -95,6 +100,7 @@ export async function searchLibraries(query, libraryName, context = {}) {
         url.searchParams.set("libraryName", libraryName);
         const headers = generateHeaders(context);
         const response = await fetch(url, { headers });
+        readPromptSignal(response, context);
         if (!response.ok) {
             const errorMessage = await parseErrorResponse(response, context.apiKey);
             console.error(errorMessage);
@@ -122,6 +128,7 @@ export async function fetchLibraryContext(request, context = {}) {
         url.searchParams.set("libraryId", request.libraryId);
         const headers = generateHeaders(context);
         const response = await fetch(url, { headers });
+        readPromptSignal(response, context);
         if (!response.ok) {
             const errorMessage = await parseErrorResponse(response, context.apiKey);
             console.error(errorMessage);

package/dist/lib/auth/auth-prompt.js

@@ -0,0 +1,51 @@
+function clientFlagForCli(ide) {
+    if (!ide)
+        return "";
+    const lower = ide.toLowerCase();
+    if (lower.includes("cursor"))
+        return "--cursor";
+    if (lower.includes("claude"))
+        return "--claude";
+    if (lower.includes("codex"))
+        return "--codex";
+    if (lower.includes("opencode"))
+        return "--opencode";
+    if (lower.includes("gemini"))
+        return "--gemini";
+    return "";
+}
+/**
+ * Appends a sign-in nudge to `text` when the backend has signaled (via
+ * `X-Context7-Auth-Prompt: 1`, captured on `ctx.shouldPrompt` in api.ts)
+ * that the anonymous caller should be prompted to authenticate. No-op for
+ * authenticated callers or when the signal wasn't set.
+ */
+export function appendAuthPrompt(text, ctx) {
+    if (ctx.apiKey || !ctx.shouldPrompt)
+        return text;
+    return `${text}\n\n${buildAuthPrompt({
+        clientIde: ctx.clientInfo?.ide,
+        transport: ctx.transport,
+    })}`;
+}
+export function buildAuthPrompt(opts) {
+    const flag = clientFlagForCli(opts.clientIde);
+    const transportFlag = opts.transport === "stdio" ? " --stdio" : "";
+    const command = flag
+        ? `npx ctx7 setup ${flag} --mcp${transportFlag} -y`
+        : `npx ctx7 setup --mcp${transportFlag}`;
+    return [
+        "---",
+        `**[Heads up] Notice for the user — please relay the following section to them and offer to run the command for them after their confirmation:**`,
+        "",
+        "> You're using Context7 anonymously. To sign in for **free** higher rate limits, run this in your terminal:",
+        ">",
+        "> ```",
+        `> ${command}`,
+        "> ```",
+        ">",
+        "> It opens the browser, completes sign-in, and writes credentials into your MCP client config. After it finishes, disable + re-enable the Context7 MCP server in your editor so the new credentials take effect.",
+        "",
+        `(Background for the assistant: this user is using Context7 anonymously. Surface the notice above to the user; with their permission, you may run \`${command}\` for them via your shell tool.)`,
+    ].join("\n");
+}

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.2.5",
+  "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",