@upstash/context7-mcp 1.0.34-canary.0 → 1.0.34-canary.2

package/dist/index.js

@@ -2,7 +2,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { fetchLibraryContext } from "./lib/api.js";
+import { searchLibraries, fetchLibraryContext } from "./lib/api.js";
+import { formatSearchResults } from "./lib/utils.js";
 import express from "express";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { Command } from "commander";
@@ -44,29 +45,79 @@ const CLI_PORT = (() => {
 const requestContext = new AsyncLocalStorage();
 // Store API key globally for stdio mode (where requestContext may not be available in tool handlers)
 let globalApiKey;
-const stripIpv6Prefix = (ip) => ip.replace(/^::ffff:/, "");
-const isPrivateIp = (ip) => ip.startsWith("10.") || ip.startsWith("192.168.") || /^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(ip);
 function getClientIp(req) {
-    const forwardedFor = req.headers["x-forwarded-for"];
+    const forwardedFor = req.headers["x-forwarded-for"] || req.headers["X-Forwarded-For"];
     if (forwardedFor) {
         const ips = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor;
-        const ipList = ips.split(",").map((ip) => stripIpv6Prefix(ip.trim()));
-        return ipList.find((ip) => !isPrivateIp(ip)) ?? ipList[0];
+        const ipList = ips.split(",").map((ip) => ip.trim());
+        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;
+            }
+        }
+        return ipList[0].replace(/^::ffff:/, "");
+    }
+    if (req.socket?.remoteAddress) {
+        return req.socket.remoteAddress.replace(/^::ffff:/, "");
     }
-    return req.socket?.remoteAddress ? stripIpv6Prefix(req.socket.remoteAddress) : undefined;
+    return undefined;
 }
 const server = new McpServer({
     name: "Context7",
     version: "2.0.0",
 }, {
-    capabilities: {
-        tools: { listChanged: true },
-    },
     instructions: "Use this server to retrieve up-to-date documentation and code examples for any library.",
 });
-server.registerTool("get-docs", {
-    title: "Get Library Documentation",
-    description: `Retrieves up-to-date documentation and code examples from Context7 for any programming library or framework.
+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.
+
+You MUST call this function before 'query-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.
+
+Each result includes: Library ID (format: /org/project), name, description, code snippet count, source reputation (High/Medium/Low/Unknown), benchmark score (0-100), and available versions (/org/project/version format).
+
+Select the best match based on: name similarity, description relevance, snippet coverage, source reputation, and benchmark score. For ambiguous queries, ask for clarification.`,
+    inputSchema: {
+        query: z
+            .string()
+            .describe("The user's original question or task. This is used to rank library results by relevance to what the user is trying to accomplish. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."),
+        libraryName: z
+            .string()
+            .describe("Library name to search for and retrieve a Context7-compatible library ID."),
+    },
+}, async ({ query, libraryName }) => {
+    const ctx = requestContext.getStore();
+    const apiKey = ctx?.apiKey || globalApiKey;
+    const searchResponse = await searchLibraries(query, libraryName, ctx?.clientIp, apiKey);
+    if (!searchResponse.results || searchResponse.results.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: searchResponse.error
+                        ? searchResponse.error
+                        : "No libraries found matching the provided name.",
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: formatSearchResults(searchResponse),
+            },
+        ],
+    };
+});
+server.registerTool("query-docs", {
+    title: "Query Documentation",
+    description: `Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework.
+
+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.
 
 USE THIS TOOL TO:
 - Get current, accurate documentation for libraries (e.g., React, Next.js, Express, LangChain)
@@ -77,24 +128,14 @@ USE THIS TOOL TO:
         query: z
             .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."),
-        library: z
-            .string()
-            .optional()
-            .describe("Library or framework name (e.g., 'react', 'express') OR exact library ID if provided by the user with or without version (e.g., '/vercel/next.js', '/vercel/next.js@v14.3.0-canary.87'). If omitted, auto-selects based on query."),
-        topic: z
+        libraryId: z
             .string()
-            .optional()
-            .describe("Narrow down results to a specific topic within the library. Examples: 'hooks', 'routing', 'middleware', 'authentication', 'state management'."),
-        mode: z
-            .enum(["code", "info"])
-            .optional()
-            .default("code")
-            .describe("Type of content to prioritize. Use 'code' (default) when you need working code examples, API usage patterns, and implementation snippets. Use 'info' when you need conceptual narrative explanations, architectural overviews, or understanding how something works."),
+            .describe("Context7-compatible library ID (e.g., '/mongodb/docs' or '/vercel/next.js'). Retrieved from 'resolve-library-id' or directly from user query in the format '/org/project' or '/org/project/version'."),
     },
-}, async ({ query, library, topic, mode = "code" }) => {
+}, async ({ query, libraryId }) => {
     const ctx = requestContext.getStore();
     const apiKey = ctx?.apiKey || globalApiKey;
-    const response = await fetchLibraryContext({ query, library, topic, mode }, ctx?.clientIp, apiKey);
+    const response = await fetchLibraryContext({ query, libraryId }, ctx?.clientIp, apiKey);
     return {
         content: [
             {
@@ -108,6 +149,7 @@ async function main() {
     const transportType = TRANSPORT_TYPE;
     if (transportType === "http") {
         const initialPort = CLI_PORT ?? DEFAULT_PORT;
+        let actualPort = initialPort;
         const app = express();
         app.use(express.json());
         app.use((req, res, next) => {
@@ -137,8 +179,14 @@ async function main() {
         };
         const extractApiKey = (req) => {
             return (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["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"]));
         };
         app.all("/mcp", async (req, res) => {
             try {
@@ -190,7 +238,8 @@ async function main() {
                 }
             });
             httpServer.once("listening", () => {
-                console.error(`Context7 Documentation MCP Server running on HTTP at http://localhost:${port}/mcp`);
+                actualPort = port;
+                console.error(`Context7 Documentation MCP Server running on HTTP at http://localhost:${actualPort}/mcp`);
             });
         };
         startServer(initialPort);

