@upstash/context7-mcp 1.0.14 → 1.0.16

package/dist/index.js

@@ -11,36 +11,75 @@ import { Command } from "commander";
 const DEFAULT_MINIMUM_TOKENS = 10000;
 // Parse CLI arguments using commander
 const program = new Command()
-    .option("--transport <stdio|http|sse>", "transport type", "stdio")
-    .option("--port <number>", "port for HTTP/SSE transport", "3000")
+    .option("--transport <stdio|http>", "transport type", "stdio")
+    .option("--port <number>", "port for HTTP transport", "3000")
+    .option("--api-key <key>", "API key for authentication")
     .allowUnknownOption() // let MCP Inspector / other wrappers pass through extra flags
     .parse(process.argv);
 const cliOptions = program.opts();
 // Validate transport option
-const allowedTransports = ["stdio", "http", "sse"];
+const allowedTransports = ["stdio", "http"];
 if (!allowedTransports.includes(cliOptions.transport)) {
-    console.error(`Invalid --transport value: '${cliOptions.transport}'. Must be one of: stdio, http, sse.`);
+    console.error(`Invalid --transport value: '${cliOptions.transport}'. Must be one of: stdio, http.`);
     process.exit(1);
 }
 // Transport configuration
 const TRANSPORT_TYPE = (cliOptions.transport || "stdio");
-// HTTP/SSE port configuration
+// Disallow incompatible flags based on transport
+const passedPortFlag = process.argv.includes("--port");
+const passedApiKeyFlag = process.argv.includes("--api-key");
+if (TRANSPORT_TYPE === "http" && passedApiKeyFlag) {
+    console.error("The --api-key flag is not allowed when using --transport http. Use header-based auth at the HTTP layer instead.");
+    process.exit(1);
+}
+if (TRANSPORT_TYPE === "stdio" && passedPortFlag) {
+    console.error("The --port flag is not allowed when using --transport stdio.");
+    process.exit(1);
+}
+// HTTP port configuration
 const CLI_PORT = (() => {
     const parsed = parseInt(cliOptions.port, 10);
     return isNaN(parsed) ? undefined : parsed;
 })();
 // Store SSE transports by session ID
 const sseTransports = {};
+function getClientIp(req) {
+    // Check both possible header casings
+    const forwardedFor = req.headers["x-forwarded-for"] || req.headers["X-Forwarded-For"];
+    if (forwardedFor) {
+        // X-Forwarded-For can contain multiple IPs
+        const ips = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor;
+        const ipList = ips.split(",").map((ip) => ip.trim());
+        // Find the first public IP address
+        for (const ip of ipList) {
+            const plainIp = ip.replace(/^::ffff:/, "");
+            if (!plainIp.startsWith("10.") &&
+                !plainIp.startsWith("192.168.") &&
+                !/^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(plainIp)) {
+                return plainIp;
+            }
+        }
+        // If all are private, use the first one
+        return ipList[0].replace(/^::ffff:/, "");
+    }
+    // Fallback: use remote address, strip IPv6-mapped IPv4
+    if (req.socket?.remoteAddress) {
+        return req.socket.remoteAddress.replace(/^::ffff:/, "");
+    }
+    return undefined;
+}
 // Function to create a new server instance with all tools registered
