@upstash/context7-mcp 1.0.3 → 1.0.5

package/README.md

@@ -1,4 +1,5 @@
 # Context7 MCP - Up-to-date Docs For Any Cursor 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)
 
 ## ❌ Without Context7
 
@@ -26,7 +27,7 @@ How do I invalidate a query in React Query? use context7
 How do I protect a route with NextAuth? use context7
 ```
 
-Context7 fetches up-to-date documentation and working code examples right into your LLM’s context.
+Context7 fetches up-to-date documentation and working code examples right into your LLM's context.
 
 - 1️⃣ Ask your question naturally
 - 2️⃣ Tell the LLM to `use context7`
@@ -41,23 +42,63 @@ No tab-switching, no hallucinated APIs that don't exist, no outdated code genera
 - Node.js >= v18.0.0
 - Cursor, Windsurf, Claude Desktop or another MCP Client
 
+### Installing via Smithery
+
+To install Context7 MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@upstash/context7-mcp):
+
+```bash
+npx -y @smithery/cli install @upstash/context7-mcp --client claude
+```
+
 ### Install in Cursor
 
 Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`
 
-Paste this into your Cursor `~/.cursor/mcp.json` file. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.
+Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.
 
 ```json
 {
   "mcpServers": {
     "context7": {
       "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
+      "args": ["-y", "@upstash/context7-mcp@latest"]
     }
   }
 }
 ```
 
+<details>
+<summary>Alternative: Use Bun</summary>
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "bunx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Alternative: Use Deno</summary>
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "deno",
+      "args": ["run", "--allow-net", "npm:@upstash/context7-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
 ### Install in Windsurf
 
 Add this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) for more info.
