@upstash/context7-mcp
Version:
MCP server for Context7
283 lines (271 loc) • 13 kB
JavaScript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { searchLibraries, fetchLibraryContext } from "./lib/api.js";
import { formatSearchResults } from "./lib/utils.js";
import express from "express";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { Command } from "commander";
import { AsyncLocalStorage } from "async_hooks";
/** 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", DEFAULT_PORT.toString())
.option("--api-key <key>", "API key for authentication (or set CONTEXT7_API_KEY env var)")
.allowUnknownOption() // let MCP Inspector / other wrappers pass through extra flags
.parse(process.argv);
const cliOptions = program.opts();
// Validate transport option
const allowedTransports = ["stdio", "http"];
if (!allowedTransports.includes(cliOptions.transport)) {
console.error(`Invalid --transport value: '${cliOptions.transport}'. Must be one of: stdio, http.`);
process.exit(1);
}
// Transport configuration
const TRANSPORT_TYPE = (cliOptions.transport || "stdio");
// Disallow incompatible flags based on transport
const passedPortFlag = process.argv.includes("--port");
const passedApiKeyFlag = process.argv.includes("--api-key");
if (TRANSPORT_TYPE === "http" && passedApiKeyFlag) {
console.error("The --api-key flag is not allowed when using --transport http. Use header-based auth at the HTTP layer instead.");
process.exit(1);
}
if (TRANSPORT_TYPE === "stdio" && passedPortFlag) {
console.error("The --port flag is not allowed when using --transport stdio.");
process.exit(1);
}
// HTTP port configuration
const CLI_PORT = (() => {
const parsed = parseInt(cliOptions.port, 10);
return isNaN(parsed) ? undefined : parsed;
})();
const requestContext = new AsyncLocalStorage();
// Store API key globally for stdio mode (where requestContext may not be available in tool handlers)
let globalApiKey;
function getClientIp(req) {
const forwardedFor = req.headers["x-forwarded-for"] || 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:/, "");
}
return undefined;
}
const server = new McpServer({
name: "Context7",
version: "2.0.0",
}, {
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 matching libraries.
You MUST call this function before 'query-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.
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.
IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.`,
inputSchema: {
query: z
.string()
.describe("The user's original question or task. This is used to rank library results by relevance to what the user is trying to accomplish. IMPORTANT: Do not include any sensitive or confidential information such as API keys, passwords, credentials, or personal data in your query."),
libraryName: z
.string()
.describe("Library name to search for and retrieve a Context7-compatible library ID."),
},
}, async ({ query, libraryName }) => {
const ctx = requestContext.getStore();
const apiKey = ctx?.apiKey || globalApiKey;
const searchResponse = await searchLibraries(query, libraryName, ctx?.clientIp, apiKey);
if (!searchResponse.results || searchResponse.results.length === 0) {
return {
content: [
{
type: "text",
text: searchResponse.error
? searchResponse.error
: "No libraries found matching the provided name.",
},
],
};
}
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("query-docs", {
title: "Query Documentation",
description: `Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework.
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.
IMPORTANT: Do not call this tool more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.`,
inputSchema: {
libraryId: 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'."),
query: z
.string()
.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."),
},
}, async ({ query, libraryId }) => {
const ctx = requestContext.getStore();
const apiKey = ctx?.apiKey || globalApiKey;
const response = await fetchLibraryContext({ query, libraryId }, ctx?.clientIp, apiKey);
return {
content: [
{
type: "text",
text: response.data,
},
],
};
});
async function main() {
const transportType = TRANSPORT_TYPE;
if (transportType === "http") {
const initialPort = CLI_PORT ?? DEFAULT_PORT;
const app = express();
app.use(express.json());
app.use((req, res, next) => {
res.setHeader("Access-Control-Allow-Origin", "*");
res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS,DELETE");
res.setHeader("Access-Control-Allow-Headers", "Content-Type, MCP-Session-Id, MCP-Protocol-Version, X-Context7-API-Key, Context7-API-Key, X-API-Key, Authorization");
res.setHeader("Access-Control-Expose-Headers", "MCP-Session-Id");
if (req.method === "OPTIONS") {
res.sendStatus(200);
return;
}
next();
});
const extractHeaderValue = (value) => {
if (!value)
return undefined;
return typeof value === "string" ? value : value[0];
};
const extractBearerToken = (authHeader) => {
const header = extractHeaderValue(authHeader);
if (!header)
return undefined;
if (header.startsWith("Bearer ")) {
return header.substring(7).trim();
}
return header;
};
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"]));
};
app.all("/mcp", async (req, res) => {
try {
const clientIp = getClientIp(req);
const apiKey = extractApiKey(req);
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
enableJsonResponse: true,
});
res.on("close", () => {
transport.close();
});
await requestContext.run({ clientIp, apiKey }, async () => {
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
});
}
catch (error) {
console.error("Error handling MCP request:", error);
if (!res.headersSent) {
res.status(500).json({
jsonrpc: "2.0",
error: { code: -32603, message: "Internal server error" },
id: null,
});
}
}
});
app.get("/ping", (_req, res) => {
res.json({ status: "ok", message: "pong" });
});
// Catch-all 404 handler - must be after all other routes
app.use((_req, res) => {
res.status(404).json({
error: "not_found",
message: "Endpoint not found. Use /mcp for MCP protocol communication.",
});
});
const startServer = (port, maxAttempts = 10) => {
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);
}
else {
console.error(`Failed to start server: ${err.message}`);
process.exit(1);
}
});
httpServer.once("listening", () => {
console.error(`Context7 Documentation MCP Server running on HTTP at http://localhost:${port}/mcp`);
});
};
startServer(initialPort);
}
else {
const apiKey = cliOptions.apiKey || process.env.CONTEXT7_API_KEY;
globalApiKey = apiKey; // Store globally for tool handlers in stdio mode
const transport = new StdioServerTransport();
await requestContext.run({ apiKey }, async () => {
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);
});