@upstash/context7-mcp 2.0.0 → 2.0.2

package/dist/index.js

@@ -3,11 +3,12 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { searchLibraries, fetchLibraryContext } from "./lib/api.js";
-import { formatSearchResults } from "./lib/utils.js";
+import { formatSearchResults, extractClientInfoFromUserAgent } from "./lib/utils.js";
 import express from "express";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { Command } from "commander";
 import { AsyncLocalStorage } from "async_hooks";
+import { SERVER_VERSION } from "./lib/constants.js";
 /** Default HTTP server port */
 const DEFAULT_PORT = 3000;
 // Parse CLI arguments using commander
@@ -43,8 +44,29 @@ const CLI_PORT = (() => {
     return isNaN(parsed) ? undefined : parsed;
 })();
 const requestContext = new AsyncLocalStorage();
-// Store API key globally for stdio mode (where requestContext may not be available in tool handlers)
-let globalApiKey;
+// Global state for stdio mode only
+let stdioApiKey;
+let stdioClientInfo;
+/**
+ * Get the effective client context
+ */
+function getClientContext() {
+    const ctx = requestContext.getStore();
+    // HTTP mode: context is fully populated from request
+    if (ctx) {
+        return ctx;
+    }
+    // stdio mode: use globals
+    return {
+        apiKey: stdioApiKey,
+        clientInfo: stdioClientInfo,
+        transport: "stdio",
+    };
+}
+/**
+ * Extract client IP address from request headers.
+ * Handles X-Forwarded-For header for proxied requests.
+ */
 function getClientIp(req) {
     const forwardedFor = req.headers["x-forwarded-for"] || req.headers["X-Forwarded-For"];
     if (forwardedFor) {
@@ -67,10 +89,20 @@ function getClientIp(req) {
 }
 const server = new McpServer({
     name: "Context7",
-    version: "2.0.0",
+    version: SERVER_VERSION,
 }, {
     instructions: "Use this server to retrieve up-to-date documentation and code examples for any library.",
 });
+// Capture client info from MCP initialize handshake
+server.server.oninitialized = () => {
+    const clientVersion = server.server.getClientVersion();
+    if (clientVersion) {
+        stdioClientInfo = {
+            ide: clientVersion.name,
+            version: clientVersion.version,
+        };
+    }
+};
 server.registerTool("resolve-library-id", {
     title: "Resolve Context7 Library ID",
     description: `Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
@@ -103,10 +135,11 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f
             .string()
             .describe("Library name to search for and retrieve a Context7-compatible library ID."),
     },
+    annotations: {
+        readOnlyHint: true,
+    },
 }, async ({ query, libraryName }) => {
-    const ctx = requestContext.getStore();
-    const apiKey = ctx?.apiKey || globalApiKey;
-    const searchResponse = await searchLibraries(query, libraryName, ctx?.clientIp, apiKey);
+    const searchResponse = await searchLibraries(query, libraryName, getClientContext());
     if (!searchResponse.results || searchResponse.results.length === 0) {
         return {
             content: [
@@ -160,10 +193,11 @@ IMPORTANT: Do not call this tool more than 3 times per question. If you cannot f
             .string()
             .describe("The question or task you need help with. Be specific and include relevant details. Good: 'How to set up authentication with JWT in Express.js' or 'React useEffect cleanup function examples'. Bad: 'auth' or 'hooks'. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."),
     },
+    annotations: {
+        readOnlyHint: true,
+    },
 }, async ({ query, libraryId }) => {
-    const ctx = requestContext.getStore();
-    const apiKey = ctx?.apiKey || globalApiKey;
-    const response = await fetchLibraryContext({ query, libraryId }, ctx?.clientIp, apiKey);
+    const response = await fetchLibraryContext({ query, libraryId }, getClientContext());
     return {
         content: [
             {
@@ -213,8 +247,12 @@ async function main() {
         };
         app.all("/mcp", async (req, res) => {
             try {
-                const clientIp = getClientIp(req);
-                const apiKey = extractApiKey(req);
+                const context = {
+                    clientIp: getClientIp(req),
+                    apiKey: extractApiKey(req),
+                    clientInfo: extractClientInfoFromUserAgent(req.headers["user-agent"]),
+                    transport: "http",
+                };
                 const transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: undefined,
                     enableJsonResponse: true,
@@ -222,7 +260,7 @@ async function main() {
                 res.on("close", () => {
                     transport.close();
                 });
-                await requestContext.run({ clientIp, apiKey }, async () => {
+                await requestContext.run(context, async () => {
                     await server.connect(transport);
                     await transport.handleRequest(req, res, req.body);
                 });
@@ -261,19 +299,16 @@ async function main() {
                 }
             });
             httpServer.once("listening", () => {
-                console.error(`Context7 Documentation MCP Server running on HTTP at http://localhost:${port}/mcp`);
+                console.error(`Context7 Documentation MCP Server v${SERVER_VERSION} running on HTTP at http://localhost:${port}/mcp`);
             });
         };
         startServer(initialPort);
     }
     else {
-        const apiKey = cliOptions.apiKey || process.env.CONTEXT7_API_KEY;
-        globalApiKey = apiKey; // Store globally for tool handlers in stdio mode
+        stdioApiKey = cliOptions.apiKey || process.env.CONTEXT7_API_KEY;
         const transport = new StdioServerTransport();
-        await requestContext.run({ apiKey }, async () => {
-            await server.connect(transport);
-        });
-        console.error("Context7 Documentation MCP Server running on stdio");
+        await server.connect(transport);
+        console.error(`Context7 Documentation MCP Server v${SERVER_VERSION} running on stdio`);
     }
 }
 main().catch((error) => {

package/dist/lib/api.js

@@ -18,7 +18,6 @@ async function parseErrorResponse(response, apiKey) {
     catch {
         // JSON parsing failed, fall through to default
     }
-    // Fallback for non-JSON responses
     const status = response.status;
     if (status === 429) {
         return apiKey
@@ -33,7 +32,6 @@ async function parseErrorResponse(response, apiKey) {
     }
     return `Request failed with status ${status}. Please try again later.`;
 }
-// Pick up proxy configuration in a variety of common env var names.
 const PROXY_URL = process.env.HTTPS_PROXY ??
     process.env.https_proxy ??
     process.env.HTTP_PROXY ??
@@ -41,14 +39,9 @@ const PROXY_URL = process.env.HTTPS_PROXY ??
     null;
 if (PROXY_URL && !PROXY_URL.startsWith("$") && /^(http|https):\/\//i.test(PROXY_URL)) {
     try {
-        // Configure a global proxy agent once at startup. Subsequent fetch calls will
-        // automatically use this dispatcher.
-        // Using `any` cast because ProxyAgent implements the Dispatcher interface but
-        // TS may not infer it correctly in some versions.
         setGlobalDispatcher(new ProxyAgent(PROXY_URL));
     }
     catch (error) {
-        // Don't crash the app if proxy initialisation fails – just log a warning.
         console.error(`[Context7] Failed to configure proxy agent for provided proxy URL: ${PROXY_URL}:`, error);
     }
 }
@@ -56,24 +49,20 @@ if (PROXY_URL && !PROXY_URL.startsWith("$") && /^(http|https):\/\//i.test(PROXY_
  * Searches for libraries matching the given query
  * @param query The user's question or task (used for LLM relevance ranking)
  * @param libraryName The library name to search for in the database
- * @param clientIp Optional client IP address to include in headers
- * @param apiKey Optional API key for authentication
- * @returns Search results or null if the request fails
+ * @param context Client context including IP, API key, and client info
+ * @returns Search results or error
  */
-export async function searchLibraries(query, libraryName, clientIp, apiKey) {
+export async function searchLibraries(query, libraryName, context = {}) {
     try {
         const url = new URL(`${CONTEXT7_API_BASE_URL}/v2/libs/search`);
         url.searchParams.set("query", query);
         url.searchParams.set("libraryName", libraryName);
-        const headers = generateHeaders(clientIp, apiKey);
+        const headers = generateHeaders(context);
         const response = await fetch(url, { headers });
         if (!response.ok) {
-            const errorMessage = await parseErrorResponse(response, apiKey);
+            const errorMessage = await parseErrorResponse(response, context.apiKey);
             console.error(errorMessage);
-            return {
-                results: [],
-                error: errorMessage,
-            };
+            return { results: [], error: errorMessage };
         }
         const searchData = await response.json();
         return searchData;
@@ -86,20 +75,19 @@ export async function searchLibraries(query, libraryName, clientIp, apiKey) {
 }
 /**
  * Fetches intelligent, reranked context for a natural language query
- * @param request The context request parameters (query, topic, library, mode)
- * @param clientIp Optional client IP address to include in headers
- * @param apiKey Optional API key for authentication
+ * @param request The context request parameters (query, libraryId)
+ * @param context Client context including IP, API key, and client info
  * @returns Context response with data
  */
-export async function fetchLibraryContext(request, clientIp, apiKey) {
+export async function fetchLibraryContext(request, context = {}) {
     try {
         const url = new URL(`${CONTEXT7_API_BASE_URL}/v2/context`);
         url.searchParams.set("query", request.query);
         url.searchParams.set("libraryId", request.libraryId);
-        const headers = generateHeaders(clientIp, apiKey, { "X-Context7-Source": "mcp-server" });
+        const headers = generateHeaders(context);
         const response = await fetch(url, { headers });
         if (!response.ok) {
-            const errorMessage = await parseErrorResponse(response, apiKey);
+            const errorMessage = await parseErrorResponse(response, context.apiKey);
             console.error(errorMessage);
             return { data: errorMessage };
         }

package/dist/lib/constants.js

@@ -0,0 +1,2 @@
+import pkg from "../../package.json" with { type: "json" };
+export const SERVER_VERSION = pkg.version;

package/dist/lib/encryption.js

@@ -1,4 +1,5 @@
 import { createCipheriv, randomBytes } from "crypto";
+import { SERVER_VERSION } from "./constants.js";
 const DEFAULT_ENCRYPTION_KEY = "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f";
 const ENCRYPTION_KEY = process.env.CLIENT_IP_ENCRYPTION_KEY || DEFAULT_ENCRYPTION_KEY;
 const ALGORITHM = "aes-256-cbc";
@@ -26,13 +27,29 @@ function encryptClientIp(clientIp) {
         return clientIp; // Fallback to unencrypted
     }
 }
-export function generateHeaders(clientIp, apiKey, extraHeaders = {}) {
-    const headers = { ...extraHeaders };
-    if (clientIp) {
-        headers["mcp-client-ip"] = encryptClientIp(clientIp);
+/**
+ * Generate headers for Context7 API requests.
+ * Handles client IP encryption, authentication, and telemetry headers.
+ */
+export function generateHeaders(context) {
+    const headers = {
+        "X-Context7-Source": "mcp-server",
+        "X-Context7-Server-Version": SERVER_VERSION,
+    };
+    if (context.clientIp) {
+        headers["mcp-client-ip"] = encryptClientIp(context.clientIp);
     }
-    if (apiKey) {
-        headers["Authorization"] = `Bearer ${apiKey}`;
+    if (context.apiKey) {
+        headers["Authorization"] = `Bearer ${context.apiKey}`;
+    }
+    if (context.clientInfo?.ide) {
+        headers["X-Context7-Client-IDE"] = context.clientInfo.ide;
+    }
+    if (context.clientInfo?.version) {
+        headers["X-Context7-Client-Version"] = context.clientInfo.version;
+    }
+    if (context.transport) {
+        headers["X-Context7-Transport"] = context.transport;
     }
     return headers;
 }

package/dist/lib/utils.js

@@ -58,3 +58,16 @@ export function formatSearchResults(searchResponse) {
     const formattedResults = searchResponse.results.map(formatSearchResult);
     return formattedResults.join("\n----------\n");
 }
+/**
+ * Extract client info from User-Agent header.
+ * Parses formats like "Cursor/2.2.44 (darwin arm64)" or "claude-code/2.0.71"
+ */
+export function extractClientInfoFromUserAgent(userAgent) {
+    if (!userAgent)
+        return undefined;
+    const match = userAgent.match(/^([^\/\s]+)\/([^\s(]+)/);
+    if (match) {
+        return { ide: match[1], version: match[2] };
+    }
+    return undefined;
+}

package/package.json

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