ctx7 0.2.4 → 0.3.1

package/README.md

@@ -16,6 +16,18 @@ npm install -g ctx7
 
 ## Quick Start
 
+```bash
+# Set up Context7 MCP for your coding agents
+ctx7 setup
+
+# Target a specific agent
+ctx7 setup --cursor
+ctx7 setup --claude
+ctx7 setup --opencode
+```
+
+### Skills
+
 ```bash
 # Search for skills
 ctx7 skills search pdf
@@ -32,6 +44,32 @@ ctx7 skills list --claude
 
 ## Usage
 
+### Setup
+
+Configure Context7 MCP and a rule for your AI coding agents. Authenticates via OAuth, generates an API key, and writes the config.
+
+```bash
+# Interactive (prompts for agent selection)
+ctx7 setup
+
+# Target specific agents
+ctx7 setup --cursor
+ctx7 setup --claude
+ctx7 setup --opencode
+
+# Use an existing API key instead of OAuth
+ctx7 setup --api-key YOUR_API_KEY
+
+# Use OAuth endpoint (IDE handles auth flow)
+ctx7 setup --oauth
+
+# Configure for current project only (default is global)
+ctx7 setup --project
+
+# Skip prompts
+ctx7 setup --yes
+```
+
 ### Generate skills
 
 Generate custom skills tailored to your use case using AI. Requires authentication.

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
-import pc8 from "picocolors";
+import pc9 from "picocolors";
 import figlet from "figlet";
 
 // src/commands/skill.ts
@@ -2256,19 +2256,450 @@ ${headerLine}`,
   logInstallSummary(targets, targetDirs, installedNames);
 }
 
