@upstash/context7-mcp 1.0.29 → 1.0.31-canary-20251124145014

package/README.md

@@ -280,6 +280,72 @@ Or you can directly edit MCP servers configuration:
 
 </details>
 
+<details>
+<summary><b>Install in Zed</b></summary>
+
+It can be installed via [Zed Extensions](https://zed.dev/extensions?query=Context7) or you can add this to your Zed `settings.json`. See [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) for more info.
+
+```json
+{
+  "context_servers": {
+    "Context7": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in Augment Code</b></summary>
+
+To configure Context7 MCP in Augment Code, you can use either the graphical interface or manual configuration.
+
+### **A. Using the Augment Code UI**
+
+1. Click the hamburger menu.
+2. Select **Settings**.
+3. Navigate to the **Tools** section.
+4. Click the **+ Add MCP** button.
+5. Enter the following command:
+
+   ```
+   npx -y @upstash/context7-mcp@latest
+   ```
+
+6. Name the MCP: **Context7**.
+7. Click the **Add** button.
+
+Once the MCP server is added, you can start using Context7's up-to-date code documentation features directly within Augment Code.
+
+---
+
+### **B. Manual Configuration**
+
+1. Press Cmd/Ctrl Shift P or go to the hamburger menu in the Augment panel
+2. Select Edit Settings
+3. Under Advanced, click Edit in settings.json
+4. Add the server configuration to the `mcpServers` array in the `augment.advanced` object
+
+```json
+"augment.advanced": {
+  "mcpServers": [
+    {
+      "name": "context7",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
+    }
+  ]
+}
+```
+
+Once the MCP server is added, restart your editor. If you receive any errors, check the syntax to make sure closing brackets or commas are not missing.
+
+</details>
+
 <details>
 <summary><b>Install in Kilo Code</b></summary>
 
@@ -307,6 +373,7 @@ If a server is defined in both places, the **project-level configuration overrid
 `https://mcp.context7.com/mcp`
 
 **Headers → Add Header**
+
 - **Key:** `Authorization`
 - **Value:** `Bearer YOUR_API_KEY`
 
@@ -351,69 +418,38 @@ Kilo Code will automatically detect and load the configuration.
 </details>
 
 <details>
-<summary><b>Install in Zed</b></summary>
+<summary><b>Install in Google Antigravity</b></summary>
 
-It can be installed via [Zed Extensions](https://zed.dev/extensions?query=Context7) or you can add this to your Zed `settings.json`. See [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) for more info.
+Add this to your Antigravity MCP config file. See [Antigravity MCP docs](https://antigravity.google/docs/mcp) for more info.
+
+#### Google Antigravity Remote Server Connection
 
 ```json
 {
-  "context_servers": {
-    "Context7": {
-      "source": "custom",
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
+  "mcpServers": {
+    "context7": {
+      "serverUrl": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "YOUR_API_KEY"
+      }
     }
   }
 }
 ```
 
-</details>
-
-<details>
-<summary><b>Install in Augment Code</b></summary>
-
-To configure Context7 MCP in Augment Code, you can use either the graphical interface or manual configuration.
-
-### **A. Using the Augment Code UI**
-
-1. Click the hamburger menu.
-2. Select **Settings**.
-3. Navigate to the **Tools** section.
-4. Click the **+ Add MCP** button.
-5. Enter the following command:
-
-   ```
-   npx -y @upstash/context7-mcp@latest
-   ```
-
-6. Name the MCP: **Context7**.
-7. Click the **Add** button.
-
-Once the MCP server is added, you can start using Context7's up-to-date code documentation features directly within Augment Code.
-
----
-
-### **B. Manual Configuration**
-
-1. Press Cmd/Ctrl Shift P or go to the hamburger menu in the Augment panel
-2. Select Edit Settings
-3. Under Advanced, click Edit in settings.json
-4. Add the server configuration to the `mcpServers` array in the `augment.advanced` object
+#### Google Antigravity Local Server Connection
 
 ```json
-"augment.advanced": {
-  "mcpServers": [
-    {
-      "name": "context7",
+{
+  "mcpServers": {
+    "context7": {
       "command": "npx",
       "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
     }
-  ]
+  }
 }
 ```
 
-Once the MCP server is added, restart your editor. If you receive any errors, check the syntax to make sure closing brackets or commas are not missing.
-
 </details>
 
 <details>
@@ -1253,6 +1289,24 @@ Once configured, Context7 tools will be available in your droid sessions. Type `
 
 </details>
 
+<details>
+<summary><b>Install in Emdash</b></summary>
+
+[Emdash](https://github.com/generalaction/emdash) is an orchestration layer for running multiple coding agents in parallel. Provider-agnostic, worktree-isolated, and local-first. Emdash supports Context7 MCP to enable Context7 for your agents.
+
+**What Emdash provides:**
+
+- Global toggle: Settings → MCP → "Enable Context7 MCP"
+- Per-workspace enable: The Context7 button in the ProviderBar (off by default). First click enables it for that workspace. Clicking again disables it.
+- ProviderBar: The Context7 button shows status, a short explanation, and a link to docs
+
+**What you still need to do:**
+Configure your coding agent (Codex, Claude Code, Cursor, etc.) to connect to Context7 MCP. Emdash does not modify your agent's config. See the respective MCP configuration sections above for your agent (e.g., OpenAI Codex, Claude Code, Cursor).
+
+See the [Emdash repository](https://github.com/generalaction/emdash) for more information.
+
+</details>
+
 ## 🔨 Available Tools
 
 Context7 MCP provides the following tools that LLMs can use:

package/dist/index.js

@@ -4,6 +4,7 @@ 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 { DOCUMENTATION_MODES } from "./lib/types.js";
 import express from "express";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { Command } from "commander";
@@ -69,7 +70,7 @@ function getClientIp(req) {
 }
 const server = new McpServer({
     name: "Context7",
-    version: "1.0.29",
+    version: "1.0.13",
 }, {
     instructions: "Use this server to retrieve up-to-date documentation and code examples for any library.",
 });
@@ -116,7 +117,7 @@ For ambiguous queries, request clarification before proceeding with a best-guess
         };
     }
     const resultsText = formatSearchResults(searchResponse);
-    const responseText = `Available Libraries (top matches):
+    const responseText = `Available Libraries:
 
 Each result includes:
 - Library ID: Context7-compatible identifier (format: /org/project)
@@ -143,11 +144,16 @@ ${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.",
+    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.",
     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'."),
+        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
             .string()
             .optional()
@@ -160,10 +166,10 @@ server.registerTool("get-library-docs", {
             .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."),
     },
-}, async ({ context7CompatibleLibraryID, page = 1, topic }) => {
+}, async ({ context7CompatibleLibraryID, mode = DOCUMENTATION_MODES.CODE, page = 1, topic }) => {
     const ctx = requestContext.getStore();
     const apiKey = ctx?.apiKey || globalApiKey;
-    const fetchDocsResponse = await fetchLibraryDocumentation(context7CompatibleLibraryID, {
+    const fetchDocsResponse = await fetchLibraryDocumentation(context7CompatibleLibraryID, mode, {
         page,
         limit: DEFAULT_RESULTS_LIMIT,
         topic,
@@ -268,11 +274,8 @@ async function main() {
             });
         });
         const startServer = (port, maxAttempts = 10) => {
-            const httpServer = app.listen(port, () => {
-                actualPort = port;
-                console.error(`Context7 Documentation MCP Server running on HTTP at http://localhost:${actualPort}/mcp`);
-            });
-            httpServer.on("error", (err) => {
+            const httpServer = app.listen(port);
+            httpServer.once("error", (err) => {
                 if (err.code === "EADDRINUSE" && port < initialPort + maxAttempts) {
                     console.warn(`Port ${port} is in use, trying port ${port + 1}...`);
                     startServer(port + 1, maxAttempts);
@@ -282,6 +285,10 @@ async function main() {
                     process.exit(1);
                 }
             });
+            httpServer.once("listening", () => {
+                actualPort = port;
+                console.error(`Context7 Documentation MCP Server running on HTTP at http://localhost:${actualPort}/mcp`);
+            });
         };
         startServer(initialPort);
     }

package/dist/lib/api.js

@@ -1,7 +1,50 @@
 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)
+ * @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}`;
+    }
+}
 // Pick up proxy configuration in a variety of common env var names.
 const PROXY_URL = process.env.HTTPS_PROXY ??
     process.env.https_proxy ??
@@ -30,40 +73,21 @@ if (PROXY_URL && !PROXY_URL.startsWith("$") && /^(http|https):\/\//i.test(PROXY_
  */
 export async function searchLibraries(query, clientIp, apiKey) {
     try {
-        const url = new URL(`${CONTEXT7_API_BASE_URL}/v1/search`);
+        const url = new URL(`${CONTEXT7_API_BASE_URL}/v2/search`);
         url.searchParams.set("query", query);
         const headers = generateHeaders(clientIp, apiKey);
         const response = await fetch(url, { headers });
         if (!response.ok) {
             const errorCode = response.status;
-            if (errorCode === 429) {
-                const errorMessage = 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.";
-                console.error(errorMessage);
-                return {
-                    results: [],
-                    error: errorMessage,
-                };
-            }
-            if (errorCode === 401) {
-                const errorMessage = "Unauthorized. Please check your API key. The API key you provided (possibly incorrect) is: " +
-                    apiKey +
-                    ". API keys should start with 'ctx7sk'";
-                console.error(errorMessage);
-                return {
-                    results: [],
-                    error: errorMessage,
-                };
-            }
-            const errorMessage = `Failed to search libraries. Please try again later. Error code: ${errorCode}`;
+            const errorMessage = createErrorMessage(errorCode, apiKey);
             console.error(errorMessage);
             return {
                 results: [],
                 error: errorMessage,
             };
         }
-        return await response.json();
+        const searchData = await response.json();
+        return searchData;
     }
     catch (error) {
         const errorMessage = `Error searching libraries: ${error}`;
@@ -74,54 +98,42 @@ export async function searchLibraries(query, clientIp, apiKey) {
 /**
  * Fetches documentation context for a specific library
  * @param libraryId The library ID to fetch documentation for
- * @param options Options for the request
+ * @param docMode Documentation mode (CODE for API references and code examples, INFO for conceptual guides)
+ * @param options Optional request parameters (page, limit, topic)
  * @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 = {}, clientIp, apiKey) {
+export async function fetchLibraryDocumentation(libraryId, docMode, options = {}, clientIp, apiKey) {
     try {
-        if (libraryId.startsWith("/")) {
-            libraryId = libraryId.slice(1);
+        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(`${CONTEXT7_API_BASE_URL}/v2/docs/code/${libraryId}`);
+        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());
-        if (options.topic)
-            url.searchParams.set("topic", options.topic);
-        url.searchParams.set("type", DEFAULT_TYPE);
         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 = 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.";
-                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. The API key you provided (possibly incorrect) is: " +
-                    apiKey +
-                    ". API keys should start with 'ctx7sk'";
-                console.error(errorMessage);
-                return errorMessage;
-            }
-            const errorMessage = `Failed to fetch documentation. Please try again later. Error code: ${errorCode}`;
+            const errorMessage = createErrorMessage(errorCode, apiKey);
             console.error(errorMessage);
             return errorMessage;
         }
         const text = await response.text();
         if (!text || text === "No content available" || text === "No context data available") {
-            return null;
+            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}`;
         }
         return text;
     }