-function createServerInstance() {
+function createServerInstance(clientIp, apiKey) {
     const server = new McpServer({
         name: "Context7",
-        version: "v1.0.14",
+        version: "1.0.16",
     }, {
         instructions: "Use this server to retrieve up-to-date documentation and code examples for any library.",
     });
     // Register Context7 tools
-    server.tool("resolve-library-id", `Resolves a package/product name to a Context7-compatible library ID and returns a list of matching libraries.
+    server.registerTool("resolve-library-id", {
+        title: "Resolve Context7 Library ID",
+        description: `Resolves a package/product name to a Context7-compatible library ID and returns a list of matching libraries.
 
 You MUST call this function before 'get-library-docs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
 
@@ -58,12 +97,14 @@ Response Format:
 - If multiple good matches exist, acknowledge this but proceed with the most relevant one
 - If no good matches exist, clearly state this and suggest query refinements
 
-For ambiguous queries, request clarification before proceeding with a best-guess match.`, {
-        libraryName: z
-            .string()
-            .describe("Library name to search for and retrieve a Context7-compatible library ID."),
+For ambiguous queries, request clarification before proceeding with a best-guess match.`,
+        inputSchema: {
+            libraryName: z
+                .string()
+                .describe("Library name to search for and retrieve a Context7-compatible library ID."),
+        },
     }, async ({ libraryName }) => {
-        const searchResponse = await searchLibraries(libraryName);
+        const searchResponse = await searchLibraries(libraryName, clientIp, apiKey);
         if (!searchResponse.results || searchResponse.results.length === 0) {
             return {
                 content: [
@@ -100,24 +141,28 @@ ${resultsText}`,
             ],
         };
     });
-    server.tool("get-library-docs", "Fetches up-to-date documentation for a library. You must call 'resolve-library-id' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.", {
-        context7CompatibleLibraryID: z
-            .string()
-            .describe("Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolve-library-id' or directly from user query in the format '/org/project' or '/org/project/version'."),
-        topic: z
-            .string()
-            .optional()
-            .describe("Topic to focus documentation on (e.g., 'hooks', 'routing')."),
-        tokens: z
-            .preprocess((val) => (typeof val === "string" ? Number(val) : val), z.number())
-            .transform((val) => (val < DEFAULT_MINIMUM_TOKENS ? DEFAULT_MINIMUM_TOKENS : val))
-            .optional()
-            .describe(`Maximum number of tokens of documentation to retrieve (default: ${DEFAULT_MINIMUM_TOKENS}). Higher values provide more context but consume more tokens.`),
+    server.registerTool("get-library-docs", {
+        title: "Get Library Docs",
+        description: "Fetches up-to-date documentation for a library. You must call 'resolve-library-id' first to obtain the exact Context7-compatible library ID required to use this tool, UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.",
+        inputSchema: {
+            context7CompatibleLibraryID: z
+                .string()
+                .describe("Exact Context7-compatible library ID (e.g., '/mongodb/docs', '/vercel/next.js', '/supabase/supabase', '/vercel/next.js/v14.3.0-canary.87') retrieved from 'resolve-library-id' or directly from user query in the format '/org/project' or '/org/project/version'."),
+            topic: z
+                .string()
+                .optional()
+                .describe("Topic to focus documentation on (e.g., 'hooks', 'routing')."),
+            tokens: z
+                .preprocess((val) => (typeof val === "string" ? Number(val) : val), z.number())
+                .transform((val) => (val < DEFAULT_MINIMUM_TOKENS ? DEFAULT_MINIMUM_TOKENS : val))
+                .optional()
+                .describe(`Maximum number of tokens of documentation to retrieve (default: ${DEFAULT_MINIMUM_TOKENS}). Higher values provide more context but consume more tokens.`),
+        },
     }, async ({ context7CompatibleLibraryID, tokens = DEFAULT_MINIMUM_TOKENS, topic = "" }) => {
         const fetchDocsResponse = await fetchLibraryDocumentation(context7CompatibleLibraryID, {
             tokens,
             topic,
-        });
+        }, clientIp, apiKey);
         if (!fetchDocsResponse) {
             return {
                 content: [
@@ -141,7 +186,7 @@ ${resultsText}`,
 }
 async function main() {
     const transportType = TRANSPORT_TYPE;
-    if (transportType === "http" || transportType === "sse") {
+    if (transportType === "http") {
         // Get initial port from environment or use default
         const initialPort = CLI_PORT ?? 3000;
         // Keep track of which port we end up using
@@ -151,16 +196,47 @@ async function main() {
             // Set CORS headers for all responses
             res.setHeader("Access-Control-Allow-Origin", "*");
             res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS,DELETE");
-            res.setHeader("Access-Control-Allow-Headers", "Content-Type, MCP-Session-Id, mcp-session-id");
+            res.setHeader("Access-Control-Allow-Headers", "Content-Type, MCP-Session-Id, MCP-Protocol-Version, X-Context7-API-Key, Context7-API-Key, X-API-Key, Authorization");
+            res.setHeader("Access-Control-Expose-Headers", "MCP-Session-Id");
             // Handle preflight OPTIONS requests
             if (req.method === "OPTIONS") {
                 res.writeHead(200);
                 res.end();
                 return;
             }
+            // Function to extract header value safely, handling both string and string[] cases
+            const extractHeaderValue = (value) => {
+                if (!value)
+                    return undefined;
+                return typeof value === "string" ? value : value[0];
+            };
+            // Extract Authorization header and remove Bearer prefix if present
+            const extractBearerToken = (authHeader) => {
+                const header = extractHeaderValue(authHeader);
+                if (!header)
+                    return undefined;
+                // If it starts with 'Bearer ', remove that prefix
+                if (header.startsWith("Bearer ")) {
+                    return header.substring(7).trim();
+                }
+                // Otherwise return the raw value
+                return header;
+            };
+            // Check headers in order of preference
+            const apiKey = extractBearerToken(req.headers.authorization) ||
+                extractHeaderValue(req.headers["Context7-API-Key"]) ||
+                extractHeaderValue(req.headers["X-API-Key"]) ||
+                extractHeaderValue(req.headers["context7-api-key"]) ||
+                extractHeaderValue(req.headers["x-api-key"]) ||
+                extractHeaderValue(req.headers["Context7_API_Key"]) ||
+                extractHeaderValue(req.headers["X_API_Key"]) ||
+                extractHeaderValue(req.headers["context7_api_key"]) ||
+                extractHeaderValue(req.headers["x_api_key"]);
             try {
+                // Extract client IP address using socket remote address (most reliable)
+                const clientIp = getClientIp(req);
                 // Create new server instance for each request
-                const requestServer = createServerInstance();
+                const requestServer = createServerInstance(clientIp, apiKey);
                 if (url === "/mcp") {
                     const transport = new StreamableHTTPServerTransport({
                         sessionIdGenerator: undefined,
@@ -229,7 +305,7 @@ async function main() {
             });
             httpServer.listen(port, () => {
                 actualPort = port;
-                console.error(`Context7 Documentation MCP Server running on ${transportType.toUpperCase()} at http://localhost:${actualPort}/mcp and legacy SSE at /sse`);
+                console.error(`Context7 Documentation MCP Server running on ${transportType.toUpperCase()} at http://localhost:${actualPort}/mcp with SSE endpoint at /sse`);
             });
         };
         // Start the server with initial port
@@ -237,7 +313,7 @@ async function main() {
     }
     else {
         // Stdio transport - this is already stateless by nature
-        const server = createServerInstance();
+        const server = createServerInstance(undefined, cliOptions.apiKey);
         const transport = new StdioServerTransport();
         await server.connect(transport);
         console.error("Context7 Documentation MCP Server running on stdio");

package/dist/lib/api.js

@@ -1,22 +1,53 @@
+import { generateHeaders } from "./encryption.js";
+import { ProxyAgent, setGlobalDispatcher } from "undici";
 const CONTEXT7_API_BASE_URL = "https://context7.com/api";
 const DEFAULT_TYPE = "txt";
+// 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 ??
+    process.env.http_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);
+    }
+}
 /**
  * Searches for libraries matching the given query
  * @param query The search query
+ * @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
  */
-export async function searchLibraries(query) {
+export async function searchLibraries(query, clientIp, apiKey) {
     try {
         const url = new URL(`${CONTEXT7_API_BASE_URL}/v1/search`);
         url.searchParams.set("query", query);
-        const response = await fetch(url);
+        const headers = generateHeaders(clientIp, apiKey);
+        const response = await fetch(url, { headers });
         if (!response.ok) {
             const errorCode = response.status;
             if (errorCode === 429) {
-                console.error(`Rate limited due to too many requests. Please try again later.`);
+                console.error("Rate limited due to too many requests. Please try again later.");
                 return {
                     results: [],
-                    error: `Rate limited due to too many requests. Please try again later.`,
+                    error: "Rate limited due to too many requests. Please try again later.",
+                };
+            }
+            if (errorCode === 401) {
+                console.error("Unauthorized. Please check your API key.");
+                return {
+                    results: [],
+                    error: "Unauthorized. Please check your API key.",
                 };
             }
             console.error(`Failed to search libraries. Please try again later. Error code: ${errorCode}`);
@@ -36,9 +67,11 @@ export async function searchLibraries(query) {
  * Fetches documentation context for a specific library
  * @param libraryId The library ID to fetch documentation for
  * @param options Options for the request
+ * @param clientIp Optional client IP address to include in headers
+ * @param apiKey Optional API key for authentication
  * @returns The documentation text or null if the request fails
  */
-export async function fetchLibraryDocumentation(libraryId, options = {}) {
+export async function fetchLibraryDocumentation(libraryId, options = {}, clientIp, apiKey) {
     try {
         if (libraryId.startsWith("/")) {
             libraryId = libraryId.slice(1);
@@ -49,15 +82,22 @@ export async function fetchLibraryDocumentation(libraryId, options = {}) {
         if (options.topic)
             url.searchParams.set("topic", options.topic);
         url.searchParams.set("type", DEFAULT_TYPE);
-        const response = await fetch(url, {
-            headers: {
-                "X-Context7-Source": "mcp-server",
-            },
-        });
+        const headers = generateHeaders(clientIp, apiKey, { "X-Context7-Source": "mcp-server" });
+        const response = await fetch(url, { headers });
         if (!response.ok) {
             const errorCode = response.status;
             if (errorCode === 429) {
-                const errorMessage = `Rate limited due to too many requests. Please try again later.`;
+                const errorMessage = "Rate limited due to too many requests. Please try again later.";
+                console.error(errorMessage);
+                return errorMessage;
+            }
+            if (errorCode === 404) {
+                const errorMessage = "The library you are trying to access does not exist. Please try with a different library ID.";
+                console.error(errorMessage);
+                return errorMessage;
+            }
+            if (errorCode === 401) {
+                const errorMessage = "Unauthorized. Please check your API key.";
                 console.error(errorMessage);
                 return errorMessage;
             }

package/dist/lib/encryption.js

@@ -0,0 +1,35 @@
+import { createCipheriv, randomBytes } from "crypto";
+const ENCRYPTION_KEY = process.env.CLIENT_IP_ENCRYPTION_KEY ||
+    "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f";
+const ALGORITHM = "aes-256-cbc";
+function validateEncryptionKey(key) {
+    // Must be exactly 64 hex characters (32 bytes)
+    return /^[0-9a-fA-F]{64}$/.test(key);
+}
+function encryptClientIp(clientIp) {
+    if (!validateEncryptionKey(ENCRYPTION_KEY)) {
+        console.error("Invalid encryption key format. Must be 64 hex characters.");
+        return clientIp; // Fallback to unencrypted
+    }
+    try {
+        const iv = randomBytes(16);
+        const cipher = createCipheriv(ALGORITHM, Buffer.from(ENCRYPTION_KEY, "hex"), iv);
+        let encrypted = cipher.update(clientIp, "utf8", "hex");
+        encrypted += cipher.final("hex");
+        return iv.toString("hex") + ":" + encrypted;
+    }
+    catch (error) {
+        console.error("Error encrypting client IP:", error);
+        return clientIp; // Fallback to unencrypted
+    }
+}
+export function generateHeaders(clientIp, apiKey, extraHeaders = {}) {
+    const headers = { ...extraHeaders };
+    if (clientIp) {
+        headers["mcp-client-ip"] = encryptClientIp(clientIp);
+    }
+    if (apiKey) {
+        headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+    return headers;
+}

package/package.json

@@ -1 +1 @@
-{"name":"@upstash/context7-mcp","version":"v1.0.14","description":"MCP server for Context7","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc && chmod 755 dist/index.js","format":"prettier --write .","lint":"eslint \"**/*.{js,ts,tsx}\" --fix","lint:check":"eslint \"**/*.{js,ts,tsx}\"","start":"node dist/index.js --transport http"},"repository":{"type":"git","url":"git+https://github.com/upstash/context7.git"},"keywords":["modelcontextprotocol","mcp","context7"],"author":"abdush","license":"MIT","type":"module","bin":{"context7-mcp":"dist/index.js"},"files":["dist"],"bugs":{"url":"https://github.com/upstash/context7/issues"},"homepage":"https://github.com/upstash/context7#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","commander":"^14.0.0","zod":"^3.24.2"},"devDependencies":{"@types/node":"^22.13.14","@typescript-eslint/eslint-plugin":"^8.28.0","@typescript-eslint/parser":"^8.28.0","eslint":"^9.23.0","eslint-config-prettier":"^10.1.1","eslint-plugin-prettier":"^5.2.5","prettier":"^3.5.3","typescript":"^5.8.2","typescript-eslint":"^8.28.0"}}
+{"name":"@upstash/context7-mcp","version":"1.0.16","description":"MCP server for Context7","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc && chmod 755 dist/index.js","format":"prettier --write .","lint":"eslint \"**/*.{js,ts,tsx}\" --fix","lint:check":"eslint \"**/*.{js,ts,tsx}\"","start":"node dist/index.js --transport http","pack-dxt":"bun install && bun run build && rm -rf node_modules && bun install --production && mv dxt/.dxtignore .dxtignore && mv dxt/manifest.json manifest.json && dxt validate manifest.json && dxt pack . dxt/context7.dxt && mv manifest.json dxt/manifest.json && mv .dxtignore dxt/.dxtignore && bun install"},"repository":{"type":"git","url":"git+https://github.com/upstash/context7.git"},"keywords":["modelcontextprotocol","mcp","context7"],"author":"abdush","license":"MIT","type":"module","bin":{"context7-mcp":"dist/index.js"},"files":["dist"],"bugs":{"url":"https://github.com/upstash/context7/issues"},"homepage":"https://github.com/upstash/context7#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.13.2","commander":"^14.0.0","undici":"^6.6.3","zod":"^3.24.2"},"devDependencies":{"@types/node":"^22.13.14","@typescript-eslint/eslint-plugin":"^8.28.0","@typescript-eslint/parser":"^8.28.0","eslint":"^9.23.0","eslint-config-prettier":"^10.1.1","eslint-plugin-prettier":"^5.2.5","prettier":"^3.5.3","typescript":"^5.8.2","typescript-eslint":"^8.28.0"}}