Context7 Platform -- Up-to-date docs for AI agents
feat(setup): install rules alongside skills, update rule/skill content for better trigger rates (#2320)
Fahreddin Özcan4f1316853548
diff --git a/.changeset/setup-rules-install.md b/.changeset/setup-rules-install.mdnew file mode 100644index 00000000..fd0618a6--- /dev/null+++ b/.changeset/setup-rules-install.md@@ -0,0 +1,12 @@+---+"ctx7": patch+---++Install rules alongside skills in `ctx7 setup` for better trigger rates++- CLI setup now installs a rule file for each agent (previously only installed the skill)+- Rule content fetched from GitHub, with agent-specific formatting (alwaysApply for Cursor)+- Updated find-docs skill description for higher invocation rates (66% -> 98%)+- Added Codex agent support with AGENTS.md append+- OpenCode now writes to AGENTS.md instead of .opencode/rules/+- Selective rule content with explicit when-to-use/when-not-to-use guidancediff --git a/packages/cli/src/__tests__/setup.test.ts b/packages/cli/src/__tests__/setup.test.tsnew file mode 100644index 00000000..1c8de98a--- /dev/null+++ b/packages/cli/src/__tests__/setup.test.ts@@ -0,0 +1,353 @@+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";+import { mkdir, readFile, writeFile, rm } from "fs/promises";+import { join } from "path";+import { tmpdir } from "os";++const MOCK_MCP_RULE = "Use Context7 MCP to fetch docs.\n";+const MOCK_CLI_RULE = "Use the `ctx7` CLI to fetch docs.\n";++vi.stubGlobal(+ "fetch",+ vi.fn((url: string) => {+ if (url.includes("context7-mcp.md")) {+ return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_MCP_RULE) });+ }+ if (url.includes("context7-cli.md")) {+ return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_CLI_RULE) });+ }+ return Promise.resolve({ ok: false });+ })+);++import { getRuleContent } from "../setup/templates.js";+import {+ mergeServerEntry,+ readJsonConfig,+ writeJsonConfig,+ readTomlServerExists,+ buildTomlServerBlock,+ appendTomlServer,+ resolveMcpPath,+} from "../setup/mcp-writer.js";++describe("getRuleContent", () => {+ test("returns correct content per mode", async () => {+ expect(await getRuleContent("mcp", "claude")).toBe(MOCK_MCP_RULE);+ expect(await getRuleContent("cli", "claude")).toBe(MOCK_CLI_RULE);+ });++ test("only cursor gets alwaysApply frontmatter", async () => {+ const cursor = await getRuleContent("mcp", "cursor");+ expect(cursor).toContain("---\nalwaysApply: true\n---");+ expect(cursor).toContain(MOCK_MCP_RULE);++ for (const agent of ["claude", "codex", "opencode"]) {+ const content = await getRuleContent("mcp", agent);+ expect(content).not.toContain("alwaysApply");+ }+ });++ test("returns fallback content when all fetch URLs fail", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn(() => Promise.resolve({ ok: false }))+ );+ const content = await getRuleContent("mcp", "claude");+ expect(content).toContain("Context7 MCP");+ expect(content.length).toBeGreaterThan(100);++ vi.stubGlobal(+ "fetch",+ vi.fn((url: string) => {+ if (url.includes("context7-mcp.md"))+ return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_MCP_RULE) });+ if (url.includes("context7-cli.md"))+ return Promise.resolve({ ok: true, text: () => Promise.resolve(MOCK_CLI_RULE) });+ return Promise.resolve({ ok: false });+ })+ );+ });+});++describe("mergeServerEntry", () => {+ test("adds server to empty config", () => {+ const { config, alreadyExists } = mergeServerEntry({}, "mcpServers", "context7", {+ url: "https://mcp.context7.com/mcp",+ });+ expect(alreadyExists).toBe(false);+ expect((config.mcpServers as Record<string, unknown>).context7).toEqual({+ url: "https://mcp.context7.com/mcp",+ });+ });++ test("preserves existing servers when adding new one", () => {+ const { config } = mergeServerEntry(+ { mcpServers: { other: { url: "https://other.com" } } },+ "mcpServers",+ "context7",+ { url: "https://mcp.context7.com/mcp" }+ );+ const servers = config.mcpServers as Record<string, unknown>;+ expect(servers.context7).toBeTruthy();+ expect(servers.other).toEqual({ url: "https://other.com" });+ });++ test("does not overwrite existing server", () => {+ const existing = { mcpServers: { context7: { url: "https://old.com" } } };+ const { config, alreadyExists } = mergeServerEntry(existing, "mcpServers", "context7", {+ url: "https://new.com",+ });+ expect(alreadyExists).toBe(true);+ expect(config).toBe(existing);+ });++ test("works with opencode configKey 'mcp'", () => {+ const { config } = mergeServerEntry({}, "mcp", "context7", {+ type: "remote",+ url: "https://mcp.context7.com/mcp",+ });+ expect((config.mcp as Record<string, unknown>).context7).toEqual({+ type: "remote",+ url: "https://mcp.context7.com/mcp",+ });+ });+});++describe("readJsonConfig / writeJsonConfig", () => {+ let tempDir: string;++ beforeEach(async () => {+ tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`);+ await mkdir(tempDir, { recursive: true });+ });++ afterEach(async () => {+ await rm(tempDir, { recursive: true, force: true });+ });++ test("returns empty object for missing or empty file", async () => {+ expect(await readJsonConfig(join(tempDir, "nope.json"))).toEqual({});++ await writeFile(join(tempDir, "empty.json"), "", "utf-8");+ expect(await readJsonConfig(join(tempDir, "empty.json"))).toEqual({});+ });++ test("roundtrip write then read preserves data", async () => {+ const path = join(tempDir, "sub", "dir", "config.json");+ const data = { mcpServers: { context7: { url: "https://mcp.context7.com/mcp" } } };++ await writeJsonConfig(path, data);+ const result = await readJsonConfig(path);+ expect(result).toEqual(data);++ const raw = await readFile(path, "utf-8");+ expect(raw.endsWith("\n")).toBe(true);+ });+});++describe("JSONC support", () => {+ let tempDir: string;++ beforeEach(async () => {+ tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`);+ await mkdir(tempDir, { recursive: true });+ });++ afterEach(async () => {+ await rm(tempDir, { recursive: true, force: true });+ });++ test("readJsonConfig strips comments without corrupting URLs", async () => {+ const path = join(tempDir, "config.jsonc");+ await writeFile(+ path,+ `{+ // This is a comment+ "mcp": {},+ "$schema": "https://opencode.ai/config.json"+}`,+ "utf-8"+ );+ const result = await readJsonConfig(path);+ expect(result.$schema).toBe("https://opencode.ai/config.json");+ expect(result.mcp).toEqual({});+ });++ test("readJsonConfig handles block comments", async () => {+ const path = join(tempDir, "config.jsonc");+ await writeFile(path, '{ /* block */ "key": "value" }', "utf-8");+ const result = await readJsonConfig(path);+ expect(result.key).toBe("value");+ });++ test("resolveMcpPath returns .jsonc when it exists", async () => {+ const jsoncPath = join(tempDir, "opencode.jsonc");+ await writeFile(jsoncPath, "{}", "utf-8");+ const resolved = await resolveMcpPath(join(tempDir, "opencode.json"));+ expect(resolved).toBe(jsoncPath);+ });++ test("resolveMcpPath falls back to .json when no .jsonc", async () => {+ const jsonPath = join(tempDir, "opencode.json");+ const resolved = await resolveMcpPath(jsonPath);+ expect(resolved).toBe(jsonPath);+ });++ test("resolveMcpPath returns non-json paths unchanged", async () => {+ const tomlPath = join(tempDir, "config.toml");+ const resolved = await resolveMcpPath(tomlPath);+ expect(resolved).toBe(tomlPath);+ });+});++describe("TOML config", () => {+ let tempDir: string;++ beforeEach(async () => {+ tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`);+ await mkdir(tempDir, { recursive: true });+ });++ afterEach(async () => {+ await rm(tempDir, { recursive: true, force: true });+ });++ test("buildTomlServerBlock generates correct TOML", () => {+ const block = buildTomlServerBlock("context7", {+ url: "https://mcp.context7.com/mcp",+ });+ expect(block).toContain("[mcp_servers.context7]");+ expect(block).toContain('url = "https://mcp.context7.com/mcp"');+ });++ test("buildTomlServerBlock includes http_headers", () => {+ const block = buildTomlServerBlock("context7", {+ url: "https://mcp.context7.com/mcp",+ headers: { CONTEXT7_API_KEY: "sk-test" },+ });+ expect(block).toContain("[mcp_servers.context7]");+ expect(block).toContain("[mcp_servers.context7.http_headers]");+ expect(block).toContain('CONTEXT7_API_KEY = "sk-test"');+ expect(block).not.toContain("headers =");+ });++ test("readTomlServerExists detects existing server", async () => {+ const path = join(tempDir, "config.toml");+ await writeFile(path, '[mcp_servers.context7]\nurl = "https://test.com"\n', "utf-8");+ expect(await readTomlServerExists(path, "context7")).toBe(true);+ expect(await readTomlServerExists(path, "other")).toBe(false);+ });++ test("readTomlServerExists returns false for missing file", async () => {+ expect(await readTomlServerExists(join(tempDir, "nope.toml"), "context7")).toBe(false);+ });++ test("appendTomlServer appends to empty file", async () => {+ const path = join(tempDir, "config.toml");+ const { alreadyExists } = await appendTomlServer(path, "context7", {+ url: "https://mcp.context7.com/mcp",+ });+ expect(alreadyExists).toBe(false);+ const content = await readFile(path, "utf-8");+ expect(content).toContain("[mcp_servers.context7]");+ expect(content).toContain('url = "https://mcp.context7.com/mcp"');+ });++ test("appendTomlServer preserves existing config", async () => {+ const path = join(tempDir, "config.toml");+ await writeFile(path, 'model = "gpt-5"\n\n[mcp_servers.other]\nurl = "https://other.com"\n');+ await appendTomlServer(path, "context7", { url: "https://mcp.context7.com/mcp" });+ const content = await readFile(path, "utf-8");+ expect(content).toContain('model = "gpt-5"');+ expect(content).toContain("[mcp_servers.other]");+ expect(content).toContain("[mcp_servers.context7]");+ });++ test("appendTomlServer is idempotent", async () => {+ const path = join(tempDir, "config.toml");+ await appendTomlServer(path, "context7", { url: "https://mcp.context7.com/mcp" });+ const { alreadyExists } = await appendTomlServer(path, "context7", {+ url: "https://mcp.context7.com/mcp",+ });+ expect(alreadyExists).toBe(true);+ const content = await readFile(path, "utf-8");+ expect(content.match(/\[mcp_servers\.context7\]/g)?.length).toBe(1);+ });+});++describe("AGENTS.md append", () => {+ let tempDir: string;++ beforeEach(async () => {+ tempDir = join(tmpdir(), `ctx7-test-${Date.now()}`);+ await mkdir(tempDir, { recursive: true });+ });++ afterEach(async () => {+ await rm(tempDir, { recursive: true, force: true });+ });++ const marker = "<!-- context7 -->";+ const ruleContent = "Use ctx7 CLI for docs.\n";++ async function appendRule(filePath: string, existing?: string): Promise<string> {+ if (existing !== undefined) {+ await writeFile(filePath, existing, "utf-8");+ }++ const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");+ const section = `${marker}\n${ruleContent}${marker}`;++ let content = "";+ try {+ content = await readFile(filePath, "utf-8");+ } catch {+ // doesn't exist+ }++ if (content.includes(marker)) {+ const regex = new RegExp(`${escapedMarker}\\n[\\s\\S]*?${escapedMarker}`);+ await writeFile(filePath, content.replace(regex, section), "utf-8");+ } else {+ const separator =+ content.length > 0 && !content.endsWith("\n") ? "\n\n" : content.length > 0 ? "\n" : "";+ await mkdir(join(filePath, ".."), { recursive: true });+ await writeFile(filePath, content + separator + section + "\n", "utf-8");+ }++ return readFile(filePath, "utf-8");+ }++ test("creates new file cleanly", async () => {+ const result = await appendRule(join(tempDir, "AGENTS.md"));+ expect(result).toBe(`${marker}\n${ruleContent}${marker}\n`);+ expect(result[0]).not.toBe("\n");+ });++ test("appends to existing content with proper spacing", async () => {+ const withNewline = await appendRule(join(tempDir, "a.md"), "# Rules\n");+ expect(withNewline).toContain("# Rules\n\n<!-- context7 -->");++ const withoutNewline = await appendRule(join(tempDir, "b.md"), "No trailing newline");+ expect(withoutNewline).toContain("No trailing newline\n\n<!-- context7 -->");+ });++ test("is idempotent on re-run", async () => {+ const filePath = join(tempDir, "AGENTS.md");+ const first = await appendRule(filePath);+ const second = await appendRule(filePath);+ expect(second).toBe(first);+ expect(second.match(/<!-- context7 -->/g)?.length).toBe(2);+ });++ test("replaces section without affecting surrounding content", async () => {+ const filePath = join(tempDir, "AGENTS.md");+ await writeFile(filePath, `# Before\n\n${marker}\nold content\n${marker}\n\n# After\n`);++ const result = await appendRule(filePath);+ expect(result).toContain("# Before");+ expect(result).toContain("# After");+ expect(result).not.toContain("old content");+ expect(result).toContain(ruleContent);+ });+});diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.tsindex 859b740f..99f897ab 100644--- a/packages/cli/src/commands/setup.ts+++ b/packages/cli/src/commands/setup.ts@@ -2,7 +2,7 @@ import { Command } from "commander";import pc from "picocolors";import ora from "ora";import { select } from "@inquirer/prompts";-import { mkdir, writeFile } from "fs/promises";+import { mkdir, readFile, writeFile } from "fs/promises";import { dirname, join } from "path";import { randomBytes } from "crypto";@@ -11,7 +11,6 @@ import { checkboxWithHover } from "../utils/prompts.js";import { trackEvent } from "../utils/tracking.js";import { getBaseUrl, downloadSkill } from "../utils/api.js";import { installSkillFiles } from "../utils/installer.js";-import { promptForInstallTargets, getTargetDirs } from "../utils/ide.js";import { performLogin } from "./auth.js";import { saveTokens, getValidAccessToken } from "../utils/auth.js";import {@@ -23,12 +22,13 @@ import {getAgent,detectAgents,} from "../setup/agents.js";-import { RULE_CONTENT } from "../setup/templates.js";+import { getRuleContent } from "../setup/templates.js";import {readJsonConfig,mergeServerEntry,- mergeInstructions,writeJsonConfig,+ resolveMcpPath,+ appendTomlServer,} from "../setup/mcp-writer.js";type Scope = "global" | "project";@@ -40,6 +40,7 @@ interface SetupOptions {universal?: boolean;antigravity?: boolean;opencode?: boolean;+ codex?: boolean;project?: boolean;yes?: boolean;apiKey?: string;@@ -60,6 +61,7 @@ function getSelectedAgents(options: SetupOptions): SetupAgent[] {if (options.claude) agents.push("claude");if (options.cursor) agents.push("cursor");if (options.opencode) agents.push("opencode");+ if (options.codex) agents.push("codex");return agents;}@@ -72,6 +74,7 @@ export function registerSetupCommand(program: Command): void {.option("--universal", "Set up for Universal (.agents/skills)").option("--antigravity", "Set up for Antigravity (.agent/skills)").option("--opencode", "Set up for OpenCode")+ .option("--codex", "Set up for Codex").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")@@ -171,9 +174,14 @@ async function resolveCliAuth(apiKey?: string): Promise<void> {async function isAlreadyConfigured(agentName: SetupAgent, scope: Scope): Promise<boolean> {const agent = getAgent(agentName);- const mcpPath =+ const baseMcpPath =scope === "global" ? agent.mcp.globalPath : join(process.cwd(), agent.mcp.projectPath);+ const mcpPath = await resolveMcpPath(baseMcpPath);try {+ if (mcpPath.endsWith(".toml")) {+ const { readTomlServerExists } = await import("../setup/mcp-writer.js");+ return readTomlServerExists(mcpPath, "context7");+ }const existing = await readJsonConfig(mcpPath);const section = (existing[agent.mcp.configKey] as Record<string, unknown> | undefined) ?? {};return "context7" in section;@@ -199,10 +207,7 @@ async function promptAgents(scope: Scope, mode: SetupMode): Promise<SetupAgent[]return null;}- const message =- mode === "cli"- ? "Install find-docs skill for which agents?"- : "Which agents do you want to set up?";+ const message = "Which agents do you want to set up?";try {return await checkboxWithHover(@@ -240,6 +245,51 @@ async function resolveAgents(return selected;}+/** Install a rule for an agent, handling both "file" (standalone) and "append" (AGENTS.md) types. */+async function installRule(+ agentName: SetupAgent,+ mode: SetupMode,+ scope: Scope+): Promise<{ status: string; path: string }> {+ const agent = getAgent(agentName);+ const rule = agent.rule;+ const content = await getRuleContent(mode, agentName);++ if (rule.kind === "file") {+ 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, content, "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 setupAgent(agentName: SetupAgent,auth: AuthOptions,@@ -255,48 +305,51 @@ async function setupAgent(}> {const agent = getAgent(agentName);- const mcpPath =+ const baseMcpPath =scope === "global" ? agent.mcp.globalPath : join(process.cwd(), agent.mcp.projectPath);+ const mcpPath = await resolveMcpPath(baseMcpPath);let mcpStatus: string;try {- const existing = await readJsonConfig(mcpPath);- const { config, alreadyExists } = mergeServerEntry(- existing,- agent.mcp.configKey,- "context7",- agent.mcp.buildEntry(auth)- );-- if (alreadyExists) {- mcpStatus = "already configured";+ if (mcpPath.endsWith(".toml")) {+ const { alreadyExists } = await appendTomlServer(+ mcpPath,+ "context7",+ agent.mcp.buildEntry(auth)+ );+ mcpStatus = alreadyExists+ ? "already configured"+ : `configured with ${AUTH_MODE_LABELS[auth.mode]}`;} 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);+ 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]}`;+ }+ if (config !== existing) {+ await writeJsonConfig(mcpPath, config);+ }}} catch (err) {mcpStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;}- const rulePath =- scope === "global"- ? join(agent.rule.dir("global"), agent.rule.filename)- : join(process.cwd(), agent.rule.dir("project"), agent.rule.filename);-let ruleStatus: string;+ let rulePath: string;try {- await mkdir(dirname(rulePath), { recursive: true });- await writeFile(rulePath, RULE_CONTENT, "utf-8");- ruleStatus = "installed";+ const result = await installRule(agentName, "mcp", scope);+ ruleStatus = result.status;+ rulePath = result.path;} catch (err) {ruleStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;+ rulePath = "";}const skillDir =@@ -365,14 +418,46 @@ async function setupMcp(agents: SetupAgent[], options: SetupOptions, scope: ScoptrackEvent("install", { skills: ["/upstash/context7/context7-mcp"], ides: agents });}+async function setupCliAgent(+ agentName: SetupAgent,+ scope: Scope,+ downloadData: { files: 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 {+ await installSkillFiles("find-docs", downloadData.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, "cli", scope);+ 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 targets = await promptForInstallTargets({ ...options, global: !options.project }, false);- if (!targets) {- log.warn("Setup cancelled");- return;- }+ const scope: Scope = options.project ? "project" : "global";+ const agents = await resolveAgents(options, scope, "cli");+ if (agents.length === 0) return;log.blank();const spinner = ora("Downloading find-docs skill...").start();@@ -385,32 +470,38 @@ async function setupCli(options: SetupOptions): Promise<void> {spinner.succeed("Downloaded find-docs skill");- const targetDirs = getTargetDirs(targets);- const installSpinner = ora("Installing find-docs skill...").start();+ const installSpinner = ora("Installing...").start();+ const results: Array<{+ agent: string;+ skillPath: string;+ skillStatus: string;+ rulePath: string;+ ruleStatus: string;+ }> = [];- for (const dir of targetDirs) {- installSpinner.text = `Installing to ${dir}...`;- await installSkillFiles("find-docs", downloadData.files, dir);+ for (const agentName of agents) {+ installSpinner.text = `Setting up ${getAgent(agentName).displayName}...`;+ const r = await setupCliAgent(agentName, scope, downloadData);+ results.push({ agent: getAgent(agentName).displayName, ...r });}- installSpinner.stop();- log.blank();- log.plain(`${pc.green("✔")} Context7 CLI setup complete`);+ installSpinner.succeed("Context7 CLI setup complete");log.blank();- for (const dir of targetDirs) {- log.itemAdd(- `find-docs ${pc.dim("Guides your agent to fetch up-to-date library docs on demand using ctx7 CLI commands")}`- );- log.plain(` ${pc.dim(dir)}`);+ for (const r of results) {+ log.plain(` ${pc.bold(r.agent)}`);+ const skillIcon = r.skillStatus === "installed" ? pc.green("+") : pc.dim("~");+ log.plain(` ${skillIcon} Skill ${r.skillStatus}`);+ log.plain(` ${pc.dim(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();- log.plain(` ${pc.bold("Next steps")}`);- log.plain(` Ask your agent: ${pc.cyan(`"Use ctx7 CLI to look up React hooks"`)}`);- log.blank();trackEvent("setup", { mode: "cli" });- trackEvent("install", { skills: ["/upstash/context7/find-docs"], ides: targets.ides });+ trackEvent("install", { skills: ["/upstash/context7/find-docs"], ides: agents });}async function setupCommand(options: SetupOptions): Promise<void> {diff --git a/packages/cli/src/setup/agents.ts b/packages/cli/src/setup/agents.tsindex bfcd4d31..4dbc23db 100644--- a/packages/cli/src/setup/agents.ts+++ b/packages/cli/src/setup/agents.ts@@ -2,7 +2,7 @@ import { access } from "fs/promises";import { join } from "path";import { homedir } from "os";-export type SetupAgent = "claude" | "cursor" | "opencode";+export type SetupAgent = "claude" | "cursor" | "opencode" | "codex";export type AuthMode = "oauth" | "api-key";export interface AuthOptions {@@ -14,6 +14,7 @@ export const SETUP_AGENT_NAMES: Record<SetupAgent, string> = {claude: "Claude Code",cursor: "Cursor",opencode: "OpenCode",+ codex: "Codex",};export const AUTH_MODE_LABELS: Record<AuthMode, string> = {@@ -23,6 +24,14 @@ export const AUTH_MODE_LABELS: Record<AuthMode, string> = {const MCP_BASE_URL = "https://mcp.context7.com";+export type RuleType =+ | {+ kind: "file";+ dir: (scope: "project" | "global") => string;+ filename: string;+ }+ | { kind: "append"; file: (scope: "project" | "global") => string; sectionMarker: string };+export interface AgentConfig {name: SetupAgent;displayName: string;@@ -32,12 +41,7 @@ export interface AgentConfig {configKey: string;buildEntry: (auth: AuthOptions) => Record<string, unknown>;};- rule: {- dir: (scope: "project" | "global") => string;- filename: string;- /** When set, the rule path is registered in the agent's config `instructions` array */- instructionsGlob?: (scope: "project" | "global") => string;- };+ rule: RuleType;skill: {name: string;dir: (scope: "project" | "global") => string;@@ -70,6 +74,7 @@ const agents: Record<SetupAgent, AgentConfig> = {buildEntry: (auth) => withHeaders({ type: "http", url: mcpUrl(auth) }, auth),},rule: {+ kind: "file",dir: (scope) =>scope === "global" ? join(homedir(), ".claude", "rules") : join(".claude", "rules"),filename: "context7.md",@@ -95,6 +100,7 @@ const agents: Record<SetupAgent, AgentConfig> = {buildEntry: (auth) => withHeaders({ url: mcpUrl(auth) }, auth),},rule: {+ kind: "file",dir: (scope) =>scope === "global" ? join(homedir(), ".cursor", "rules") : join(".cursor", "rules"),filename: "context7.mdc",@@ -114,21 +120,16 @@ const agents: Record<SetupAgent, AgentConfig> = {name: "opencode",displayName: "OpenCode",mcp: {- projectPath: ".opencode.json",+ projectPath: "opencode.json",globalPath: join(homedir(), ".config", "opencode", "opencode.json"),configKey: "mcp",buildEntry: (auth) => withHeaders({ type: "remote", url: mcpUrl(auth), enabled: true }, auth),},rule: {- dir: (scope) =>- scope === "global"- ? join(homedir(), ".config", "opencode", "rules")- : join(".opencode", "rules"),- filename: "context7.md",- instructionsGlob: (scope) =>- scope === "global"- ? join(homedir(), ".config", "opencode", "rules", "*.md")- : ".opencode/rules/*.md",+ kind: "append",+ file: (scope) =>+ scope === "global" ? join(homedir(), ".config", "opencode", "AGENTS.md") : "AGENTS.md",+ sectionMarker: "<!-- context7 -->",},skill: {name: "context7-mcp",@@ -140,6 +141,37 @@ const agents: Record<SetupAgent, AgentConfig> = {globalPaths: [join(homedir(), ".config", "opencode")],},},++ codex: {+ name: "codex",+ displayName: "Codex",+ mcp: {+ projectPath: join(".codex", "config.toml"),+ globalPath: join(homedir(), ".codex", "config.toml"),+ configKey: "mcp_servers",+ buildEntry: (auth) => {+ const entry: Record<string, unknown> = { type: "http", url: mcpUrl(auth) };+ if (auth.mode === "api-key" && auth.apiKey) {+ entry.headers = { CONTEXT7_API_KEY: auth.apiKey };+ }+ return entry;+ },+ },+ rule: {+ kind: "append",+ file: (scope) => (scope === "global" ? join(homedir(), ".codex", "AGENTS.md") : "AGENTS.md"),+ sectionMarker: "<!-- context7 -->",+ },+ skill: {+ name: "context7-mcp",+ dir: (scope) =>+ scope === "global" ? join(homedir(), ".agents", "skills") : join(".agents", "skills"),+ },+ detect: {+ projectPaths: [".codex"],+ globalPaths: [join(homedir(), ".codex")],+ },+ },};export function getAgent(name: SetupAgent): AgentConfig {diff --git a/packages/cli/src/setup/mcp-writer.ts b/packages/cli/src/setup/mcp-writer.tsindex abbb03ba..e9431cd0 100644--- a/packages/cli/src/setup/mcp-writer.ts+++ b/packages/cli/src/setup/mcp-writer.ts@@ -1,6 +1,31 @@-import { readFile, writeFile, mkdir } from "fs/promises";+import { access, readFile, writeFile, mkdir } from "fs/promises";import { dirname } from "path";+function stripJsonComments(text: string): string {+ let result = "";+ let i = 0;+ while (i < text.length) {+ if (text[i] === '"') {+ const start = i++;+ while (i < text.length && text[i] !== '"') {+ if (text[i] === "\\") i++;+ i++;+ }+ result += text.slice(start, ++i);+ } else if (text[i] === "/" && text[i + 1] === "/") {+ i += 2;+ while (i < text.length && text[i] !== "\n") i++;+ } else if (text[i] === "/" && text[i + 1] === "*") {+ i += 2;+ while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;+ i += 2;+ } else {+ result += text[i++];+ }+ }+ return result;+}+export async function readJsonConfig(filePath: string): Promise<Record<string, unknown>> {let raw: string;try {@@ -12,7 +37,7 @@ export async function readJsonConfig(filePath: string): Promise<Record<string, uraw = raw.trim();if (!raw) return {};- return JSON.parse(raw) as Record<string, unknown>;+ return JSON.parse(stripJsonComments(raw)) as Record<string, unknown>;}export function mergeServerEntry(@@ -39,13 +64,17 @@ export function mergeServerEntry(};}-export function mergeInstructions(- config: Record<string, unknown>,- glob: string-): Record<string, unknown> {- const instructions = (config.instructions as string[] | undefined) ?? [];- if (instructions.includes(glob)) return config;- return { ...config, instructions: [...instructions, glob] };+export async function resolveMcpPath(basePath: string): Promise<string> {+ if (basePath.endsWith(".json")) {+ const jsoncPath = basePath.replace(/\.json$/, ".jsonc");+ try {+ await access(jsoncPath);+ return jsoncPath;+ } catch {+ return basePath;+ }+ }+ return basePath;}export async function writeJsonConfig(@@ -55,3 +84,57 @@ export async function writeJsonConfig(await mkdir(dirname(filePath), { recursive: true });await writeFile(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");}++export async function readTomlServerExists(filePath: string, serverName: string): Promise<boolean> {+ try {+ const raw = await readFile(filePath, "utf-8");+ return raw.includes(`[mcp_servers.${serverName}]`);+ } catch {+ return false;+ }+}++export function buildTomlServerBlock(serverName: string, entry: Record<string, unknown>): string {+ const lines: string[] = [`[mcp_servers.${serverName}]`];+ const headers = entry.headers as Record<string, string> | undefined;++ for (const [key, value] of Object.entries(entry)) {+ if (key === "headers") continue;+ lines.push(`${key} = ${JSON.stringify(value)}`);+ }++ if (headers && Object.keys(headers).length > 0) {+ lines.push("");+ lines.push(`[mcp_servers.${serverName}.http_headers]`);+ for (const [key, value] of Object.entries(headers)) {+ lines.push(`${key} = ${JSON.stringify(value)}`);+ }+ }++ return lines.join("\n") + "\n";+}++export async function appendTomlServer(+ filePath: string,+ serverName: string,+ entry: Record<string, unknown>+): Promise<{ alreadyExists: boolean }> {+ if (await readTomlServerExists(filePath, serverName)) {+ return { alreadyExists: true };+ }++ const block = buildTomlServerBlock(serverName, entry);++ let existing = "";+ try {+ existing = await readFile(filePath, "utf-8");+ } catch {+ // File doesn't exist+ }++ 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 + block, "utf-8");+ return { alreadyExists: false };+}diff --git a/packages/cli/src/setup/templates.ts b/packages/cli/src/setup/templates.tsindex 819fa570..63ae24ff 100644--- a/packages/cli/src/setup/templates.ts+++ b/packages/cli/src/setup/templates.ts@@ -1,13 +1,57 @@-export const RULE_CONTENT = `----alwaysApply: true----+const GITHUB_RAW_URLS = [+ "https://raw.githubusercontent.com/upstash/context7/master/rules",+ "https://raw.githubusercontent.com/upstash/context7/main/rules",+];-When working with libraries, frameworks, or APIs — 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.+const FALLBACK_MCP = `Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.++Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.++## Steps++1. \`resolve-library-id\` with the library name and the user's question+2. Pick the best match by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). Use version-specific IDs when the user mentions a version+3. \`query-docs\` with the selected library ID and the user's full question (not single words)+4. Answer using the fetched docs+`;++const FALLBACK_CLI = `Use the \`ctx7\` CLI to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.++Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.## Steps-1. Call \`resolve-library-id\` with the library name and the user's question-2. Pick the best match — 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 — include code examples and cite the version+1. Resolve library: \`npx ctx7@latest library <name> "<user's question>"\`+2. Pick the best match by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try the full name with punctuation (e.g., "next.js" not "nextjs")+3. Fetch docs: \`npx ctx7@latest docs <libraryId> "<user's question>"\`+4. Answer using the fetched documentation++You MUST call \`library\` first to get a valid ID (format: \`/org/project\`) unless the user provides one directly. Use the user's full question as the query -- specific and detailed queries return better results than vague single words. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries.++For version-specific docs, use \`/org/project/version\` from the \`library\` output (e.g., \`/vercel/next.js/v14.3.0\`).++If a command fails with a quota error, inform the user and suggest \`npx ctx7@latest login\` or setting \`CONTEXT7_API_KEY\` env var for higher limits. Do not silently fall back to training data.`;++const CURSOR_FRONTMATTER = `---\nalwaysApply: true\n---\n\n`;++export type RuleMode = "mcp" | "cli";++async function fetchRule(filename: string, fallback: string): Promise<string> {+ for (const base of GITHUB_RAW_URLS) {+ try {+ const res = await fetch(`${base}/${filename}`);+ if (res.ok) return await res.text();+ } catch {+ continue;+ }+ }+ return fallback;+}++export async function getRuleContent(mode: RuleMode, agent: string): Promise<string> {+ const [filename, fallback] =+ mode === "mcp" ? ["context7-mcp.md", FALLBACK_MCP] : ["context7-cli.md", FALLBACK_CLI];+ const body = await fetchRule(filename, fallback);+ return agent === "cursor" ? `${CURSOR_FRONTMATTER}${body}` : body;+}diff --git a/packages/cli/src/utils/prompts.ts b/packages/cli/src/utils/prompts.tsindex 11e75b6d..c6a09ed0 100644--- a/packages/cli/src/utils/prompts.ts+++ b/packages/cli/src/utils/prompts.ts@@ -80,16 +80,21 @@ export async function checkboxWithHover<T>();const values = choices.map((c) => c.value);const totalItems = values.length;- let cursorPosition = 0;+ let cursorPosition = choices.findIndex((c) => !c.disabled);+ if (cursorPosition < 0) cursorPosition = 0;// Default getName assumes object has 'name' propertyconst getName = options?.getName ?? ((v: T) => (v as { name: string }).name);const keypressHandler = (_str: string | undefined, key: readline.Key) => {- if (key.name === "up" && cursorPosition > 0) {- cursorPosition--;- } else if (key.name === "down" && cursorPosition < totalItems - 1) {- cursorPosition++;+ if (key.name === "up") {+ let next = cursorPosition - 1;+ while (next >= 0 && choices[next].disabled) next--;+ if (next >= 0) cursorPosition = next;+ } else if (key.name === "down") {+ let next = cursorPosition + 1;+ while (next < totalItems && choices[next].disabled) next++;+ if (next < totalItems) cursorPosition = next;}};diff --git a/rules/context7-cli.md b/rules/context7-cli.mdnew file mode 100644index 00000000..6986a4a5--- /dev/null+++ b/rules/context7-cli.md@@ -0,0 +1,16 @@+Use the `ctx7` CLI to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.++Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.++## Steps++1. Resolve library: `npx ctx7@latest library <name> "<user's question>"`+2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question)+3. Fetch docs: `npx ctx7@latest docs <libraryId> "<user's question>"`+4. Answer using the fetched documentation++You MUST call `library` first to get a valid ID unless the user provides one directly in `/org/project` format. Use the user's full question as the query -- specific and detailed queries return better results than vague single words. Do not run more than 3 commands per question. Do not include sensitive information (API keys, passwords, credentials) in queries.++For version-specific docs, use `/org/project/version` from the `library` output (e.g., `/vercel/next.js/v14.3.0`).++If a command fails with a quota error, inform the user and suggest `npx ctx7@latest login` or setting `CONTEXT7_API_KEY` env var for higher limits. Do not silently fall back to training data.diff --git a/rules/context7-mcp.md b/rules/context7-mcp.mdnew file mode 100644index 00000000..fe994d41--- /dev/null+++ b/rules/context7-mcp.md@@ -0,0 +1,10 @@+Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.++Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.++## Steps++1. Always start with `resolve-library-id` using the library name and the user's question, unless the user provides an exact library ID in `/org/project` format+2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question). Use version-specific IDs when the user mentions a version+3. `query-docs` with the selected library ID and the user's full question (not single words)+4. Answer using the fetched docsdiff --git a/skills/find-docs/SKILL.md b/skills/find-docs/SKILL.mdindex 97c9b398..99e5c6e1 100644--- a/skills/find-docs/SKILL.md+++ b/skills/find-docs/SKILL.md@@ -1,25 +1,20 @@---name: find-docsdescription: >-- Retrieves authoritative, up-to-date technical documentation, API references,- configuration details, and code examples for any developer technology.-- Use this skill whenever answering technical questions or writing code that- interacts with external technologies. This includes libraries, frameworks,- programming languages, SDKs, APIs, CLI tools, cloud services, infrastructure- tools, and developer platforms.-- Common scenarios:- - looking up API endpoints, classes, functions, or method parameters- - checking configuration options or CLI commands- - answering "how do I" technical questions- - generating code that uses a specific library or service- - debugging issues related to frameworks, SDKs, or APIs- - retrieving setup instructions, examples, or migration guides- - verifying version-specific behavior or breaking changes-- Prefer this skill whenever documentation accuracy matters or when model- knowledge may be outdated.+ Retrieves up-to-date documentation, API references, and code examples for any+ developer technology. Use this skill whenever the user asks about a specific+ library, framework, SDK, CLI tool, or cloud service -- even for well-known ones+ like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. Your+ training data may not reflect recent API changes or version updates.++ Always use for: API syntax questions, configuration options, version migration+ issues, "how do I" questions mentioning a library name, debugging that involves+ library-specific behavior, setup instructions, and CLI tool usage.++ Use even when you think you know the answer -- do not rely on training data+ for API details, signatures, or configuration options as they are frequently+ outdated. Always verify against current docs. Prefer this over web search for+ library documentation and API details.---# Documentation Lookup