+// src/commands/setup.ts
+import pc8 from "picocolors";
+import ora4 from "ora";
+import { mkdir as mkdir4, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname3, join as join8 } from "path";
+import { randomBytes as randomBytes2 } from "crypto";
+
+// src/setup/agents.ts
+import { access as access2 } from "fs/promises";
+import { join as join7 } from "path";
+import { homedir as homedir5 } from "os";
+var SETUP_AGENT_NAMES = {
+  claude: "Claude Code",
+  cursor: "Cursor",
+  opencode: "OpenCode"
+};
+var AUTH_MODE_LABELS = {
+  oauth: "OAuth",
+  "api-key": "API Key"
+};
+var MCP_BASE_URL = "https://mcp.context7.com";
+function mcpUrl(auth) {
+  return auth.mode === "oauth" ? `${MCP_BASE_URL}/mcp/oauth` : `${MCP_BASE_URL}/mcp`;
+}
+function withHeaders(base, auth) {
+  if (auth.mode === "api-key" && auth.apiKey) {
+    return { ...base, headers: { CONTEXT7_API_KEY: auth.apiKey } };
+  }
+  return base;
+}
+var agents = {
+  claude: {
+    name: "claude",
+    displayName: "Claude Code",
+    mcp: {
+      projectPath: ".mcp.json",
+      globalPath: join7(homedir5(), ".claude.json"),
+      configKey: "mcpServers",
+      buildEntry: (auth) => withHeaders({ type: "http", url: mcpUrl(auth) }, auth)
+    },
+    rule: {
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".claude", "rules") : join7(".claude", "rules"),
+      filename: "context7.md"
+    },
+    skill: {
+      name: "documentation-lookup",
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".claude", "skills") : join7(".claude", "skills")
+    },
+    detect: {
+      projectPaths: [".mcp.json", ".claude"],
+      globalPaths: [join7(homedir5(), ".claude")]
+    }
+  },
+  cursor: {
+    name: "cursor",
+    displayName: "Cursor",
+    mcp: {
+      projectPath: join7(".cursor", "mcp.json"),
+      globalPath: join7(homedir5(), ".cursor", "mcp.json"),
+      configKey: "mcpServers",
+      buildEntry: (auth) => withHeaders({ url: mcpUrl(auth) }, auth)
+    },
+    rule: {
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".cursor", "rules") : join7(".cursor", "rules"),
+      filename: "context7.mdc"
+    },
+    skill: {
+      name: "documentation-lookup",
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".cursor", "skills") : join7(".cursor", "skills")
+    },
+    detect: {
+      projectPaths: [".cursor"],
+      globalPaths: [join7(homedir5(), ".cursor")]
+    }
+  },
+  opencode: {
+    name: "opencode",
+    displayName: "OpenCode",
+    mcp: {
+      projectPath: ".opencode.json",
+      globalPath: join7(homedir5(), ".config", "opencode", "opencode.json"),
+      configKey: "mcp",
+      buildEntry: (auth) => withHeaders({ type: "remote", url: mcpUrl(auth), enabled: true }, auth)
+    },
+    rule: {
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".config", "opencode", "rules") : join7(".opencode", "rules"),
+      filename: "context7.md",
+      instructionsGlob: (scope) => scope === "global" ? join7(homedir5(), ".config", "opencode", "rules", "*.md") : ".opencode/rules/*.md"
+    },
+    skill: {
+      name: "documentation-lookup",
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".agents", "skills") : join7(".agents", "skills")
+    },
+    detect: {
+      projectPaths: [".opencode.json"],
+      globalPaths: [join7(homedir5(), ".config", "opencode")]
+    }
+  }
+};
+function getAgent(name) {
+  return agents[name];
+}
+var ALL_AGENT_NAMES = Object.keys(agents);
+async function pathExists(p) {
+  try {
+    await access2(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function detectAgents(scope) {
+  const detected = [];
+  for (const agent of Object.values(agents)) {
+    const paths = scope === "global" ? agent.detect.globalPaths : agent.detect.projectPaths;
+    for (const p of paths) {
+      const fullPath = scope === "global" ? p : join7(process.cwd(), p);
+      if (await pathExists(fullPath)) {
+        detected.push(agent.name);
+        break;
+      }
+    }
+  }
+  return detected;
+}
+
+// src/setup/templates.ts
+var SKILL_CONTENT = `---
+name: documentation-lookup
+description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.
+---
+
+When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data.
+
+## When to Use This Skill
+
+Activate this skill when the user:
+
+- Asks setup or configuration questions ("How do I configure Next.js middleware?")
+- Requests code involving libraries ("Write a Prisma query for...")
+- Needs API references ("What are the Supabase auth methods?")
+- Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
+
+## How to Fetch Documentation
+
+### Step 1: Resolve the Library ID
+
+Call \`resolve-library-id\` with:
+
+- \`libraryName\`: The library name extracted from the user's question
+- \`query\`: The user's full question (improves relevance ranking)
+
+### Step 2: Select the Best Match
+
+From the resolution results, choose based on:
+
+- Exact or closest name match to what the user asked for
+- Higher benchmark scores indicate better documentation quality
+- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs
+
+### Step 3: Fetch the Documentation
+
+Call \`query-docs\` with:
+
+- \`libraryId\`: The selected Context7 library ID (e.g., \`/vercel/next.js\`)
+- \`query\`: The user's specific question
+
+### Step 4: Use the Documentation
+
+Incorporate the fetched documentation into your response:
+
+- Answer the user's question using current, accurate information
+- Include relevant code examples from the docs
+- Cite the library version when relevant
+
+## Guidelines
+
+- **Be specific**: Pass the user's full question as the query for better results
+- **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step
+- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks
+`;
+var RULE_CONTENT = `---
+alwaysApply: true
+---
+
+When working with libraries, frameworks, or APIs \u2014 use Context7 MCP to fetch current documentation instead of relying on training data. This includes setup questions, code generation, API references, and anything involving specific packages.
+
+## Steps
+
+1. Call \`resolve-library-id\` with the library name and the user's question
+2. Pick the best match \u2014 prefer exact names and version-specific IDs when a version is mentioned
+3. Call \`query-docs\` with the selected library ID and the user's question
+4. Answer using the fetched docs \u2014 include code examples and cite the version
+`;
+
+// src/setup/mcp-writer.ts
+import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
+import { dirname as dirname2 } from "path";
+async function readJsonConfig(filePath) {
+  let raw;
+  try {
+    raw = await readFile3(filePath, "utf-8");
+  } catch {
+    return {};
+  }
+  raw = raw.trim();
+  if (!raw) return {};
+  return JSON.parse(raw);
+}
+function mergeServerEntry(existing, configKey, serverName, entry) {
+  const section = existing[configKey] ?? {};
+  if (serverName in section) {
+    return { config: existing, alreadyExists: true };
+  }
+  return {
+    config: {
+      ...existing,
+      [configKey]: {
+        ...section,
+        [serverName]: entry
+      }
+    },
+    alreadyExists: false
+  };
+}
+function mergeInstructions(config, glob) {
+  const instructions = config.instructions ?? [];
+  if (instructions.includes(glob)) return config;
+  return { ...config, instructions: [...instructions, glob] };
+}
+async function writeJsonConfig(filePath, config) {
+  await mkdir3(dirname2(filePath), { recursive: true });
+  await writeFile3(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+// src/commands/setup.ts
+var CHECKBOX_THEME = {
+  style: {
+    highlight: (text) => pc8.green(text),
+    disabledChoice: (text) => ` ${pc8.dim("\u25EF")} ${pc8.dim(text)}`
+  }
+};
+function getSelectedAgents(options) {
+  const agents2 = [];
+  if (options.claude) agents2.push("claude");
+  if (options.cursor) agents2.push("cursor");
+  if (options.opencode) agents2.push("opencode");
+  return agents2;
+}
+function registerSetupCommand(program2) {
+  program2.command("setup").description("Set up Context7 MCP and rule for your AI coding agent").option("--claude", "Set up for Claude Code").option("--cursor", "Set up for Cursor").option("--opencode", "Set up for OpenCode").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)").action(async (options) => {
+    await setupCommand(options);
+  });
+}
+async function authenticateAndGenerateKey() {
+  const existingTokens = loadTokens();
+  const accessToken = existingTokens && !isTokenExpired(existingTokens) ? existingTokens.access_token : await performLogin();
+  if (!accessToken) return null;
+  const spinner = ora4("Configuring authentication...").start();
+  try {
+    const response = await fetch(`${getBaseUrl()}/api/dashboard/api-keys`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ name: `ctx7-cli-${randomBytes2(3).toString("hex")}` })
+    });
+    if (!response.ok) {
+      const err = await response.json().catch(() => ({}));
+      spinner.fail("Authentication failed");
+      log.error(err.message || err.error || `HTTP ${response.status}`);
+      return null;
+    }
+    const result = await response.json();
+    spinner.succeed("Authenticated");
+    return result.data.apiKey;
+  } catch (err) {
+    spinner.fail("Authentication failed");
+    log.error(err instanceof Error ? err.message : String(err));
+    return null;
+  }
+}
+async function resolveAuth(options) {
+  if (options.apiKey) return { mode: "api-key", apiKey: options.apiKey };
+  if (options.oauth) return { mode: "oauth" };
+  const apiKey = await authenticateAndGenerateKey();
+  if (!apiKey) return null;
+  return { mode: "api-key", apiKey };
+}
+async function isAlreadyConfigured(agentName, scope) {
+  const agent = getAgent(agentName);
+  const mcpPath = scope === "global" ? agent.mcp.globalPath : join8(process.cwd(), agent.mcp.projectPath);
+  try {
+    const existing = await readJsonConfig(mcpPath);
+    const section = existing[agent.mcp.configKey] ?? {};
+    return "context7" in section;
+  } catch {
+    return false;
+  }
+}
+async function promptAgents(scope) {
+  const choices = await Promise.all(
+    ALL_AGENT_NAMES.map(async (name) => {
+      const configured = await isAlreadyConfigured(name, scope);
+      return {
+        name: SETUP_AGENT_NAMES[name],
+        value: name,
+        disabled: configured ? "(already configured)" : false
+      };
+    })
+  );
+  if (choices.every((c) => c.disabled)) {
+    log.info("Context7 is already configured for all detected agents.");
+    return null;
+  }
+  try {
+    return await checkboxWithHover(
+      {
+        message: "Which agents do you want to set up?",
+        choices,
+        loop: false,
+        theme: CHECKBOX_THEME
+      },
+      { getName: (a) => SETUP_AGENT_NAMES[a] }
+    );
+  } catch {
+    return null;
+  }
+}
+async function resolveAgents(options, scope) {
+  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(scope);
+  if (!selected) {
+    log.warn("Setup cancelled");
+    return [];
+  }
+  return selected;
+}
+async function setupAgent(agentName, auth, scope) {
+  const agent = getAgent(agentName);
+  const mcpPath = scope === "global" ? agent.mcp.globalPath : join8(process.cwd(), agent.mcp.projectPath);
+  let mcpStatus;
+  try {
+    const existing = await readJsonConfig(mcpPath);
+    const { config, alreadyExists } = mergeServerEntry(
+      existing,
+      agent.mcp.configKey,
+      "context7",
+      agent.mcp.buildEntry(auth)
+    );
+    if (alreadyExists) {
+      mcpStatus = "already configured";
+    } else {
+      mcpStatus = `configured with ${AUTH_MODE_LABELS[auth.mode]}`;
+    }
+    const finalConfig = agent.rule.instructionsGlob ? mergeInstructions(config, agent.rule.instructionsGlob(scope)) : config;
+    if (finalConfig !== existing) {
+      await writeJsonConfig(mcpPath, finalConfig);
+    }
+  } catch (err) {
+    mcpStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  const rulePath = scope === "global" ? join8(agent.rule.dir("global"), agent.rule.filename) : join8(process.cwd(), agent.rule.dir("project"), agent.rule.filename);
+  let ruleStatus;
+  try {
+    await mkdir4(dirname3(rulePath), { recursive: true });
+    await writeFile4(rulePath, RULE_CONTENT, "utf-8");
+    ruleStatus = "installed";
+  } catch (err) {
+    ruleStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  const skillDir = scope === "global" ? agent.skill.dir("global") : join8(process.cwd(), agent.skill.dir("project"));
+  const skillPath = join8(skillDir, agent.skill.name, "SKILL.md");
+  let skillStatus;
+  try {
+    await mkdir4(dirname3(skillPath), { recursive: true });
+    await writeFile4(skillPath, SKILL_CONTENT, "utf-8");
+    skillStatus = "installed";
+  } catch (err) {
+    skillStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  return {
+    agent: agent.displayName,
+    mcpStatus,
+    mcpPath,
+    ruleStatus,
+    rulePath,
+    skillStatus,
+    skillPath
+  };
+}
+async function setupCommand(options) {
+  trackEvent("command", { name: "setup" });
+  const scope = options.project ? "project" : "global";
+  const agents2 = await resolveAgents(options, scope);
+  if (agents2.length === 0) return;
+  const auth = await resolveAuth(options);
+  if (!auth) {
+    log.warn("Setup cancelled");
+    return;
+  }
+  log.blank();
+  const spinner = ora4("Setting up Context7...").start();
+  const results = [];
+  for (const agentName of agents2) {
+    spinner.text = `Setting up ${getAgent(agentName).displayName}...`;
+    results.push(await setupAgent(agentName, auth, scope));
+  }
+  spinner.succeed("Context7 setup complete");
+  log.blank();
+  for (const r of results) {
+    log.plain(`  ${pc8.bold(r.agent)}`);
+    const mcpIcon = r.mcpStatus.startsWith("configured") ? pc8.green("+") : pc8.dim("~");
+    log.plain(`    ${mcpIcon} MCP server ${r.mcpStatus}`);
+    log.plain(`      ${pc8.dim(r.mcpPath)}`);
+    const ruleIcon = r.ruleStatus === "installed" ? pc8.green("+") : pc8.dim("~");
+    log.plain(`    ${ruleIcon} Rule ${r.ruleStatus}`);
+    log.plain(`      ${pc8.dim(r.rulePath)}`);
+    const skillIcon = r.skillStatus === "installed" ? pc8.green("+") : pc8.dim("~");
+    log.plain(`    ${skillIcon} Skill ${r.skillStatus}`);
+    log.plain(`      ${pc8.dim(r.skillPath)}`);
+  }
+  log.blank();
+  trackEvent("setup", { agents: agents2, scope, authMode: auth.mode });
+}
+
 // src/constants.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { fileURLToPath } from "url";
-import { dirname as dirname2, join as join7 } from "path";
-var __dirname = dirname2(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(readFileSync2(join7(__dirname, "../package.json"), "utf-8"));
+import { dirname as dirname4, join as join9 } from "path";
+var __dirname = dirname4(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync2(join9(__dirname, "../package.json"), "utf-8"));
 var VERSION = pkg.version;
 var NAME = pkg.name;
 
 // src/index.ts
 var brand = {
-  primary: pc8.green,
-  dim: pc8.dim
+  primary: pc9.green,
+  dim: pc9.dim
 };
 var program = new Command();
 program.name("ctx7").description("Context7 CLI - Manage AI coding skills and documentation context").version(VERSION).option("--base-url <url>").hook("preAction", (thisCommand) => {
@@ -2303,6 +2734,7 @@ Visit ${brand.primary("https://context7.com")} to browse skills
 registerSkillCommands(program);
 registerSkillAliases(program);
 registerAuthCommands(program);
+registerSetupCommand(program);
 program.action(() => {
   console.log("");
   const banner = figlet.textSync("Context7", { font: "ANSI Shadow" });