agent-skills-standard 2.1.2 → 2.2.0

package/dist/index.js

@@ -9,6 +9,7 @@ const path = require("path");
 const yaml = require("js-yaml");
 const zod = require("zod");
 const fetch$1 = require("cross-fetch");
+const os = require("os");
 const child_process = require("child_process");
 class FeedbackService {
   /**
@@ -838,6 +839,13 @@ const SUPPORTED_AGENTS = Object.values(Agent).map(getAgentDefinition);
 const SUPPORTED_FRAMEWORKS = Object.values(
   Framework
 ).map(getFrameworkDefinition);
+const McpScopeSchema = zod.z.enum(["project", "user", "snippets-only", "disabled"]);
+const McpConfigSchema = zod.z.object({
+  enabled: zod.z.boolean(),
+  scope: McpScopeSchema,
+  prompted: zod.z.boolean(),
+  version: zod.z.string().optional()
+});
 const SkillConfigSchema = zod.z.object({
   registry: zod.z.string().url(),
   agents: zod.z.array(zod.z.nativeEnum(Agent)).optional(),
@@ -851,7 +859,8 @@ const SkillConfigSchema = zod.z.object({
     })
   ),
   custom_overrides: zod.z.array(zod.z.string()).optional(),
-  workflows: zod.z.union([zod.z.boolean(), zod.z.array(zod.z.string())]).optional()
+  workflows: zod.z.union([zod.z.boolean(), zod.z.array(zod.z.string())]).optional(),
+  mcp: McpConfigSchema.optional()
 });
 class ConfigService {
   /**
@@ -1369,6 +1378,13 @@ class InitService {
     const projectDeps = await this.detectionService.getProjectDeps();
     this.configService.applyDependencyExclusions(config, projectDeps);
     this.configService.reconcileDependencies(config, projectDeps);
+    if (answers.mcpScope !== void 0) {
+      config.mcp = {
+        enabled: answers.mcpEnabled === true,
+        scope: answers.mcpEnabled === false ? "disabled" : answers.mcpScope,
+        prompted: true
+      };
+    }
     const commentHeader = `# Auto-detected configuration generated by agent-skills-standard init
 #
 # Presence in 'skills' list = Active. To disable a skill, remove it from the list.
@@ -1669,15 +1685,70 @@ class InitCommand {
         default: DEFAULT_REGISTER
       }
     ]);
+    this.printMcpValueProp();
+    const mcpDecision = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "mcpEnabled",
+        message: "Enable MCP server integration?",
+        default: true
+      },
+      {
+        type: "list",
+        name: "mcpScope",
+        message: "Where should sync write MCP configs?",
+        when: (a) => a.mcpEnabled === true,
+        choices: [
+          {
+            name: "project (recommended)  — only files inside this project (.mcp.json, .cursor/mcp.json, etc.)",
+            value: "project"
+          },
+          {
+            name: "user                    — also $HOME files (~/.cursor/mcp.json, ~/.gemini/settings.json) — sync prompts each",
+            value: "user"
+          },
+          {
+            name: "snippets-only           — never edits any runtime config; just generates ./mcp-config-snippets/*.json",
+            value: "snippets-only"
+          }
+        ],
+        default: "project"
+      }
+    ]);
+    answers.mcpEnabled = mcpDecision.mcpEnabled;
+    answers.mcpScope = mcpDecision.mcpEnabled ? mcpDecision.mcpScope : "disabled";
     await this.initService.buildAndSaveConfig(answers, metadata);
     console.log(pc.green("\n✅ Initialized .skillsrc with your preferences!"));
     console.log(pc.gray(`   Selected framework: ${answers.framework}`));
+    if (answers.mcpEnabled) {
+      console.log(pc.gray(`   MCP integration: enabled (scope: ${answers.mcpScope})`));
+    } else {
+      console.log(pc.gray(`   MCP integration: disabled (change later via \`ags mcp enable\`)`));
+    }
     console.log(
       pc.cyan(
-        "\nNext step: Run `agent-skills-standard sync` to generate rule files."
+        "\nNext step: Run `agent-skills-standard sync` to install skills and wire MCP."
       )
     );
   }
+  printMcpValueProp() {
+    console.log(pc.bold("\n🔌 MCP server setup\n"));
+    console.log(
+      "agent-skills-standard ships an optional MCP server that serves your skills"
+    );
+    console.log("to AI agents at runtime. Quick comparison:\n");
+    console.log(pc.bold("  WITHOUT MCP") + " (skills as static files only)");
+    console.log(pc.green("    ✓") + " Zero setup overhead");
+    console.log(pc.red("    ✗") + " Sub-agents (Claude Code tdd-implementer, architecture-guard, etc.)");
+    console.log("      do NOT inherit AGENTS.md — they often skip skill loading entirely");
+    console.log(pc.red("    ✗") + " No audit trail of which skills were consulted");
+    console.log(pc.red("    ✗") + " False findings in code review (agent uses pre-training defaults)\n");
+    console.log(pc.bold("  WITH MCP") + " (runtime tool calls)");
+    console.log(pc.green("    ✓") + " Sub-agents in EVERY runtime can call load_skills_for_files");
+    console.log(pc.green("    ✓") + " Returns matched SKILL.md as a tool response — can't be silently skipped");
+    console.log(pc.green("    ✓") + " audit_session_compliance gives you a receipt of what was loaded");
+    console.log(pc.gray("    -") + " Adds one more process to your AI runtime config\n");
+  }
 }
 class SkillService {
   registryService = new RegistryService();
@@ -1793,9 +1864,588 @@ Available skills for ${framework}:`));
     );
   }
 }
+const SERVER_NAME = "agent-skills-standard";
+const PACKAGE = "agent-skills-standard-mcp";
+const getTargets = (home = os.homedir()) => {
+  const HOME = home;
+  return {
+    [Agent.Claude]: {
+      agent: Agent.Claude,
+      projectFile: ".mcp.json",
+      userFile: path.join(HOME, ".claude", ".mcp.json"),
+      key: "mcpServers",
+      shape: "map"
+    },
+    [Agent.Cursor]: {
+      agent: Agent.Cursor,
+      projectFile: ".cursor/mcp.json",
+      userFile: path.join(HOME, ".cursor", "mcp.json"),
+      key: "mcpServers",
+      shape: "map"
+    },
+    [Agent.Antigravity]: {
+      agent: Agent.Antigravity,
+      projectFile: ".antigravity/mcp.json",
+      userFile: null,
+      key: "mcpServers",
+      shape: "map"
+    },
+    [Agent.Kiro]: {
+      agent: Agent.Kiro,
+      projectFile: ".kiro/settings/mcp.json",
+      userFile: null,
+      key: "mcpServers",
+      shape: "map"
+    },
+    [Agent.Windsurf]: {
+      agent: Agent.Windsurf,
+      projectFile: ".codeium/windsurf/mcp_config.json",
+      userFile: path.join(HOME, ".codeium", "windsurf", "mcp_config.json"),
+      key: "mcpServers",
+      shape: "map"
+    },
+    [Agent.Trae]: {
+      agent: Agent.Trae,
+      projectFile: ".trae/mcp.json",
+      userFile: null,
+      key: "mcpServers",
+      shape: "map"
+    },
+    [Agent.Roo]: {
+      agent: Agent.Roo,
+      projectFile: ".roo/mcp.json",
+      userFile: null,
+      key: "mcpServers",
+      shape: "map"
+    },
+    [Agent.Gemini]: {
+      agent: Agent.Gemini,
+      projectFile: ".gemini/settings.json",
+      userFile: path.join(HOME, ".gemini", "settings.json"),
+      key: "mcpServers",
+      shape: "map"
+    }
+  };
+};
+class McpConfigService {
+  /** Returns the standard MCP server entry our CLI proposes. */
+  buildEntry(version2) {
+    const spec = version2 ? `${PACKAGE}@${version2}` : PACKAGE;
+    return { command: "npx", args: ["-y", spec] };
+  }
+  /** For testing: allows overriding the home directory. */
+  testHome = null;
+  setHomeForTesting(home) {
+    this.testHome = home;
+  }
+  getTargets() {
+    return getTargets(this.testHome ?? void 0);
+  }
+  /**
+   * Write MCP configs for the given agents based on the configured scope.
+   * Always safe-merge (never overwrite other servers, never replace whole files).
+   */
+  async install(opts) {
+    const report = {
+      projectWrites: [],
+      userWrites: [],
+      snippets: [],
+      declined: [],
+      unsupported: []
+    };
+    const { rootDir, agents, mcp } = opts;
+    if (mcp.scope === "disabled" || !mcp.enabled) {
+      return report;
+    }
+    const TARGETS = this.getTargets();
+    const entry = this.buildEntry(mcp.version);
+    await this.generateSnippets(rootDir, agents, entry, report);
+    if (mcp.scope === "snippets-only") {
+      return report;
+    }
+    for (const agent of agents) {
+      const target = TARGETS[agent];
+      if (!target) {
+        report.unsupported.push(agent);
+        continue;
+      }
+      if (target.projectFile) {
+        const abs = path.join(rootDir, target.projectFile);
+        const action = await this.mergeFile(abs, target, entry);
+        report.projectWrites.push({ agent, file: target.projectFile, action });
+      }
+      if (mcp.scope === "user" && target.userFile) {
+        const ok = opts.userScopePrompt ? await opts.userScopePrompt(agent, target.userFile) : false;
+        if (!ok) {
+          report.declined.push({ agent, file: target.userFile });
+          continue;
+        }
+        const action = await this.mergeFile(target.userFile, target, entry);
+        report.userWrites.push({ agent, file: target.userFile, action });
+      }
+    }
+    return report;
+  }
+  /**
+   * Remove our MCP entry from configs we may have added it to. Other entries
+   * in the same file are untouched.
+   */
+  async uninstall(opts) {
+    const removed = [];
+    const TARGETS = this.getTargets();
+    for (const agent of opts.agents) {
+      const target = TARGETS[agent];
+      if (!target) continue;
+      const candidates = [];
+      if (target.projectFile && (opts.from === "project" || opts.from === "all")) {
+        candidates.push({
+          abs: path.join(opts.rootDir, target.projectFile),
+          rel: target.projectFile
+        });
+      }
+      if (target.userFile && (opts.from === "user" || opts.from === "all")) {
+        candidates.push({ abs: target.userFile, rel: target.userFile });
+      }
+      for (const { abs, rel } of candidates) {
+        if (!await fs.pathExists(abs)) continue;
+        const removedHere = await this.removeFromFile(abs, target);
+        if (removedHere) removed.push({ agent, file: rel });
+      }
+    }
+    return { removed };
+  }
+  /** Snapshot what's currently installed. Read-only. */
+  async status(opts) {
+    const out = [];
+    const TARGETS = this.getTargets();
+    for (const agent of opts.agents) {
+      const target = TARGETS[agent];
+      if (!target) continue;
+      const row = {
+        agent
+      };
+      if (target.projectFile) {
+        row.project = await this.hasOurEntry(
+          path.join(opts.rootDir, target.projectFile),
+          target
+        );
+      }
+      if (target.userFile) {
+        row.user = await this.hasOurEntry(target.userFile, target);
+      }
+      out.push(row);
+    }
+    return out;
+  }
+  // ---- private helpers ----
+  async generateSnippets(rootDir, agents, entry, report) {
+    const dir = path.join(rootDir, "mcp-config-snippets");
+    await fs.ensureDir(dir);
+    const TARGETS = this.getTargets();
+    for (const agent of agents) {
+      const target = TARGETS[agent];
+      if (!target) continue;
+      const file = path.join(dir, `${agent}.json`);
+      const snippet = this.buildFreshDoc(target, entry);
+      await fs.writeJson(file, snippet, { spaces: 2 });
+      report.snippets.push({ agent, file: path.relative(rootDir, file) });
+    }
+  }
+  /**
+   * Read-modify-write a config file. Only the SERVER_NAME key is touched.
+   * Never replaces or removes other entries.
+   */
+  async mergeFile(abs, target, entry) {
+    const existing = await fs.pathExists(abs) ? await fs.readJson(abs).catch(() => ({})) : {};
+    const container = this.ensurePathContainer(existing, target);
+    if (target.shape === "map") {
+      const map = container;
+      const previous = map[SERVER_NAME];
+      const next = entry;
+      if (previous && deepEqual(previous, next)) {
+        return "skipped-existing";
+      }
+      map[SERVER_NAME] = next;
+      await this.writeAtomic(abs, existing);
+      return previous ? "updated" : "added";
+    } else {
+      const list = container;
+      const idx = list.findIndex((item) => item.name === SERVER_NAME);
+      const next = {
+        name: SERVER_NAME,
+        transport: { type: "stdio", ...entry }
+      };
+      if (idx >= 0) {
+        if (deepEqual(list[idx], next)) return "skipped-existing";
+        list[idx] = next;
+        await this.writeAtomic(abs, existing);
+        return "updated";
+      }
+      list.push(next);
+      await this.writeAtomic(abs, existing);
+      return "added";
+    }
+  }
+  async removeFromFile(abs, target) {
+    const data = await fs.readJson(abs).catch(() => null);
+    if (!data) return false;
+    const container = this.ensurePathContainer(data, target);
+    if (target.shape === "map") {
+      const map = container;
+      if (!(SERVER_NAME in map)) return false;
+      delete map[SERVER_NAME];
+      await this.writeAtomic(abs, data);
+      return true;
+    } else {
+      const list = container;
+      const before = list.length;
+      const filtered = list.filter((item) => item.name !== SERVER_NAME);
+      if (filtered.length === before) return false;
+      this.setNestedValue(data, target.key, filtered);
+      await this.writeAtomic(abs, data);
+      return true;
+    }
+  }
+  async hasOurEntry(abs, target) {
+    if (!await fs.pathExists(abs)) return false;
+    const data = await fs.readJson(abs).catch(() => null);
+    if (!data) return false;
+    const container = this.getNestedValue(data, target.key);
+    if (!container) return false;
+    if (target.shape === "map") {
+      return Boolean(container[SERVER_NAME]);
+    }
+    return container.some(
+      (item) => item.name === SERVER_NAME
+    );
+  }
+  buildFreshDoc(target, entry) {
+    const doc = {};
+    const container = target.shape === "map" ? { [SERVER_NAME]: entry } : [{ name: SERVER_NAME, transport: { type: "stdio", ...entry } }];
+    this.setNestedValue(doc, target.key, container);
+    return doc;
+  }
+  ensurePathContainer(data, target) {
+    const existing = this.getNestedValue(data, target.key);
+    if (existing) {
+      if (target.shape === "map") {
+        if (typeof existing === "object" && existing !== null && !Array.isArray(existing)) {
+          return existing;
+        }
+      } else if (target.shape === "list") {
+        if (Array.isArray(existing)) {
+          return existing;
+        }
+      }
+    }
+    const fresh = target.shape === "map" ? {} : [];
+    this.setNestedValue(data, target.key, fresh);
+    return fresh;
+  }
+  getNestedValue(data, dotted) {
+    const parts = dotted.split(".");
+    let cur = data;
+    for (const p of parts) {
+      if (p === "__proto__" || p === "constructor" || p === "prototype") {
+        throw new Error(
+          `Prototype pollution attempt detected in key: ${dotted}`
+        );
+      }
+      if (typeof cur !== "object" || cur === null) return void 0;
+      cur = cur[p];
+    }
+    return cur;
+  }
+  setNestedValue(data, dotted, value) {
+    const parts = dotted.split(".");
+    let cur = data;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const p = parts[i];
+      if (p === "__proto__" || p === "constructor" || p === "prototype") {
+        throw new Error(
+          `Prototype pollution attempt detected in key: ${dotted}`
+        );
+      }
+      if (typeof cur[p] !== "object" || cur[p] === null) {
+        cur[p] = {};
+      }
+      cur = cur[p];
+    }
+    const last = parts[parts.length - 1];
+    if (last === "__proto__" || last === "constructor" || last === "prototype") {
+      throw new Error(`Prototype pollution attempt detected in key: ${dotted}`);
+    }
+    cur[last] = value;
+  }
+  async writeAtomic(abs, data) {
+    await fs.ensureDir(path.dirname(abs));
+    const tmp = `${abs}.tmp`;
+    await fs.writeJson(tmp, data, { spaces: 2 });
+    await fs.move(tmp, abs, { overwrite: true });
+  }
+}
+function defaultMcpConfig() {
+  return { enabled: false, scope: "snippets-only", prompted: false };
+}
+function deepEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+const VALID_SCOPES = ["project", "user", "snippets-only", "disabled"];
+class McpCommand {
+  configService;
+  mcpService;
+  constructor(configService, mcpService) {
+    this.configService = configService ?? new ConfigService();
+    this.mcpService = mcpService ?? new McpConfigService();
+  }
+  async run(action, options = {}) {
+    const config = await this.configService.loadConfig();
+    if (!config) {
+      console.log(
+        pc.red(
+          "❌ .skillsrc not found. Run `agent-skills-standard init` first."
+        )
+      );
+      return;
+    }
+    const cwd = process.cwd();
+    const agents = config.agents ?? [];
+    switch (action) {
+      case "status":
+        return this.actionStatus(config, cwd);
+      case "enable":
+        return this.actionEnable(config);
+      case "disable":
+        return this.actionDisable(config);
+      case "scope":
+        return this.actionScope(config, options);
+      case "install":
+        return this.actionInstall(config, agents, cwd, options);
+      case "uninstall":
+        return this.actionUninstall(config, agents, cwd, options);
+      case "snippets":
+        return this.actionSnippets(config, agents, cwd);
+      default:
+        console.log(
+          pc.red(`Unknown action: ${action}`),
+          "\nValid actions: status, enable, disable, scope, install, uninstall, snippets"
+        );
+    }
+  }
+  // ---- actions ----
+  async actionStatus(config, cwd) {
+    const mcp = config.mcp ?? defaultMcpConfig();
+    const agents = config.agents ?? [];
+    const rows = await this.mcpService.status({ rootDir: cwd, agents });
+    console.log(pc.bold("\n🔌 MCP integration status\n"));
+    console.log(`  enabled : ${mcp.enabled ? pc.green("yes") : pc.gray("no")}`);
+    console.log(`  scope   : ${pc.cyan(mcp.scope)}`);
+    console.log(`  prompted: ${mcp.prompted ? "yes" : "no"}`);
+    if (mcp.version) console.log(`  version : ${mcp.version}`);
+    if (rows.length === 0) {
+      console.log(pc.gray("\n  (no agents configured)"));
+      return;
+    }
+    console.log("\n  Per-agent installation state:");
+    let installedAnywhere = false;
+    for (const row of rows) {
+      const project = row.project === void 0 ? "—" : row.project ? pc.green("✓") : pc.gray("✗");
+      const user = row.user === void 0 ? "—" : row.user ? pc.green("✓") : pc.gray("✗");
+      if (row.project === true || row.user === true) installedAnywhere = true;
+      console.log(`    ${row.agent.padEnd(12)} project: ${project}   user: ${user}`);
+    }
+    if (!mcp.enabled && installedAnywhere) {
+      console.log(
+        pc.yellow(
+          "\n⚠️  Mismatch detected: .skillsrc says mcp.enabled=false, but the MCP entry IS present in at least one runtime config."
+        )
+      );
+      console.log(
+        pc.gray(
+          "   The MCP will work, but `sync` will not keep its config in step. Consider one of:"
+        )
+      );
+      console.log(
+        pc.gray(
+          "     • `ags mcp enable`              — opt the project in (CLI keeps configs in step)"
+        )
+      );
+      console.log(
+        pc.gray(
+          "     • `ags mcp uninstall --from project` — remove the manual entry if it was unintended"
+        )
+      );
+    } else if (mcp.enabled && !installedAnywhere) {
+      console.log(
+        pc.yellow(
+          "\n⚠️  Mismatch detected: .skillsrc says mcp.enabled=true, but no runtime config has the MCP registered."
+        )
+      );
+      console.log(
+        pc.gray(
+          "   Run `ags mcp install` to write the entries, or `ags mcp disable` to clear the consent flag."
+        )
+      );
+    }
+  }
+  async actionEnable(config) {
+    const mcp = config.mcp ?? defaultMcpConfig();
+    if (mcp.scope === "disabled") {
+      console.log(
+        pc.yellow(
+          '⚠️  scope is currently "disabled". Set a real scope first: `ags mcp scope project`'
+        )
+      );
+      return;
+    }
+    config.mcp = { ...mcp, enabled: true, prompted: true };
+    await this.configService.saveConfig(config);
+    console.log(pc.green("✅ MCP enabled."));
+    console.log(pc.gray("   Run `ags mcp install` to write configs now, or it happens on next `sync`."));
+  }
+  async actionDisable(config) {
+    const mcp = config.mcp ?? defaultMcpConfig();
+    config.mcp = { ...mcp, enabled: false, prompted: true };
+    await this.configService.saveConfig(config);
+    console.log(pc.yellow("🔕 MCP disabled."));
+    console.log(pc.gray("   Existing config entries were NOT removed. Use `ags mcp uninstall` to clean them."));
+  }
+  async actionScope(config, options) {
+    const scope = options.scope ?? options._?.[0];
+    if (!scope || !VALID_SCOPES.includes(scope)) {
+      console.log(
+        pc.red(`Invalid scope. Valid: ${VALID_SCOPES.join(" | ")}`)
+      );
+      return;
+    }
+    const mcp = config.mcp ?? defaultMcpConfig();
+    config.mcp = { ...mcp, scope, prompted: true };
+    await this.configService.saveConfig(config);
+    console.log(pc.green(`✅ MCP scope set to "${scope}".`));
+    if (scope === "user") {
+      console.log(
+        pc.yellow(
+          "⚠️  user-scope writes will be prompted per file during `sync` or `install`."
+        )
+      );
+    }
+  }
+  async actionInstall(config, agents, cwd, options) {
+    const mcp = config.mcp ?? defaultMcpConfig();
+    const scopeOverride = options.scope;
+    const effectiveScope = scopeOverride ?? mcp.scope;
+    if (scopeOverride && !VALID_SCOPES.includes(scopeOverride)) {
+      console.log(
+        pc.red(`Invalid --scope value. Valid: ${VALID_SCOPES.join(" | ")}`)
+      );
+      return;
+    }
+    if (effectiveScope === "disabled") {
+      console.log(pc.yellow('Scope is "disabled" — nothing to install.'));
+      return;
+    }
+    const userPrompt = async (agent, file) => {
+      const { ok } = await inquirer.prompt([
+        {
+          type: "confirm",
+          name: "ok",
+          message: `Write user-scope MCP config for ${pc.cyan(agent)} at ${pc.gray(file)}?`,
+          default: false
+        }
+      ]);
+      return ok;
+    };
+    const report = await this.mcpService.install({
+      rootDir: cwd,
+      agents,
+      mcp: { ...mcp, enabled: true, scope: effectiveScope },
+      userScopePrompt: userPrompt
+    });
+    this.printReport(report, cwd);
+  }
+  async actionUninstall(config, agents, cwd, options) {
+    const from = options.from ?? "project";
+    if (!["project", "user", "all"].includes(from)) {
+      console.log(pc.red("--from must be: project | user | all"));
+      return;
+    }
+    const { removed } = await this.mcpService.uninstall({
+      rootDir: cwd,
+      agents,
+      from
+    });
+    if (removed.length === 0) {
+      console.log(pc.gray(`Nothing to remove at scope "${from}".`));
+      return;
+    }
+    console.log(pc.green(`✅ Removed agent-skills MCP entry from:`));
+    for (const r of removed) {
+      console.log(`   - ${pc.cyan(r.agent)} → ${pc.gray(r.file)}`);
+    }
+  }
+  async actionSnippets(config, agents, cwd) {
+    const mcp = config.mcp ?? defaultMcpConfig();
+    const report = await this.mcpService.install({
+      rootDir: cwd,
+      agents,
+      mcp: { ...mcp, enabled: true, scope: "snippets-only" }
+    });
+    if (report.snippets.length === 0) {
+      console.log(pc.gray("No snippets generated (no supported agents in .skillsrc)."));
+      return;
+    }
+    console.log(pc.green(`✅ Generated ${report.snippets.length} snippet(s):`));
+    for (const s of report.snippets) {
+      console.log(`   - ${pc.cyan(s.agent)} → ${pc.gray(s.file)}`);
+    }
+  }
+  // ---- output ----
+  printReport(report, cwd) {
+    if (report.projectWrites.length > 0) {
+      console.log(pc.bold("\n📁 Project-scope writes:"));
+      for (const w of report.projectWrites) {
+        const tag = w.action === "added" ? pc.green("+ added   ") : w.action === "updated" ? pc.cyan("~ updated ") : pc.gray("= up-to-date");
+        console.log(`   ${tag} ${w.agent.padEnd(12)} ${pc.gray(w.file)}`);
+      }
+    }
+    if (report.userWrites.length > 0) {
+      console.log(pc.bold("\n🏠 User-scope writes:"));
+      for (const w of report.userWrites) {
+        console.log(`   ${pc.green("+ wrote   ")} ${w.agent.padEnd(12)} ${pc.gray(path.relative(cwd, w.file))}`);
+      }
+    }
+    if (report.declined.length > 0) {
+      console.log(pc.bold("\n⏭  User-scope declined:"));
+      for (const d of report.declined) {
+        console.log(`   ${pc.gray("-")} ${d.agent.padEnd(12)} ${pc.gray(d.file)}`);
+      }
+    }
+    if (report.snippets.length > 0) {
+      console.log(pc.bold("\n📄 Snippet files:"));
+      for (const s of report.snippets) {
+        console.log(`   ${pc.gray(s.file)}`);
+      }
+    }
+    if (report.unsupported.length > 0) {
+      console.log(
+        pc.gray(
+          `
+(skipped — no MCP support yet: ${report.unsupported.join(", ")})`
+        )
+      );
+    }
+  }
+}
 class AgentBridgeService {
   /**
    * Bridges native agent rule files to AGENTS.md by creating discovery instructions.
+   *
+   * The MCP runtime-enforcement block lives in `AGENTS.md` (single source of
+   * truth, generated by `IndexGeneratorService.assembleRouterIndex`). Rule
+   * files generated here just instruct the agent to read AGENTS.md first —
+   * they do NOT duplicate the MCP block. This keeps the message in one place
+   * so it can't drift between surfaces.
+   *
    * @param rootDir Project root directory
    * @param agents List of agents to generate rules for
    */
@@ -1885,7 +2535,7 @@ applyTo: '**/*'
           "",
           "## Agent Protocol",
           "",
-          "See `AGENTS.md` for the Zero-Trust skill loading protocol (applies to all AI agents).",
+          "See `AGENTS.md` for the Zero-Trust skill loading protocol (applies to all AI agents) and the MCP runtime-enforcement section (when enabled).",
           "",
           "## Self-Learning Protocol",
           "",
@@ -2354,7 +3004,7 @@ class IndexGeneratorServiceImpl extends IndexGeneratorService {
     );
     return lines.join("\n");
   }
