@upstash/context7-mcp 1.1.0-canary-20251128121456 → 2.0.0

package/README.md

@@ -1,4 +1,4 @@
-![Cover](public/cover.png)
+![Cover](https://github.com/upstash/context7/blob/master/public/cover.png?raw=true)
 
 [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D) [<img alt="Install in VS Code (npx)" src="https://img.shields.io/badge/Install%20in%20VS%20Code-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22context7%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fcontext7-mcp%40latest%22%5D%7D)
 

package/dist/index.js

@@ -2,15 +2,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { searchLibraries, fetchLibraryDocumentation } from "./lib/api.js";
+import { searchLibraries, fetchLibraryContext } from "./lib/api.js";
 import { formatSearchResults } from "./lib/utils.js";
-import { DOCUMENTATION_MODES } from "./lib/types.js";
 import express from "express";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { Command } from "commander";
 import { AsyncLocalStorage } from "async_hooks";
-/** Default number of results to return per page */
-const DEFAULT_RESULTS_LIMIT = 10;
 /** Default HTTP server port */
 const DEFAULT_PORT = 3000;
 // Parse CLI arguments using commander
@@ -70,15 +67,15 @@ function getClientIp(req) {
 }
 const server = new McpServer({
     name: "Context7",
-    version: "1.0.13",
+    version: "2.0.0",
 }, {
     instructions: "Use this server to retrieve up-to-date documentation and code examples for any library.",
 });
 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.
+    description: `Resolves a package/product name to a Context7-compatible library ID and returns 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.
+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.
 
 Selection Process:
 1. Analyze the query to understand what library/package the user is looking for
@@ -95,15 +92,21 @@ 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.`,
+For ambiguous queries, request clarification before proceeding with a best-guess match.
+
+IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.`,
     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 ({ libraryName }) => {
+}, async ({ query, libraryName }) => {
     const ctx = requestContext.getStore();
-    const searchResponse = await searchLibraries(libraryName, ctx?.clientIp, ctx?.apiKey);
+    const apiKey = ctx?.apiKey || globalApiKey;
+    const searchResponse = await searchLibraries(query, libraryName, ctx?.clientIp, apiKey);
     if (!searchResponse.results || searchResponse.results.length === 0) {
         return {
             content: [
@@ -111,7 +114,7 @@ For ambiguous queries, request clarification before proceeding with a best-guess
                     type: "text",
                     text: searchResponse.error
                         ? searchResponse.error
-                        : "Failed to retrieve library documentation data from Context7",
+                        : "No libraries found matching the provided name.",
                 },
             ],
         };
@@ -142,53 +145,30 @@ ${resultsText}`;
         ],
     };
 });
-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. Use mode='code' (default) for API references and code examples, or mode='info' for conceptual guides, narrative information, and architectural questions.",
+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.
+
+IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.`,
     inputSchema: {
-        context7CompatibleLibraryID: z
+        libraryId: 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'."),
-        mode: z
-            .enum(["code", "info"])
-            .optional()
-            .default("code")
-            .describe("Documentation mode: 'code' for API references and code examples (default), 'info' for conceptual guides, narrative information, and architectural questions."),
-        topic: z
+        query: z
             .string()
-            .optional()
-            .describe("Topic to focus documentation on (e.g., 'hooks', 'routing')."),
-        page: z
-            .number()
-            .int()
-            .min(1)
-            .max(10)
-            .optional()
-            .describe("Page number for pagination (start: 1, default: 1). If the context is not sufficient, try page=2, page=3, page=4, etc. with the same topic."),
+            .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."),
     },
-}, async ({ context7CompatibleLibraryID, mode = DOCUMENTATION_MODES.CODE, page = 1, topic }) => {
+}, async ({ query, libraryId }) => {
     const ctx = requestContext.getStore();
     const apiKey = ctx?.apiKey || globalApiKey;
-    const fetchDocsResponse = await fetchLibraryDocumentation(context7CompatibleLibraryID, mode, {
-        page,
-        limit: DEFAULT_RESULTS_LIMIT,
-        topic,
-    }, ctx?.clientIp, apiKey);
-    if (!fetchDocsResponse) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: "Documentation not found or not finalized for this library. This might have happened because you used an invalid Context7-compatible library ID. To get a valid Context7-compatible library ID, use the 'resolve-library-id' with the package name you wish to retrieve documentation for.",
-                },
-            ],
-        };
-    }
+    const response = await fetchLibraryContext({ query, libraryId }, ctx?.clientIp, apiKey);
     return {
         content: [
             {
                 type: "text",
-                text: fetchDocsResponse,
+                text: response.data,
             },
         ],
     };
@@ -197,7 +177,6 @@ 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) => {
@@ -227,12 +206,8 @@ 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["Context7_API_Key"]) ||
-                extractHeaderValue(req.headers["X_API_Key"]) ||
                 extractHeaderValue(req.headers["context7_api_key"]) ||
                 extractHeaderValue(req.headers["x_api_key"]));
         };
@@ -286,8 +261,7 @@ async function main() {
                 }
             });
             httpServer.once("listening", () => {
-                actualPort = port;
-                console.error(`Context7 Documentation MCP Server running on HTTP at http://localhost:${actualPort}/mcp`);
+                console.error(`Context7 Documentation MCP Server running on HTTP at http://localhost:${port}/mcp`);
             });
         };
         startServer(initialPort);

