@rhize/skill-forge 0.4.0 → 0.5.0

package/dist/cli.js

@@ -6,6 +6,7 @@ import { createRequire } from "module";
 
 // src/commands/add.ts
 import { createInterface as createInterface2 } from "readline/promises";
+import { join as join14 } from "path";
 
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -41,7 +42,8 @@ function loadConfig() {
     licenseKey: parsed.licenseKey ?? defaults.licenseKey,
     defaultTarget: parsed.defaultTarget ?? defaults.defaultTarget,
     agents: parsed.agents ?? defaults.agents,
-    handoffCommand: parsed.handoffCommand ?? defaults.handoffCommand
+    handoffCommand: parsed.handoffCommand ?? defaults.handoffCommand,
+    mcpTargets: parsed.mcpTargets ?? defaults.mcpTargets
   };
 }
 function saveConfig(config) {
@@ -86,7 +88,8 @@ function isDir(p) {
 // src/install/resolve.ts
 var GIT_URL_PATTERN = /^(git@|https?:\/\/|ssh:\/\/)/;
 var LOCAL_PATH_PATTERN = /^(\.{1,2}\/|\/|~\/|~$)/;
-function resolve(source) {
+var NPM_SCOPED_PATTERN = /^@[^/]+\/[^/]+$/;
+function resolve(source, artifact = "skill") {
   const value = source.trim();
   if (value.startsWith("-")) {
     throw new UserError(`skill source cannot start with "-" (looks like a flag, not a source): ${value}`);
@@ -98,6 +101,9 @@ function resolve(source) {
   if (existsSync2(localCandidate) || LOCAL_PATH_PATTERN.test(value)) {
     return { type: "local", value: localCandidate };
   }
+  if (artifact === "mcp" && (NPM_SCOPED_PATTERN.test(value) || !value.includes("/"))) {
+    return { type: "npm", value };
+  }
   return { type: "skills.sh", value };
 }
 
@@ -113,6 +119,7 @@ async function quarantine(source, quarantineDir, deps = {}) {
   const id = randomUUID();
   const quarantinePath = join3(quarantineDir, id);
   mkdirSync2(quarantinePath, { recursive: true });
+  let packageDir;
   switch (source.type) {
     case "skills.sh": {
       const result = await exec("npx", ["-y", "skills@latest", "add", source.value], {
@@ -145,11 +152,37 @@ async function quarantine(source, quarantineDir, deps = {}) {
       cpSync(source.value, join3(quarantinePath, dirName), { recursive: true });
       break;
     }
+    case "npm": {
+      const packResult = await exec("npm", ["pack", source.value, "--pack-destination", quarantinePath], {
+        cwd: quarantinePath
+      });
+      if (packResult.code !== 0) {
+        throw new UserError(
+          `npm pack failed for "${source.value}" (exit ${packResult.code}): ${packResult.stderr || packResult.stdout}`
+        );
+      }
+      const tarballPath = join3(quarantinePath, findTarball(quarantinePath, source.value));
+      const extractResult = await exec("tar", ["-xzf", tarballPath, "-C", quarantinePath], {
+        cwd: quarantinePath
+      });
+      if (extractResult.code !== 0) {
+        throw new UserError(
+          `tarball extraction failed for "${source.value}" (exit ${extractResult.code}): ${extractResult.stderr || extractResult.stdout}`
+        );
+      }
+      packageDir = join3(quarantinePath, "package");
+      if (!existsSync3(packageDir)) {
+        throw new UserError(
+          `npm pack for "${source.value}" did not produce the expected package/ dir after extraction`
+        );
+      }
+      break;
+    }
     default: {
       throw new UserError(`unknown source type: ${source.type}`);
     }
   }
-  return { id, quarantinePath, skillDirs: findSkillDirs(quarantinePath), source };
+  return { id, quarantinePath, skillDirs: findSkillDirs(quarantinePath), packageDir, source };
 }
 function listQuarantineIds(quarantineDir) {
   if (!existsSync3(quarantineDir)) return [];
@@ -157,7 +190,7 @@ function listQuarantineIds(quarantineDir) {
 }
 function findSkillDirs(root) {
   const found = [];
-  function walk2(dir) {
+  function walk3(dir) {
     let entries;
     try {
       entries = readdirSync(dir, { withFileTypes: true });
@@ -169,13 +202,20 @@ function findSkillDirs(root) {
     }
     for (const entry of entries) {
       if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
-        walk2(join3(dir, entry.name));
+        walk3(join3(dir, entry.name));
       }
     }
   }
-  walk2(root);
+  walk3(root);
   return found;
 }
+function findTarball(dir, sourceValue) {
+  const tarball = readdirSync(dir).find((name) => name.endsWith(".tgz"));
+  if (!tarball) {
+    throw new UserError(`npm pack for "${sourceValue}" did not produce a .tgz file in ${dir}`);
+  }
+  return tarball;
+}
 function deriveGitDirName(url) {
   const stripped = url.replace(/\.git$/, "");
   const segments = stripped.split(/[/:]/).filter(Boolean);
@@ -235,8 +275,97 @@ function moveDir(src, dest) {
   }
 }
 
+// src/install/promoteMcp.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname } from "path";
+function promoteMcp(_entry, profile, targetConfigPath, options = {}) {
+  const force = options.force ?? false;
+  const serverName = profile.name;
+  let config = {};
+  let rawExisting;
+  if (existsSync5(targetConfigPath)) {
+    rawExisting = readFileSync2(targetConfigPath, "utf-8");
+    try {
+      config = JSON.parse(rawExisting);
+    } catch (err) {
+      throw new UserError(`could not parse existing MCP config ${targetConfigPath}: ${err.message}`);
+    }
+  }
+  const servers = { ...config.mcpServers ?? {} };
+  if (Object.prototype.hasOwnProperty.call(servers, serverName) && !force) {
+    throw new UserError(
+      `Refusing to overwrite existing MCP server entry "${serverName}" in ${targetConfigPath} (pass force to override)`
+    );
+  }
+  let backupPath;
+  if (rawExisting !== void 0) {
+    backupPath = `${targetConfigPath}.bak-${Date.now()}`;
+    writeFileSync2(backupPath, rawExisting);
+  }
+  const { command, args, envVarsToFill } = deriveServerEntry(profile);
+  const env = {};
+  for (const name of envVarsToFill) env[name] = "";
+  servers[serverName] = { command, args, env };
+  config.mcpServers = servers;
+  mkdirSync4(dirname(targetConfigPath), { recursive: true });
+  writeFileSync2(targetConfigPath, `${JSON.stringify(config, null, 2)}
+`);
+  return { target: targetConfigPath, serverName, envVarsToFill, backupPath };
+}
+function deriveServerEntry(profile) {
+  const envNames = new Set(profile.envVars ?? []);
+  if (profile.candidateEntry?.env) {
+    for (const key of Object.keys(profile.candidateEntry.env)) envNames.add(key);
+  }
+  if (profile.candidateEntry) {
+    return {
+      command: profile.candidateEntry.command,
+      args: profile.candidateEntry.args ?? [],
+      envVarsToFill: Array.from(envNames)
+    };
+  }
+  return {
+    command: "npx",
+    args: ["-y", `${profile.name}@${profile.version}`],
+    envVarsToFill: Array.from(envNames)
+  };
+}
+
+// src/install/mcpCandidate.ts
+import { readFileSync as readFileSync3 } from "fs";
+function readPackageVersion(pkgPath) {
+  try {
+    const pkg2 = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    return typeof pkg2.version === "string" ? pkg2.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readConfigEntry(configPath, name) {
+  try {
+    const cfg = JSON.parse(readFileSync3(configPath, "utf-8"));
+    const servers = cfg.mcpServers ?? cfg.servers ?? {};
+    const raw = servers[name] ?? {};
+    return {
+      command: typeof raw.command === "string" ? raw.command : void 0,
+      args: Array.isArray(raw.args) ? raw.args.filter((a) => typeof a === "string") : void 0,
+      env: raw.env && typeof raw.env === "object" && !Array.isArray(raw.env) ? raw.env : void 0
+    };
+  } catch {
+    return void 0;
+  }
+}
+function resolveMcpCandidateDetail(profile) {
+  const name = profile.servers[0];
+  if (profile.config.endsWith("package.json")) {
+    return { name, version: readPackageVersion(profile.config) };
+  }
+  const entry = readConfigEntry(profile.config, name);
+  return { name, command: entry?.command, args: entry?.args, env: entry?.env };
+}
+
 // src/provenance.ts
-import { appendFileSync, existsSync as existsSync5, statSync as statSync2, writeFileSync as writeFileSync2 } from "fs";
+import { appendFileSync, existsSync as existsSync6, statSync as statSync2, writeFileSync as writeFileSync3 } from "fs";
 import { join as join5 } from "path";
 var FORGE_VERBS = ["DEFER", "ABSORB", "FORK", "REJECT", "WATCH"];
 var LEDGER_HEADER = "# Skill Forge \u2014 Provenance Ledger\n\nOne entry per external-skill ingestion decision.\n";
@@ -251,7 +380,7 @@ function appendProvenance(entry, skillsRoot) {
   if (!FORGE_VERBS.includes(entry.verb)) {
     throw new Error(`verb must be one of ${FORGE_VERBS.join(", ")}`);
   }
-  if (!existsSync5(skillsRoot) || !statSync2(skillsRoot).isDirectory()) {
+  if (!existsSync6(skillsRoot) || !statSync2(skillsRoot).isDirectory()) {
     throw new Error(`skills-root not a directory: ${skillsRoot}`);
   }
   const today = todayLocalIsoDate();
@@ -269,28 +398,32 @@ function appendProvenance(entry, skillsRoot) {
 - **Notes:** ${entry.notes ?? ""}
 `;
   const ledgerPath = join5(skillsRoot, "SOURCES.md");
-  if (!existsSync5(ledgerPath)) {
-    writeFileSync2(ledgerPath, LEDGER_HEADER, "utf-8");
+  if (!existsSync6(ledgerPath)) {
+    writeFileSync3(ledgerPath, LEDGER_HEADER, "utf-8");
   }
   appendFileSync(ledgerPath, block, "utf-8");
   return ledgerPath;
 }
 
+// src/commands/gatePipeline.ts
+import { readdirSync as readdirSync6 } from "fs";
+import { join as join10 } from "path";
+
 // src/gate/profile.ts
 import { execFileSync } from "child_process";
 import {
   closeSync,
-  existsSync as existsSync6,
+  existsSync as existsSync7,
   mkdtempSync,
   openSync,
-  readFileSync as readFileSync2,
+  readFileSync as readFileSync4,
   readdirSync as readdirSync2,
   readSync,
   rmSync as rmSync2,
   statSync as statSync3
 } from "fs";
 import { tmpdir } from "os";
-import { basename as basename3, dirname, extname, join as join6, resolve as resolve2 } from "path";
+import { basename as basename3, dirname as dirname2, extname, join as join6, resolve as resolve2 } from "path";
 var SPDX_HINTS = {
   mit: "MIT (permissive)",
   apache: "Apache-2.0 (permissive)",
@@ -332,7 +465,7 @@ var PYTHON_STDLIB = /* @__PURE__ */ new Set([
 ]);
 function profileSkill(inputPath) {
   const p = resolve2(expandHome(inputPath));
-  if (!existsSync6(p)) {
+  if (!existsSync7(p)) {
     throw new Error(`path does not exist: ${p}`);
   }
   const stat = statSync3(p);
@@ -346,8 +479,41 @@ function profileSkill(inputPath) {
   return profileSkillDir(p);
 }
 function classifyInput(p) {
-  if (existsSync6(join6(p, ".claude-plugin", "plugin.json"))) return "plugin";
-  if (existsSync6(join6(p, ".mcp.json")) || existsSync6(join6(p, "mcp.json"))) return "mcp";
+  if (existsSync7(join6(p, ".claude-plugin", "plugin.json"))) return "plugin";
+  if (detectArtifactType(p) === "mcp") return "mcp";
+  return "skill";
+}
+var MCP_SDK_DEP = "@modelcontextprotocol/sdk";
+var MCP_KEYWORD = "mcp-server";
+var MCP_BIN_PREFIX = /^mcp-/i;
+function readPackageJsonSafe(root) {
+  const pkgPath = join6(root, "package.json");
+  if (!existsSync7(pkgPath)) return void 0;
+  try {
+    return JSON.parse(readFileSync4(pkgPath, "utf-8"));
+  } catch {
+    return void 0;
+  }
+}
+function hasMcpPackageMarkers(pkg2) {
+  for (const section of ["dependencies", "devDependencies", "peerDependencies"]) {
+    const deps = pkg2[section];
+    if (deps && typeof deps === "object" && MCP_SDK_DEP in deps) return true;
+  }
+  const keywords = pkg2.keywords;
+  if (Array.isArray(keywords) && keywords.some((k) => k === MCP_KEYWORD)) return true;
+  const bin = pkg2.bin;
+  if (typeof bin === "string") {
+    if (MCP_BIN_PREFIX.test(basename3(bin))) return true;
+  } else if (bin && typeof bin === "object") {
+    if (Object.keys(bin).some((k) => MCP_BIN_PREFIX.test(k))) return true;
+  }
+  return false;
+}
+function detectArtifactType(root) {
+  if (existsSync7(join6(root, ".mcp.json")) || existsSync7(join6(root, "mcp.json"))) return "mcp";
+  const pkg2 = readPackageJsonSafe(root);
+  if (pkg2 && hasMcpPackageMarkers(pkg2)) return "mcp";
   return "skill";
 }
 function resolveSkillMd(inputPath) {
@@ -361,16 +527,16 @@ function resolveSkillMd(inputPath) {
   }
   const stat = statSync3(currentPath);
   if (stat.isFile() && basename3(currentPath) === "SKILL.md") {
-    return { skillMd: currentPath, root: dirname(currentPath), tmpDir };
+    return { skillMd: currentPath, root: dirname2(currentPath), tmpDir };
   }
   if (stat.isDirectory()) {
     const direct = join6(currentPath, "SKILL.md");
-    if (existsSync6(direct)) {
+    if (existsSync7(direct)) {
       return { skillMd: direct, root: currentPath, tmpDir };
     }
     const matches = findSkillMdOneLevelDown(currentPath);
     if (matches.length === 1) {
-      return { skillMd: matches[0], root: dirname(matches[0]), tmpDir };
+      return { skillMd: matches[0], root: dirname2(matches[0]), tmpDir };
     }
     if (matches.length > 1) {
       cleanupTmp(tmpDir);
@@ -391,7 +557,7 @@ function findSkillMdOneLevelDown(dir) {
   for (const entry of readdirSync2(dir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
       const candidate = join6(dir, entry.name, "SKILL.md");
-      if (existsSync6(candidate)) matches.add(candidate);
+      if (existsSync7(candidate)) matches.add(candidate);
     }
   }
   const skillsDir = join6(dir, "skills");
@@ -399,7 +565,7 @@ function findSkillMdOneLevelDown(dir) {
     for (const entry of readdirSync2(skillsDir, { withFileTypes: true })) {
       if (entry.isDirectory()) {
         const candidate = join6(skillsDir, entry.name, "SKILL.md");
-        if (existsSync6(candidate)) matches.add(candidate);
+        if (existsSync7(candidate)) matches.add(candidate);
       }
     }
   }
@@ -483,8 +649,8 @@ function detectLicense(root, fm) {
   const names = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING", "license"];
   for (const name of names) {
     const p = join6(root, name);
-    if (existsSync6(p) && statSync3(p).isFile()) {
-      const head = readFileSync2(p, "utf-8").slice(0, 2e3).toLowerCase();
+    if (existsSync7(p) && statSync3(p).isFile()) {
+      const head = readFileSync4(p, "utf-8").slice(0, 2e3).toLowerCase();
       for (const [hint, label] of Object.entries(SPDX_HINTS)) {
         if (head.includes(hint)) return label;
       }
@@ -523,7 +689,7 @@ function scanMcpAndImports(text, root) {
   if (isDir(scriptsDir)) {
     for (const f of walkFiles(scriptsDir)) {
       if (!f.endsWith(".py")) continue;
-      const ft = readFileSync2(f, "utf-8");
+      const ft = readFileSync4(f, "utf-8");
       for (const m2 of ft.match(mcpRefRe) ?? []) mcpRefs.add(m2);
       const importRe = /^\s*(?:import|from)\s+([a-zA-Z0-9_]+)/gm;
       let m;
@@ -540,7 +706,7 @@ function scanMcpAndImports(text, root) {
 function profileSkillDir(inputPath) {
   const { skillMd, root, tmpDir } = resolveSkillMd(inputPath);
   try {
-    const text = readFileSync2(skillMd, "utf-8");
+    const text = readFileSync4(skillMd, "utf-8");
     const fm = parseFrontmatter(text);
     const bodyLines = (text.match(/\n/g)?.length ?? 0) + 1;
     const headers = Array.from(text.matchAll(/^#{1,3}\s+(.+)$/gm)).map((m) => m[1]);
@@ -560,7 +726,8 @@ function profileSkillDir(inputPath) {
       topHeaders: headers.slice(0, 12),
       resources,
       mcpDependencies: mcpDeps,
-      externalPythonDeps: externalDeps
+      externalPythonDeps: externalDeps,
+      artifactType: detectArtifactType(root)
     };
   } finally {
     cleanupTmp(tmpDir);
@@ -570,14 +737,14 @@ function profilePlugin(p) {
   const manifestPath = join6(p, ".claude-plugin", "plugin.json");
   let manifest;
   try {
-    manifest = JSON.parse(readFileSync2(manifestPath, "utf-8"));
+    manifest = JSON.parse(readFileSync4(manifestPath, "utf-8"));
   } catch (err) {
     throw new Error(`could not parse plugin.json under ${p}: ${err.message}`);
   }
   const skillsDir = join6(p, "skills");
   let skills = [];
   if (isDir(skillsDir)) {
-    skills = readdirSync2(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync6(join6(skillsDir, d.name, "SKILL.md"))).map((d) => d.name).sort();
+    skills = readdirSync2(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync7(join6(skillsDir, d.name, "SKILL.md"))).map((d) => d.name).sort();
   }
   const commandsDir = join6(p, "commands");
   const commands = isDir(commandsDir) ? readdirSync2(commandsDir).filter((f) => f.endsWith(".md")).length : 0;
@@ -592,30 +759,50 @@ function profilePlugin(p) {
     skills,
     skillCount: skills.length,
     commands,
-    mcpServers
+    mcpServers,
+    artifactType: detectArtifactType(p)
   };
 }
 function profileMcp(p) {
-  const cfgPath = existsSync6(join6(p, ".mcp.json")) ? join6(p, ".mcp.json") : join6(p, "mcp.json");
-  let cfg;
+  const explicitConfig = existsSync7(join6(p, ".mcp.json")) ? join6(p, ".mcp.json") : existsSync7(join6(p, "mcp.json")) ? join6(p, "mcp.json") : void 0;
+  if (explicitConfig) {
+    let cfg;
+    try {
+      cfg = JSON.parse(readFileSync4(explicitConfig, "utf-8"));
+    } catch (err) {
+      throw new Error(`could not parse MCP config ${explicitConfig}: ${err.message}`);
+    }
+    const servers = cfg.mcpServers ?? cfg.servers ?? {};
+    const names = typeof servers === "object" && servers !== null ? Object.keys(servers).sort() : [];
+    return {
+      kind: "mcp",
+      inputPath: p,
+      config: explicitConfig,
+      servers: names,
+      serverCount: names.length,
+      artifactType: "mcp"
+    };
+  }
+  const pkgPath = join6(p, "package.json");
+  let pkg2;
   try {
-    cfg = JSON.parse(readFileSync2(cfgPath, "utf-8"));
+    pkg2 = JSON.parse(readFileSync4(pkgPath, "utf-8"));
   } catch (err) {
-    throw new Error(`could not parse MCP config ${cfgPath}: ${err.message}`);
+    throw new Error(`could not parse package.json ${pkgPath}: ${err.message}`);
   }
-  const servers = cfg.mcpServers ?? cfg.servers ?? {};
-  const names = typeof servers === "object" && servers !== null ? Object.keys(servers).sort() : [];
+  const name = typeof pkg2.name === "string" && pkg2.name.length > 0 ? pkg2.name : basename3(p);
   return {
     kind: "mcp",
     inputPath: p,
-    config: cfgPath,
-    servers: names,
-    serverCount: names.length
+    config: pkgPath,
+    servers: [name],
+    serverCount: 1,
+    artifactType: "mcp"
   };
 }
 
 // src/gate/safety.ts
-import { readFileSync as readFileSync3, readdirSync as readdirSync3, statSync as statSync4 } from "fs";
+import { readFileSync as readFileSync5, readdirSync as readdirSync3, statSync as statSync4 } from "fs";
 import { execFile } from "child_process";
 import { delimiter, extname as extname2, join as join7 } from "path";
 import { promisify } from "util";
@@ -731,7 +918,7 @@ function readTextFile(file) {
   if (BINARY_EXT.has(extname2(file).toLowerCase())) return void 0;
   try {
     if (statSync4(file).size > MAX_FILE_BYTES) return void 0;
-    const content = readFileSync3(file, "utf-8");
+    const content = readFileSync5(file, "utf-8");
     if (content.slice(0, 512).includes("\0")) return void 0;
     return content;
   } catch {
@@ -818,8 +1005,8 @@ async function scanSafety(targetPath, strictness = DEFAULT_STRICTNESS) {
 }
 
 // src/gate/overlap.ts
-import { existsSync as existsSync7, readFileSync as readFileSync4, readdirSync as readdirSync4 } from "fs";
-import { basename as basename4, dirname as dirname2, join as join8, resolve as resolve3 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync6, readdirSync as readdirSync4 } from "fs";
+import { basename as basename4, dirname as dirname3, join as join8, resolve as resolve3 } from "path";
 var STOPWORDS = new Set(
   `
 a an the and or of to for in on with use used using when whether this that these those is are be
@@ -840,8 +1027,8 @@ function splitLimited(text, sep, maxSplit) {
   return parts;
 }
 function readFrontmatter(skillMdPath) {
-  const text = readFileSync4(skillMdPath, "utf-8");
-  const meta = { name: basename4(dirname2(skillMdPath)), description: "" };
+  const text = readFileSync6(skillMdPath, "utf-8");
+  const meta = { name: basename4(dirname3(skillMdPath)), description: "" };
   if (text.startsWith("---\n")) {
     const block = splitLimited(text, "---", 2)[1] ?? "";
     const nameMatch = block.match(/^name:\s*(.+)$/m);
@@ -935,7 +1122,7 @@ function suggestVerbCode(topScore) {
   return verbTier(topScore).verb;
 }
 function listSubdirs(dir) {
-  if (!existsSync7(dir)) return [];
+  if (!existsSync8(dir)) return [];
   let entries;
   try {
     entries = readdirSync4(dir, { withFileTypes: true });
@@ -948,16 +1135,16 @@ function findSkillMdFiles(root) {
   const found = /* @__PURE__ */ new Set();
   for (const dir of listSubdirs(root)) {
     const candidate = join8(dir, "SKILL.md");
-    if (existsSync7(candidate)) found.add(resolve3(candidate));
+    if (existsSync8(candidate)) found.add(resolve3(candidate));
   }
   for (const dir of listSubdirs(join8(root, "skills"))) {
     const candidate = join8(dir, "SKILL.md");
-    if (existsSync7(candidate)) found.add(resolve3(candidate));
+    if (existsSync8(candidate)) found.add(resolve3(candidate));
   }
   for (const topDir of listSubdirs(root)) {
     for (const dir of listSubdirs(join8(topDir, "skills"))) {
       const candidate = join8(dir, "SKILL.md");
-      if (existsSync7(candidate)) found.add(resolve3(candidate));
+      if (existsSync8(candidate)) found.add(resolve3(candidate));
     }
   }
   return Array.from(found).filter((p) => !p.includes("/.git/")).sort();
@@ -971,7 +1158,7 @@ function scanOverlap(candidatePath, skillsRoot) {
   if (isDir(cpath)) {
     cpath = join8(cpath, "SKILL.md");
   }
-  if (!existsSync7(cpath)) {
+  if (!existsSync8(cpath)) {
     throw new Error(`candidate SKILL.md not found: ${cpath}`);
   }
   const cand = readFrontmatter(cpath);
@@ -994,6 +1181,338 @@ function scanOverlap(candidatePath, skillsRoot) {
   };
 }
 
+// src/gate/mcpSafety.ts
+import { readFileSync as readFileSync7, readdirSync as readdirSync5, statSync as statSync5 } from "fs";
+import { basename as basename5, extname as extname3, join as join9 } from "path";
+var SKIP_DIRS3 = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", "__pycache__", ".venv", "venv"]);
+var BINARY_EXT2 = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".ico",
+  ".pdf",
+  ".zip",
+  ".tar",
+  ".gz",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+  ".mp4",
+  ".mp3",
+  ".wasm",
+  ".bin",
+  ".exe"
+]);
+var MAX_FILE_BYTES2 = 2 * 1024 * 1024;
+function* walk2(dir) {
+  let entries;
+  try {
+    entries = readdirSync5(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join9(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS3.has(entry.name)) continue;
+      yield* walk2(full);
+    } else if (entry.isFile()) {
+      yield full;
+    }
+  }
+}
+function readTextFile2(file) {
+  if (BINARY_EXT2.has(extname3(file).toLowerCase())) return void 0;
+  try {
+    if (statSync5(file).size > MAX_FILE_BYTES2) return void 0;
+    const content = readFileSync7(file, "utf-8");
+    if (content.slice(0, 512).includes("\0")) return void 0;
+    return content;
+  } catch {
+    return void 0;
+  }
+}
+function isConfigOrExampleFile(file) {
+  const base = basename5(file).toLowerCase();
+  if (base.startsWith(".env")) return true;
+  if (/\.(json|ya?ml)$/.test(base)) return true;
+  return /(example|sample|config)/.test(base);
+}
+var CREDENTIAL_KEY_RE = /(API[_-]?KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL)/i;
+function looksCredentialKey(name) {
+  return CREDENTIAL_KEY_RE.test(name);
+}
+var PLACEHOLDER_VALUE_RE = /^(\$\{.*\}|\$[A-Z0-9_]+|your[_-]?.*|<.*>|xxx+|changeme|replace[_-]?me|example|placeholder|todo|fill[_-]?me|none|null|redacted|\.\.\.)$/i;
+function isPlaceholderValue(value) {
+  const v = value.trim();
+  if (v === "") return true;
+  if (v.startsWith("process.env")) return true;
+  return PLACEHOLDER_VALUE_RE.test(v);
+}
+function looksHighEntropy(value) {
+  if (/\s/.test(value)) return false;
+  if (value.length < 20) return false;
+  const hasLower = /[a-z]/.test(value);
+  const hasUpper = /[A-Z]/.test(value);
+  const hasDigit = /[0-9]/.test(value);
+  const varietyCount = [hasLower, hasUpper, hasDigit].filter(Boolean).length;
+  const uniqueChars = new Set(value).size;
+  return varietyCount >= 2 && uniqueChars / value.length > 0.4;
+}
+function isPinnedPackageSpec(spec) {
+  const withoutScope = spec.startsWith("@") ? spec.slice(spec.indexOf("/") + 1) : spec;
+  return withoutScope.includes("@");
+}
+function collectServerNodes(node, out) {
+  if (Array.isArray(node)) {
+    for (const item of node) collectServerNodes(item, out);
+    return;
+  }
+  if (node && typeof node === "object") {
+    const obj = node;
+    if (typeof obj.command === "string" || Array.isArray(obj.args) || obj.env && typeof obj.env === "object") {
+      out.push(obj);
+    }
+    for (const value of Object.values(obj)) collectServerNodes(value, out);
+  }
+}
+function tryParseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function scanJsonConfig(file, parsed) {
+  const findings = [];
+  const nodes = [];
+  collectServerNodes(parsed, nodes);
+  for (const node of nodes) {
+    const command = typeof node.command === "string" ? node.command : void 0;
+    const args = Array.isArray(node.args) ? node.args.filter((a) => typeof a === "string") : [];
+    if (command === "npx") {
+      const flagIdx = args.findIndex((a) => a === "-y" || a === "--yes");
+      if (flagIdx !== -1) {
+        const pkgSpec = args.slice(flagIdx + 1).find((a) => !a.startsWith("-"));
+        if (pkgSpec && !isPinnedPackageSpec(pkgSpec)) {
+          findings.push({
+            severity: "MEDIUM",
+            rule: "mcp-unpinned-npx",
+            file,
+            detail: `npx -y ${pkgSpec} is unpinned \u2014 pin an exact version (${pkgSpec}@<version>) so the resolved server code can't change silently`
+          });
+        }
+      }
+    }
+    for (const a of args) {
+      if (/^--dangerously-/i.test(a) || a === "--no-sandbox") {
+        findings.push({
+          severity: "HIGH",
+          rule: "mcp-dangerous-flag",
+          file,
+          detail: `launch arg ${a} disables a safety guard`
+        });
+      }
+      if (a === "/" || a === "~") {
+        findings.push({
+          severity: "MEDIUM",
+          rule: "mcp-filesystem-root-arg",
+          file,
+          detail: `launch arg "${a}" grants filesystem access at the root/home directory \u2014 scope this to a specific directory`
+        });
+      }
+    }
+    if (node.env && typeof node.env === "object" && !Array.isArray(node.env)) {
+      for (const [key, value] of Object.entries(node.env)) {
+        if (typeof value !== "string" || isPlaceholderValue(value)) continue;
+        if (looksCredentialKey(key) || looksHighEntropy(value)) {
+          findings.push({
+            severity: "HIGH",
+            rule: "mcp-inline-credential-value",
+            file,
+            detail: `env.${key} has an inline credential value \u2014 emit an empty string and document that the user must fill it in`
+          });
+        }
+      }
+    }
+  }
+  return findings;
+}
+var NPX_SHELL_RE = /\bnpx\s+(?:-y|--yes)\s+((?:@[\w.-]+\/)?[\w.-]+)(@[\w.-]+)?/g;
+var DANGEROUS_FLAG_RE = /--dangerously-[\w-]+|--no-sandbox\b/g;
+var CREDENTIAL_ASSIGNMENT_RE = /["']?([A-Za-z][A-Za-z0-9_]*)["']?\s*[:=]\s*["']([^"']{6,})["']/g;
+function scanTextFile(file, content, allowCredentialCheck) {
+  const findings = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNo = i + 1;
+    NPX_SHELL_RE.lastIndex = 0;
+    let m;
+    while ((m = NPX_SHELL_RE.exec(line)) !== null) {
+      const pkgSpec = m[1];
+      const pinned = m[2] !== void 0;
+      if (!pinned) {
+        findings.push({
+          severity: "MEDIUM",
+          rule: "mcp-unpinned-npx",
+          file,
+          detail: `line ${lineNo}: npx -y ${pkgSpec} is unpinned \u2014 pin an exact version (${pkgSpec}@<version>)`
+        });
+      }
+    }
+    DANGEROUS_FLAG_RE.lastIndex = 0;
+    while ((m = DANGEROUS_FLAG_RE.exec(line)) !== null) {
+      findings.push({
+        severity: "HIGH",
+        rule: "mcp-dangerous-flag",
+        file,
+        detail: `line ${lineNo}: launch arg ${m[0]} disables a safety guard`
+      });
+    }
+    if (allowCredentialCheck) {
+      CREDENTIAL_ASSIGNMENT_RE.lastIndex = 0;
+      while ((m = CREDENTIAL_ASSIGNMENT_RE.exec(line)) !== null) {
+        const varName = m[1];
+        const value = m[2];
+        if (isPlaceholderValue(value)) continue;
+        if (looksCredentialKey(varName) || looksHighEntropy(value)) {
+          findings.push({
+            severity: "HIGH",
+            rule: "mcp-inline-credential-value",
+            file,
+            detail: `line ${lineNo}: inline credential value assigned to ${varName}`
+          });
+        }
+      }
+    }
+  }
+  return findings;
+}
+function scanFileForMcpFindings(file) {
+  const content = readTextFile2(file);
+  if (content === void 0) return [];
+  if (extname3(file).toLowerCase() === ".json") {
+    const parsed = tryParseJson(content);
+    if (parsed !== void 0) return scanJsonConfig(file, parsed);
+  }
+  return scanTextFile(file, content, isConfigOrExampleFile(file));
+}
+function scanMcpFindings(targetPath) {
+  let root;
+  try {
+    root = statSync5(targetPath);
+  } catch {
+    return [];
+  }
+  const files = root.isDirectory() ? Array.from(walk2(targetPath)) : [targetPath];
+  const findings = [];
+  for (const file of files) {
+    findings.push(...scanFileForMcpFindings(file));
+  }
+  return findings;
+}
+var BLOCK_SEVERITIES_BY_STRICTNESS2 = {
+  "block-high": /* @__PURE__ */ new Set(["HIGH", "CRITICAL"]),
+  "block-medium": /* @__PURE__ */ new Set(["MEDIUM", "HIGH", "CRITICAL"]),
+  "warn-only": /* @__PURE__ */ new Set()
+};
+function verdictFor2(findings, strictness) {
+  const blockSeverities = BLOCK_SEVERITIES_BY_STRICTNESS2[strictness];
+  if (findings.some((f) => blockSeverities.has(f.severity))) return "block";
+  if (findings.length > 0) return "warn";
+  return "pass";
+}
+async function mcpScan(targetPath, strictness = DEFAULT_STRICTNESS) {
+  const base = await scanSafety(targetPath, strictness);
+  const mcpFindings = scanMcpFindings(targetPath);
+  const findings = [...base.findings, ...mcpFindings];
+  return { findings, verdict: verdictFor2(findings, strictness) };
+}
+
+// src/gate/mcpOverlap.ts
+import { existsSync as existsSync9, readFileSync as readFileSync8 } from "fs";
+import { resolve as resolve4 } from "path";
+function readTargetServers(targetPath) {
+  const path = resolve4(expandHome(targetPath));
+  if (!existsSync9(path)) return [];
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync8(path, "utf-8"));
+  } catch {
+    return [];
+  }
+  const servers = cfg.mcpServers ?? cfg.servers ?? {};
+  if (typeof servers !== "object" || servers === null) return [];
+  return Object.entries(servers).map(([name, raw]) => {
+    const v = raw ?? {};
+    return {
+      name,
+      command: typeof v.command === "string" ? v.command : void 0,
+      args: Array.isArray(v.args) ? v.args.filter((a) => typeof a === "string") : void 0
+    };
+  });
+}
+function tokenizeName(name) {
+  return new Set(name.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+}
+function nameSimilarity(a, b) {
+  if (a.toLowerCase() === b.toLowerCase()) return 1;
+  const ta = tokenizeName(a);
+  const tb = tokenizeName(b);
+  if (ta.size === 0 || tb.size === 0) return 0;
+  let inter = 0;
+  for (const t of ta) if (tb.has(t)) inter += 1;
+  const union = (/* @__PURE__ */ new Set([...ta, ...tb])).size;
+  return union ? inter / union : 0;
+}
+function packageBaseName(spec) {
+  const searchFrom = spec.startsWith("@") ? 1 : 0;
+  const atIdx = spec.indexOf("@", searchFrom);
+  return atIdx === -1 ? spec : spec.slice(0, atIdx);
+}
+function extractPackageSpec(command, args = []) {
+  if (!command) return void 0;
+  const base = command.split("/").pop() ?? command;
+  if (["npx", "npm", "pnpm", "yarn", "uvx"].includes(base)) {
+    return args.find((a) => !a.startsWith("-"));
+  }
+  return base;
+}
+function commandSimilarity(candidate, target) {
+  const candSpec = candidate.packageName ?? extractPackageSpec(candidate.command, candidate.args ?? []);
+  const targetSpec = extractPackageSpec(target.command, target.args ?? []);
+  if (!candSpec || !targetSpec) return 0;
+  return packageBaseName(candSpec).toLowerCase() === packageBaseName(targetSpec).toLowerCase() ? 1 : 0;
+}
+function round32(n) {
+  return Math.round(n * 1e3) / 1e3;
+}
+function score2(candidate, target) {
+  return round32(0.6 * nameSimilarity(candidate.name, target.name) + 0.4 * commandSimilarity(candidate, target));
+}
+function scanMcpOverlap(candidate, mcpTargetPaths) {
+  const ranking = [];
+  for (const targetPath of mcpTargetPaths) {
+    const resolvedPath = resolve4(expandHome(targetPath));
+    for (const target of readTargetServers(targetPath)) {
+      ranking.push({ skill: target.name, path: resolvedPath, score: score2(candidate, target) });
+    }
+  }
+  ranking.sort((a, b) => b.score - a.score);
+  const top = ranking[0];
+  return {
+    candidate: candidate.name,
+    nearest: top?.skill ?? "",
+    nearestScore: top?.score ?? 0,
+    suggestedVerb: suggestVerb(top?.score ?? 0),
+    ranking
+  };
+}
+
 // src/license.ts
 import { verify as cryptoVerify } from "crypto";
 var LICENSE_PREFIX = "skf1";
@@ -1109,11 +1628,20 @@ function renderFindingsLines(findings) {
   if (!findings?.length) return [];
   return [`${padLabel("Findings")}:`, ...findings.map(renderFindingLine)];
 }
+function profileHeaderFields(profile) {
+  if (profile.kind === "mcp") {
+    const name = profile.serverCount === 1 ? profile.servers[0] : `${profile.serverCount} servers`;
+    return { name, version: "n/a", license: "n/a" };
+  }
+  return {
+    name: profile.name ?? "unknown",
+    version: profile.version ?? "unknown",
+    license: profile.kind === "skill" ? profile.license : "UNKNOWN"
+  };
+}
 function renderReport(result) {
   const { profile, overlap, overlapLocked, safety, worthTaking, leaveBehind } = result;
-  const name = profile.name ?? "unknown";
-  const version = profile.version ?? "unknown";
-  const license = profile.license ?? "UNKNOWN";
+  const { name, version, license } = profileHeaderFields(profile);
   const overlapLines = overlapLocked ? [`${padLabel("Overlap analysis")}: ${upgradeNotice("overlap analysis")}`] : overlap ? [
     `${padLabel("Nearest existing skill")}: ${overlap.nearest}  (overlap ${overlap.nearestScore})`,
     `${padLabel("Recommended verb")}: ${overlap.suggestedVerb}`
@@ -1122,6 +1650,7 @@ function renderReport(result) {
     BORDER,
     `\u{1F528} Forge: ${name}  (v${version}, ${license})`,
     BORDER,
+    `${padLabel("Artifact type")}: ${profile.artifactType}`,
     ...overlapLines,
     renderListField("What's worth taking", worthTaking, "(pending \u2014 not yet determined)"),
     renderListField("What to leave behind", leaveBehind, "(pending \u2014 not yet determined)"),
@@ -1147,10 +1676,13 @@ function printGateOutput(gateResult, json) {
   }
   console.log(json ? renderJson(gateResult) : renderReport(gateResult));
 }
-function asSkillProfile(candidatePath) {
+function asProfile(candidatePath, artifact) {
   const profile = profileSkill(candidatePath);
-  if (profile.kind !== "skill") {
-    throw new Error(`expected a skill candidate at ${candidatePath}, found a ${profile.kind}`);
+  const expectedKind = artifact === "mcp" ? "mcp" : "skill";
+  if (profile.kind !== expectedKind) {
+    throw new Error(
+      artifact === "mcp" ? `expected an MCP candidate at ${candidatePath} (--artifact mcp), found a ${profile.kind}` : `expected a skill candidate at ${candidatePath}, found a ${profile.kind}`
+    );
   }
   return profile;
 }
@@ -1162,14 +1694,42 @@ function tryOverlap(candidatePath, skillsRoot) {
     return void 0;
   }
 }
+function tryMcpOverlap(profile, mcpTargets) {
+  try {
+    const detail = resolveMcpCandidateDetail(profile);
+    return scanMcpOverlap(
+      {
+        name: detail.name,
+        command: detail.command,
+        args: detail.args,
+        packageName: detail.command ? void 0 : detail.name
+      },
+      mcpTargets
+    );
+  } catch (err) {
+    console.error(`[skill-forge] mcp overlap scan skipped: ${err.message}`);
+    return void 0;
+  }
+}
+function resolveMcpCandidatePath(entry) {
+  if (entry.packageDir) return entry.packageDir;
+  let children = [];
+  try {
+    children = readdirSync6(entry.quarantinePath, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch {
+  }
+  return children.length === 1 ? join10(entry.quarantinePath, children[0]) : entry.quarantinePath;
+}
 async function runGate(candidatePath, skillsRoot, {
   proFeatureLabel = "overlap analysis",
-  strictness = DEFAULT_STRICTNESS
+  strictness = DEFAULT_STRICTNESS,
+  artifact = "skill",
+  mcpTargets = []
 } = {}) {
-  const profile = asSkillProfile(candidatePath);
-  const safety = await scanSafety(candidatePath, strictness);
+  const profile = asProfile(candidatePath, artifact);
   const proStatus = proFeatureStatus(proFeatureLabel);
-  const overlap = proStatus.enabled ? tryOverlap(candidatePath, skillsRoot) : void 0;
+  const safety = artifact === "mcp" ? await mcpScan(candidatePath, strictness) : await scanSafety(candidatePath, strictness);
+  const overlap = !proStatus.enabled ? void 0 : artifact === "mcp" ? tryMcpOverlap(profile, mcpTargets) : tryOverlap(candidatePath, skillsRoot);
   const gateResult = {
     profile,
     overlap,
@@ -1189,23 +1749,23 @@ async function runGate(candidatePath, skillsRoot, {
 
 // src/queue.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
+import { join as join11 } from "path";
 function getQueuePath() {
-  return join9(getHomeDir(), "queue.json");
+  return join11(getHomeDir(), "queue.json");
 }
 function readQueue() {
   const path = getQueuePath();
-  if (!existsSync8(path)) {
+  if (!existsSync10(path)) {
     return { version: 1, entries: [] };
   }
-  const raw = readFileSync5(path, "utf-8");
+  const raw = readFileSync9(path, "utf-8");
   const parsed = JSON.parse(raw);
   return { version: 1, entries: parsed.entries ?? [] };
 }
 function writeQueue(queue) {
-  mkdirSync4(getHomeDir(), { recursive: true });
-  writeFileSync3(getQueuePath(), JSON.stringify(queue, null, 2) + "\n", "utf-8");
+  mkdirSync5(getHomeDir(), { recursive: true });
+  writeFileSync4(getQueuePath(), JSON.stringify(queue, null, 2) + "\n", "utf-8");
 }
 function appendQueueEntry(entry) {
   const queue = readQueue();
@@ -1229,16 +1789,16 @@ function generateId(existingIds) {
 
 // src/handoff.ts
 import { spawnSync } from "child_process";
-import { existsSync as existsSync9 } from "fs";
-import { dirname as dirname3, join as join10 } from "path";
+import { existsSync as existsSync11 } from "fs";
+import { dirname as dirname4, join as join12 } from "path";
 import { fileURLToPath } from "url";
 var KNOWN_AGENT_BINARIES = ["claude", "codex", "cursor-agent", "windsurf", "opencode", "gemini"];
 var HANDOFF_INSTRUCTION = "Read {prompt} and follow its instructions for the skill installed at {path}";
 function resolvePromptPath() {
-  const here = dirname3(fileURLToPath(import.meta.url));
-  const builtCandidate = join10(here, "ingest-prompt.md");
-  if (existsSync9(builtCandidate)) return builtCandidate;
-  return join10(here, "..", "assets", "ingest-prompt.md");
+  const here = dirname4(fileURLToPath(import.meta.url));
+  const builtCandidate = join12(here, "ingest-prompt.md");
+  if (existsSync11(builtCandidate)) return builtCandidate;
+  return join12(here, "..", "assets", "ingest-prompt.md");
 }
 function defaultIsOnPath(bin) {
   const finder = process.platform === "win32" ? "where" : "which";
@@ -1293,20 +1853,28 @@ function runHandoff(config, installedPath, options = {}) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync10 } from "fs";
+import { existsSync as existsSync12 } from "fs";
 import { homedir as homedir4 } from "os";
 import { createInterface } from "readline/promises";
 
 // src/agents.ts
+import { statSync as statSync6 } from "fs";
 import { homedir as homedir3 } from "os";
-import { join as join11, resolve as resolve4 } from "path";
+import { join as join13, resolve as resolve5 } from "path";
+function isFile(p) {
+  try {
+    return statSync6(p).isFile();
+  } catch {
+    return false;
+  }
+}
 function projectPath(root, cwd) {
-  return root ? resolve4(cwd, root) : void 0;
+  return root ? resolve5(cwd, root) : void 0;
 }
 function globalPath(root, home) {
   if (!root) return void 0;
   if (root === "~") return home;
-  if (root.startsWith("~/")) return join11(home, root.slice(2));
+  if (root.startsWith("~/")) return join13(home, root.slice(2));
   return root;
 }
 function makeAgent(spec) {
@@ -1317,6 +1885,7 @@ function makeAgent(spec) {
     globalRoot: spec.globalRoot,
     verified: spec.verified ?? true,
     defaultHandoffTemplate: spec.defaultHandoffTemplate,
+    mcpConfig: spec.mcpConfig,
     detect: (cwd, home) => detectAgentRoot(agent, cwd, home) !== void 0
   };
   return agent;
@@ -1331,6 +1900,19 @@ function detectAgentRoot(agent, cwd = process.cwd(), home = homedir3()) {
   }
   return void 0;
 }
+function resolveMcpConfigPath(agent, scope, cwd = process.cwd(), home = homedir3()) {
+  if (!agent.mcpConfig) return void 0;
+  return scope === "project" ? projectPath(agent.mcpConfig.project, cwd) : globalPath(agent.mcpConfig.global, home);
+}
+function detectMcpConfigFiles(agent, cwd = process.cwd(), home = homedir3()) {
+  if (!agent.mcpConfig) return [];
+  const found = [];
+  for (const scope of ["project", "global"]) {
+    const path = resolveMcpConfigPath(agent, scope, cwd, home);
+    if (path && isFile(path)) found.push({ scope, path });
+  }
+  return found;
+}
 var AGENTS = [
   { id: "aider-desk", displayName: "AiderDesk", projectRoot: ".aider-desk/skills", globalRoot: "~/.aider-desk/skills" },
   { id: "amp", displayName: "Amp", projectRoot: ".agents/skills", globalRoot: "~/.config/agents/skills" },
@@ -1354,7 +1936,12 @@ var AGENTS = [
     globalRoot: "~/.claude/skills",
     // `claude -p "<prompt>"` runs one non-interactive turn and exits. Verified 2026-07-11:
     // https://code.claude.com/docs/en/headless
-    defaultHandoffTemplate: ["claude", "-p", HANDOFF_INSTRUCTION]
+    defaultHandoffTemplate: ["claude", "-p", HANDOFF_INSTRUCTION],
+    // Project scope writes to `.mcp.json` at the project root (shared via version control).
+    // User scope writes to a top-level `mcpServers` key in `~/.claude.json` (not exclusively
+    // an MCP file — it's Claude Code's broader state file — but it's the correct read/write
+    // target for user-scoped servers). Verified 2026-07-12: https://code.claude.com/docs/en/mcp
+    mcpConfig: { project: ".mcp.json", global: "~/.claude.json", verified: true }
   },
   { id: "openclaw", displayName: "OpenClaw", projectRoot: "skills", globalRoot: "~/.openclaw/skills" },
   { id: "cline", displayName: "Cline", projectRoot: ".agents/skills", globalRoot: "~/.agents/skills" },
@@ -1379,7 +1966,12 @@ var AGENTS = [
     globalRoot: "~/.codex/skills",
     // `codex exec "<prompt>"` runs one non-interactive task and prints the final message.
     // Verified 2026-07-11: https://developers.openai.com/codex/noninteractive
-    defaultHandoffTemplate: ["codex", "exec", HANDOFF_INSTRUCTION]
+    defaultHandoffTemplate: ["codex", "exec", HANDOFF_INSTRUCTION],
+    // TOML, not JSON: `[mcp_servers.<name>]` tables. User config at `~/.codex/config.toml`;
+    // project config at `.codex/config.toml` (only honored for trusted projects). Verified
+    // 2026-07-12: https://learn.chatgpt.com/docs/extend/mcp?surface=cli — detect/report-only
+    // per the v0.5 contract (promote only writes JSON targets).
+    mcpConfig: { project: ".codex/config.toml", global: "~/.codex/config.toml", format: "toml", verified: true }
   },
   {
     id: "command-code",
@@ -1390,7 +1982,16 @@ var AGENTS = [
   { id: "continue", displayName: "Continue", projectRoot: ".continue/skills", globalRoot: "~/.continue/skills" },
   { id: "cortex", displayName: "Cortex Code", projectRoot: ".cortex/skills", globalRoot: "~/.snowflake/cortex/skills" },
   { id: "crush", displayName: "Crush", projectRoot: ".crush/skills", globalRoot: "~/.config/crush/skills" },
-  { id: "cursor", displayName: "Cursor", projectRoot: ".agents/skills", globalRoot: "~/.cursor/skills" },
+  {
+    id: "cursor",
+    displayName: "Cursor",
+    projectRoot: ".agents/skills",
+    globalRoot: "~/.cursor/skills",
+    // Both scopes use a top-level `mcpServers` key. Verified 2026-07-12:
+    // https://cursor.com/docs/context/mcp ("Create `.cursor/mcp.json` in your project ...";
+    // "Create `~/.cursor/mcp.json` in your home directory ...").
+    mcpConfig: { project: ".cursor/mcp.json", global: "~/.cursor/mcp.json", verified: true }
+  },
   {
     id: "deepagents",
     displayName: "Deep Agents",
@@ -1409,13 +2010,24 @@ var AGENTS = [
     globalRoot: "~/.gemini/skills",
     // `gemini -p "<prompt>"` executes a single turn headlessly and exits. Verified 2026-07-11:
     // https://google-gemini.github.io/gemini-cli/docs/cli/headless.html
-    defaultHandoffTemplate: ["gemini", "-p", HANDOFF_INSTRUCTION]
+    defaultHandoffTemplate: ["gemini", "-p", HANDOFF_INSTRUCTION],
+    // `mcpServers` key inside `settings.json` (shared with other CLI settings, not an
+    // MCP-exclusive file, but the correct read/write target). User config at
+    // `~/.gemini/settings.json`, project config at `.gemini/settings.json`. Verified
+    // 2026-07-12: https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html
+    mcpConfig: { project: ".gemini/settings.json", global: "~/.gemini/settings.json", verified: true }
   },
   {
     id: "github-copilot",
     displayName: "GitHub Copilot",
     projectRoot: ".agents/skills",
-    globalRoot: "~/.copilot/skills"
+    globalRoot: "~/.copilot/skills",
+    // Copilot CLI (matches the `~/.copilot` skills convention above, not the VS Code
+    // extension — which uses a different `servers`-keyed `.vscode/mcp.json` and isn't covered
+    // by this entry). User config `~/.copilot/mcp-config.json` (`mcpServers` key), repo-level
+    // config `.github/mcp.json`. Verified 2026-07-12:
+    // https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers
+    mcpConfig: { project: ".github/mcp.json", global: "~/.copilot/mcp-config.json", verified: true }
   },
   { id: "goose", displayName: "Goose", projectRoot: ".goose/skills", globalRoot: "~/.config/goose/skills" },
   { id: "hermes-agent", displayName: "Hermes Agent", projectRoot: ".hermes/skills", globalRoot: "~/.hermes/skills" },
@@ -1464,7 +2076,15 @@ var AGENTS = [
   { id: "tinycloud", displayName: "Tinycloud", projectRoot: ".tinycloud/skills", globalRoot: "~/.tinycloud/skills" },
   { id: "trae", displayName: "Trae", projectRoot: ".trae/skills", globalRoot: "~/.trae/skills" },
   { id: "trae-cn", displayName: "Trae CN", projectRoot: ".trae/skills", globalRoot: "~/.trae-cn/skills" },
-  { id: "windsurf", displayName: "Windsurf", projectRoot: ".windsurf/skills", globalRoot: "~/.codeium/windsurf/skills" },
+  {
+    id: "windsurf",
+    displayName: "Windsurf",
+    projectRoot: ".windsurf/skills",
+    globalRoot: "~/.codeium/windsurf/skills",
+    // `mcpServers` key; global only — no project-scoped MCP config is documented. Verified
+    // 2026-07-12: https://docs.windsurf.com/windsurf/cascade/mcp
+    mcpConfig: { global: "~/.codeium/windsurf/mcp_config.json", verified: true }
+  },
   { id: "zcode", displayName: "ZCode", projectRoot: ".zcode/skills", globalRoot: "~/.zcode/skills" },
   { id: "zencoder", displayName: "Zencoder", projectRoot: ".zencoder/skills", globalRoot: "~/.zencoder/skills" },
   { id: "zenflow", displayName: "Zenflow", projectRoot: ".zencoder/skills", globalRoot: "~/.zencoder/skills" },
@@ -1483,6 +2103,15 @@ function detectAgents(cwd, home) {
   }
   return found;
 }
+function detectMcpTargets(cwd, home) {
+  const found = [];
+  for (const agent of AGENTS) {
+    for (const hit of detectMcpConfigFiles(agent, cwd, home)) {
+      found.push({ agent, ...hit });
+    }
+  }
+  return found;
+}
 function printDetectionResults(detected) {
   console.log(`[skill-forge] init \u2014 agent detection (${AGENTS.length} known agents)`);
   if (detected.length === 0) {
@@ -1493,17 +2122,27 @@ function printDetectionResults(detected) {
     console.log(`  ${d.agent.displayName} (${d.agent.id}) \u2014 ${d.scope}: ${d.root}`);
   }
 }
+function printMcpDetectionResults(detectedMcp) {
+  if (detectedMcp.length === 0) return;
+  console.log("\n[skill-forge] init \u2014 MCP config detection");
+  for (const d of detectedMcp) {
+    console.log(`  ${d.agent.displayName} (${d.agent.id}) \u2014 ${d.scope}: ${d.path}`);
+  }
+}
 function handoffTemplateFor(agent) {
   return agent.defaultHandoffTemplate ?? [agent.id, "-p", HANDOFF_INSTRUCTION];
 }
-function buildConfig(selected, defaultTargetEntry, handoffAgent) {
+function buildConfig(selected, defaultTargetEntry, handoffAgent, selectedMcp = []) {
   const existing = loadConfig();
   return {
     ...existing,
-    skillsRoots: selected.map((s) => s.root),
-    agents: selected.map((s) => ({ id: s.agent.id, skillsRoot: s.root })),
+    // Skill-root selections are only overwritten when this run actually offered a choice —
+    // an mcp-only run (no skill roots detected) must not blank out an existing skillsRoots/agents.
+    skillsRoots: selected.length > 0 ? selected.map((s) => s.root) : existing.skillsRoots,
+    agents: selected.length > 0 ? selected.map((s) => ({ id: s.agent.id, skillsRoot: s.root })) : existing.agents,
     defaultTarget: defaultTargetEntry?.root ?? existing.defaultTarget,
-    handoffCommand: handoffAgent ? handoffTemplateFor(handoffAgent) : existing.handoffCommand
+    handoffCommand: handoffAgent ? handoffTemplateFor(handoffAgent) : existing.handoffCommand,
+    mcpTargets: selectedMcp.length > 0 ? selectedMcp.map((m) => m.path) : existing.mcpTargets
   };
 }
 function printSummary(config) {
@@ -1512,6 +2151,7 @@ function printSummary(config) {
   console.log(`  gate targets: ${config.skillsRoots.join(", ")}`);
   if (config.defaultTarget) console.log(`  default target: ${config.defaultTarget}`);
   if (config.handoffCommand?.length) console.log(`  handoff command: ${config.handoffCommand.join(" ")}`);
+  if (config.mcpTargets?.length) console.log(`  mcp targets: ${config.mcpTargets.join(", ")}`);
 }
 function parseChoice(answer, max) {
   const n = Number(answer);
@@ -1537,6 +2177,26 @@ async function promptMultiSelect(rl, detected) {
   }
   return detected.filter((_, i) => chosen.has(i));
 }
+async function promptMcpMultiSelect(rl, detectedMcp) {
+  const chosen = new Set(detectedMcp.map((_, i) => i));
+  for (; ; ) {
+    console.log("\nMCP targets (all detected config files pre-selected \u2014 type a number to toggle, Enter to confirm):");
+    detectedMcp.forEach((d, i) => {
+      const mark = chosen.has(i) ? "[x]" : "[ ]";
+      console.log(`  ${mark} ${i + 1}. ${d.agent.displayName} (${d.scope}) \u2014 ${d.path}`);
+    });
+    const answer = (await rl.question("> ")).trim();
+    if (answer === "") break;
+    const idx = parseChoice(answer, detectedMcp.length);
+    if (idx !== void 0) {
+      if (chosen.has(idx)) chosen.delete(idx);
+      else chosen.add(idx);
+    } else {
+      console.log("  (invalid selection \u2014 enter a listed number, or press Enter to confirm)");
+    }
+  }
+  return detectedMcp.filter((_, i) => chosen.has(i));
+}
 async function promptDefaultTarget(rl, selected) {
   console.log("\nDefault promotion target:");
   selected.forEach((d, i) => console.log(`  ${i + 1}. ${d.agent.displayName} \u2014 ${d.root}`));
@@ -1559,17 +2219,19 @@ async function init(options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const home = options.home ?? homedir4();
   const detected = detectAgents(cwd, home);
+  const detectedMcp = detectMcpTargets(cwd, home);
   if (options.list) {
     printDetectionResults(detected);
+    printMcpDetectionResults(detectedMcp);
     return;
   }
-  if (detected.length === 0) {
-    console.log("[skill-forge] No known agent skill directories were found.");
+  if (detected.length === 0 && detectedMcp.length === 0) {
+    console.log("[skill-forge] No known agent skill directories or MCP config files were found.");
     console.log("  Install a coding agent (Claude Code, Codex, Cursor, ...) or create a skills root, then re-run `skill-forge init`.");
     return;
   }
   if (options.defaults) {
-    const config = buildConfig(detected, detected[0], void 0);
+    const config = buildConfig(detected, detected[0], void 0, detectedMcp);
     saveConfig(config);
     printSummary(config);
     return;
@@ -1579,16 +2241,18 @@ async function init(options = {}) {
     return;
   }
   printDetectionResults(detected);
+  printMcpDetectionResults(detectedMcp);
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const selected = await promptMultiSelect(rl, detected);
-    if (selected.length === 0) {
+    const selected = detected.length > 0 ? await promptMultiSelect(rl, detected) : [];
+    const selectedMcp = detectedMcp.length > 0 ? await promptMcpMultiSelect(rl, detectedMcp) : [];
+    if (selected.length === 0 && selectedMcp.length === 0) {
       console.log("[skill-forge] No targets selected \u2014 aborting, nothing written.");
       return;
     }
-    const target = await promptDefaultTarget(rl, selected);
-    const handoffAgent = await promptHandoffAgent(rl, detected);
-    const config = buildConfig(selected, target, handoffAgent);
+    const target = selected.length > 0 ? await promptDefaultTarget(rl, selected) : void 0;
+    const handoffAgent = detected.length > 0 ? await promptHandoffAgent(rl, detected) : void 0;
+    const config = buildConfig(selected, target, handoffAgent, selectedMcp);
     saveConfig(config);
     printSummary(config);
   } finally {
@@ -1597,7 +2261,7 @@ async function init(options = {}) {
 }
 async function maybeOfferInit(options = {}) {
   if (options.json || options.yes || !process.stdin.isTTY) return;
-  if (existsSync10(getConfigPath())) return;
+  if (existsSync12(getConfigPath())) return;
   console.log("[skill-forge] No config found \u2014 run `skill-forge init` to detect your agents and set gate targets.");
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   let answer = "";
@@ -1613,6 +2277,7 @@ async function maybeOfferInit(options = {}) {
 
 // src/commands/add.ts
 var PRO_FEATURE_LABEL = "overlap analysis, the provenance ledger, and the pending-ingestion queue";
+var MCP_PRO_FEATURE_LABEL = "overlap analysis and the pending-ingestion queue";
 function logOutcome(message, json) {
   if (json) console.error(message);
   else console.log(message);
@@ -1620,11 +2285,16 @@ function logOutcome(message, json) {
 async function add(source, options = {}) {
   await maybeOfferInit({ json: options.json, yes: options.yes });
   const config = loadConfig();
+  const artifact = options.artifact ?? "skill";
+  if (artifact === "mcp") {
+    await addMcp(source, config, options);
+    return;
+  }
   const targetRoot = options.target ?? config.defaultTarget ?? config.skillsRoots[0];
   if (!targetRoot) {
     throw new Error("no target skills root configured; pass --target <dir> or set skillsRoots in the config");
   }
-  const resolved = resolve(source);
+  const resolved = resolve(source, artifact);
   const entry = await quarantine(resolved, config.quarantineDir);
   if (entry.skillDirs.length === 0) {
     console.error(`[skill-forge] no SKILL.md found in installed source: ${source}`);
@@ -1640,9 +2310,13 @@ async function add(source, options = {}) {
   }
   const { safety, gateResult, proEnabled } = await runGate(entry.skillDirs[0], targetRoot, {
     proFeatureLabel: PRO_FEATURE_LABEL,
-    strictness: config.strictness
+    strictness: config.strictness,
+    artifact
   });
   const { profile, overlap } = gateResult;
+  if (profile.kind !== "skill") {
+    throw new Error(`expected a skill candidate, found a ${profile.kind}`);
+  }
   printGateOutput(gateResult, options.json);
   const decision = options.yes || options.json ? yesDecision(safety.verdict) : await promptDecision(safety.verdict);
   let installedPath = null;
@@ -1695,6 +2369,78 @@ async function add(source, options = {}) {
     }
   }
 }
+async function addMcp(source, config, options) {
+  const resolved = resolve(source, "mcp");
+  const entry = await quarantine(resolved, config.quarantineDir);
+  const candidatePath = resolveMcpCandidatePath(entry);
+  const { safety, gateResult, proEnabled } = await runGate(candidatePath, "", {
+    proFeatureLabel: MCP_PRO_FEATURE_LABEL,
+    strictness: config.strictness,
+    artifact: "mcp",
+    mcpTargets: config.mcpTargets ?? []
+  });
+  const { profile, overlap } = gateResult;
+  if (profile.kind !== "mcp") {
+    throw new Error(`expected an MCP candidate, found a ${profile.kind}`);
+  }
+  if (profile.serverCount > 1) {
+    console.error(
+      `[skill-forge] ${profile.serverCount} MCP servers found in ${source}; gating/promoting the first \u2014 the whole quarantine entry is promoted/rejected together:
+  ${profile.servers.join(", ")}`
+    );
+  }
+  printGateOutput(gateResult, options.json);
+  const decision = options.yes || options.json ? yesDecision(safety.verdict) : await promptDecision(safety.verdict);
+  let installedPath = null;
+  if (decision === "promote") {
+    const detail = resolveMcpCandidateDetail(profile);
+    const serverProfile = {
+      name: detail.name,
+      version: detail.version ?? "unknown",
+      envVars: detail.env ? Object.keys(detail.env) : void 0,
+      candidateEntry: detail.command ? { command: detail.command, args: detail.args, env: detail.env } : void 0
+    };
+    const mcpTargetPath = options.mcpTarget ?? config.mcpTargets?.[0] ?? join14(process.cwd(), ".mcp.json");
+    const result = promoteMcp(entry, serverProfile, mcpTargetPath, { force: options.force });
+    reject(entry);
+    logOutcome(`[skill-forge] promoted -> ${result.target} (server "${result.serverName}")`, options.json);
+    if (result.backupPath) {
+      logOutcome(`[skill-forge] backed up existing config -> ${result.backupPath}`, options.json);
+    }
+    if (result.envVarsToFill.length > 0) {
+      logOutcome(`[skill-forge] fill in these env vars before use: ${result.envVarsToFill.join(", ")}`, options.json);
+    }
+    installedPath = result.target;
+  } else if (decision === "reject") {
+    reject(entry);
+    logOutcome("[skill-forge] rejected \u2014 quarantine sandbox removed", options.json);
+    if (safety.verdict === "block") process.exitCode = 1;
+    return;
+  } else {
+    hold(entry);
+    logOutcome(`[skill-forge] held in quarantine -> ${entry.quarantinePath}`, options.json);
+  }
+  if (proEnabled) {
+    appendQueueEntry({
+      source,
+      sourceType: resolved.type,
+      installedPath,
+      quarantinePath: entry.quarantinePath,
+      gate: {
+        license: null,
+        safetyVerdict: safety.verdict,
+        safetyFindings: safety.findings.map((f) => `${f.severity} [${f.rule}] ${f.file}: ${f.detail}`),
+        overlapTop: overlap ? overlap.ranking.slice(0, 3).map((r) => ({ skill: r.skill, score: r.score })) : [],
+        suggestedVerb: overlap ? suggestVerbCode(overlap.nearestScore) : null
+      },
+      status: "pending",
+      artifactType: "mcp"
+    });
+    if (options.ingest && installedPath) {
+      runHandoff(config, installedPath);
+    }
+  }
+}
 function yesDecision(verdict) {
   return verdict === "block" ? "reject" : "promote";
 }
@@ -1722,25 +2468,41 @@ ${prompt}`);
 async function scan(source, options = {}) {
   await maybeOfferInit({ json: options.json });
   const config = loadConfig();
+  const artifact = options.artifact ?? "skill";
   const skillsRoot = config.defaultTarget ?? config.skillsRoots[0];
-  if (!skillsRoot) {
+  if (artifact === "skill" && !skillsRoot) {
     throw new Error("no skills root configured; set skillsRoots in the config");
   }
-  const resolved = resolve(source);
+  const resolved = resolve(source, artifact);
   const entry = await quarantine(resolved, config.quarantineDir);
   try {
-    if (entry.skillDirs.length === 0) {
-      console.error(`[skill-forge] no SKILL.md found in installed source: ${source}`);
-      process.exitCode = 1;
-      return;
+    let candidatePath;
+    if (artifact === "mcp") {
+      candidatePath = resolveMcpCandidatePath(entry);
+    } else {
+      if (entry.skillDirs.length === 0) {
+        console.error(`[skill-forge] no SKILL.md found in installed source: ${source}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (entry.skillDirs.length > 1) {
+        console.error(
+          `[skill-forge] ${entry.skillDirs.length} skills found in ${source}; scanning the first:
+` + entry.skillDirs.map((d) => `  - ${d}`).join("\n")
+        );
+      }
+      candidatePath = entry.skillDirs[0];
     }
-    if (entry.skillDirs.length > 1) {
+    const { safety, gateResult } = await runGate(candidatePath, skillsRoot ?? "", {
+      strictness: config.strictness,
+      artifact,
+      mcpTargets: config.mcpTargets ?? []
+    });
+    if (artifact === "mcp" && gateResult.profile.kind === "mcp" && gateResult.profile.serverCount > 1) {
       console.error(
-        `[skill-forge] ${entry.skillDirs.length} skills found in ${source}; scanning the first:
-` + entry.skillDirs.map((d) => `  - ${d}`).join("\n")
+        `[skill-forge] ${gateResult.profile.serverCount} MCP servers found in ${source}; scanning the first \u2014 ` + gateResult.profile.servers.join(", ")
       );
     }
-    const { safety, gateResult } = await runGate(entry.skillDirs[0], skillsRoot, { strictness: config.strictness });
     printGateOutput(gateResult, options.json);
     if (safety.verdict === "block") {
       process.exitCode = 1;
@@ -1751,7 +2513,7 @@ async function scan(source, options = {}) {
 }
 
 // src/commands/list.ts
-import { join as join12 } from "path";
+import { join as join15 } from "path";
 async function list() {
   await maybeOfferInit();
   const config = loadConfig();
@@ -1764,14 +2526,14 @@ async function list() {
   }
   console.log(`[skill-forge] ${ids.length} held in quarantine (${quarantineDir}):`);
   for (const id of ids) {
-    const skillDirs = findSkillDirs(join12(quarantineDir, id));
+    const skillDirs = findSkillDirs(join15(quarantineDir, id));
     if (skillDirs.length === 0) {
       console.log(`  ${id}  (no SKILL.md found)`);
       continue;
     }
     const names = skillDirs.map((dir) => {
       try {
-        return readFrontmatter(join12(dir, "SKILL.md")).name;
+        return readFrontmatter(join15(dir, "SKILL.md")).name;
       } catch {
         return dir;
       }
@@ -1795,10 +2557,19 @@ async function status() {
 // src/cli.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
+function parseArtifact(value) {
+  if (value !== "skill" && value !== "mcp") {
+    throw new UserError(`--artifact must be "skill" or "mcp" (got "${value}")`);
+  }
+  return value;
+}
 var program = new Command();
 program.name("skill-forge").description("The supply-chain gate for agent skills").version(pkg.version);
-program.command("add <source>").description("Quarantine-install a skill and run it through the safety gate").option("-y, --yes", "skip the interactive prompt; honor the gate verdict automatically").option("-t, --target <dir>", "skills root to promote into (defaults to config defaultTarget, then skillsRoots[0])").option("--json", "print the gate result as JSON instead of the terminal report").option("--ingest", "after a successful promote, hand off the bundled ingest prompt to a coding agent").action(add);
-program.command("scan <source>").description("Run the safety gate against a skill without installing it").option("--json", "print the gate result as JSON instead of the terminal report").action(scan);
+program.command("add <source>").description("Quarantine-install a skill and run it through the safety gate").option("-y, --yes", "skip the interactive prompt; honor the gate verdict automatically").option("-t, --target <dir>", "skills root to promote into (defaults to config defaultTarget, then skillsRoots[0])").option("--json", "print the gate result as JSON instead of the terminal report").option("--ingest", "after a successful promote, hand off the bundled ingest prompt to a coding agent").option("--artifact <type>", 'gate as a "skill" or an "mcp" server (default: skill)', parseArtifact).option(
+  "--mcp-target <file>",
+  "MCP config file to promote into (mcp artifacts only; defaults to config.mcpTargets[0], then <cwd>/.mcp.json)"
+).option("--force", "overwrite an existing same-name MCP server entry when promoting (mcp artifacts only)").action(add);
+program.command("scan <source>").description("Run the safety gate against a skill without installing it").option("--json", "print the gate result as JSON instead of the terminal report").option("--artifact <type>", 'gate as a "skill" or an "mcp" server (default: skill)', parseArtifact).action(scan);
 program.command("list").description("List skills currently in quarantine").action(list);
 program.command("status").description("Show skill-forge configuration and quarantine status").action(status);
 program.command("init").description("Detect installed agents and set gate targets, default promotion target, and handoff agent").option("--defaults", "non-interactive: use all detected agents as gate targets, the first as the default target").option("--list", "print detected agent skill roots and exit \u2014 no writes").action(init);