@upstash/context7-mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Upstash, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# Context7 MCP Server
+
+In this repository, we provide an MCP Server for [Context7](https://context7.com), which offers access to high-quality documentation for popular libraries.
+
+This lets you use Cursor, Windsurf, Claude Desktop, or any MCP Client, to use natural language to search and access documentation for libraries, e.g.:
+
+- "What are the main features of React hooks?"
+- "How do I implement authentication with Next.js?"
+- "Rate limiting with Redis"
+- "Get examples of using React Query"
+
+## Usage
+
+### Requirements
+
+- Node.js >= v18.0.0
+- Cursor, Windsurf, Claude Desktop or another MCP Client
+
+### How to use locally
+
+#### Installing for Cursor
+
+Add this command to the MCP list in Cursor. For more info, check the [Cursor MCP](https://docs.cursor.com/context/model-context-protocol) docs.
+
+```bash
+npx -y @upstash/context7-mcp
+```
+
+#### Installing for Windsurf
+
+Add this to your Windsurf MCP config file. For more info, check the [Windsurf MCP](https://docs.windsurf.com/windsurf/mcp) docs.
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    }
+  }
+}
+```
+
+### Tools
+
+- `list-available-docs`: Lists all available documentation libraries from Context7
+- `get-library-documentation`: Retrieves documentation for a specific library with options for:
+  - `libraryName`: Name of the library to retrieve docs for
+  - `topic`: Specific topic within the library
+  - `tokens`: Maximum tokens to retrieve (default: 5000)
+
+## Development
+
+Clone the project and run:
+
+```bash
+npm install
+```
+
+You can use the following commands to format and lint the code:
+
+```bash
+npm run format
+npm run lint
+```
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing with MCP Inspector
+
+You can also use the MCP Inspector to test the tools by following the MCP documentation for setting up the inspector.
+
+```bash
+npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp
+```
+
+## License
+
+MIT

package/build/index.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+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";
+// Create server instance
+const server = new McpServer({
+    name: "Context7",
+    description: "Retrieves documentation and code examples for software libraries.",
+    version: "1.0.0",
+    capabilities: {
+        resources: {},
+        tools: {},
+    },
+});
+// Register Context7 tools
+server.tool("list-available-docs", "Lists all available library documentation from Context7. The library names can be used with 'get-library-documentation' to retrieve documentation.", {
+    libraryName: z
+        .string()
+        .optional()
+        .describe("Optional library name to search for and rerank results based on"),
+}, async ({ libraryName }) => {
+    const projects = await fetchProjects();
+    if (!projects) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Failed to retrieve library documentation data from Context7",
+                },
+            ],
+        };
+    }
+    // Filter projects to only include those with state "finalized"
+    const finalizedProjects = projects.filter((project) => project.version.state === "finalized");
+    if (finalizedProjects.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No finalized documentation libraries available",
+                },
+            ],
+        };
+    }
+    // Rerank projects if a library name is provided
+    const rankedProjects = libraryName
+        ? rerankProjects(finalizedProjects, libraryName)
+        : finalizedProjects;
+    const projectsText = formatProjectsList(rankedProjects);
+    return {
+        content: [
+            {
+                type: "text",
+                text: projectsText,
+            },
+        ],
+    };
+});
+server.tool("get-library-documentation", "Retrieves documentation for a specific library from Context7. Use 'list-available-docs' first to see what's available.", {
+    libraryName: z
+        .string()
+        .describe("Name of the library to retrieve documentation for (e.g., 'upstash-redis', 'nextjs'). Must match exactly a library name from 'list-available-docs'."),
+    topic: z
+        .string()
+        .optional()
+        .describe("Specific topic within the library to focus the documentation on (e.g., 'hooks', 'routing')."),
+    tokens: z
+        .number()
+        .min(5000)
+        .optional()
+        .describe("Maximum number of tokens of documentation to retrieve (default: 5000).Higher values provide more comprehensive documentation but use more context window."),
+}, async ({ libraryName, tokens = 5000, topic = "" }) => {
+    const documentationText = await fetchLibraryDocumentation(libraryName, tokens, topic);
+    if (!documentationText) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Documentation not found or not finalized for this library. Verify you've provided a valid library name exactly as listed by the 'list-available-docs' tool.",
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: documentationText,
+            },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Context7 Documentation MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/build/lib/api.js

@@ -0,0 +1,55 @@
+const CONTEXT7_BASE_URL = "https://context7.com";
+/**
+ * Fetches projects from the Context7 API
+ * @returns Array of projects or null if the request fails
+ */
+export async function fetchProjects() {
+    try {
+        const response = await fetch(`${CONTEXT7_BASE_URL}/api/projects`);
+        if (!response.ok) {
+            console.error(`Failed to fetch projects: ${response.status}`);
+            return null;
+        }
+        return await response.json();
+    }
+    catch (error) {
+        console.error("Error fetching projects:", 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
+ * @returns The documentation text or null if the request fails
+ */
+export async function fetchLibraryDocumentation(libraryName, tokens = 5000, topic = "") {
+    try {
+        let contextURL = `${CONTEXT7_BASE_URL}/${libraryName}/llms.txt`;
+        const params = [];
+        if (tokens) {
+            params.push(`tokens=${tokens}`);
+        }
+        if (topic) {
+            params.push(`topic=${encodeURIComponent(topic)}`);
+        }
+        if (params.length > 0) {
+            contextURL += `?${params.join("&")}`;
+        }
+        const response = await fetch(contextURL);
+        if (!response.ok) {
+            console.error(`Failed to fetch documentation: ${response.status}`);
+            return null;
+        }
+        const text = await response.text();
+        if (!text || text === "No content available" || text === "No context data available") {
+            return null;
+        }
+        return text;
+    }
+    catch (error) {
+        console.error("Error fetching library documentation:", error);
+        return null;
+    }
+}

package/build/lib/types.js

@@ -0,0 +1 @@
+export {};

package/build/lib/utils.js

@@ -0,0 +1,127 @@
+/**
+ * Format a project into a string representation
+ * @param project Project to format
+ * @returns Formatted project string
+ */
+export function formatProject(project) {
+    return `Title: ${project.settings.title}\nLibrary name: ${project.settings.project}\n`;
+}
+/**
+ * Format a list of projects into a string representation
+ * @param projects Projects to format
+ * @returns Formatted projects 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;
+    }
+    return score;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@upstash/context7-mcp",
+  "version": "0.0.1",
+  "description": "MCP server for Context7",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc && chmod 755 build/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": "./build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "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"
+  }
+}