-  async assembleRouterIndex(baseDir, allowedCategories) {
+  async assembleRouterIndex(baseDir, allowedCategories, mcpEnabled = false) {
     const fileRouting = await this.reader.loadFileRouting(baseDir);
     let availableCategories = [];
     if (await fs.pathExists(baseDir)) {
@@ -2403,12 +3053,35 @@ class IndexGeneratorServiceImpl extends IndexGeneratorService {
         "| QE workflow | `<SKILLS>/quality-engineering/_INDEX.md` |"
       );
     }
+    const mcpStatusNote = mcpEnabled ? "> [!TIP] **This project has the MCP server enabled in `.skillsrc`** — `sync` keeps your runtime configs in step. Run `ags mcp status` to verify per-agent installation." : "> [!NOTE] To enable MCP-managed installs in this project, run `ags mcp enable` (or edit `.skillsrc`). The MCP works fine if you registered it manually too.";
+    const mcpBlock = [
+      "## 🔌 Runtime Enforcement via MCP",
+      "",
+      "If the `agent-skills-standard` MCP server is registered in your runtime (check your tool list — look for `load_skills_for_files`), **prefer those tools over manually walking the router below**. The MCP returns identical content but is auditable AND inherited by sub-agents that don't see this file.",
+      "",
+      "| Tool | When to call it |",
+      "| --- | --- |",
+      "| `load_skills_for_files(files=[...])` | Before editing/reviewing any source file |",
+      "| `load_skills_for_keywords(keywords=[...])` | Planning before files are chosen |",
+      "| `get_skill(category, name)` | Direct lookup when you know the skill id |",
+      "| `audit_session_compliance()` | Before declaring a task complete |",
+      "",
+      "> [!IMPORTANT] **Sub-agents don't inherit this `AGENTS.md` — they do inherit the MCP.** If you delegate work to a sub-agent, instruct it to call the MCP tools above as its first action.",
+      "",
+      mcpStatusNote,
+      "",
+      "If `load_skills_for_files` is **not** in your tool list, the MCP is not registered — fall back to the router table below.",
+      "",
+      "---",
+      ""
+    ].join("\n");
     const header = [
       "## Agent Skills Index",
       "",
       "> [!CRITICAL] Zero-Trust: Read the matching `SKILL.md` BEFORE writing any code.",
       '> Skills from this index override pre-training patterns. If no skill matches, state: "No project-specific skills applicable."',
       "",
+      mcpBlock,
       "## Skill Resolution Protocol",
       "",
       "Each `_INDEX.md` has two sections - follow both:",
@@ -3060,9 +3733,11 @@ class SyncService {
           )
         );
       }
+      const mcpEnabled = config.mcp?.enabled === true;
       const routerIndex = await generator.assembleRouterIndex(
         baseDir,
-        allowedCategories
+        allowedCategories,
+        mcpEnabled
       );
       await MarkdownUtils.injectIndex(
         process.cwd(),
@@ -3121,10 +3796,12 @@ class SyncCommand {
   configService;
   detectionService;
   syncService;
-  constructor(configService, detectionService, syncService) {
+  mcpService;
+  constructor(configService, detectionService, syncService, mcpService) {
     this.configService = configService || new ConfigService();
     this.detectionService = detectionService || new DetectionService();
     this.syncService = syncService || new SyncService();
+    this.mcpService = mcpService || new McpConfigService();
   }
   /**
    * Executes the synchronization flow.
@@ -3198,6 +3875,7 @@ class SyncCommand {
       await this.syncService.writeWorkflows(workflows, config);
       await this.syncService.applyIndices(config, config.agents);
       console.log(pc.green("✅ All skills synced successfully!"));
+      await this.runMcpPhase(config, options);
     } catch (error) {
       if (error instanceof Error) {
         console.error(pc.red("❌ Sync failed:"), error.message);
@@ -3206,19 +3884,132 @@ class SyncCommand {
       }
     }
   }
+  /**
+   * Phase 7 — MCP integration. Three paths:
+   *   A. Never prompted yet: ask once now (with full value-prop), persist decision.
+   *   B. Already prompted, mcp.enabled=true: dispatch install at the configured scope.
+   *   C. Already prompted, mcp.enabled=false: skip silently.
+   *
+   * In non-interactive mode (no TTY) and never-prompted: skip with a hint, do
+   * not assume consent. Users can opt in later via `ags mcp enable`.
+   */
+  async runMcpPhase(config, options) {
+    const mcp = config.mcp ?? defaultMcpConfig();
+    const agents = config.agents ?? [];
+    if (!mcp.prompted) {
+      if (!process.stdin.isTTY && !options.yes) {
+        console.log(
+          pc.gray(
+            "\nℹ️  MCP integration not yet configured. Run `ags mcp enable` (or `ags mcp scope project`) when ready."
+          )
+        );
+        return;
+      }
+      const decided = await this.promptMcpConsent(options);
+      config.mcp = {
+        enabled: decided.enabled,
+        scope: decided.enabled ? decided.scope : "disabled",
+        prompted: true
+      };
+      await this.configService.saveConfig(config);
+    }
+    const finalMcp = config.mcp ?? defaultMcpConfig();
+    if (!finalMcp.enabled || finalMcp.scope === "disabled") {
+      return;
+    }
+    const userScopePrompt = options.yes ? async () => true : async (agent, file) => {
+      const { ok } = await inquirer.prompt([
+        {
+          type: "confirm",
+          name: "ok",
+          message: `Write user-scope MCP config for ${pc.cyan(agent)} at ${pc.gray(file)}?`,
+          default: false
+        }
+      ]);
+      return ok;
+    };
+    console.log(pc.cyan("\n🔌 Wiring MCP server..."));
+    const report = await this.mcpService.install({
+      rootDir: process.cwd(),
+      agents,
+      mcp: finalMcp,
+      userScopePrompt
+    });
+    for (const w of report.projectWrites) {
+      const tag = w.action === "added" ? pc.green("  + added   ") : w.action === "updated" ? pc.cyan("  ~ updated ") : pc.gray("  = up-to-date");
+      console.log(`${tag} ${w.agent.padEnd(12)} ${pc.gray(w.file)}`);
+    }
+    for (const w of report.userWrites) {
+      console.log(`  ${pc.green("+ wrote   ")} ${w.agent.padEnd(12)} ${pc.gray(w.file)}`);
+    }
+    for (const d of report.declined) {
+      console.log(`  ${pc.gray("-         ")} ${d.agent.padEnd(12)} ${pc.gray(d.file)} (declined)`);
+    }
+    if (report.snippets.length > 0) {
+      console.log(
+        pc.gray(`  ${report.snippets.length} snippet(s) written to ./mcp-config-snippets/`)
+      );
+    }
+    if (report.unsupported.length > 0) {
+      console.log(
+        pc.gray(`  (skipped — no MCP support yet: ${report.unsupported.join(", ")})`)
+      );
+    }
+  }
+  async promptMcpConsent(options) {
+    if (options.yes) {
+      return { enabled: true, scope: "project" };
+    }
+    console.log(pc.bold("\n🔌 MCP server setup\n"));
+    console.log("agent-skills-standard ships an optional MCP server that serves your skills");
+    console.log("to AI agents at runtime. Quick comparison:\n");
+    console.log(pc.bold("  WITHOUT MCP:") + " sub-agents skip skill loading; no audit trail");
+    console.log(pc.bold("  WITH MCP:   ") + " every sub-agent can call load_skills_for_files; auditable\n");
+    const decision = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "enabled",
+        message: "Enable MCP server integration?",
+        default: true
+      },
+      {
+        type: "list",
+        name: "scope",
+        message: "Where should sync write MCP configs?",
+        when: (a) => a.enabled === true,
+        choices: [
+          {
+            name: "project (recommended)  — only files inside this project",
+            value: "project"
+          },
+          {
+            name: "user                    — also $HOME files (sync prompts each)",
+            value: "user"
+          },
+          {
+            name: "snippets-only           — never edits any runtime config",
+            value: "snippets-only"
+          }
+        ],
+        default: "project"
+      }
+    ]);
+    return decision;
+  }
 }
