ctx7 0.4.1 → 0.4.3

package/dist/index.js

@@ -9,7 +9,7 @@ import figlet from "figlet";
 import pc7 from "picocolors";
 import ora3 from "ora";
 import { readdir, rm as rm2 } from "fs/promises";
-import { join as join7 } from "path";
+import { join as join6 } from "path";
 
 // src/utils/parse-input.ts
 function parseSkillInput(input2) {
@@ -30,6 +30,31 @@ function parseSkillInput(input2) {
 
 // src/utils/github.ts
 import { execSync } from "child_process";
+
+// src/utils/skill-name.ts
+import { resolve, dirname, basename } from "path";
+var SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+function isSafeSkillName(name) {
+  if (typeof name !== "string") return false;
+  if (name.length === 0 || name.length > 128) return false;
+  if (name === "." || name === "..") return false;
+  if (name.includes("\0")) return false;
+  if (!SAFE_NAME.test(name)) return false;
+  return true;
+}
+function assertSkillNameInRoot(skillsRoot, skillName) {
+  if (!isSafeSkillName(skillName)) {
+    throw new Error(`Unsafe skill name: ${JSON.stringify(skillName)}`);
+  }
+  const root = resolve(skillsRoot);
+  const target = resolve(root, skillName);
+  if (dirname(target) !== root || basename(target) !== skillName) {
+    throw new Error(`Skill name "${skillName}" escapes the skills root`);
+  }
+  return target;
+}
+
+// src/utils/github.ts
 var GITHUB_API = "https://api.github.com";
 var GITHUB_RAW = "https://raw.githubusercontent.com";
 function parseGitHubUrl(url) {
@@ -85,7 +110,8 @@ function parseSkillFrontmatter(content) {
   const frontmatter = frontmatterMatch[1];
   const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
   if (!nameMatch) return null;
-  const name = nameMatch[1].trim().replace(/^["']|["']$/g, "").toLowerCase();
+  const name = nameMatch[1].trim().replace(/^["']|["']$/g, "");
+  if (!isSafeSkillName(name)) return null;
   let description = "";
   const multiLineMatch = frontmatter.match(/^description:\s*([|>])-?\s*$/m);
   if (multiLineMatch) {
@@ -176,7 +202,7 @@ async function listSkillsFromGitHub(project) {
 async function getSkillFromGitHub(project, skillName) {
   const result = await listSkillsFromGitHub(project);
   if (result.status !== "ok") return result;
-  const skill = result.skills.find((s) => s.name === skillName.toLowerCase());
+  const skill = result.skills.find((s) => s.name.toLowerCase() === skillName.toLowerCase());
   return { ...result, skill };
 }
 async function downloadSkillFromGitHub(skill) {
@@ -226,8 +252,8 @@ async function downloadSkillFromGitHub(skill) {
 // src/constants.ts
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
-import { dirname, join } from "path";
-var __dirname = dirname(fileURLToPath(import.meta.url));
+import { dirname as dirname2, join } from "path";
+var __dirname = dirname2(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
 var VERSION = pkg.version;
 var NAME = pkg.name;
@@ -518,7 +544,7 @@ var log = {
 import pc3 from "picocolors";
 import { select, confirm } from "@inquirer/prompts";
 import { access } from "fs/promises";
-import { join as join2, dirname as dirname2 } from "path";
+import { join as join2, dirname as dirname3 } from "path";
 import { homedir } from "os";
 
 // src/utils/prompts.ts
@@ -661,7 +687,7 @@ async function detectVendorSpecificAgents(scope) {
   const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS;
   const detected = [];
   for (const ide of VENDOR_SPECIFIC_AGENTS) {
-    const parentDir = dirname2(pathMap[ide]);
+    const parentDir = dirname3(pathMap[ide]);
     try {
       await access(join2(baseDir, parentDir));
       detected.push(ide);
@@ -692,7 +718,7 @@ async function promptForInstallTargets(options, forceUniversal = true) {
   const detectedVendor = await detectVendorSpecificAgents(scope);
   let hasUniversalDir = false;
   try {
-    await access(join2(baseDir, dirname2(universalPath)));
+    await access(join2(baseDir, dirname3(universalPath)));
     hasUniversalDir = true;
   } catch {
   }
@@ -859,21 +885,21 @@ function getTargetDirFromSelection(ide, scope) {
 
 // src/utils/installer.ts
 import { mkdir, writeFile, rm, symlink, lstat } from "fs/promises";
-import { join as join3, resolve, dirname as dirname3 } from "path";
-async function installSkillFiles(skillName, files, targetDir) {
-  const skillDir = resolve(targetDir, skillName);
+import { resolve as resolve2, dirname as dirname4 } from "path";
+async function installSkillFiles(skillName, files, skillsRoot) {
+  const skillDir = assertSkillNameInRoot(skillsRoot, skillName);
   for (const file of files) {
-    const filePath = resolve(skillDir, file.path);
+    const filePath = resolve2(skillDir, file.path);
     if (!filePath.startsWith(skillDir + "/") && !filePath.startsWith(skillDir + "\\") && filePath !== skillDir) {
       throw new Error(`Skill file path "${file.path}" resolves outside the target directory`);
     }
-    const fileDir = dirname3(filePath);
+    const fileDir = dirname4(filePath);
     await mkdir(fileDir, { recursive: true });
     await writeFile(filePath, file.content);
   }
 }
-async function symlinkSkill(skillName, sourcePath, targetDir) {
-  const targetPath = join3(targetDir, skillName);
+async function symlinkSkill(skillName, sourcePath, skillsRoot) {
+  const targetPath = assertSkillNameInRoot(skillsRoot, skillName);
   try {
     const stats = await lstat(targetPath);
     if (stats.isSymbolicLink() || stats.isDirectory()) {
@@ -881,7 +907,7 @@ async function symlinkSkill(skillName, sourcePath, targetDir) {
     }
   } catch {
   }
-  await mkdir(targetDir, { recursive: true });
+  await mkdir(skillsRoot, { recursive: true });
   await symlink(sourcePath, targetPath);
 }
 
@@ -900,7 +926,7 @@ function trackEvent(event, data) {
 import pc6 from "picocolors";
 import ora2 from "ora";
 import { mkdir as mkdir2, writeFile as writeFile2, readFile, unlink } from "fs/promises";
-import { join as join5 } from "path";
+import { join as join4 } from "path";
 import { homedir as homedir3 } from "os";
 import { spawn } from "child_process";
 import { input, select as select2 } from "@inquirer/prompts";
@@ -997,11 +1023,11 @@ function createCallbackServer(expectedState) {
   let resolveResult;
   let rejectResult;
   let serverInstance = null;
-  const portPromise = new Promise((resolve2) => {
-    resolvePort = resolve2;
+  const portPromise = new Promise((resolve3) => {
+    resolvePort = resolve3;
   });
-  const resultPromise = new Promise((resolve2, reject) => {
-    resolveResult = resolve2;
+  const resultPromise = new Promise((resolve3, reject) => {
+    resolveResult = resolve3;
     rejectResult = reject;
   });
   const server = http.createServer((req, res) => {
@@ -1681,19 +1707,19 @@ async function generateCommand(options) {
       log.blank();
     };
     const openInEditor = async () => {
-      const previewDir = join5(homedir3(), ".context7", "previews");
+      const previewDir = join4(homedir3(), ".context7", "previews");
       await mkdir2(previewDir, { recursive: true });
-      previewFile = join5(previewDir, `${skillName}.md`);
+      previewFile = join4(previewDir, `${skillName}.md`);
       if (!previewFileWritten) {
         await writeFile2(previewFile, generatedContent, "utf-8");
         previewFileWritten = true;
       }
       const editor = process.env.EDITOR || "open";
-      await new Promise((resolve2) => {
+      await new Promise((resolve3) => {
         const child = spawn(editor, [previewFile], {
           stdio: "inherit"
         });
-        child.on("close", () => resolve2());
+        child.on("close", () => resolve3());
       });
     };
     const syncFromPreviewFile = async () => {
@@ -1702,7 +1728,7 @@ async function generateCommand(options) {
       }
     };
     showPreview();
-    await new Promise((resolve2) => setTimeout(resolve2, 100));
+    await new Promise((resolve3) => setTimeout(resolve3, 100));
     try {
       let action;
       while (true) {
@@ -1759,8 +1785,8 @@ async function generateCommand(options) {
     if (options.output && !targetDir.includes("/.config/") && !targetDir.startsWith(homedir3())) {
       finalDir = targetDir.replace(process.cwd(), options.output);
     }
-    const skillDir = join5(finalDir, skillName);
-    const skillPath = join5(skillDir, "SKILL.md");
+    const skillDir = join4(finalDir, skillName);
+    const skillPath = join4(skillDir, "SKILL.md");
     try {
       await mkdir2(skillDir, { recursive: true });
       await writeFile2(skillPath, generatedContent, "utf-8");
@@ -1779,7 +1805,7 @@ async function generateCommand(options) {
     log.blank();
     console.log(pc6.yellow("Fix permissions with:"));
     for (const dir of failedDirs) {
-      const parentDir = join5(dir, "..");
+      const parentDir = join4(dir, "..");
       console.log(pc6.dim(`  sudo chown -R $(whoami) "${parentDir}"`));
     }
     log.blank();
@@ -1801,7 +1827,7 @@ import { homedir as homedir4 } from "os";
 
 // src/utils/deps.ts
 import { readFile as readFile2 } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join5 } from "path";
 async function readFileOrNull(path2) {
   try {
     return await readFile2(path2, "utf-8");
@@ -1813,7 +1839,7 @@ function isSkippedLocally(name) {
   return name.startsWith("@types/");
 }
 async function parsePackageJson(cwd) {
-  const content = await readFileOrNull(join6(cwd, "package.json"));
+  const content = await readFileOrNull(join5(cwd, "package.json"));
   if (!content) return [];
   try {
     const pkg2 = JSON.parse(content);
@@ -1830,7 +1856,7 @@ async function parsePackageJson(cwd) {
   }
 }
 async function parseRequirementsTxt(cwd) {
-  const content = await readFileOrNull(join6(cwd, "requirements.txt"));
+  const content = await readFileOrNull(join5(cwd, "requirements.txt"));
   if (!content) return [];
   const deps = [];
   for (const line of content.split("\n")) {
@@ -1844,7 +1870,7 @@ async function parseRequirementsTxt(cwd) {
   return deps;
 }
 async function parsePyprojectToml(cwd) {
-  const content = await readFileOrNull(join6(cwd, "pyproject.toml"));
+  const content = await readFileOrNull(join5(cwd, "pyproject.toml"));
   if (!content) return [];
   const deps = [];
   const seen = /* @__PURE__ */ new Set();
@@ -2106,7 +2132,7 @@ ${headerLine}`,
         }
         throw dirErr;
       }
-      const primarySkillDir = join7(primaryDir, skill.name);
+      const primarySkillDir = join6(primaryDir, skill.name);
       for (const targetDir of symlinkDirs) {
         try {
           await symlinkSkill(skill.name, primarySkillDir, targetDir);
@@ -2134,7 +2160,7 @@ ${headerLine}`,
     log.blank();
     log.warn("Fix permissions with:");
     for (const dir of failedDirs) {
-      const parentDir = join7(dir, "..");
+      const parentDir = join6(dir, "..");
       log.dim(`  sudo chown -R $(whoami) "${parentDir}"`);
     }
     log.blank();
@@ -2259,7 +2285,7 @@ ${headerLine}`,
         }
         throw dirErr;
       }
-      const primarySkillDir = join7(primaryDir, skill.name);
+      const primarySkillDir = join6(primaryDir, skill.name);
       for (const targetDir of symlinkDirs) {
         try {
           await symlinkSkill(skill.name, primarySkillDir, targetDir);
@@ -2287,7 +2313,7 @@ ${headerLine}`,
     log.blank();
     log.warn("Fix permissions with:");
     for (const dir of failedDirs) {
-      const parentDir = join7(dir, "..");
+      const parentDir = join6(dir, "..");
       log.dim(`  sudo chown -R $(whoami) "${parentDir}"`);
     }
     log.blank();
@@ -2314,7 +2340,7 @@ async function listCommand(options) {
   if (hasExplicitIdeOption(options)) {
     const ides = getSelectedIdes(options);
     for (const ide of ides) {
-      const dir = ide === "universal" ? join7(baseDir, scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH) : join7(baseDir, (scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS)[ide]);
+      const dir = ide === "universal" ? join6(baseDir, scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH) : join6(baseDir, (scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS)[ide]);
       const label = ide === "universal" ? UNIVERSAL_AGENTS_LABEL : IDE_NAMES[ide];
       const skills = await scanDir(dir);
       if (skills.length > 0) {
@@ -2323,14 +2349,14 @@ async function listCommand(options) {
     }
   } else {
     const universalPath = scope === "global" ? UNIVERSAL_SKILLS_GLOBAL_PATH : UNIVERSAL_SKILLS_PATH;
-    const universalDir = join7(baseDir, universalPath);
+    const universalDir = join6(baseDir, universalPath);
     const universalSkills = await scanDir(universalDir);
     if (universalSkills.length > 0) {
       results.push({ label: UNIVERSAL_AGENTS_LABEL, path: universalPath, skills: universalSkills });
     }
     for (const ide of VENDOR_SPECIFIC_AGENTS) {
       const pathMap = scope === "global" ? IDE_GLOBAL_PATHS : IDE_PATHS;
-      const dir = join7(baseDir, pathMap[ide]);
+      const dir = join6(baseDir, pathMap[ide]);
       const skills = await scanDir(dir);
       if (skills.length > 0) {
         results.push({ label: IDE_NAMES[ide], path: pathMap[ide], skills });
@@ -2358,7 +2384,13 @@ async function removeCommand(name, options) {
     return;
   }
   const skillsDir = getTargetDirFromSelection(target.ide, target.scope);
-  const skillPath = join7(skillsDir, name);
+  let skillPath;
+  try {
+    skillPath = assertSkillNameInRoot(skillsDir, name);
+  } catch {
+    log.error(`Invalid skill name: ${name}`);
+    return;
+  }
   try {
     await rm2(skillPath, { recursive: true });
     log.success(`Removed skill: ${name}`);
@@ -2539,7 +2571,7 @@ ${headerLine}`,
         }
         throw dirErr;
       }
-      const primarySkillDir = join7(primaryDir, skill.name);
+      const primarySkillDir = join6(primaryDir, skill.name);
       for (const targetDir of symlinkDirs) {
         try {
           await symlinkSkill(skill.name, primarySkillDir, targetDir);
@@ -2567,7 +2599,7 @@ ${headerLine}`,
     log.blank();
     log.warn("Fix permissions with:");
     for (const dir of failedDirs) {
-      const parentDir = join7(dir, "..");
+      const parentDir = join6(dir, "..");
       log.dim(`  sudo chown -R $(whoami) "${parentDir}"`);
     }
     log.blank();
@@ -2584,12 +2616,12 @@ import pc8 from "picocolors";
 import ora4 from "ora";
 import { select as select3 } from "@inquirer/prompts";
 import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname5, join as join9 } from "path";
+import { dirname as dirname6, 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 join8 } from "path";
+import { join as join7 } from "path";
 import { homedir as homedir5 } from "os";
 var SETUP_AGENT_NAMES = {
   claude: "Claude Code",
@@ -2603,6 +2635,26 @@ var AUTH_MODE_LABELS = {
   "api-key": "API Key"
 };
 var MCP_BASE_URL = "https://mcp.context7.com";
+var STDIO_PACKAGE = "@upstash/context7-mcp";
+function stdioArgs(auth) {
+  const args = ["-y", STDIO_PACKAGE];
+  if (auth.mode === "api-key" && auth.apiKey) {
+    args.push("--api-key", auth.apiKey);
+  }
+  return args;
+}
+function stdioEntry(auth) {
+  return { command: "npx", args: stdioArgs(auth) };
+}
+function claudeConfigDir() {
+  return process.env.CLAUDE_CONFIG_DIR || join7(homedir5(), ".claude");
+}
+function claudeGlobalMcpPath() {
+  if (process.env.CLAUDE_CONFIG_DIR) {
+    return join7(claudeConfigDir(), ".claude.json");
+  }
+  return join7(homedir5(), ".claude.json");
+}
 function mcpUrl(auth) {
   return auth.mode === "oauth" ? `${MCP_BASE_URL}/mcp/oauth` : `${MCP_BASE_URL}/mcp`;
 }
@@ -2618,45 +2670,49 @@ var agents = {
     displayName: "Claude Code",
     mcp: {
       projectPaths: [".mcp.json"],
-      globalPaths: [join8(homedir5(), ".claude.json")],
+      get globalPaths() {
+        return [claudeGlobalMcpPath()];
+      },
       configKey: "mcpServers",
-      buildEntry: (auth) => withHeaders({ type: "http", url: mcpUrl(auth) }, auth)
+      buildEntry: (auth, transport) => transport === "stdio" ? stdioEntry(auth) : withHeaders({ type: "http", url: mcpUrl(auth) }, auth)
     },
     rule: {
       kind: "file",
-      dir: (scope) => scope === "global" ? join8(homedir5(), ".claude", "rules") : join8(".claude", "rules"),
+      dir: (scope) => scope === "global" ? join7(claudeConfigDir(), "rules") : join7(".claude", "rules"),
       filename: "context7.md"
     },
     skill: {
       name: "context7-mcp",
-      dir: (scope) => scope === "global" ? join8(homedir5(), ".claude", "skills") : join8(".claude", "skills")
+      dir: (scope) => scope === "global" ? join7(claudeConfigDir(), "skills") : join7(".claude", "skills")
     },
     detect: {
       projectPaths: [".mcp.json", ".claude"],
-      globalPaths: [join8(homedir5(), ".claude")]
+      get globalPaths() {
+        return [claudeConfigDir()];
+      }
     }
   },
   cursor: {
     name: "cursor",
     displayName: "Cursor",
     mcp: {
-      projectPaths: [join8(".cursor", "mcp.json")],
-      globalPaths: [join8(homedir5(), ".cursor", "mcp.json")],
+      projectPaths: [join7(".cursor", "mcp.json")],
+      globalPaths: [join7(homedir5(), ".cursor", "mcp.json")],
       configKey: "mcpServers",
-      buildEntry: (auth) => withHeaders({ url: mcpUrl(auth) }, auth)
+      buildEntry: (auth, transport) => transport === "stdio" ? stdioEntry(auth) : withHeaders({ url: mcpUrl(auth) }, auth)
     },
     rule: {
       kind: "file",
-      dir: (scope) => scope === "global" ? join8(homedir5(), ".cursor", "rules") : join8(".cursor", "rules"),
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".cursor", "rules") : join7(".cursor", "rules"),
       filename: "context7.mdc"
     },
     skill: {
       name: "context7-mcp",
-      dir: (scope) => scope === "global" ? join8(homedir5(), ".cursor", "skills") : join8(".cursor", "skills")
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".cursor", "skills") : join7(".cursor", "skills")
     },
     detect: {
       projectPaths: [".cursor"],
-      globalPaths: [join8(homedir5(), ".cursor")]
+      globalPaths: [join7(homedir5(), ".cursor")]
     }
   },
   opencode: {
@@ -2665,78 +2721,72 @@ var agents = {
     mcp: {
       projectPaths: ["opencode.json", "opencode.jsonc", ".opencode.json", ".opencode.jsonc"],
       globalPaths: [
-        join8(homedir5(), ".config", "opencode", "opencode.json"),
-        join8(homedir5(), ".config", "opencode", "opencode.jsonc"),
-        join8(homedir5(), ".config", "opencode", ".opencode.json"),
-        join8(homedir5(), ".config", "opencode", ".opencode.jsonc")
+        join7(homedir5(), ".config", "opencode", "opencode.json"),
+        join7(homedir5(), ".config", "opencode", "opencode.jsonc"),
+        join7(homedir5(), ".config", "opencode", ".opencode.json"),
+        join7(homedir5(), ".config", "opencode", ".opencode.jsonc")
       ],
       configKey: "mcp",
-      buildEntry: (auth) => withHeaders({ type: "remote", url: mcpUrl(auth), enabled: true }, auth)
+      buildEntry: (auth, transport) => transport === "stdio" ? { type: "local", command: ["npx", ...stdioArgs(auth)], enabled: true } : withHeaders({ type: "remote", url: mcpUrl(auth), enabled: true }, auth)
     },
     rule: {
       kind: "append",
-      file: (scope) => scope === "global" ? join8(homedir5(), ".config", "opencode", "AGENTS.md") : "AGENTS.md",
+      file: (scope) => scope === "global" ? join7(homedir5(), ".config", "opencode", "AGENTS.md") : "AGENTS.md",
       sectionMarker: "<!-- context7 -->"
     },
     skill: {
       name: "context7-mcp",
-      dir: (scope) => scope === "global" ? join8(homedir5(), ".agents", "skills") : join8(".agents", "skills")
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".agents", "skills") : join7(".agents", "skills")
     },
     detect: {
       projectPaths: ["opencode.json", "opencode.jsonc", ".opencode.json", ".opencode.jsonc"],
-      globalPaths: [join8(homedir5(), ".config", "opencode")]
+      globalPaths: [join7(homedir5(), ".config", "opencode")]
     }
   },
   codex: {
     name: "codex",
     displayName: "Codex",
     mcp: {
-      projectPaths: [join8(".codex", "config.toml")],
-      globalPaths: [join8(homedir5(), ".codex", "config.toml")],
+      projectPaths: [join7(".codex", "config.toml")],
+      globalPaths: [join7(homedir5(), ".codex", "config.toml")],
       configKey: "mcp_servers",
-      buildEntry: (auth) => {
-        const entry = { type: "http", url: mcpUrl(auth) };
-        if (auth.mode === "api-key" && auth.apiKey) {
-          entry.headers = { CONTEXT7_API_KEY: auth.apiKey };
-        }
-        return entry;
-      }
+      buildEntry: (auth, transport) => transport === "stdio" ? stdioEntry(auth) : withHeaders({ type: "http", url: mcpUrl(auth) }, auth)
     },
     rule: {
       kind: "append",
-      file: (scope) => scope === "global" ? join8(homedir5(), ".codex", "AGENTS.md") : "AGENTS.md",
+      file: (scope) => scope === "global" ? join7(homedir5(), ".codex", "AGENTS.md") : "AGENTS.md",
       sectionMarker: "<!-- context7 -->"
     },
     skill: {
       name: "context7-mcp",
-      dir: (scope) => scope === "global" ? join8(homedir5(), ".agents", "skills") : join8(".agents", "skills")
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".agents", "skills") : join7(".agents", "skills")
     },
     detect: {
       projectPaths: [".codex"],
-      globalPaths: [join8(homedir5(), ".codex")]
+      globalPaths: [join7(homedir5(), ".codex")]
     }
   },
   gemini: {
     name: "gemini",
     displayName: "Gemini CLI",
     mcp: {
-      projectPaths: [join8(".gemini", "settings.json")],
-      globalPaths: [join8(homedir5(), ".gemini", "settings.json")],
+      projectPaths: [join7(".gemini", "settings.json")],
+      globalPaths: [join7(homedir5(), ".gemini", "settings.json")],
       configKey: "mcpServers",
-      buildEntry: (auth) => withHeaders({ httpUrl: mcpUrl(auth) }, auth)
+      buildEntry: (auth, transport) => transport === "stdio" ? stdioEntry(auth) : withHeaders({ httpUrl: mcpUrl(auth) }, auth)
     },
     rule: {
       kind: "append",
-      file: (scope) => scope === "global" ? join8(homedir5(), ".gemini", "GEMINI.md") : "GEMINI.md",
+      file: (scope) => scope === "global" ? join7(homedir5(), ".gemini", "GEMINI.md") : "GEMINI.md",
       sectionMarker: "<!-- context7 -->"
     },
     skill: {
       name: "context7-mcp",
-      dir: (scope) => scope === "global" ? join8(homedir5(), ".gemini", "skills") : join8(".gemini", "skills")
+      dir: (scope) => scope === "global" ? join7(homedir5(), ".gemini", "skills") : join7(".gemini", "skills")
     },
     detect: {
       projectPaths: [".gemini"],
-      globalPaths: [join8(homedir5(), ".gemini")]
+      globalPaths: [join7(homedir5(), ".gemini")]
     }
   }
 };
@@ -2757,7 +2807,7 @@ async function detectAgents(scope) {
   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 : join8(process.cwd(), p);
+      const fullPath = scope === "global" ? p : join7(process.cwd(), p);
       if (await pathExists(fullPath)) {
         detected.push(agent.name);
         break;
@@ -2856,7 +2906,7 @@ function customizeSkillFilesForAgent(agent, skillName, files) {
 
 // src/setup/mcp-writer.ts
 import { access as access3, readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
-import { dirname as dirname4 } from "path";
+import { dirname as dirname5 } from "path";
 function stripJsonComments(text) {
   let result = "";
   let i = 0;
@@ -2935,7 +2985,7 @@ async function resolveMcpPath(candidates) {
   return candidates[0];
 }
 async function writeJsonConfig(filePath, config) {
-  await mkdir3(dirname4(filePath), { recursive: true });
+  await mkdir3(dirname5(filePath), { recursive: true });
   await writeFile3(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
 }
 async function readTomlServerExists(filePath, serverName) {
@@ -2946,6 +2996,70 @@ async function readTomlServerExists(filePath, serverName) {
     return false;
   }
 }
+async function readTomlServerEntry(filePath, serverName) {
+  let raw;
+  try {
+    raw = await readFile3(filePath, "utf-8");
+  } catch {
+    return void 0;
+  }
+  const sectionHeader = `[mcp_servers.${serverName}]`;
+  const startIdx = raw.indexOf(sectionHeader);
+  if (startIdx === -1) return void 0;
+  const rest = raw.slice(startIdx + sectionHeader.length);
+  const nextHeader = /^\[/m.exec(rest);
+  const block = nextHeader ? rest.slice(0, nextHeader.index) : rest;
+  const entry = {};
+  const lineRe = /^([A-Za-z_][\w-]*)\s*=\s*(.+?)\s*$/gm;
+  let lineMatch;
+  while ((lineMatch = lineRe.exec(block)) !== null) {
+    const [, key, valueText] = lineMatch;
+    try {
+      entry[key] = JSON.parse(valueText);
+    } catch {
+    }
+  }
+  return Object.keys(entry).length > 0 ? entry : void 0;
+}
+function isStdioContext7Entry(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  const e = entry;
+  const refs = (s) => typeof s === "string" && s.includes(STDIO_PACKAGE);
+  if (Array.isArray(e.command)) {
+    return e.command.some(refs);
+  }
+  if (typeof e.command === "string" && Array.isArray(e.args)) {
+    return e.args.some(refs);
+  }
+  return false;
+}
+function getJsonServerEntry(config, configKey, serverName) {
+  const section = config[configKey];
+  if (!section || typeof section !== "object") return void 0;
+  const entry = section[serverName];
+  return entry && typeof entry === "object" ? entry : void 0;
+}
+function stripApiKeyPair(args) {
+  const result = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--api-key") {
+      i++;
+      continue;
+    }
+    result.push(args[i]);
+  }
+  return result;
+}
+function patchStdioApiKey(entry, apiKey) {
+  if (Array.isArray(entry.command)) {
+    const cmd = stripApiKeyPair(entry.command);
+    if (apiKey) cmd.push("--api-key", apiKey);
+    return { ...entry, command: cmd };
+  }
+  const args = Array.isArray(entry.args) ? stripApiKeyPair(entry.args) : [];
+  if (apiKey) args.push("--api-key", apiKey);
+  return { ...entry, args };
+}
 function buildTomlServerBlock(serverName, entry) {
   const lines = [`[mcp_servers.${serverName}]`];
   const headers = entry.headers;
@@ -2991,11 +3105,11 @@ async function appendTomlServer(filePath, serverName, entry) {
     const before = rawBefore.length > 0 ? rawBefore + "\n\n" : "";
     const after = rawAfter.length > 0 ? "\n" + rawAfter : "";
     const content = before + block + after;
-    await mkdir3(dirname4(filePath), { recursive: true });
+    await mkdir3(dirname5(filePath), { recursive: true });
     await writeFile3(filePath, content, "utf-8");
   } else {
     const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n\n" : existing.length > 0 ? "\n" : "";
-    await mkdir3(dirname4(filePath), { recursive: true });
+    await mkdir3(dirname5(filePath), { recursive: true });
     await writeFile3(filePath, existing + separator + block, "utf-8");
   }
   return { alreadyExists };
@@ -3028,13 +3142,16 @@ async function removeTomlServer(filePath, serverName) {
   const rawBefore = existing.slice(0, startIdx).replace(/\n+$/, "");
   const rawAfter = existing.slice(startIdx + sectionHeader.length + endOffset).replace(/^\n+/, "");
   const content = [rawBefore, rawAfter].filter(Boolean).join("\n\n");
-  await mkdir3(dirname4(filePath), { recursive: true });
+  await mkdir3(dirname5(filePath), { recursive: true });
   await writeFile3(filePath, content.length > 0 ? `${content}
 ` : "", "utf-8");
   return { removed: true };
 }
 
 // src/commands/setup.ts
+function resolveTransport(options) {
+  return options.stdio ? "stdio" : "http";
+}
 var CHECKBOX_THEME = {
   style: {
     highlight: (text) => pc8.green(text),
@@ -3051,7 +3168,7 @@ function getSelectedAgents(options) {
   return agents2;
 }
 function registerSetupCommand(program2) {
-  program2.command("setup").description("Set up Context7 for your AI coding agent").option("--claude", "Set up for Claude Code").option("--cursor", "Set up for Cursor").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("--gemini", "Set up for Gemini CLI").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)").action(async (options) => {
+  program2.command("setup").description("Set up Context7 for your AI coding agent").option("--claude", "Set up for Claude Code").option("--cursor", "Set up for Cursor").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("--gemini", "Set up for Gemini CLI").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)").action(async (options) => {
     await setupCommand(options);
   });
 }
@@ -3092,7 +3209,7 @@ async function resolveAuth(options) {
 }
 async function resolveMode(options) {
   if (options.cli) return "cli";
-  if (options.mcp || options.yes || options.oauth || options.apiKey) return "mcp";
+  if (options.mcp || options.yes || options.oauth || options.apiKey || options.stdio) return "mcp";
   return select3({
     message: "How should your agent access Context7?",
     choices: [
@@ -3168,13 +3285,13 @@ async function installRule(agentName, mode, scope) {
   const rule = agent.rule;
   const content = await getRuleContent(mode, agentName);
   if (rule.kind === "file") {
-    const ruleDir = scope === "global" ? rule.dir("global") : join9(process.cwd(), rule.dir("project"));
-    const rulePath = join9(ruleDir, rule.filename);
-    await mkdir4(dirname5(rulePath), { recursive: true });
+    const ruleDir = scope === "global" ? rule.dir("global") : join8(process.cwd(), rule.dir("project"));
+    const rulePath = join8(ruleDir, rule.filename);
+    await mkdir4(dirname6(rulePath), { recursive: true });
     await writeFile4(rulePath, content, "utf-8");
     return { status: "installed", path: rulePath };
   }
-  const filePath = scope === "global" ? rule.file("global") : join9(process.cwd(), rule.file("project"));
+  const filePath = scope === "global" ? rule.file("global") : join8(process.cwd(), rule.file("project"));
   const escapedMarker = rule.sectionMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const section = `${rule.sectionMarker}
 ${content}${rule.sectionMarker}`;
@@ -3190,30 +3307,37 @@ ${content}${rule.sectionMarker}`;
     return { status: "updated", path: filePath };
   }
   const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n\n" : existing.length > 0 ? "\n" : "";
-  await mkdir4(dirname5(filePath), { recursive: true });
+  await mkdir4(dirname6(filePath), { recursive: true });
   await writeFile4(filePath, existing + separator + section + "\n", "utf-8");
   return { status: "installed", path: filePath };
 }
-async function setupAgent(agentName, auth, scope) {
+function resolveEntryToWrite(agent, auth, transport, existingEntry) {
+  if (transport === "stdio" && existingEntry && isStdioContext7Entry(existingEntry)) {
+    const apiKey = auth.mode === "api-key" ? auth.apiKey : void 0;
+    return patchStdioApiKey(existingEntry, apiKey);
+  }
+  return agent.mcp.buildEntry(auth, transport);
+}
+async function setupAgent(agentName, auth, transport, scope) {
   const agent = getAgent(agentName);
-  const mcpCandidates = scope === "global" ? agent.mcp.globalPaths : agent.mcp.projectPaths.map((p) => join9(process.cwd(), p));
+  const mcpCandidates = scope === "global" ? agent.mcp.globalPaths : agent.mcp.projectPaths.map((p) => join8(process.cwd(), p));
   const mcpPath = await resolveMcpPath(mcpCandidates);
   let mcpStatus;
   try {
     if (mcpPath.endsWith(".toml")) {
-      const { alreadyExists } = await appendTomlServer(
-        mcpPath,
-        "context7",
-        agent.mcp.buildEntry(auth)
-      );
+      const existingTomlEntry = transport === "stdio" ? await readTomlServerEntry(mcpPath, "context7") : void 0;
+      const entry = resolveEntryToWrite(agent, auth, transport, existingTomlEntry);
+      const { alreadyExists } = await appendTomlServer(mcpPath, "context7", entry);
       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") : void 0;
+      const entry = resolveEntryToWrite(agent, auth, transport, existingJsonEntry);
       const { config, alreadyExists } = mergeServerEntry(
         existing,
         agent.mcp.configKey,
         "context7",
-        agent.mcp.buildEntry(auth)
+        entry
       );
       mcpStatus = alreadyExists ? `reconfigured with ${AUTH_MODE_LABELS[auth.mode]}` : `configured with ${AUTH_MODE_LABELS[auth.mode]}`;
       await writeJsonConfig(mcpPath, config);
@@ -3231,8 +3355,8 @@ async function setupAgent(agentName, auth, scope) {
     ruleStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
     rulePath = "";
   }
-  const skillDir = scope === "global" ? agent.skill.dir("global") : join9(process.cwd(), agent.skill.dir("project"));
-  const skillPath = join9(skillDir, agent.skill.name, "SKILL.md");
+  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 {
     const downloadData = await downloadSkill("/upstash/context7", agent.skill.name);
@@ -3255,6 +3379,11 @@ async function setupAgent(agentName, auth, scope) {
   };
 }
 async function setupMcp(agents2, options, scope) {
+  const transport = resolveTransport(options);
+  if (transport === "stdio" && options.oauth) {
+    log.error("--stdio is incompatible with --oauth (OAuth uses the hosted HTTP endpoint).");
+    return;
+  }
   const auth = await resolveAuth(options);
   if (!auth) {
     log.warn("Setup cancelled");
@@ -3265,7 +3394,7 @@ async function setupMcp(agents2, options, scope) {
   const results = [];
   for (const agentName of agents2) {
     spinner.text = `Setting up ${getAgent(agentName).displayName}...`;
-    results.push(await setupAgent(agentName, auth, scope));
+    results.push(await setupAgent(agentName, auth, transport, scope));
   }
   spinner.succeed("Context7 setup complete");
   log.blank();
@@ -3282,7 +3411,7 @@ async function setupMcp(agents2, options, scope) {
     log.plain(`      ${pc8.dim(r.skillPath)}`);
     if (r.skillStatus.includes("EACCES")) {
       log.plain(
-        `      ${pc8.yellow("tip:")} fix permissions with: ${pc8.cyan(`sudo chown -R $(whoami) ${dirname5(dirname5(r.skillPath))}`)}`
+        `      ${pc8.yellow("tip:")} fix permissions with: ${pc8.cyan(`sudo chown -R $(whoami) ${dirname6(dirname6(r.skillPath))}`)}`
       );
     }
   }
@@ -3292,7 +3421,7 @@ async function setupMcp(agents2, options, scope) {
 }
 async function setupCliAgent(agentName, scope, downloadData) {
   const agent = getAgent(agentName);
-  const skillDir = scope === "global" ? agent.skill.dir("global") : join9(process.cwd(), agent.skill.dir("project"));
+  const skillDir = scope === "global" ? agent.skill.dir("global") : join8(process.cwd(), agent.skill.dir("project"));
   let skillStatus;
   try {
     const files = customizeSkillFilesForAgent(agentName, "find-docs", downloadData.files);
@@ -3301,7 +3430,7 @@ async function setupCliAgent(agentName, scope, downloadData) {
   } catch (err) {
     skillStatus = `failed: ${err instanceof Error ? err.message : String(err)}`;
   }
-  const skillPath = join9(skillDir, "find-docs");
+  const skillPath = join8(skillDir, "find-docs");
   let ruleStatus;
   let rulePath;
   try {
@@ -3343,7 +3472,7 @@ async function setupCli(options) {
     log.plain(`      ${pc8.dim(r.skillPath)}`);
     if (r.skillStatus.includes("EACCES")) {
       log.plain(
-        `      ${pc8.yellow("tip:")} fix permissions with: ${pc8.cyan(`sudo chown -R $(whoami) ${dirname5(dirname5(r.skillPath))}`)}`
+        `      ${pc8.yellow("tip:")} fix permissions with: ${pc8.cyan(`sudo chown -R $(whoami) ${dirname6(dirname6(r.skillPath))}`)}`
       );
     }
     const ruleIcon = r.ruleStatus === "installed" || r.ruleStatus === "updated" ? pc8.green("+") : pc8.dim("~");
@@ -3375,7 +3504,7 @@ async function setupCommand(options) {
 // src/commands/remove.ts
 import pc9 from "picocolors";
 import ora5 from "ora";
-import { join as join10 } from "path";
+import { join as join9 } from "path";
 import { access as access4, readFile as readFile5, rm as rm3, writeFile as writeFile5 } from "fs/promises";
 var CHECKBOX_THEME2 = {
   style: {
@@ -3483,12 +3612,20 @@ async function pathExists2(path2) {
 }
 async function hasMcpConfig(agentName, scope) {
   const agent = getAgent(agentName);
-  const candidates = scope === "global" ? agent.mcp.globalPaths : agent.mcp.projectPaths.map((path2) => join10(process.cwd(), path2));
+  const candidates = scope === "global" ? agent.mcp.globalPaths : agent.mcp.projectPaths.map((path2) => join9(process.cwd(), path2));
   const mcpPath = await resolveMcpPath(candidates);
   if (mcpPath.endsWith(".toml")) {
     return readTomlServerExists(mcpPath, "context7");
   }
-  const existing = await readJsonConfig(mcpPath);
+  let existing;
+  try {
+    existing = await readJsonConfig(mcpPath);
+  } catch (err) {
+    log.warn(
+      `Skipped ${mcpPath}: could not parse (${err instanceof Error ? err.message : String(err)})`
+    );
+    return false;
+  }
   const section = existing[agent.mcp.configKey];
   return !!section && typeof section === "object" && !Array.isArray(section) && "context7" in section;
 }
@@ -3496,10 +3633,10 @@ async function hasRule(agentName, scope) {
   const agent = getAgent(agentName);
   const rule = agent.rule;
   if (rule.kind === "file") {
-    const ruleDir = scope === "global" ? rule.dir("global") : join10(process.cwd(), rule.dir("project"));
-    return pathExists2(join10(ruleDir, rule.filename));
+    const ruleDir = scope === "global" ? rule.dir("global") : join9(process.cwd(), rule.dir("project"));
+    return pathExists2(join9(ruleDir, rule.filename));
   }
-  const filePath = scope === "global" ? rule.file("global") : join10(process.cwd(), rule.file("project"));
+  const filePath = scope === "global" ? rule.file("global") : join9(process.cwd(), rule.file("project"));
   try {
     const existing = await readFile5(filePath, "utf-8");
     return existing.includes(CONTEXT7_SECTION_MARKER);
@@ -3509,8 +3646,8 @@ async function hasRule(agentName, scope) {
 }
 async function hasSkill(agentName, scope, skillName) {
   const agent = getAgent(agentName);
-  const skillsDir = scope === "global" ? agent.skill.dir("global") : join10(process.cwd(), agent.skill.dir("project"));
-  return pathExists2(join10(skillsDir, skillName));
+  const skillsDir = scope === "global" ? agent.skill.dir("global") : join9(process.cwd(), agent.skill.dir("project"));
+  return pathExists2(join9(skillsDir, skillName));
 }
 async function detectAvailableModes(agents2, scope) {
   let hasMcpArtifacts = false;
@@ -3562,7 +3699,7 @@ async function resolveModes(options, agents2, scope) {
 }
 async function uninstallMcp(agentName, scope) {
   const agent = getAgent(agentName);
-  const mcpCandidates = scope === "global" ? agent.mcp.globalPaths : agent.mcp.projectPaths.map((path2) => join10(process.cwd(), path2));
+  const mcpCandidates = scope === "global" ? agent.mcp.globalPaths : agent.mcp.projectPaths.map((path2) => join9(process.cwd(), path2));
   const mcpPath = await resolveMcpPath(mcpCandidates);
   try {
     if (mcpPath.endsWith(".toml")) {
@@ -3583,8 +3720,8 @@ async function uninstallRule(agentName, scope) {
   const agent = getAgent(agentName);
   const rule = agent.rule;
   if (rule.kind === "file") {
-    const rulePath = scope === "global" ? rule.dir("global") : join10(process.cwd(), rule.dir("project"));
-    const targetPath = join10(rulePath, rule.filename);
+    const rulePath = scope === "global" ? rule.dir("global") : join9(process.cwd(), rule.dir("project"));
+    const targetPath = join9(rulePath, rule.filename);
     try {
       await rm3(targetPath);
       return { status: "removed", path: targetPath };
@@ -3594,7 +3731,7 @@ async function uninstallRule(agentName, scope) {
       return { status: `failed: ${error.message}`, path: targetPath };
     }
   }
-  const filePath = scope === "global" ? rule.file("global") : join10(process.cwd(), rule.file("project"));
+  const filePath = scope === "global" ? rule.file("global") : join9(process.cwd(), rule.file("project"));
   try {
     const existing = await readFile5(filePath, "utf-8");
     if (!existing.includes(CONTEXT7_SECTION_MARKER)) {
@@ -3617,10 +3754,10 @@ async function uninstallRule(agentName, scope) {
 }
 async function uninstallSkills(agentName, scope, skillNames) {
   const agent = getAgent(agentName);
-  const skillsDir = scope === "global" ? agent.skill.dir("global") : join10(process.cwd(), agent.skill.dir("project"));
+  const skillsDir = scope === "global" ? agent.skill.dir("global") : join9(process.cwd(), agent.skill.dir("project"));
   const results = [];
   for (const skillName of skillNames) {
-    const skillPath = join10(skillsDir, skillName);
+    const skillPath = join9(skillsDir, skillName);
     try {
       await rm3(skillPath, { recursive: true });
       results.push({ name: skillName, status: "removed", path: skillPath });
@@ -3883,10 +4020,10 @@ import pc11 from "picocolors";
 
 // src/utils/update-check.ts
 import { homedir as homedir6 } from "os";
-import { dirname as dirname6, join as join11 } from "path";
+import { dirname as dirname7, join as join10 } from "path";
 import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile6 } from "fs/promises";
 var DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
-var UPDATE_STATE_FILE = join11(homedir6(), ".context7", "cli-state.json");
+var UPDATE_STATE_FILE = join10(homedir6(), ".context7", "cli-state.json");
 function getStateFilePath(stateFile) {
   return stateFile ?? UPDATE_STATE_FILE;
 }
@@ -3900,7 +4037,7 @@ async function readUpdateState(stateFile) {
 }
 async function writeUpdateState(state, stateFile) {
   const path2 = getStateFilePath(stateFile);
-  await mkdir5(dirname6(path2), { recursive: true });
+  await mkdir5(dirname7(path2), { recursive: true });
   await writeFile6(path2, JSON.stringify(state, null, 2) + "\n", "utf-8");
 }
 function compareVersions(a, b) {
@@ -4077,13 +4214,13 @@ function registerUpgradeCommand(program2) {
   });
 }
 function runCommand(command, args) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const child = spawn2(command, args, {
       stdio: "inherit",
       shell: process.platform === "win32"
     });
     child.on("error", reject);
-    child.on("close", (code) => resolve2(code));
+    child.on("close", (code) => resolve3(code));
   });
 }
 async function runUpgradePlan(plan) {