@@ -67,7 +108,46 @@ Add this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.
   "mcpServers": {
     "context7": {
       "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}
+```
+
+### Install in VSCode
+
+Add this to your VSCode MCP config file. See [VSCode MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
+
+```json
+{
+  "servers": {
+    "Context7": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}
+```
+
+### Install in Claude Code
+
+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.
+
+```sh
+claude mcp add context7 -- npx -y @upstash/context7-mcp@latest
+```
+
+### Install in Claude Desktop
+
+Add this to your Claude Desktop `claude_desktop_config.json` file. See [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info.
+
+```json
+{
+  "mcpServers": {
+    "Context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
     }
   }
 }
@@ -112,9 +192,28 @@ bun run build
 ### Testing with MCP Inspector
 
 ```bash
-npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp
+npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp@latest
+```
+
+## Troubleshooting
+
+### ERR_MODULE_NOT_FOUND
+
+If you see this error, try using `bunx` instead of `npx`.
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "bunx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}
 ```
 
+This often resolves module resolution issues, especially in environments where `npx` does not properly install or resolve packages.
+
 ## License
 
 MIT

package/dist/index.js

@@ -2,13 +2,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { fetchProjects, fetchLibraryDocumentation } from "./lib/api.js";
-import { formatProjectsList, rerankProjects } from "./lib/utils.js";
+import { searchLibraries, fetchLibraryDocumentation } from "./lib/api.js";
+import { formatSearchResults } from "./lib/utils.js";
+const DEFAULT_MINIMUM_TOKENS = 5000;
 // Create server instance
 const server = new McpServer({
     name: "Context7",
     description: "Retrieves up-to-date documentation and code examples for any library.",
-    version: "1.0.0",
+    version: "1.0.4",
     capabilities: {
         resources: {},
         tools: {},
@@ -18,11 +19,10 @@ const server = new McpServer({
 server.tool("resolve-library-id", "Required first step: Resolves a general package name into a Context7-compatible library ID. Must be called before using 'get-library-docs' to retrieve a valid Context7-compatible library ID.", {
     libraryName: z
         .string()
-        .optional()
-        .describe("Optional library name to search for and rerank results based on."),
+        .describe("Library name to search for and retrieve a Context7-compatible library ID."),
 }, async ({ libraryName }) => {
-    const projects = await fetchProjects();
-    if (!projects) {
+    const searchResponse = await searchLibraries(libraryName);
+    if (!searchResponse || !searchResponse.results) {
         return {
             content: [
                 {
@@ -32,28 +32,22 @@ server.tool("resolve-library-id", "Required first step: Resolves a general packa
             ],
         };
     }
-    // Filter projects to only include those with state "finalized"
-    const finalizedProjects = projects.filter((project) => project.version.state === "finalized");
-    if (finalizedProjects.length === 0) {
+    if (searchResponse.results.length === 0) {
         return {
             content: [
                 {
                     type: "text",
-                    text: "No finalized documentation libraries available",
+                    text: "No documentation libraries available",
                 },
             ],
         };
     }
-    // Rerank projects if a library name is provided
-    const rankedProjects = libraryName
-        ? rerankProjects(finalizedProjects, libraryName)
-        : finalizedProjects;
-    const projectsText = formatProjectsList(rankedProjects);
+    const resultsText = formatSearchResults(searchResponse);
     return {
         content: [
             {
                 type: "text",
-                text: "Available libraries and their Context7-compatible library ID:\n\n" + projectsText,
+                text: "Available libraries and their Context7-compatible library IDs:\n\n" + resultsText,
             },
         ],
     };
@@ -67,12 +61,26 @@ server.tool("get-library-docs", "Fetches up-to-date documentation for a library.
         .optional()
         .describe("Topic to focus documentation on (e.g., 'hooks', 'routing')."),
     tokens: z
-        .number()
-        .min(5000)
+        .preprocess((val) => (typeof val === "string" ? Number(val) : val), z.number())
+        .refine((val) => typeof val === "number" && val >= DEFAULT_MINIMUM_TOKENS, {
+        message: `Must be a number >= ${DEFAULT_MINIMUM_TOKENS}`,
+    })
         .optional()
-        .describe("Maximum number of tokens of documentation to retrieve (default: 5000). Higher values provide more context but consume more tokens."),
-}, async ({ context7CompatibleLibraryID, tokens = 5000, topic = "" }) => {
-    const documentationText = await fetchLibraryDocumentation(context7CompatibleLibraryID, tokens, topic);
+        .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 = "" }) => {
+    // Extract folders parameter if present in the ID
+    let folders = "";
+    let libraryId = context7CompatibleLibraryID;
+    if (context7CompatibleLibraryID.includes("?folders=")) {
+        const [id, foldersParam] = context7CompatibleLibraryID.split("?folders=");
+        libraryId = id;
+        folders = foldersParam;
+    }
+    const documentationText = await fetchLibraryDocumentation(libraryId, {
+        tokens,
+        topic,
+        folders,
+    });
     if (!documentationText) {
         return {
             content: [

package/dist/lib/api.js

@@ -1,51 +1,46 @@
-const CONTEXT7_BASE_URL = "https://context7.com";
+const CONTEXT7_API_BASE_URL = "https://context7.com/api";
+const DEFAULT_TYPE = "txt";
 /**
- * Fetches projects from the Context7 API
- * @returns Array of projects or null if the request fails
+ * Searches for libraries matching the given query
+ * @param query The search query
+ * @returns Search results or null if the request fails
  */
-export async function fetchProjects() {
+export async function searchLibraries(query) {
     try {
-        const response = await fetch(`${CONTEXT7_BASE_URL}/api/libraries`);
+        const url = new URL(`${CONTEXT7_API_BASE_URL}/v1/search`);
+        url.searchParams.set("query", query);
+        const response = await fetch(url);
         if (!response.ok) {
-            console.error(`Failed to fetch projects: ${response.status}`);
+            console.error(`Failed to search libraries: ${response.status}`);
             return null;
         }
         return await response.json();
     }
     catch (error) {
-        console.error("Error fetching projects:", error);
+        console.error("Error searching libraries:", error);
         return null;
     }
 }
 /**
  * Fetches documentation context for a specific library
- * @param libraryName The library name to fetch documentation for
- * @param tokens Number of tokens to retrieve (default: 5000)
- * @param topic Optional topic to rerank context for
+ * @param libraryId The library ID to fetch documentation for
+ * @param options Options for the request
  * @returns The documentation text or null if the request fails
  */
-export async function fetchLibraryDocumentation(libraryName, tokens = 5000, topic = "") {
+export async function fetchLibraryDocumentation(libraryId, options = {}) {
     try {
-        // if libraryName has a "/" as the first character, remove it
-        if (libraryName.startsWith("/")) {
-            libraryName = libraryName.slice(1);
+        if (libraryId.startsWith("/")) {
+            libraryId = libraryId.slice(1);
         }
-        // Handle folders parameter
-        let basePath = libraryName;
-        let folders = "";
-        if (libraryName.includes("?folders=")) {
-            const [path, foldersParam] = libraryName.split("?folders=");
-            basePath = path;
-            folders = foldersParam;
-        }
-        const contextURL = new URL(`${CONTEXT7_BASE_URL}/${basePath}/llms.txt`);
-        if (folders)
-            contextURL.searchParams.set("folders", folders);
-        if (tokens)
-            contextURL.searchParams.set("tokens", tokens.toString());
-        if (topic)
-            contextURL.searchParams.set("topic", topic);
-        const response = await fetch(contextURL, {
+        const url = new URL(`${CONTEXT7_API_BASE_URL}/v1/${libraryId}`);
+        if (options.tokens)
+            url.searchParams.set("tokens", options.tokens.toString());
+        if (options.topic)
+            url.searchParams.set("topic", options.topic);
+        if (options.folders)
+            url.searchParams.set("folders", options.folders);
+        url.searchParams.set("type", DEFAULT_TYPE);
+        const response = await fetch(url, {
             headers: {
                 "X-Context7-Source": "mcp-server",
             },

package/dist/lib/utils.js

@@ -1,127 +1,20 @@
 /**
- * Format a project into a string representation
- * @param project Project to format
- * @returns Formatted project string
+ * Format a search result into a string representation
+ * @param result SearchResult to format
+ * @returns Formatted search result string
  */
-export function formatProject(project) {
-    return `Title: ${project.settings.title}\nContext7-compatible library ID: ${project.settings.project}\n`;
+export function formatSearchResult(result) {
+    return `Title: ${result.title}\n\nContext7-compatible library ID: ${result.id}\n\nDescription: ${result.description}`;
 }
 /**
- * Format a list of projects into a string representation
- * @param projects Projects to format
- * @returns Formatted projects string
+ * Format search results into a string representation
+ * @param searchResponse The search response to format
+ * @returns Formatted search results string
  */
-export function formatProjectsList(projects) {
-    const formattedProjects = projects.map(formatProject);
-    return (formattedProjects.length +
-        " available documentation libraries:\n\n" +
-        formattedProjects.join("\n"));
-}
-/**
- * Rerank projects based on a search term
- * @param projects Projects to rerank
- * @param searchTerm Search term to rerank by
- * @returns Reranked projects
- */
-export function rerankProjects(projects, searchTerm) {
-    if (!searchTerm)
-        return projects;
-    // Normalize the search term - remove special characters and convert to lowercase
-    const normalizedSearchTerm = searchTerm.toLowerCase().replace(/[^\w\s]/g, "");
-    return [...projects].sort((a, b) => {
-        const aTitle = a.settings.title.toLowerCase();
-        const aProject = a.settings.project.toLowerCase();
-        const aProjectName = aProject.split("/").pop() || "";
-        const aProjectPath = aProject.split("/").slice(0, -1).join("/");
-        const bTitle = b.settings.title.toLowerCase();
-        const bProject = b.settings.project.toLowerCase();
-        const bProjectName = bProject.split("/").pop() || "";
-        const bProjectPath = bProject.split("/").slice(0, -1).join("/");
-        // Normalize project names for better matching - remove special characters
-        const normalizedATitle = aTitle.replace(/[^\w\s]/g, "");
-        const normalizedAProject = aProject.replace(/[^\w\s]/g, "");
-        const normalizedAProjectName = aProjectName.replace(/[^\w\s]/g, "");
-        const normalizedBTitle = bTitle.replace(/[^\w\s]/g, "");
-        const normalizedBProject = bProject.replace(/[^\w\s]/g, "");
-        const normalizedBProjectName = bProjectName.replace(/[^\w\s]/g, "");
-        // Calculate match scores for better ranking
-        const aScore = calculateMatchScore(normalizedSearchTerm, {
-            original: {
-                title: aTitle,
-                project: aProject,
-                projectName: aProjectName,
-                projectPath: aProjectPath,
-            },
-            normalized: {
-                title: normalizedATitle,
-                project: normalizedAProject,
-                projectName: normalizedAProjectName,
-            },
-        });
-        const bScore = calculateMatchScore(normalizedSearchTerm, {
-            original: {
-                title: bTitle,
-                project: bProject,
-                projectName: bProjectName,
-                projectPath: bProjectPath,
-            },
-            normalized: {
-                title: normalizedBTitle,
-                project: normalizedBProject,
-                projectName: normalizedBProjectName,
-            },
-        });
-        // Higher score first
-        if (aScore !== bScore) {
-            return bScore - aScore;
-        }
-        // Default to alphabetical by project name
-        return aProject.localeCompare(bProject);
-    });
-}
-/**
- * Calculate a match score for ranking
- * Higher score means better match
- */
-function calculateMatchScore(searchTerm, projectData) {
-    const { original, normalized } = projectData;
-    let score = 0;
-    // Exact matches (highest priority)
-    if (original.project === searchTerm ||
-        original.title === searchTerm ||
-        original.projectName === searchTerm) {
-        score += 100;
-    }
-    // Normalized exact matches
-    if (normalized.project === searchTerm ||
-        normalized.title === searchTerm ||
-        normalized.projectName === searchTerm) {
-        score += 90;
-    }
-    // Starts with matches
-    if (original.project.startsWith(searchTerm) ||
-        original.title.startsWith(searchTerm) ||
-        original.projectName.startsWith(searchTerm)) {
-        score += 80;
-    }
-    // Normalized starts with matches
-    if (normalized.project.startsWith(searchTerm) ||
-        normalized.title.startsWith(searchTerm) ||
-        normalized.projectName.startsWith(searchTerm)) {
-        score += 70;
-    }
-    // Contains matches
-    if (original.project.includes(searchTerm) ||
-        original.title.includes(searchTerm) ||
-        original.projectName.includes(searchTerm) ||
-        original.projectPath.includes(searchTerm)) {
-        score += 60;
-    }
-    // Normalized contains matches
-    if (normalized.project.includes(searchTerm) ||
-        normalized.title.includes(searchTerm) ||
-        normalized.projectName.includes(searchTerm)) {
-        score += 50;
+export function formatSearchResults(searchResponse) {
+    if (!searchResponse.results || searchResponse.results.length === 0) {
+        return "No documentation libraries found matching your query.";
     }
-    return score;
+    const formattedResults = searchResponse.results.map(formatSearchResult);
+    return formattedResults.join("\n\n--------------------\n");
 }

package/package.json

@@ -1,44 +1 @@
-{
-  "name": "@upstash/context7-mcp",
-  "version": "1.0.3",
-  "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"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/upstash/context7-mcp.git"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "context7-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "bugs": {
-    "url": "https://github.com/upstash/context7-mcp/issues"
-  },
-  "homepage": "https://github.com/upstash/context7-mcp#readme",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.8.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":"v1.0.5","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"},"repository":{"type":"git","url":"git+https://github.com/upstash/context7-mcp.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-mcp/issues"},"homepage":"https://github.com/upstash/context7-mcp#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.8.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"}}