-const version = "2.1.2";
+const version = "2.2.0";
 const pkg = {
   version
 };
 class UpgradeCommand {
+  currentVersion = pkg.version;
   /**
    * Executes the upgrade flow.
    * @param options Command options, including `dryRun` to check for updates without installing.
    */
   async run(options) {
     console.log(pc.cyan("🔍 Checking for updates..."));
-    const currentVersion = pkg.version;
+    const currentVersion = this.currentVersion;
     let latestVersion = null;
     try {
       latestVersion = child_process.execSync("npm view agent-skills-standard version", {
@@ -3737,7 +4528,7 @@ dotenv.config();
 const program = new commander.Command();
 program.name("agent-skills-standard").description(
   "A CLI to manage and sync AI agent skills for Cursor, Claude, Copilot, Windsurf, and more."
-).version("2.1.2");
+).version("2.2.0");
 program.command("init").description("Initialize a .skillsrc configuration file interactively").action(async () => {
   const init = new InitCommand();
   await init.run();
@@ -3786,5 +4577,15 @@ program.command("upgrade").description("Upgrade the CLI to the latest version").
   const cmd = new UpgradeCommand();
   await cmd.run(options);
 });
+program.command("mcp <action> [scope]").description(
+  "Manage the optional MCP server integration. Actions: status | enable | disable | scope <project|user|snippets-only|disabled> | install | uninstall | snippets"
+).option("--scope <scope>", "Override scope for install (project|user|snippets-only|disabled)").option("--from <from>", "For uninstall: project | user | all (default: project)").action(
+  async (action, positional, opts) => {
+    const merged = { ...opts };
+    if (positional) merged.scope = opts.scope ?? positional;
+    const cmd = new McpCommand();
+    await cmd.run(action, merged);
+  }
+);
 program.parse();
 //# sourceMappingURL=index.js.map