package/dist/lib/encryption.js

@@ -1,7 +1,10 @@
 import { createCipheriv, randomBytes } from "crypto";
-const ENCRYPTION_KEY = process.env.CLIENT_IP_ENCRYPTION_KEY ||
-    "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f";
+const DEFAULT_ENCRYPTION_KEY = "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f";
+const ENCRYPTION_KEY = process.env.CLIENT_IP_ENCRYPTION_KEY || DEFAULT_ENCRYPTION_KEY;
 const ALGORITHM = "aes-256-cbc";
+if (ENCRYPTION_KEY === DEFAULT_ENCRYPTION_KEY) {
+    console.warn("WARNING: Using default CLIENT_IP_ENCRYPTION_KEY.");
+}
 function validateEncryptionKey(key) {
     // Must be exactly 64 hex characters (32 bytes)
     return /^[0-9a-fA-F]{64}$/.test(key);

package/dist/lib/types.js

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

package/dist/lib/utils.js

@@ -58,3 +58,20 @@ 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 +1,54 @@
-{"name":"@upstash/context7-mcp","version":"1.0.29","mcpName":"io.github.upstash/context7","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-mcpb":"bun install && bun run build && rm -rf node_modules && bun install --production && 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"},"repository":{"type":"git","url":"git+https://github.com/upstash/context7.git"},"keywords":["modelcontextprotocol","mcp","context7","vibe-coding","developer tools","documentation","context"],"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.17.5","@types/express":"^5.0.4","commander":"^14.0.0","express":"^5.1.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.34.0","eslint-config-prettier":"^10.1.1","eslint-plugin-prettier":"^5.2.5","prettier":"^3.6.2","typescript":"^5.8.2","typescript-eslint":"^8.28.0"}}
+{
+  "name": "@upstash/context7-mcp",
+  "version": "1.0.31-canary-20251124145014",
+  "mcpName": "io.github.upstash/context7",
+  "description": "MCP server for Context7",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/upstash/context7.git",
+    "directory": "packages/mcp"
+  },
+  "keywords": [
+    "modelcontextprotocol",
+    "mcp",
+    "context7",
+    "vibe-coding",
+    "developer tools",
+    "documentation",
+    "context"
+  ],
+  "author": "abdush",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "context7-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "bugs": {
+    "url": "https://github.com/upstash/context7/issues"
+  },
+  "homepage": "https://github.com/upstash/context7#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "@types/express": "^5.0.4",
+    "commander": "^14.0.0",
+    "express": "^5.1.0",
+    "undici": "^6.6.3",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.14",
+    "typescript": "^5.8.2"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 dist/index.js",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "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"
+  }
+}