@upstash/context7-mcp 1.0.33 → 1.0.34-canary.0

package/dist/benchmark/simulate.js

@@ -0,0 +1,319 @@
+import "dotenv/config";
+import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";
+import { generateText, stepCountIs } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+// Check for required environment variables
+if (!process.env.CONTEXT7_API_KEY) {
+    console.error("Error: CONTEXT7_API_KEY environment variable is required");
+    console.error("Set it in your .env file or export it in your shell");
+    process.exit(1);
+}
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Package root is two levels up from dist/benchmark/
+const packageRoot = join(__dirname, "..", "..");
+/**
+ * Creates a logging function bound to a specific simulation state
+ */
+function createLogger(state) {
+    return (message) => {
+        console.log(message);
+        state.consoleLog += message + "\n";
+    };
+}
+/**
+ * Simulates an LLM-powered conversation using Context7 MCP server
+ *
+ * Usage:
+ * - CLI: pnpm run simulate "your question here"
+ * - Programmatic: import { simulate } from './simulate.js'; await simulate("your question");
+ */
+export async function simulate(question, uniqueId) {
+    // Create local state for this simulation (prevents race conditions)
+    const state = {
+        consoleLog: "",
+        toolCallsMap: new Map(),
+        totalTokens: 0,
+    };
+    // Create logger bound to this simulation's state
+    const log = createLogger(state);
+    // If no question provided, try to get from command line args
+    if (!question) {
+        question = process.argv[2];
+    }
+    if (!question) {
+        console.error("Error: Please provide a question as an argument");
+        console.error('Usage: pnpm run simulate "your question here"');
+        process.exit(1);
+    }
+    // Store original question for display
+    const originalQuestion = question;
+    // Append Context7 instruction to the question
+    question = `${question}. Use Context7 to fetch docs.`;
+    const startTime = new Date();
+    log("=".repeat(80));
+    log("Context7 MCP Simulation");
+    log("=".repeat(80));
+    log(`Question: ${originalQuestion}`);
+    log(`Timestamp: ${startTime.toISOString()}`);
+    log("");
+    let mcpClient = null;
+    try {
+        // Get API key from environment
+        const apiKey = process.env.CONTEXT7_API_KEY;
+        if (!apiKey) {
+            throw new Error("CONTEXT7_API_KEY environment variable is required");
+        }
+        // Initialize MCP client using AI SDK's experimental_createMCPClient
+        log("─".repeat(80));
+        log("Initializing MCP Connection");
+        log("─".repeat(80));
+        const mcpServerPath = join(packageRoot, "dist", "index.js");
+        mcpClient = await createMCPClient({
+            transport: new StdioClientTransport({
+                command: "node",
+                args: [mcpServerPath, "--api-key", apiKey],
+                env: {
+                    ...process.env,
+                    CONTEXT7_API_KEY: apiKey,
+                },
+            }),
+        });
+        log("✅ Connected to Context7 MCP server");
+        log("");
+        // Get AI SDK-compatible tools
+        const tools = await mcpClient.tools();
+        const toolNames = Object.keys(tools);
+        log(`📦 Available tools: ${toolNames.join(", ")}`);
+        log("");
+        // Use AI model to interact with tools
+        log("─".repeat(80));
+        log("🤖 AI Processing");
+        log("─".repeat(80));
+        log("Model: Claude Haiku 4.5");
+        log("");
+        const model = anthropic("claude-haiku-4-5");
+        const result = await generateText({
+            model,
+            tools,
+            stopWhen: stepCountIs(15),
+            messages: [
+                {
+                    role: "user",
+                    content: question,
+                },
+            ],
+            onStepFinish: (step) => {
+                if (step.toolCalls) {
+                    step.toolCalls.forEach((tc) => {
+                        const input = tc.input || tc.args || {};
+                        log("─".repeat(80));
+                        log(`🔧 Tool Call: ${tc.toolName}`);
+                        log("─".repeat(80));
+                        log(`Arguments:`);
+                        log("```json");
+                        log(JSON.stringify(input, null, 2));
+                        log("```");
+                        log("");
+                        // Store for structured report using toolCallId as key
+                        state.toolCallsMap.set(tc.toolCallId, {
+                            tool: tc.toolName,
+                            args: input,
+                            response: null,
+                        });
+                    });
+                }
+                if (step.toolResults) {
+                    step.toolResults.forEach((tr) => {
+                        const resultText = JSON.stringify(tr, null, 2);
+                        log(`Result:`);
+                        log("```json");
+                        if (resultText.length > 2000) {
+                            log(resultText.substring(0, 2000));
+                            log(`... (truncated ${resultText.length - 2000} characters)`);
+                        }
+                        else {
+                            log(resultText);
+                        }
+                        log("```");
+                        log("");
+                        // Store response for structured report by matching toolCallId
+                        const toolCall = state.toolCallsMap.get(tr.toolCallId);
+                        if (toolCall) {
+                            const output = tr.output || tr;
+                            toolCall.response = output;
+                            // Extract usage data from MCP response structure
+                            try {
+                                // Check if output has MCP format: {content: [{type: "text", text: "..."}]}
+                                if (output && output.content && Array.isArray(output.content)) {
+                                    output.content.forEach((item) => {
+                                        if (item.type === "text" && item.text) {
+                                            try {
+                                                const parsed = JSON.parse(item.text);
+                                                // Check for new API format: {data: "...", usage: {...}}
+                                                if (parsed.usage && parsed.usage.totalTokens) {
+                                                    toolCall.usage = parsed.usage;
+                                                    state.totalTokens += parsed.usage.totalTokens;
+                                                    log(`Token usage: ${parsed.usage.totalTokens} total (input: ${parsed.usage.inputTokens}, output: ${parsed.usage.outputTokens})`);
+                                                    log("");
+                                                }
+                                            }
+                                            catch {
+                                                // Not JSON or doesn't have usage data
+                                            }
+                                        }
+                                    });
+                                }
+                            }
+                            catch {
+                                // If parsing fails, it's not JSON or doesn't have usage data, which is fine
+                            }
+                        }
+                    });
+                }
+            },
+        });
+        log("─".repeat(80));
+        log("✅ AI Final Response");
+        log("─".repeat(80));
+        log(result.text);
+        log("");
+        const endTime = new Date();
+        const duration = endTime.getTime() - startTime.getTime();
+        // Summary
+        log("=".repeat(80));
+        log("Summary");
+        log("=".repeat(80));
+        log(`✅ Simulation completed in ${(duration / 1000).toFixed(2)}s`);
+        log(`⏱️  Start: ${startTime.toISOString()}`);
+        log(`⏱️  End: ${endTime.toISOString()}`);
+        if (state.totalTokens > 0) {
+            log(`🪙 Total Tokens: ${state.totalTokens}`);
+        }
+        log("=".repeat(80));
+        // Create reports directory under benchmark folder
+        const reportsDir = join(packageRoot, "src", "benchmark", "reports");
+        mkdirSync(reportsDir, { recursive: true });
+        // Generate filenames with timestamp and optional unique identifier
+        const baseFilename = uniqueId
+            ? `${startTime.toISOString().replace(/[:.]/g, "-").split("Z")[0]}_${uniqueId}`
+            : startTime.toISOString().replace(/[:.]/g, "-").split("Z")[0];
+        const reportPath = join(reportsDir, `${baseFilename}.md`);
+        const rawReportPath = join(reportsDir, `${baseFilename}_raw.md`);
+        // Convert Map to array for report generation (preserves insertion order)
+        const structuredToolCalls = Array.from(state.toolCallsMap.values());
+        // Generate structured markdown report
+        let structuredReport = `# Context7 MCP Simulation Report\n\n`;
+        structuredReport += `**Date**: ${startTime.toISOString()}\n`;
+        structuredReport += `**Duration**: ${(duration / 1000).toFixed(2)}s\n`;
+        if (state.totalTokens > 0) {
+            structuredReport += `**Total Tokens**: ${state.totalTokens}\n`;
+        }
+        structuredReport += `\n## Question\n\n${originalQuestion}\n\n`;
+        // Add tool calls and responses
+        if (structuredToolCalls.length > 0) {
+            structuredReport += `## Tool Calls\n\n`;
+            structuredToolCalls.forEach((call, idx) => {
+                structuredReport += `### Tool Call ${idx + 1}: ${call.tool}\n\n`;
+                structuredReport += `**Parameters:**\n\`\`\`json\n${JSON.stringify(call.args, null, 2)}\n\`\`\`\n\n`;
+                if (call.usage) {
+                    structuredReport += `**Token Usage:**\n`;
+                    structuredReport += `- Input: ${call.usage.inputTokens}\n`;
+                    structuredReport += `- Output: ${call.usage.outputTokens}\n`;
+                    structuredReport += `- Total: ${call.usage.totalTokens}\n\n`;
+                }
+                structuredReport += `**Response:**\n\`\`\`json\n`;
+                const responseText = JSON.stringify(call.response, null, 2);
+                if (responseText.length > 3000) {
+                    structuredReport +=
+                        responseText.substring(0, 3000) +
+                            `...\n(truncated ${responseText.length - 3000} characters)\n`;
+                }
+                else {
+                    structuredReport += responseText + "\n";
+                }
+                structuredReport += `\`\`\`\n\n`;
+            });
+        }
+        // Add final AI response
+        structuredReport += `## AI Final Response\n\n${result.text}\n\n`;
+        // Add console log section
+        structuredReport += `---\n\n## Console Log\n\n\`\`\`\n${state.consoleLog}\n\`\`\`\n`;
+        // Save structured markdown report
+        writeFileSync(reportPath, structuredReport);
+        // Generate raw markdown report (just question and raw text responses)
+        let rawReport = `QUESTION: ${originalQuestion}\n\n`;
+        rawReport += `${"─".repeat(80)}\n\n`;
+        rawReport += `CONTEXT:\n\n`;
+        // Add raw tool responses (extract text content only, skip resolve-library-id)
+        structuredToolCalls.forEach((call) => {
+            // Skip resolve-library-id tool responses
+            if (call.tool === "resolve-library-id") {
+                return;
+            }
+            if (call.response && call.response.content) {
+                const content = call.response.content;
+                // Extract text from MCP response format: {content: [{type: "text", text: "..."}]}
+                if (Array.isArray(content)) {
+                    content.forEach((item) => {
+                        if (item.type === "text" && item.text) {
+                            // Try to parse the text as JSON (new API format with {data, usage})
+                            try {
+                                const parsed = JSON.parse(item.text);
+                                // New API format: {data: "text", usage: {...}}
+                                if (parsed.data && typeof parsed.data === "string") {
+                                    rawReport += parsed.data + "\n\n";
+                                    return;
+                                }
+                            }
+                            catch {
+                                // Not JSON, treat as plain text (legacy format)
+                                rawReport += item.text + "\n\n";
+                            }
+                        }
+                    });
+                }
+                else if (typeof content === "string") {
+                    // Try to parse string content as JSON
+                    try {
+                        const parsed = JSON.parse(content);
+                        if (parsed.data && typeof parsed.data === "string") {
+                            rawReport += parsed.data + "\n\n";
+                            return;
+                        }
+                    }
+                    catch {
+                        // Not JSON, treat as plain text
+                        rawReport += content + "\n\n";
+                    }
+                }
+            }
+        });
+        // Save raw markdown report
+        writeFileSync(rawReportPath, rawReport);
+        log("");
+        log(`📝 Structured report saved to: ${reportPath}`);
+        log(`📝 Raw report saved to: ${rawReportPath}`);
+    }
+    catch (error) {
+        const errorMsg = `❌ Simulation failed: ${error}`;
+        log(errorMsg);
+        process.exit(1);
+    }
+    finally {
+        if (mcpClient) {
+            await mcpClient.close();
+        }
+    }
+}
+// Run simulation if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    simulate().catch((error) => {
+        console.error("Fatal error:", error);
+        process.exit(1);
+    });
+}