package/dist/lib/api.js

@@ -1,49 +1,37 @@
 import { generateHeaders } from "./encryption.js";
 import { ProxyAgent, setGlobalDispatcher } from "undici";
-import { DOCUMENTATION_MODES } from "./types.js";
-import { maskApiKey } from "./utils.js";
 const CONTEXT7_API_BASE_URL = "https://context7.com/api";
-const DEFAULT_TYPE = "txt";
 /**
- * Parses a Context7-compatible library ID into its components
- * @param libraryId The library ID (e.g., "/vercel/next.js" or "/vercel/next.js/v14.3.0")
- * @returns Object with username, library, and optional tag
- */
-function parseLibraryId(libraryId) {
-    // Remove leading slash if present
-    const cleaned = libraryId.startsWith("/") ? libraryId.slice(1) : libraryId;
-    const parts = cleaned.split("/");
-    if (parts.length < 2) {
-        throw new Error(`Invalid library ID format: ${libraryId}. Expected format: /username/library or /username/library/tag`);
-    }
-    return {
-        username: parts[0],
-        library: parts[1],
-        tag: parts[2], // undefined if not present
-    };
-}
-/**
- * Generates appropriate error messages based on HTTP status codes
- * @param errorCode The HTTP error status code
- * @param apiKey Optional API key (used for rate limit message)
+ * Parses error response from the Context7 API
+ * Extracts the server's error message, falling back to status-based messages if parsing fails
+ * @param response The fetch Response object
+ * @param apiKey Optional API key (used for fallback messages)
  * @returns Error message string
  */