package/dist/lib/api.js

@@ -26,7 +26,7 @@ async function parseErrorResponse(response, apiKey) {
             : "Rate limited or quota exceeded. Create a free API key at https://context7.com/dashboard for higher limits.";
     }
     if (status === 404) {
-        return "No documentation found. Try a different library name or refine your query.";
+        return "The library you are trying to access does not exist. Please try with a different library ID.";
     }
     if (status === 401) {
         return "Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix.";
@@ -52,6 +52,38 @@ if (PROXY_URL && !PROXY_URL.startsWith("$") && /^(http|https):\/\//i.test(PROXY_
         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 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
+ */
+export async function searchLibraries(query, libraryName, clientIp, apiKey) {
+    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 response = await fetch(url, { headers });
+        if (!response.ok) {
+            const errorMessage = await parseErrorResponse(response, apiKey);
+            console.error(errorMessage);
+            return {
+                results: [],
+                error: errorMessage,
+            };
+        }
+        const searchData = await response.json();
+        return searchData;
+    }
+    catch (error) {
+        const errorMessage = `Error searching libraries: ${error}`;
+        console.error(errorMessage);
+        return { results: [], error: errorMessage };
+    }
+}
 /**
  * Fetches intelligent, reranked context for a natural language query
  * @param request The context request parameters (query, topic, library, mode)
@@ -63,12 +95,7 @@ export async function fetchLibraryContext(request, clientIp, apiKey) {
     try {
         const url = new URL(`${CONTEXT7_API_BASE_URL}/v2/context`);
         url.searchParams.set("query", request.query);
-        if (request.topic)
-            url.searchParams.set("topic", request.topic);
-        if (request.library)
-            url.searchParams.set("library", request.library);
-        if (request.mode)
-            url.searchParams.set("mode", request.mode);
+        url.searchParams.set("libraryId", request.libraryId);
         const headers = generateHeaders(clientIp, apiKey, { "X-Context7-Source": "mcp-server" });
         const response = await fetch(url, { headers });
         if (!response.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upstash/context7-mcp",
-  "version": "1.0.34-canary.0",
+  "version": "1.0.34-canary.2",
   "mcpName": "io.github.upstash/context7",
   "description": "MCP server for Context7",
   "repository": {
@@ -41,13 +41,7 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^1.2.12",
-    "@ai-sdk/google": "^1.2.7",
-    "@ai-sdk/mcp": "^0.2.0",
-    "@ai-sdk/openai": "^1.3.22",
     "@types/node": "^22.13.14",
-    "ai": "^4.3.16",
-    "dotenv": "^16.5.0",
     "typescript": "^5.8.2"
   },
   "scripts": {
@@ -60,8 +54,6 @@
     "format:check": "prettier --check .",
     "dev": "tsc --watch",
     "start": "node dist/index.js --transport http",
-    "pack-mcpb": "pnpm install && pnpm run build && rm -rf node_modules && pnpm install --prod && mv mcpb/.mcpbignore .mcpbignore && mv mcpb/manifest.json manifest.json && mv public/icon.png icon.png && mcpb validate manifest.json && mcpb pack . mcpb/context7.mcpb && mv manifest.json mcpb/manifest.json && mv .mcpbignore mcpb/.mcpbignore && mv icon.png public/icon.png && bun install",
-    "run-benchmark": "pnpm run build && node dist/benchmark/run-benchmark.js",
-    "compare-benchmark": "pnpm run build && node dist/benchmark/compare-benchmark.js"
+    "pack-mcpb": "pnpm install && pnpm run build && rm -rf node_modules && pnpm install --prod && mv mcpb/.mcpbignore .mcpbignore && mv mcpb/manifest.json manifest.json && mv public/icon.png icon.png && mcpb validate manifest.json && mcpb pack . mcpb/context7.mcpb && mv manifest.json mcpb/manifest.json && mv .mcpbignore mcpb/.mcpbignore && mv icon.png public/icon.png && bun install"
   }
 }