Context7 Platform -- Up-to-date docs for AI agents
import { Command } from "commander";
import pc from "picocolors";
import ora from "ora";
import { password, select } from "@inquirer/prompts";
import { mkdir, readFile, writeFile } from "fs/promises";
import { dirname, join } from "path";
import { log } from "../utils/logger.js";
import { checkboxWithHover } from "../utils/prompts.js";
import { trackEvent } from "../utils/tracking.js";
import { installSkillFiles } from "../utils/installer.js";
import { performLogin } from "./auth.js";
import { saveTokens, getValidAccessToken } from "../utils/auth.js";
import type { SkillFile } from "../types.js";
import { resolveSetupApiKey } from "../setup/auth.js";
import {
type SetupAgent,
type AuthOptions,
type Transport,
AUTH_MODE_LABELS,
ALL_AGENT_NAMES,
getAgent,
detectAgents,
} from "../setup/agents.js";
import {
customizeSkillFilesForAgent,
fetchSetupSkillFiles,
getBundledFindDocsSkillFiles,
getBundledMcpSkillFiles,
getBundledRuleContent,
getRuleContent,
} from "../setup/templates.js";
import {
getMcpUrl,
getOnPremMcpAuthStatus,
resolveSetupDeployment,
type CustomSetupDeployment,
type SetupDeployment,
} from "../setup/deployment.js";
import {
readJsonConfig,
mergeServerEntry,
writeJsonConfig,
resolveMcpPath,
appendTomlServer,
patchTomlStdioApiKey,
isStdioContext7Entry,
patchStdioApiKey,
getJsonServerEntry,
} from "../setup/mcp-writer.js";
import { editOpenCodeServer } from "../setup/opencode-editor.js";
type Scope = "global" | "project";
type SetupMode = "mcp" | "cli";
interface McpSkillPayload {
files: SkillFile[];
status: "installed" | "installed (bundled)" | "installed (bundled fallback)";
}
type SetupOptions = Partial<Record<SetupAgent, boolean>> & {
project?: boolean;
yes?: boolean;
apiKey?: string;
oauth?: boolean;
cli?: boolean;
mcp?: boolean;
stdio?: boolean;
baseUrl?: string;
};
function resolveTransport(options: SetupOptions): Transport {
return options.stdio ? "stdio" : "http";
}
const CHECKBOX_THEME = {
style: {
highlight: (text: string) => pc.green(text),
disabledChoice: (text: string) => ` ${pc.dim("◯")} ${pc.dim(text)}`,
},
};
function getSelectedAgents(options: SetupOptions): SetupAgent[] {
return ALL_AGENT_NAMES.filter((name) => options[name]);
}
export function registerSetupCommand(program: Command): void {
const command = program.command("setup").description("Set up Context7 for your AI coding agent");
for (const name of ALL_AGENT_NAMES) {
const agent = getAgent(name);
command.option(`--${name}`, agent.setupDescription ?? `Set up for ${agent.displayName}`);
}
command
.option("--mcp", "Set up MCP server mode")
.option("--cli", "Set up CLI + Skills mode (no MCP server)")
.option("-p, --project", "Configure for current project instead of globally")
.option("-y, --yes", "Skip confirmation prompts")
.option("--api-key <key>", "Use API key authentication")
.option("--oauth", "Use OAuth endpoint (IDE handles auth flow)")
.option("--stdio", "Configure the MCP server as a local stdio process (default: HTTP)")
// The root option handles shared API configuration; this local declaration also
// lets Commander accept --base-url after `setup`.
.option("--base-url <url>", "Use a custom Context7 deployment (for example, on-premise)")
.action(async (_options: SetupOptions, command: Command) => {
await setupCommand(command.optsWithGlobals<SetupOptions>());
});
}
async function promptForOnPremApiKey(deployment: CustomSetupDeployment): Promise<string | null> {
try {
return await password({
message: `Personal API key (create one at ${deployment.baseUrl}/account)`,
mask: true,
validate: (value) => value.trim().length > 0 || "API key is required",
}).then((value) => value.trim());
} catch {
log.error("Setup cancelled before a personal API key was entered.");
return null;
}
}
async function resolveAuth(
options: SetupOptions,
deployment: SetupDeployment
): Promise<AuthOptions | null> {
const explicitApiKey = options.apiKey?.trim();
if (deployment.kind === "custom") {
try {
if (!(await getOnPremMcpAuthStatus(deployment))) return { mode: "none" };
} catch (err) {
log.error(
`Could not check MCP authentication at ${deployment.baseUrl}: ${err instanceof Error ? err.message : String(err)}`
);
process.exitCode = 1;
return null;
}
const apiKey = explicitApiKey || process.env.CONTEXT7_API_KEY?.trim();
if (apiKey) return { mode: "api-key", apiKey };
if (!options.yes) {
const promptedApiKey = await promptForOnPremApiKey(deployment);
return promptedApiKey ? { mode: "api-key", apiKey: promptedApiKey } : null;
}
log.error(
`MCP authentication is enabled at ${deployment.baseUrl}. Pass --api-key, set CONTEXT7_API_KEY, or rerun without --yes to enter a personal API key securely.`
);
process.exitCode = 1;
return null;
}
if (explicitApiKey) return { mode: "api-key", apiKey: explicitApiKey };
if (options.oauth) return { mode: "oauth" };
const resolvedApiKey = await resolveSetupApiKey();
if (!resolvedApiKey) return null;
return { mode: "api-key", apiKey: resolvedApiKey };
}
function getSetupValidationError(
mode: SetupMode,
options: SetupOptions,
deployment: SetupDeployment
): string | null {
if (deployment.kind === "custom") {
if (mode === "cli") {
return "--base-url currently supports MCP setup only. Use --mcp with an on-premise deployment.";
}
if (options.stdio) {
return "--stdio is not supported with --base-url. On-premise setup uses the HTTP /mcp endpoint.";
}
if (options.oauth) {
return "--oauth is only supported by hosted Context7. Use a personal on-premise API key.";
}
}
if (mode === "mcp" && options.stdio && options.oauth) {
return "--stdio is incompatible with --oauth (OAuth uses the hosted HTTP endpoint).";
}
return null;
}
async function resolveMode(options: SetupOptions): Promise<SetupMode> {
if (options.cli) return "cli";
if (options.baseUrl || options.mcp || options.yes || options.oauth || options.stdio) return "mcp";
return select<SetupMode>({
message: "How should your agent access Context7?",
choices: [
{
name: `MCP server\n ${pc.dim("Agent calls Context7 tools via MCP protocol to retrieve up-to-date library docs")}`,
value: "mcp" as SetupMode,
},
{
name: `CLI + Skills\n ${pc.dim("Installs a find-docs skill that guides your agent to fetch up-to-date library docs using ")}${pc.dim(pc.bold("ctx7"))}${pc.dim(" CLI commands")}`,
value: "cli" as SetupMode,
},
],
theme: {
style: {
highlight: (text: string) => pc.green(text),
answer: (text: string) => pc.green(text.split("\n")[0].trim()),
},
},
});
}
async function resolveCliAuth(apiKey?: string): Promise<void> {
if (apiKey) {
saveTokens({ access_token: apiKey, token_type: "bearer" });
log.blank();
log.plain(`${pc.green("✔")} Authenticated`);
return;
}
const validToken = await getValidAccessToken({ recoverExpiredSession: false });
if (validToken) {
log.blank();
log.plain(`${pc.green("✔")} Authenticated`);
return;
}
await performLogin();
}
async function promptAgents(): Promise<SetupAgent[] | null> {
const choices = ALL_AGENT_NAMES.map((name) => ({
name: getAgent(name).displayName,
value: name,
}));
const message = "Which agents do you want to set up?";
try {
return await checkboxWithHover(
{
message,
choices,
loop: false,
theme: CHECKBOX_THEME,
},
{ getName: (a: SetupAgent) => getAgent(a).displayName }
);
} catch {
return null;
}
}
async function resolveAgents(options: SetupOptions, scope: Scope): Promise<SetupAgent[]> {
const explicit = getSelectedAgents(options);
if (explicit.length > 0) return explicit;
const detected = await detectAgents(scope);
if (detected.length > 0 && options.yes) return detected;
log.blank();
const selected = await promptAgents();
if (!selected) {
log.warn("Setup cancelled");
return [];
}
return selected;
}
/** Install a rule for an agent, handling both "file" (standalone) and "append" (AGENTS.md) types. */
async function installRule(
agentName: SetupAgent,
scope: Scope,
content: string
): Promise<{ status: string; path: string }> {
const agent = getAgent(agentName);
const rule = agent.rule;
if (rule.kind === "file") {
const ruleContent = `${rule.contentPrefix ?? ""}${content}`;
const ruleDir =
scope === "global" ? rule.dir("global") : join(process.cwd(), rule.dir("project"));
const rulePath = join(ruleDir, rule.filename);
await mkdir(dirname(rulePath), { recursive: true });
await writeFile(rulePath, ruleContent, "utf-8");
return { status: "installed", path: rulePath };
}
const filePath =
scope === "global" ? rule.file("global") : join(process.cwd(), rule.file("project"));
const escapedMarker = rule.sectionMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
const section = `${rule.sectionMarker}\n${content}${rule.sectionMarker}`;
let existing = "";
try {
existing = await readFile(filePath, "utf-8");
} catch {
// File doesn't exist yet
}
if (existing.includes(rule.sectionMarker)) {
const regex = new RegExp(`${escapedMarker}\\n[\\s\\S]*?${escapedMarker}`);
const updated = existing.replace(regex, section);
await writeFile(filePath, updated, "utf-8");
return { status: "updated", path: filePath };
}
const separator =
existing.length > 0 && !existing.endsWith("\n") ? "\n\n" : existing.length > 0 ? "\n" : "";
await mkdir(dirname(filePath), { recursive: true });
await writeFile(filePath, existing + separator + section + "\n", "utf-8");
return { status: "installed", path: filePath };
}
async function loadMcpSkillPayload(deployment: SetupDeployment): Promise<McpSkillPayload> {
const bundled = getBundledMcpSkillFiles();
if (deployment.kind === "custom") {
return { files: bundled, status: "installed (bundled)" };
}
const files = await fetchSetupSkillFiles("context7-mcp");
return files
? { files, status: "installed" }
: { files: bundled, status: "installed (bundled fallback)" };
}
/**
* For stdio transport, preserve an existing `@upstash/context7-mcp` invocation
* (e.g., `@upstash/context7-mcp@latest` or a user-pinned version) and only
* swap the `--api-key` value. Falls back to the agent's canonical shape when
* no existing stdio entry is detected. HTTP transport always uses the
* canonical shape.
*/
function resolveEntryToWrite(
agent: ReturnType<typeof getAgent>,
auth: AuthOptions,
transport: Transport,
existingEntry: Record<string, unknown> | undefined,
mcpUrl: string
): Record<string, unknown> {
if (transport === "stdio" && existingEntry && isStdioContext7Entry(existingEntry)) {
const apiKey = auth.mode === "api-key" ? auth.apiKey : undefined;
return patchStdioApiKey(existingEntry, apiKey);
}
return agent.mcp.buildEntry(auth, transport, mcpUrl);
}
async function setupAgent(
agentName: SetupAgent,
auth: AuthOptions,
transport: Transport,
scope: Scope,
deployment: SetupDeployment,
mcpUrl: string,
skillPayload: McpSkillPayload
): Promise<{
agent: string;
mcpStatus: string;
mcpPath: string;
ruleStatus: string;
rulePath: string;
skillStatus: string;
skillPath: string;
}> {
const agent = getAgent(agentName);
const mcpCandidates =
scope === "global" || agent.mcp.projectPaths.length === 0
? agent.mcp.globalPaths
: agent.mcp.projectPaths.map((p) => join(process.cwd(), p));
const mcpPath = await resolveMcpPath(mcpCandidates);
let mcpStatus: string;
try {
if (mcpPath.endsWith(".toml")) {
const apiKey = auth.mode === "api-key" ? auth.apiKey : undefined;
const patched =
transport === "stdio" ? await patchTomlStdioApiKey(mcpPath, "context7", apiKey) : false;
const { alreadyExists } = patched
? { alreadyExists: true }
: await appendTomlServer(
mcpPath,
"context7",
resolveEntryToWrite(agent, auth, transport, undefined, mcpUrl)
);
mcpStatus = alreadyExists
? `reconfigured with ${AUTH_MODE_LABELS[auth.mode]}`
: `configured with ${AUTH_MODE_LABELS[auth.mode]}`;
} else {
const existing = await readJsonConfig(mcpPath);
const existingJsonEntry =
transport === "stdio"
? getJsonServerEntry(existing, agent.mcp.configKey, "context7")
: undefined;
const entry = resolveEntryToWrite(agent, auth, transport, existingJsonEntry, mcpUrl);
const { config, alreadyExists } = mergeServerEntry(
existing,
agent.mcp.configKey,
"context7",
entry
);
mcpStatus = alreadyExists
? `reconfigured with ${AUTH_MODE_LABELS[auth.mode]}`
: `configured with ${AUTH_MODE_LABELS[auth.mode]}`;
if (agentName === "opencode") await editOpenCodeServer(mcpPath, entry);
else await writeJsonConfig(mcpPath, config);
}
} catch (err) {
mcpStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
}
let ruleStatus: string;
let rulePath: string;
try {
const ruleContent =
deployment.kind === "custom"
? getBundledRuleContent("mcp", agentName)
: await getRuleContent("mcp", agentName);
const result = await installRule(agentName, scope, ruleContent);
ruleStatus = result.status;
rulePath = result.path;
} catch (err) {
ruleStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
rulePath = "";
}
const skillDir =
scope === "global"
? agent.skill.dir("global")
: join(process.cwd(), agent.skill.dir("project"));
const skillPath = join(skillDir, agent.skill.name, "SKILL.md");
let skillStatus: string;
try {
await installSkillFiles(agent.skill.name, skillPayload.files, skillDir);
skillStatus = skillPayload.status;
} catch (err) {
skillStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
}
return {
agent: agent.displayName,
mcpStatus,
mcpPath,
ruleStatus,
rulePath,
skillStatus,
skillPath,
};
}
function logSkillStatus(skillStatus: string, skillPath: string): void {
const skillFailed = skillStatus.startsWith("failed:");
const skillIcon = skillStatus.startsWith("installed")
? pc.green("+")
: skillFailed
? pc.red("✖")
: pc.dim("~");
log.plain(` ${skillIcon} Skill ${skillFailed ? "failed" : skillStatus}`);
log.plain(` ${pc.dim(skillPath)}`);
if (skillFailed) {
log.plain(` ${pc.red(skillStatus.slice("failed: ".length))}`);
if (skillStatus.includes("EACCES")) {
log.plain(
` ${pc.yellow("tip:")} fix permissions with: ${pc.cyan(`sudo chown -R $(whoami) ${dirname(dirname(skillPath))}`)}`
);
}
}
}
async function setupMcp(
agents: SetupAgent[],
options: SetupOptions,
scope: Scope,
deployment: SetupDeployment
): Promise<void> {
const transport = resolveTransport(options);
const auth = await resolveAuth(options, deployment);
if (!auth) {
log.warn("Setup cancelled");
return;
}
log.blank();
const spinner = ora("Setting up Context7...").start();
const mcpUrl = getMcpUrl(deployment, auth);
const skillPayload = await loadMcpSkillPayload(deployment);
const results = [];
for (const agentName of agents) {
spinner.text = `Setting up ${getAgent(agentName).displayName}...`;
results.push(
await setupAgent(agentName, auth, transport, scope, deployment, mcpUrl, skillPayload)
);
}
spinner.succeed("Context7 setup complete");
log.blank();
for (const r of results) {
log.plain(` ${pc.bold(r.agent)}`);
const mcpIcon =
r.mcpStatus.startsWith("configured") || r.mcpStatus.startsWith("reconfigured")
? pc.green("+")
: pc.dim("~");
log.plain(` ${mcpIcon} MCP server ${r.mcpStatus}`);
log.plain(` ${pc.dim(r.mcpPath)}`);
const ruleIcon = r.ruleStatus === "installed" ? pc.green("+") : pc.dim("~");
log.plain(` ${ruleIcon} Rule ${r.ruleStatus}`);
log.plain(` ${pc.dim(r.rulePath)}`);
logSkillStatus(r.skillStatus, r.skillPath);
}
log.blank();
trackEvent("setup", { agents, scope, authMode: auth.mode });
}
async function setupCliAgent(
agentName: SetupAgent,
scope: Scope,
skillFiles: Array<{ path: string; content: string }>
): Promise<{ skillPath: string; skillStatus: string; rulePath: string; ruleStatus: string }> {
const agent = getAgent(agentName);
const skillDir =
scope === "global"
? agent.skill.dir("global")
: join(process.cwd(), agent.skill.dir("project"));
let skillStatus: string;
try {
const files = customizeSkillFilesForAgent(agentName, "find-docs", skillFiles);
await installSkillFiles("find-docs", files, skillDir);
skillStatus = "installed";
} catch (err) {
skillStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
}
const skillPath = join(skillDir, "find-docs");
let ruleStatus: string;
let rulePath: string;
try {
const result = await installRule(agentName, scope, await getRuleContent("cli", agentName));
ruleStatus = result.status;
rulePath = result.path;
} catch (err) {
ruleStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
rulePath = "";
}
return { skillPath, skillStatus, rulePath, ruleStatus };
}
async function setupCli(options: SetupOptions): Promise<void> {
await resolveCliAuth(options.apiKey);
const scope: Scope = options.project ? "project" : "global";
const agents = await resolveAgents(options, scope);
if (agents.length === 0) return;
log.blank();
const spinner = ora("Downloading find-docs skill...").start();
const downloaded = await fetchSetupSkillFiles("find-docs");
const files = downloaded ?? getBundledFindDocsSkillFiles();
if (downloaded) {
spinner.succeed("Downloaded find-docs skill");
} else {
spinner.warn("Could not download find-docs skill, using the bundled copy");
}
const installSpinner = ora("Installing...").start();
const results: Array<{
agent: string;
skillPath: string;
skillStatus: string;
rulePath: string;
ruleStatus: string;
}> = [];
for (const agentName of agents) {
const agentDef = getAgent(agentName);
installSpinner.text = `Setting up ${agentDef.displayName}...`;
const r = await setupCliAgent(agentName, scope, files);
results.push({ agent: agentDef.displayName, ...r });
}
installSpinner.succeed("Context7 CLI setup complete");
log.blank();
for (const r of results) {
log.plain(` ${pc.bold(r.agent)}`);
logSkillStatus(r.skillStatus, r.skillPath);
const ruleIcon =
r.ruleStatus === "installed" || r.ruleStatus === "updated" ? pc.green("+") : pc.dim("~");
log.plain(` ${ruleIcon} Rule ${r.ruleStatus}`);
log.plain(` ${pc.dim(r.rulePath)}`);
}
log.blank();
trackEvent("setup", { mode: "cli" });
}
async function setupCommand(options: SetupOptions): Promise<void> {
try {
let deployment: SetupDeployment;
try {
deployment = resolveSetupDeployment(options.baseUrl);
} catch (err) {
log.error(err instanceof Error ? err.message : String(err));
process.exitCode = 1;
return;
}
const mode = await resolveMode(options);
const validationError = getSetupValidationError(mode, options, deployment);
if (validationError) {
log.error(validationError);
process.exitCode = 1;
return;
}
trackEvent("command", { name: "setup" });
if (mode === "mcp") {
const scope: Scope = options.project ? "project" : "global";
const agents = await resolveAgents(options, scope);
if (agents.length === 0) return;
await setupMcp(agents, options, scope, deployment);
} else {
await setupCli(options);
}
} catch (err) {
if (err instanceof Error && err.name === "ExitPromptError") process.exit(0);
throw err;
}
}