package/dist/index.js

@@ -2,15 +2,11 @@
 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 { formatSearchResults } from "./lib/utils.js";
-import { DOCUMENTATION_MODES } from "./lib/types.js";
+import { fetchLibraryContext } from "./lib/api.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
@@ -48,148 +44,62 @@ const CLI_PORT = (() => {
 const requestContext = new AsyncLocalStorage();
 // Store API key globally for stdio mode (where requestContext may not be available in tool handlers)
 let globalApiKey;
+const stripIpv6Prefix = (ip) => ip.replace(/^::ffff:/, "");
+const isPrivateIp = (ip) => ip.startsWith("10.") || ip.startsWith("192.168.") || /^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(ip);
 function getClientIp(req) {
-    const forwardedFor = req.headers["x-forwarded-for"] || req.headers["X-Forwarded-For"];
+    const forwardedFor = req.headers["x-forwarded-for"];
     if (forwardedFor) {
         const ips = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor;
-        const ipList = ips.split(",").map((ip) => ip.trim());
-        for (const ip of ipList) {
-            const plainIp = ip.replace(/^::ffff:/, "");
-            if (!plainIp.startsWith("10.") &&
-                !plainIp.startsWith("192.168.") &&
-                !/^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(plainIp)) {
-                return plainIp;
-            }
-        }
-        return ipList[0].replace(/^::ffff:/, "");
-    }
-    if (req.socket?.remoteAddress) {
-        return req.socket.remoteAddress.replace(/^::ffff:/, "");
+        const ipList = ips.split(",").map((ip) => stripIpv6Prefix(ip.trim()));
+        return ipList.find((ip) => !isPrivateIp(ip)) ?? ipList[0];
     }
-    return undefined;
+    return req.socket?.remoteAddress ? stripIpv6Prefix(req.socket.remoteAddress) : undefined;
 }
 const server = new McpServer({
     name: "Context7",
-    version: "1.0.13",
+    version: "2.0.0",
 }, {
+    capabilities: {
+        tools: { listChanged: true },
+    },
     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.
-
-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.
+server.registerTool("get-docs", {
+    title: "Get Library Documentation",
+    description: `Retrieves up-to-date documentation and code examples from Context7 for any programming library or framework.
 
-Selection Process:
-1. Analyze the query to understand what library/package the user is looking for
-2. Return the most relevant match based on:
-- Name similarity to the query (exact matches prioritized)
-- Description relevance to the query's intent
-- Documentation coverage (prioritize libraries with higher Code Snippet counts)
-- Source reputation (consider libraries with High or Medium reputation more authoritative)
-- Benchmark Score: Quality indicator (100 is the highest score)
-
-Response Format:
-- Return the selected library ID in a clearly marked section
-- Provide a brief explanation for why this library was chosen
-- 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.`,
+USE THIS TOOL TO:
+- Get current, accurate documentation for libraries (e.g., React, Next.js, Express, LangChain)
+- Find working code examples and implementation patterns
+- Answer "how do I..." questions about specific libraries
+- Look up API references, configuration options, and best practices`,
     inputSchema: {
-        libraryName: z
+        query: z
             .string()
-            .describe("Library name to search for and retrieve a Context7-compatible library ID."),
-    },
-}, async ({ libraryName }) => {
-    const ctx = requestContext.getStore();
-    const apiKey = ctx?.apiKey || globalApiKey;
-    const searchResponse = await searchLibraries(libraryName, ctx?.clientIp, apiKey);
-    if (!searchResponse.results || searchResponse.results.length === 0) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: searchResponse.error
-                        ? searchResponse.error
-                        : "Failed to retrieve library documentation data from Context7",
-                },
-            ],
-        };
-    }
-    const resultsText = formatSearchResults(searchResponse);
-    const responseText = `Available Libraries:
-
-Each result includes:
-- Library ID: Context7-compatible identifier (format: /org/project)
-- Name: Library or package name
-- Description: Short summary
-- Code Snippets: Number of available code examples
-- Source Reputation: Authority indicator (High, Medium, Low, or Unknown)
-- Benchmark Score: Quality indicator (100 is the highest score)
-- 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, source reputation, snippet coverage, benchmark score, and relevance to your use case.
-
-----------
-
-${resultsText}`;
-    return {
-        content: [
-            {
-                type: "text",
-                text: responseText,
-            },
-        ],
-    };
-});
-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.",
-    inputSchema: {
-        context7CompatibleLibraryID: z
+            .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."),
+        library: 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."),
+            .describe("Library or framework name (e.g., 'react', 'express') OR exact library ID if provided by the user with or without version (e.g., '/vercel/next.js', '/vercel/next.js@v14.3.0-canary.87'). If omitted, auto-selects based on query."),
         topic: z
             .string()
             .optional()
-            .describe("Topic to focus documentation on (e.g., 'hooks', 'routing')."),
-        page: z
-            .number()
-            .int()
-            .min(1)
-            .max(10)
+            .describe("Narrow down results to a specific topic within the library. Examples: 'hooks', 'routing', 'middleware', 'authentication', 'state management'."),
+        mode: z
+            .enum(["code", "info"])
             .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."),
+            .default("code")
+            .describe("Type of content to prioritize. Use 'code' (default) when you need working code examples, API usage patterns, and implementation snippets. Use 'info' when you need conceptual narrative explanations, architectural overviews, or understanding how something works."),
     },
-}, async ({ context7CompatibleLibraryID, mode = DOCUMENTATION_MODES.CODE, page = 1, topic }) => {
+}, async ({ query, library, topic, mode = "code" }) => {
     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, library, topic, mode }, ctx?.clientIp, apiKey);
     return {
         content: [
             {
                 type: "text",
-                text: fetchDocsResponse,
+                text: response.data,
             },
         ],
     };
@@ -198,7 +108,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) => {
@@ -228,14 +137,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"]));
+                extractHeaderValue(req.headers["x-api-key"]));
         };
         app.all("/mcp", async (req, res) => {
             try {
@@ -287,8 +190,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);