@upstash/context7-mcp 2.2.4 → 2.3.0

package/dist/index.js

@@ -10,6 +10,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { Command } from "commander";
 import { AsyncLocalStorage } from "async_hooks";
 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
@@ -156,28 +157,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,18 +203,62 @@ 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),
                 },
             ],
         };
     });
     return server;
 }
+const GLOBAL_ALIASES = {
+    query: ["userQuery", "question"],
+};
+// Tool-scoped aliases, for keys that are canonical on one tool but a
+// hallucination on another (e.g. `libraryName` is canonical for
+// `resolve-library-id`, so we only rewrite it on `query-docs` calls).
+const TOOL_ALIASES = {
+    "query-docs": {
+        libraryId: ["context7CompatibleLibraryID", "libraryID", "libraryName"],
+    },
+};
+function applyAliases(args, aliases) {
+    for (const [canonical, alternatives] of Object.entries(aliases)) {
+        if (canonical in args)
+            continue;
+        for (const alt of alternatives) {
+            if (alt in args) {
+                args[canonical] = args[alt];
+                delete args[alt];
+                break;
+            }
+        }
+    }
+}
+// Install BEFORE `server.connect(transport)`: the SDK's `Protocol.connect()`
+// captures the existing `onmessage` and chains its dispatch handler over it,
+// so our hook runs first on every incoming JSON-RPC message.
+function installTransportArgAliasing(transport) {
+    transport.onmessage = (message) => {
+        const msg = message;
+        if (msg.method !== "tools/call")
+            return;
+        const args = msg.params?.arguments;
+        if (!args || typeof args !== "object")
+            return;
+        const argsRecord = args;
+        applyAliases(argsRecord, GLOBAL_ALIASES);
+        const toolName = msg.params?.name;
+        if (toolName && toolName in TOOL_ALIASES) {
+            applyAliases(argsRecord, TOOL_ALIASES[toolName]);
+        }
+    };
+}
 async function main() {
     const transportType = TRANSPORT_TYPE;
     if (transportType === "http") {
@@ -317,6 +360,7 @@ async function main() {
                     server.close();
                 });
                 await requestContext.run(context, async () => {
+                    installTransportArgAliasing(transport);
                     await server.connect(transport);
                     await transport.handleRequest(req, res, req.body);
                 });
@@ -412,6 +456,9 @@ async function main() {
     }
     else {
         stdioApiKey = cliOptions.apiKey || process.env.CONTEXT7_API_KEY;
+        process.stdin.on("end", () => process.exit(0));
+        process.stdin.on("close", () => process.exit(0));
+        process.on("SIGHUP", () => process.exit(0));
         const transport = new StdioServerTransport();
         const server = createMcpServer();
         // Capture client info from MCP initialize handshake (stdio only — HTTP
@@ -425,6 +472,7 @@ async function main() {
                 };
             }
         };
+        installTransportArgAliasing(transport);
         await server.connect(transport);
         console.error(`Context7 Documentation MCP Server v${SERVER_VERSION} running on stdio`);
     }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upstash/context7-mcp",
-  "version": "2.2.4",
+  "version": "2.3.0",
   "mcpName": "io.github.upstash/context7",
   "description": "MCP server for Context7",
   "repository": {