@upstash/context7-mcp 1.0.16 → 1.0.18

package/README.md

@@ -1,6 +1,8 @@
+![Cover](public/cover.png)
+
 # Context7 MCP - Up-to-date Code Docs For Any Prompt
 
-[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp)
+[![Website](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com) [![smithery badge](https://smithery.ai/badge/@upstash/context7-mcp)](https://smithery.ai/server/@upstash/context7-mcp) [![NPM Version](https://img.shields.io/npm/v/%40upstash%2Fcontext7-mcp?color=red)](https://www.npmjs.com/package/@upstash/context7-mcp) [![MIT licensed](https://img.shields.io/npm/l/%40upstash%2Fcontext7-mcp)](./LICENSE)
 
 [![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)
 
@@ -11,7 +13,7 @@
 LLMs rely on outdated or generic information about the libraries you use. You get:
 
 - ❌ Code examples are outdated and based on year-old training data
-- ❌ Hallucinated APIs don't even exist
+- ❌ Hallucinated APIs that don't even exist
 - ❌ Generic answers for old package versions
 
 ## ✅ With Context7
@@ -34,7 +36,7 @@ Context7 fetches up-to-date code examples and documentation right into your LLM'
 - 2️⃣ Tell the LLM to `use context7`
 - 3️⃣ Get working code answers
 
-No tab-switching, no hallucinated APIs that don't exist, no outdated code generations.
+No tab-switching, no hallucinated APIs that don't exist, no outdated code generation.
 
 ## 📚 Adding Projects
 
@@ -48,6 +50,11 @@ Check out our [project addition guide](./docs/adding-projects.md) to learn how t
 - Cursor, Claude Code, VSCode, Windsurf or another MCP Client
 - Context7 API Key (Optional for higher rate limits) (Get yours by creating an account at [context7.com/dashboard](https://context7.com/dashboard))
 
+> [!WARNING]
+> **SSE Protocol Deprecation Notice**
+>
+> The Server-Sent Events (SSE) transport protocol is deprecated and its endpoint will be removed in upcoming releases. Please use HTTP or stdio transport methods instead.
+
 <details>
 <summary><b>Installing via Smithery</b></summary>
 
@@ -107,7 +114,7 @@ Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file i
 <details>
 <summary><b>Install in Claude Code</b></summary>
 
-Run this command. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp) for more info.
+Run this command. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.
 
 #### Claude Code Remote Server Connection
 
@@ -115,12 +122,6 @@ Run this command. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/
 claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: YOUR_API_KEY"
 ```
 
-Or using SSE transport:
-
-```sh
-claude mcp add --transport sse context7 https://mcp.context7.com/sse --header "CONTEXT7_API_KEY: YOUR_API_KEY"
-```
-
 #### Claude Code Local Server Connection
 
 ```sh
@@ -216,6 +217,28 @@ You can easily install Context7 through the [Cline MCP Server Marketplace](https
 3. Use the search bar within the **Marketplace** tab to find _Context7_.
 4. Click the **Install** button.
 
+Or you can directly edit MCP servers configuration:
+
+1. Open **Cline**.
+2. Click the hamburger menu icon (☰) to enter the **MCP Servers** section.
+3. Choose **Remote Servers** tab.
+4. Click the **Edit Configuration** button.
+5. Add context7 to `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "url": "https://mcp.context7.com/mcp",
+      "type": "streamableHttp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
 </details>
 
 <details>
@@ -298,7 +321,10 @@ Add this to your Roo Code MCP configuration file. See [Roo Code MCP docs](https:
   "mcpServers": {
     "context7": {
       "type": "streamable-http",
-      "url": "https://mcp.context7.com/mcp"
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "YOUR_API_KEY",
+      }
     }
   }
 }
@@ -333,7 +359,8 @@ See [Gemini CLI Configuration](https://google-gemini.github.io/gemini-cli/docs/t
     "context7": {
       "httpUrl": "https://mcp.context7.com/mcp",
       "headers": {
-        "CONTEXT7_API_KEY": "YOUR_API_KEY"
+        "CONTEXT7_API_KEY": "YOUR_API_KEY",
+        "Accept": "application/json, text/event-stream"
       }
     }
   }
@@ -384,7 +411,7 @@ Open Claude Desktop developer settings and edit your `claude_desktop_config.json
 <details>
 <summary><b>Install in Opencode</b></summary>
 
-Add this to your Opencode configuration file. See [Opencode MCP docs](https://opencode.ai/docs/mcp-servers) docs for more info.
+Add this to your Opencode configuration file. See [Opencode MCP docs](https://opencode.ai/docs/mcp-servers) for more info.
 
 #### Opencode Remote Server Connection
 
@@ -416,6 +443,7 @@ Add this to your Opencode configuration file. See [Opencode MCP docs](https://op
 ```
 
 </details>
+
 <details>
 <summary><b>Install in OpenAI Codex</b></summary>
 
@@ -429,6 +457,40 @@ args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
 command = "npx"
 ```
 
+⚠️ Windows Notes
+
+On Windows, some users may encounter request timed out errors with the default configuration.
+In that case, explicitly configure the MCP server with the full path to Node.js and the installed package:
+
+```toml
+[mcp_servers.context7]
+command = "C:\\Program Files\\nodejs\\node.exe"
+args = [
+  "C:\\Users\\yourname\\AppData\\Roaming\\npm\\node_modules\\@upstash\\context7-mcp\\dist\\index.js",
+  "--transport",
+  "stdio",
+  "--api-key",
+  "YOUR_API_KEY"
+]
+```
+Alternatively, you can use the following configuration:
+
+```toml
+[mcp_servers.context7]
+command = "cmd"
+args = [
+    "/c",
+    "npx",
+    "-y",
+    "@upstash/context7-mcp",
+    "--api-key",
+    "YOUR_API_KEY"
+]
+env = { SystemRoot="C:\\Windows" }
+startup_timeout_ms = 20_000
+```
+
+This ensures Codex CLI works reliably on Windows.
 </details>
 
 <details>
@@ -436,7 +498,7 @@ command = "npx"
 
 See [JetBrains AI Assistant Documentation](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) for more details.
 
-1. In JetBrains IDEs go to `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)`
+1. In JetBrains IDEs, go to `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)`
 2. Click `+ Add`.
 3. Click on `Command` in the top-left corner of the dialog and select the As JSON option from the list
 4. Add this configuration and click `OK`
@@ -619,7 +681,7 @@ If you prefer to run the MCP server in a Docker container:
 <details>
 <summary><b>Install Using the Desktop Extension</b></summary>
 
-Install the [context7.dxt](dxt/context7.dxt) file under the dxt folder and add it to your client. For more information please check out [the desktop extensions docs](https://github.com/anthropics/dxt#desktop-extensions-dxt).
+Install the [context7.mcpb](mcpb/context7.mcpb) file under the mcpb folder and add it to your client. For more information, please check out [MCP bundles docs](https://github.com/anthropics/mcpb#mcp-bundles-mcpb).
 
 </details>
 
@@ -755,7 +817,7 @@ Add this to your Visual Studio MCP config file (see the [Visual Studio docs](htt
   "inputs": [],
   "servers": {
     "context7": {
-      "type": "sse",
+      "type": "http",
       "url": "https://mcp.context7.com/mcp",
       "headers": {
         "CONTEXT7_API_KEY": "YOUR_API_KEY"
@@ -807,23 +869,6 @@ Add this to your Crush configuration file. See [Crush MCP docs](https://github.c
 }
 ```
 
-#### Crush Remote Server Connection (SSE)
-
-```json
-{
-  "$schema": "https://charm.land/crush.json",
-  "mcp": {
-    "context7": {
-      "type": "sse",
-      "url": "https://mcp.context7.com/sse",
-      "headers": {
-        "CONTEXT7_API_KEY": "YOUR_API_KEY"
-      }
-    }
-  }
-}
-```
-
 #### Crush Local Server Connection
 
 ```json
@@ -985,41 +1030,48 @@ See [Local and Remote MCPs for Perplexity](https://www.perplexity.ai/help-center
 Context7 MCP provides the following tools that LLMs can use:
 
 - `resolve-library-id`: Resolves a general library name into a Context7-compatible library ID.
-
   - `libraryName` (required): The name of the library to search for
 
 - `get-library-docs`: Fetches documentation for a library using a Context7-compatible library ID.
   - `context7CompatibleLibraryID` (required): Exact Context7-compatible library ID (e.g., `/mongodb/docs`, `/vercel/next.js`)
   - `topic` (optional): Focus the docs on a specific topic (e.g., "routing", "hooks")
-  - `tokens` (optional, default 10000): Max number of tokens to return. Values less than the default value of 10000 are automatically increased to 10000.
+  - `tokens` (optional, default 5000): Max number of tokens to return. Values less than 1000 are automatically increased to 1000.
 
 ## 🛟 Tips
 
 ### Add a Rule
 
-> If you don’t want to add `use context7` to every prompt, you can define a simple rule in your `.windsurfrules` file in Windsurf or from `Cursor Settings > Rules` section in Cursor (or the equivalent in your MCP client) to auto-invoke Context7 on any code question:
->
-> ```toml
-> [[calls]]
-> match = "when the user requests code examples, setup or configuration steps, or library/API documentation"
-> tool  = "context7"
-> ```
->
-> From then on you’ll get Context7’s docs in any related conversation without typing anything extra. You can add your use cases to the match part.
+If you don’t want to add `use context7` to every prompt, you can define a simple rule in your MCP client's rule section:
+
+- For Windsurf, in `.windsurfrules` file
+- For Cursor, from `Cursor Settings > Rules` section
+- For Claude Code, in `CLAUDE.md` file
+
+Or the equivalent in your MCP client to auto-invoke Context7 on any code question.
+
+#### Example Rule
+
+```txt
+Always use context7 when I need code generation, setup or configuration steps, or
+library/API documentation. This means you should automatically use the Context7 MCP
+tools to resolve library id and get library docs without me having to explicitly ask.
+```
+
+From then on, you’ll get Context7’s docs in any related conversation without typing anything extra. You can alter the rule to match your use cases.
 
 ### Use Library Id
 
-> If you already know exactly which library you want to use, add its Context7 ID to your prompt. That way, Context7 MCP server can skip the library-matching step and directly continue with retrieving docs.
->
-> ```txt
-> implement basic authentication with supabase. use library /supabase/supabase for api and docs
-> ```
->
-> The slash syntax tells the MCP tool exactly which library to load docs for.
+If you already know exactly which library you want to use, add its Context7 ID to your prompt. That way, Context7 MCP server can skip the library-matching step and directly continue with retrieving docs.
+
+```txt
+Implement basic authentication with Supabase. use library /supabase/supabase for API and docs.
+```
+
+The slash syntax tells the MCP tool exactly which library to load docs for.
 
 ### HTTPS Proxy
 
-For users behind a http proxy, context7 should honor the standard https_proxy/HTTPS_PROXY environment variables.
+If you are behind an HTTP proxy, Context7 uses the standard `https_proxy` / `HTTPS_PROXY` environment variables.
 
 ## 💻 Development
 
@@ -1049,7 +1101,7 @@ bun run dist/index.js
 - `--port <number>` – Port to listen on when using `http` transport (default `3000`).
 - `--api-key <key>` – API key for authentication. You can get your API key by creating an account at [context7.com/dashboard](https://context7.com/dashboard).
 
-Example with http transport and port 8080:
+Example with HTTP transport and port 8080:
 
 ```bash
 bun run dist/index.js --transport http --port 8080
@@ -1069,7 +1121,7 @@ bun run dist/index.js --transport stdio --api-key YOUR_API_KEY
   "mcpServers": {
     "context7": {
       "command": "npx",
-      "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts", "--api-key", "YOUR_API_KEY"]
+      "args": ["tsx", "/path/to/folder/context7/src/index.ts", "--api-key", "YOUR_API_KEY"]
     }
   }
 }

package/dist/index.js

@@ -8,11 +8,16 @@ import { createServer } from "http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { Command } from "commander";
-const DEFAULT_MINIMUM_TOKENS = 10000;
+/** Minimum allowed tokens for documentation retrieval */
+const MINIMUM_TOKENS = 1000;
+/** Default tokens when none specified */
+const DEFAULT_TOKENS = 5000;
+/** Default HTTP server port */
+const DEFAULT_PORT = 3000;
 // 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("--port <number>", "port for HTTP transport", DEFAULT_PORT.toString())
     .option("--api-key <key>", "API key for authentication")
     .allowUnknownOption() // let MCP Inspector / other wrappers pass through extra flags
     .parse(process.argv);
@@ -72,7 +77,7 @@ function getClientIp(req) {
 function createServerInstance(clientIp, apiKey) {
     const server = new McpServer({
         name: "Context7",
-        version: "1.0.16",
+        version: "1.0.18",
     }, {
         instructions: "Use this server to retrieve up-to-date documentation and code examples for any library.",
     });
@@ -130,7 +135,7 @@ Each result includes:
 - Description: Short summary
 - Code Snippets: Number of available code examples
 - Trust Score: Authority indicator
-- Versions: List of versions if available. Use one of those versions if and only if the user explicitly provides a version in their query.
+- Versions: List of versions if available. Use one of those versions if the user provides a version in their query. The format of the version is /org/project/version.
 
 For best results, select libraries based on name match, trust score, snippet coverage, and relevance to your use case.
 
@@ -154,11 +159,11 @@ ${resultsText}`,
                 .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))
+                .transform((val) => (val < MINIMUM_TOKENS ? 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.`),
+                .describe(`Maximum number of tokens of documentation to retrieve (default: ${DEFAULT_TOKENS}). Higher values provide more context but consume more tokens.`),
         },
-    }, async ({ context7CompatibleLibraryID, tokens = DEFAULT_MINIMUM_TOKENS, topic = "" }) => {
+    }, async ({ context7CompatibleLibraryID, tokens = DEFAULT_TOKENS, topic = "" }) => {
         const fetchDocsResponse = await fetchLibraryDocumentation(context7CompatibleLibraryID, {
             tokens,
             topic,
@@ -188,11 +193,11 @@ async function main() {
     const transportType = TRANSPORT_TYPE;
     if (transportType === "http") {
         // Get initial port from environment or use default
-        const initialPort = CLI_PORT ?? 3000;
+        const initialPort = CLI_PORT ?? DEFAULT_PORT;
         // Keep track of which port we end up using
         let actualPort = initialPort;
         const httpServer = createServer(async (req, res) => {
-            const url = new URL(req.url || "", `http://${req.headers.host}`).pathname;
+            const pathname = new URL(req.url || "/", "http://localhost").pathname;
             // Set CORS headers for all responses
             res.setHeader("Access-Control-Allow-Origin", "*");
             res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS,DELETE");
@@ -237,14 +242,18 @@ async function main() {
                 const clientIp = getClientIp(req);
                 // Create new server instance for each request
                 const requestServer = createServerInstance(clientIp, apiKey);
-                if (url === "/mcp") {
+                if (pathname === "/mcp") {
                     const transport = new StreamableHTTPServerTransport({
                         sessionIdGenerator: undefined,
                     });
+                    res.on("close", () => {
+                        transport.close();
+                        requestServer.close();
+                    });
                     await requestServer.connect(transport);
                     await transport.handleRequest(req, res);
                 }
-                else if (url === "/sse" && req.method === "GET") {
+                else if (pathname === "/sse" && req.method === "GET") {
                     // Create new SSE transport for GET request
                     const sseTransport = new SSEServerTransport("/messages", res);
                     // Store the transport by session ID
@@ -252,42 +261,54 @@ async function main() {
                     // Clean up transport when connection closes
                     res.on("close", () => {
                         delete sseTransports[sseTransport.sessionId];
+                        sseTransport.close();
+                        requestServer.close();
                     });
                     await requestServer.connect(sseTransport);
+                    // Send initial message to establish communication
+                    res.write("data: " +
+                        JSON.stringify({
+                            type: "connection_established",
+                            sessionId: sseTransport.sessionId,
+                            timestamp: new Date().toISOString(),
+                        }) +
+                        "\n\n");
                 }
-                else if (url === "/messages" && req.method === "POST") {
+                else if (pathname === "/messages" && req.method === "POST") {
                     // Get session ID from query parameters
-                    const sessionId = new URL(req.url || "", `http://${req.headers.host}`).searchParams.get("sessionId") ??
-                        "";
+                    const sessionId = new URL(req.url || "/", "http://localhost").searchParams.get("sessionId") ?? "";
                     if (!sessionId) {
-                        res.writeHead(400);
-                        res.end("Missing sessionId parameter");
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "Missing sessionId parameter", status: 400 }));
                         return;
                     }
                     // Get existing transport for this session
                     const sseTransport = sseTransports[sessionId];
                     if (!sseTransport) {
-                        res.writeHead(400);
-                        res.end(`No transport found for sessionId: ${sessionId}`);
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            error: `No transport found for sessionId: ${sessionId}`,
+                            status: 400,
+                        }));
                         return;
                     }
                     // Handle the POST message with the existing transport
                     await sseTransport.handlePostMessage(req, res);
                 }
-                else if (url === "/ping") {
-                    res.writeHead(200, { "Content-Type": "text/plain" });
-                    res.end("pong");
+                else if (pathname === "/ping") {
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ status: "ok", message: "pong" }));
                 }
                 else {
-                    res.writeHead(404);
-                    res.end("Not found");
+                    res.writeHead(404, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Not found", status: 404 }));
                 }
             }
             catch (error) {
                 console.error("Error handling request:", error);
                 if (!res.headersSent) {
-                    res.writeHead(500);
-                    res.end("Internal Server Error");
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Internal Server Error", status: 500 }));
                 }
             }
         });

package/package.json

@@ -1 +1 @@
-{"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"}}
+{"name":"@upstash/context7-mcp","version":"1.0.18","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","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.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"}}