-function createErrorMessage(errorCode, apiKey) {
-    switch (errorCode) {
-        case 429:
-            return apiKey
-                ? "Rate limited due to too many requests. Please try again later."
-                : "Rate limited due to too many requests. You can create a free API key at https://context7.com/dashboard for higher rate limits.";
-        case 404:
-            return "The library you are trying to access does not exist. Please try with a different library ID.";
-        case 401:
-            if (!apiKey) {
-                return "Unauthorized. Please provide an API key.";
-            }
-            return `Unauthorized. Please check your API key. The API key you provided (possibly incorrect) is: ${maskApiKey(apiKey)}. API keys should start with 'ctx7sk'`;
-        default:
-            return `Failed to fetch documentation. Please try again later. Error code: ${errorCode}`;
+async function parseErrorResponse(response, apiKey) {
+    try {
+        const json = (await response.json());
+        if (json.message) {
+            return json.message;
+        }
+    }
+    catch {
+        // JSON parsing failed, fall through to default
     }
+    // Fallback for non-JSON responses
+    const status = response.status;
+    if (status === 429) {
+        return apiKey
+            ? "Rate limited or quota exceeded. Upgrade your plan at https://context7.com/plans for higher limits."
+            : "Rate limited or quota exceeded. Create a free API key at https://context7.com/dashboard for higher limits.";
+    }
+    if (status === 404) {
+        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.";
+    }
+    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 ??
@@ -66,20 +54,21 @@ if (PROXY_URL && !PROXY_URL.startsWith("$") && /^(http|https):\/\//i.test(PROXY_
 }
 /**
  * Searches for libraries matching the given query
- * @param query The search 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, clientIp, apiKey) {
+export async function searchLibraries(query, libraryName, clientIp, apiKey) {
     try {
-        const url = new URL(`${CONTEXT7_API_BASE_URL}/v2/search`);
+        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 errorCode = response.status;
-            const errorMessage = createErrorMessage(errorCode, apiKey);
+            const errorMessage = await parseErrorResponse(response, apiKey);
             console.error(errorMessage);
             return {
                 results: [],
@@ -96,50 +85,35 @@ export async function searchLibraries(query, clientIp, apiKey) {
     }
 }
 /**
- * Fetches documentation context for a specific library
- * @param libraryId The library ID to fetch documentation for
- * @param docMode Documentation mode (CODE for API references and code examples, INFO for conceptual guides)
- * @param options Optional request parameters (page, limit, topic)
+ * 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
- * @returns The documentation text or null if the request fails
+ * @returns Context response with data
  */
-export async function fetchLibraryDocumentation(libraryId, docMode, options = {}, clientIp, apiKey) {
+export async function fetchLibraryContext(request, clientIp, apiKey) {
     try {
-        const { username, library, tag } = parseLibraryId(libraryId);
-        // Build URL path
-        let urlPath = `${CONTEXT7_API_BASE_URL}/v2/docs/${docMode}/${username}/${library}`;
-        if (tag) {
-            urlPath += `/${tag}`;
-        }
-        const url = new URL(urlPath);
-        url.searchParams.set("type", DEFAULT_TYPE);
-        if (options.topic)
-            url.searchParams.set("topic", options.topic);
-        if (options.page)
-            url.searchParams.set("page", options.page.toString());
-        if (options.limit)
-            url.searchParams.set("limit", options.limit.toString());
+        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 response = await fetch(url, { headers });
         if (!response.ok) {
-            const errorCode = response.status;
-            const errorMessage = createErrorMessage(errorCode, apiKey);
+            const errorMessage = await parseErrorResponse(response, apiKey);
             console.error(errorMessage);
-            return errorMessage;
+            return { data: errorMessage };
         }
         const text = await response.text();
-        if (!text || text === "No content available" || text === "No context data available") {
-            const suggestion = docMode === DOCUMENTATION_MODES.CODE
-                ? " Try mode='info' for guides and tutorials."
-                : " Try mode='code' for API references and code examples.";
-            return `No ${docMode} documentation available for this library.${suggestion}`;
+        if (!text) {
+            return {
+                data: "Documentation not found or not finalized for this library. This might have happened because you used an invalid Context7-compatible library ID. To get a valid Context7-compatible library ID, use the 'resolve-library-id' with the package name you wish to retrieve documentation for.",
+            };
         }
-        return text;
+        return { data: text };
     }
     catch (error) {
-        const errorMessage = `Error fetching library documentation. Please try again later. ${error}`;
+        const errorMessage = `Error fetching library context. Please try again later. ${error}`;
         console.error(errorMessage);
-        return errorMessage;
+        return { data: errorMessage };
     }
 }

package/dist/lib/types.js

@@ -1,7 +1 @@
-/**
- * Documentation modes for fetching library documentation
- */
-export const DOCUMENTATION_MODES = {
-    CODE: "code",
-    INFO: "info",
-};
+export {};

package/dist/lib/utils.js

@@ -58,20 +58,3 @@ export function formatSearchResults(searchResponse) {
     const formattedResults = searchResponse.results.map(formatSearchResult);
     return formattedResults.join("\n----------\n");
 }
-/**
- * Masks an API key by showing only the first 10 characters and last 4 characters.
- * This prevents full API keys from being exposed in logs while maintaining some
- * identifiability for debugging.
- *
- * @param apiKey The API key to mask
- * @returns Masked API key string (e.g., "ctx7sk-abc...xyz1") or "[NO-API-KEY]" if no key provided
- */
-export function maskApiKey(apiKey) {
-    if (apiKey.length <= 14) {
-        // If the key is too short to mask meaningfully, just show first part
-        return apiKey.substring(0, 7) + "...";
-    }
-    const firstPart = apiKey.substring(0, 10);
-    const lastPart = apiKey.substring(apiKey.length - 4);
-    return `${firstPart}...${lastPart}`;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upstash/context7-mcp",
-  "version": "1.1.0-canary-20251128121456",
+  "version": "2.0.0",
   "mcpName": "io.github.upstash/context7",
   "description": "MCP server for Context7",
   "repository": {
@@ -46,13 +46,14 @@
   },
   "scripts": {
     "build": "tsc && chmod 755 dist/index.js",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "echo \"No tests yet\"",
+    "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "lint:check": "eslint .",
     "format": "prettier --write .",
     "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"
+    "pack-mcpb": "pnpm install && pnpm run build && rm -rf node_modules && pnpm install --prod && cp mcpb/manifest.json manifest.json && cp ../../public/icon.png icon.png && mcpb validate manifest.json && mcpb pack . mcpb/context7.mcpb && rm manifest.json icon.png && pnpm install"
   }
 }