@upstash/context7-mcp 1.0.13 → 1.0.15

package/dist/index.js

@@ -4,39 +4,82 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { searchLibraries, fetchLibraryDocumentation } from "./lib/api.js";
 import { formatSearchResults } from "./lib/utils.js";
-import dotenv from "dotenv";
 import { createServer } from "http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
-import { parse } from "url";
-// Load environment variables from .env file if present
-dotenv.config();
-// Get DEFAULT_MINIMUM_TOKENS from environment variable or use default
-let DEFAULT_MINIMUM_TOKENS = 10000;
-if (process.env.DEFAULT_MINIMUM_TOKENS) {
-    const parsedValue = parseInt(process.env.DEFAULT_MINIMUM_TOKENS, 10);
-    if (!isNaN(parsedValue) && parsedValue > 0) {
-        DEFAULT_MINIMUM_TOKENS = parsedValue;
-    }
-    else {
-        console.warn(`Warning: Invalid DEFAULT_MINIMUM_TOKENS value provided in environment variable. Using default value of 10000`);
-    }
+import { Command } from "commander";
+const DEFAULT_MINIMUM_TOKENS = 10000;
+// Parse CLI arguments using commander
+const program = new Command()
+    .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"];
+if (!allowedTransports.includes(cliOptions.transport)) {
+    console.error(`Invalid --transport value: '${cliOptions.transport}'. Must be one of: stdio, http.`);
+    process.exit(1);
+}
+// Transport configuration
+const TRANSPORT_TYPE = (cliOptions.transport || "stdio");
+// 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",
-        description: "Retrieves up-to-date documentation and code examples for any library.",
-        version: "v1.0.13",
-        capabilities: {
-            resources: {},
-            tools: {},
-        },
+        version: "1.0.15",
+    }, {
+        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.
 
@@ -54,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: [
@@ -96,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: [
@@ -136,27 +185,58 @@ ${resultsText}`,
     return server;
 }
 async function main() {
-    const transportType = process.env.MCP_TRANSPORT || "stdio";
-    if (transportType === "http" || transportType === "sse") {
+    const transportType = TRANSPORT_TYPE;
+    if (transportType === "http") {
         // Get initial port from environment or use default
-        const initialPort = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
+        const initialPort = CLI_PORT ?? 3000;
         // Keep track of which port we end up using
         let actualPort = initialPort;
         const httpServer = createServer(async (req, res) => {
-            const url = parse(req.url || "").pathname;
+            const url = new URL(req.url || "", `http://${req.headers.host}`).pathname;
             // 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,
@@ -177,8 +257,8 @@ async function main() {
                 }
                 else if (url === "/messages" && req.method === "POST") {
                     // Get session ID from query parameters
-                    const parsedUrl = parse(req.url || "", true);
-                    const sessionId = parsedUrl.query.sessionId;
+                    const sessionId = new URL(req.url || "", `http://${req.headers.host}`).searchParams.get("sessionId") ??
+                        "";
                     if (!sessionId) {
                         res.writeHead(400);
                         res.end("Missing sessionId parameter");
@@ -225,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
@@ -233,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,33 @@
+import { generateHeaders } from "./encryption.js";
 const CONTEXT7_API_BASE_URL = "https://context7.com/api";
 const DEFAULT_TYPE = "txt";
 /**
  * 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 +47,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 +62,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.13","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":"MCP_TRANSPORT=http node dist/index.js"},"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","dotenv":"^16.5.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.15","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","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"}}