@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/commands/feedback.js

@@ -0,0 +1,89 @@
+/**
+ * `agents feedback` — frictionless, in-CLI feedback. Opens a Discussion
+ * pre-filled with version + OS + agent inventory; falls back to printing the
+ * URL when no browser is available.
+ */
+import { spawnSync } from 'node:child_process';
+import { arch, platform, release } from 'node:os';
+import { createRequire } from 'node:module';
+import chalk from 'chalk';
+const REPO = 'phnx-labs/agents-cli';
+const DISCUSSION_BASE = `https://github.com/${REPO}/discussions/new`;
+const ISSUE_BASE = `https://github.com/${REPO}/issues/new`;
+function readCliVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require('../../package.json');
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function openInBrowser(url) {
+    const openers = process.platform === 'darwin'
+        ? [['open', [url]]]
+        : process.platform === 'win32'
+            ? [['cmd', ['/c', 'start', '""', url]]]
+            : [
+                ['xdg-open', [url]],
+                ['gnome-open', [url]]
+            ];
+    for (const [cmd, args] of openers) {
+        const r = spawnSync(cmd, args, { stdio: 'ignore' });
+        if (r.status === 0)
+            return true;
+    }
+    return false;
+}
+function buildPrefill(kind, summary) {
+    const version = readCliVersion();
+    const os = `${platform()} ${release()} (${arch()})`;
+    const node = process.version;
+    const body = [
+        summary.trim() ? `${summary.trim()}\n` : '<!-- describe what you ran into / what you want -->\n',
+        '---',
+        '',
+        '**Environment**',
+        '',
+        `- agents-cli: \`${version}\``,
+        `- OS: \`${os}\``,
+        `- Node: \`${node}\``,
+        '',
+        '<!-- For bugs: include the exact command you ran and the full output. -->',
+        '<!-- For ideas: include a concrete use case. -->'
+    ].join('\n');
+    if (kind === 'bug') {
+        const url = `${ISSUE_BASE}?template=bug_report.yml&title=${encodeURIComponent(summary || 'Bug: ')}`;
+        return { url, body };
+    }
+    const category = kind === 'idea' ? 'ideas' : 'q-a';
+    const url = `${DISCUSSION_BASE}?category=${category}&title=${encodeURIComponent(summary || '')}&body=${encodeURIComponent(body)}`;
+    return { url, body };
+}
+export function registerFeedbackCommand(program) {
+    program
+        .command('feedback [summary...]')
+        .description('Open a pre-filled feedback Discussion or bug report')
+        .option('-b, --bug', 'File as a bug report (opens issue tracker)')
+        .option('-i, --idea', 'File as a feature idea (Discussions → Ideas)')
+        .option('-q, --question', 'Ask a question (Discussions → Q&A)')
+        .option('--print', 'Print the URL instead of opening it')
+        .action((summary, opts) => {
+        const kind = opts.bug ? 'bug' : opts.idea ? 'idea' : 'question';
+        const summaryText = (summary ?? []).join(' ').trim();
+        const { url } = buildPrefill(kind, summaryText);
+        if (opts.print) {
+            console.log(url);
+            return;
+        }
+        const opened = openInBrowser(url);
+        if (opened) {
+            console.log(chalk.dim(`Opened ${kind} form in your browser:\n  ${url}`));
+        }
+        else {
+            console.log(chalk.yellow('Could not auto-open a browser. Paste this URL:'));
+            console.log(`  ${url}`);
+        }
+    });
+}

package/dist/commands/helper.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents helper` -- install, inspect, and reinstall the signed macOS
+ * Keychain helper at the stable user path.
+ *
+ * The signed `Agents CLI.app` ships inside the npm package, but its keychain
+ * ACLs need a stable signature-pinned location to survive `npm i -g` and
+ * version bumps. This command copies it to
+ * `~/Library/Application Support/agents-cli/` once and lets users force a
+ * reinstall when the trusted-app ACL needs to be re-established.
+ */
+import type { Command } from 'commander';
+export declare function registerHelperCommand(program: Command): void;

package/dist/commands/helper.js

@@ -0,0 +1,87 @@
+/**
+ * `agents helper` -- install, inspect, and reinstall the signed macOS
+ * Keychain helper at the stable user path.
+ *
+ * The signed `Agents CLI.app` ships inside the npm package, but its keychain
+ * ACLs need a stable signature-pinned location to survive `npm i -g` and
+ * version bumps. This command copies it to
+ * `~/Library/Application Support/agents-cli/` once and lets users force a
+ * reinstall when the trusted-app ACL needs to be re-established.
+ */
+import chalk from 'chalk';
+import { ensureKeychainHelperInstalled, getKeychainHelperPath, getKeychainHelperStatus, } from '../lib/secrets/install-helper.js';
+function requireDarwin() {
+    if (process.platform !== 'darwin') {
+        console.error(chalk.red('agents helper: macOS only.'));
+        process.exit(1);
+    }
+}
+export function registerHelperCommand(program) {
+    const cmd = program
+        .command('helper')
+        .description('Manage the signed macOS Keychain helper (.app) install');
+    cmd
+        .command('install')
+        .description('Copy the bundled .app to ~/Library/Application Support/agents-cli/')
+        .action(() => {
+        requireDarwin();
+        try {
+            ensureKeychainHelperInstalled({ forceReinstall: true });
+        }
+        catch (err) {
+            console.error(chalk.red(err.message || String(err)));
+            process.exit(1);
+        }
+        const s = getKeychainHelperStatus();
+        console.log(chalk.green('Installed:'), s.destination);
+        console.log(chalk.dim('codesign:'), s.codesignOk ? chalk.green('ok') : chalk.red(s.codesignOutput));
+        console.log(chalk.dim('spctl:   '), s.spctlOk ? chalk.green('ok') : chalk.yellow(s.spctlOutput));
+    });
+    cmd
+        .command('update')
+        .description('Reinstall the .app, overwriting any existing copy (alias of install)')
+        .action(() => {
+        requireDarwin();
+        try {
+            ensureKeychainHelperInstalled({ forceReinstall: true });
+        }
+        catch (err) {
+            console.error(chalk.red(err.message || String(err)));
+            process.exit(1);
+        }
+        const s = getKeychainHelperStatus();
+        console.log(chalk.green('Updated: '), s.destination);
+        console.log(chalk.dim('codesign:'), s.codesignOk ? chalk.green('ok') : chalk.red(s.codesignOutput));
+        console.log(chalk.dim('spctl:   '), s.spctlOk ? chalk.green('ok') : chalk.yellow(s.spctlOutput));
+    });
+    cmd
+        .command('status')
+        .description('Show source, destination, codesign and notarization status')
+        .action(() => {
+        requireDarwin();
+        const s = getKeychainHelperStatus();
+        console.log(chalk.bold('Source:     '), s.source ?? chalk.red('(not found)'));
+        console.log(chalk.bold('Destination:'), s.destination);
+        console.log(chalk.bold('Installed:  '), s.installed ? chalk.green('yes') : chalk.yellow('no'));
+        if (s.installed) {
+            console.log(chalk.bold('codesign:   '), s.codesignOk ? chalk.green('ok') : chalk.red(s.codesignOutput));
+            console.log(chalk.bold('spctl:      '), s.spctlOk ? chalk.green('ok') : chalk.yellow(s.spctlOutput));
+        }
+        else {
+            console.log(chalk.dim('Run `agents helper install` to copy the bundled .app to the destination.'));
+        }
+    });
+    cmd
+        .command('where')
+        .description('Print the absolute path to the installed helper executable')
+        .action(() => {
+        requireDarwin();
+        try {
+            console.log(getKeychainHelperPath());
+        }
+        catch (err) {
+            console.error(chalk.red(err.message || String(err)));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/hooks.js

@@ -8,9 +8,9 @@ import { AGENTS, HOOKS_CAPABLE_AGENTS, resolveAgentName, formatAgentError, agent
 import { supports } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverHooksFromRepo, installHooksCentrally, listCentralHooks, listInstalledHooksWithScope, getHookInfo, parseHookManifest, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
-import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, } from './utils.js';
 /** Register the `agents hooks` command tree (list, add, remove, sync, prune, view). */
 export function registerHooksCommands(program) {
     const hooksCmd = program.command('hooks')
@@ -340,13 +340,17 @@ Examples:
             let versionSelections;
             const hooksCapableAgents = Array.from(HOOKS_CAPABLE_AGENTS);
             if (options.agents) {
-                const result = resolveAgentVersionTargets(options.agents, hooksCapableAgents);
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, hooksCapableAgents, { yes: options.yes });
+                if (!result) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
             }
             else {
                 const result = await promptAgentVersionSelection(hooksCapableAgents, {
-                    skipPrompts: options.yes || !isInteractiveTerminal(),
+                    skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
@@ -459,11 +463,24 @@ Examples:
                 console.log(chalk.yellow(`  Hook '${hookName}' not found in any version.`));
                 continue;
             }
-            // Filter by --agents if specified
+            // Filter by --agents if specified. Routes through resolveInstalledAgentTargets
+            // so the same selector syntax used everywhere else (agent, agent@default,
+            // agent@x.y.z, agent@all, literal all) works here too.
             let availableTargets = hookInfo.targets;
             if (options?.agents) {
-                const requestedAgents = new Set(options.agents.split(','));
-                availableTargets = availableTargets.filter((t) => requestedAgents.has(t.agent));
+                const requestedTargets = resolveInstalledAgentTargets(options.agents, [...HOOKS_CAPABLE_AGENTS]);
+                const requested = new Set();
+                for (const aid of requestedTargets.directAgents) {
+                    for (const ver of listInstalledVersions(aid)) {
+                        requested.add(`${aid}@${ver}`);
+                    }
+                }
+                for (const [aid, versions] of requestedTargets.versionSelections) {
+                    for (const ver of versions) {
+                        requested.add(`${aid}@${ver}`);
+                    }
+                }
+                availableTargets = availableTargets.filter((t) => requested.has(`${t.agent}@${t.version}`));
             }
             if (availableTargets.length === 0) {
                 console.log(chalk.yellow(`  Hook '${hookName}' not found in specified agents.`));
@@ -508,17 +525,17 @@ Examples:
         .action(() => {
         console.error(chalk.red('"agents hooks sync" is gone.'));
         console.error(chalk.gray('Sync runs automatically when you launch the agent.'));
-        console.error(chalk.gray('To remove orphans, use:  agents prune hooks'));
+        console.error(chalk.gray('To remove orphans, use:  agents prune cleanup hooks'));
         process.exit(1);
     });
-    // `hooks prune` moved to the top-level `agents prune` command.
+    // `hooks prune` moved to the top-level `agents prune cleanup` command.
     hooksCmd
         .command('prune', { hidden: true })
         .allowUnknownOption()
         .allowExcessArguments()
         .action(() => {
         console.error(chalk.red('"agents hooks prune" moved.'));
-        console.error(chalk.gray('Use:  agents prune hooks   (or `agents prune` for everything)'));
+        console.error(chalk.gray('Use:  agents prune cleanup hooks   (or `agents prune cleanup` for everything)'));
         process.exit(1);
     });
     hooksCmd
@@ -579,4 +596,66 @@ Examples:
             printWithPager(output, contentLines.length);
         }
     });
+    hooksCmd
+        .command('profile')
+        .description('Per-hook timing + cache stats from recent invocations')
+        .option('--days <n>', 'Number of days of logs to read', '7')
+        .option('--warn-ms <n>', 'p99 threshold above which a hook is flagged as slow', '2000')
+        .option('--json', 'Emit raw JSON rows instead of the table')
+        .addHelpText('after', `
+Shows aggregated stats for every hook that emitted a hook.fire event into
+~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl. Only hooks with \`cache:\` in
+their manifest are instrumented today — the generated shim writes the events.
+
+Examples:
+  agents hooks profile                # last 7 days, table form
+  agents hooks profile --days 30      # roll up the full month
+  agents hooks profile --json | jq    # pipe somewhere
+
+A hook whose p99 exceeds --warn-ms gets flagged in the cache column. Add
+'cache: 5m' or 'cache: 5m-bg' to its hooks.yaml entry to fix it.
+`)
+        .action(async (options) => {
+        const { aggregateHookProfile, loadHookFireEvents, formatMs, formatCacheColumn, DEFAULT_SLOW_HOOK_WARN_MS } = await import('../lib/hooks/profile.js');
+        const days = Math.max(1, parseInt(options.days, 10) || 7);
+        const warnMs = Math.max(0, parseInt(options.warnMs, 10) || DEFAULT_SLOW_HOOK_WARN_MS);
+        const rows = aggregateHookProfile(loadHookFireEvents(days));
+        if (options.json) {
+            console.log(JSON.stringify(rows, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log(chalk.gray(`No hook.fire events in the last ${days} day${days === 1 ? '' : 's'}.`));
+            console.log(chalk.gray('Add \'cache: 5m\' to a hook in hooks.yaml to start collecting stats.'));
+            return;
+        }
+        const widths = { hook: 36, n: 5, p50: 7, p99: 7, mean: 7, max: 7, cache: 30 };
+        const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
+        const header = [
+            pad('HOOK', widths.hook),
+            pad('N', widths.n),
+            pad('P50', widths.p50),
+            pad('P99', widths.p99),
+            pad('MEAN', widths.mean),
+            pad('MAX', widths.max),
+            pad('CACHE', widths.cache),
+        ].join(' ');
+        console.log(chalk.bold(header));
+        console.log(chalk.gray('─'.repeat(header.length)));
+        for (const r of rows) {
+            const slow = r.p99Ms > warnMs;
+            const cacheCol = formatCacheColumn(r);
+            const warning = slow && r.cacheHitPct + r.cacheStalePct === 0 ? '  ← add cache: 5m' : '';
+            const line = [
+                pad(r.hook, widths.hook),
+                pad(String(r.n), widths.n),
+                pad(formatMs(r.p50Ms), widths.p50),
+                pad(formatMs(r.p99Ms), widths.p99),
+                pad(formatMs(r.meanMs), widths.mean),
+                pad(formatMs(r.maxMs), widths.max),
+                pad(cacheCol, widths.cache),
+            ].join(' ') + warning;
+            console.log(slow ? chalk.yellow(line) : line);
+        }
+    });
 }

package/dist/commands/mcp.js

@@ -3,20 +3,49 @@ import ora from 'ora';
 import { checkbox } from '@inquirer/prompts';
 import { AGENTS, MCP_CAPABLE_AGENTS, getAllCliStates, resolveAgentName, formatAgentError, registerMcpToTargets, unregisterMcpFromTargets, listInstalledMcpsWithScope, parseMcpConfig, getMcpConfigPathForHome, agentLabel, } from '../lib/agents.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
-import { listMcpServerConfigs } from '../lib/mcp.js';
+import { listMcpServerConfigs, discoverMcpConfigsFromRepo, installMcpConfigCentrally, } from '../lib/mcp.js';
+import { cloneRepo } from '../lib/git.js';
 import { getMcpDir } from '../lib/state.js';
-import { getEffectiveHome, getGlobalDefault, listInstalledVersions, getVersionHomePath, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, resolveVersionAlias, } from '../lib/versions.js';
+import { getEffectiveHome, getGlobalDefault, listInstalledVersions, getVersionHomePath, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, resolveVersionAlias, syncResourcesToVersion, } from '../lib/versions.js';
 import { getUserAgentsDir } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, promptRemovalTargets } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, promptRemovalTargets, parseCommaSeparatedList, ensureAgentVersionsInstalled, resolveAgentTargetsAutoInstalling, resolveInstalledAgentTargetsAutoInstalling, VersionNotInstalledError, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
-/** Parse a comma-separated --agents string into validated agent IDs and optional version targets. */
+/**
+ * Parse a comma-separated --agents string into validated agent IDs and
+ * optional version targets in the manifest shape.
+ *
+ * Supports the same selector syntax as resolveAgentVersionTargets:
+ *   - bare `agent`        → manifest agents:[agent] (no version pin)
+ *   - `agent@default`     → manifest agents:[agent] (no version pin)
+ *   - `agent@x.y.z`       → manifest agentVersions[agent] = ['x.y.z']
+ *   - `agent@all`         → manifest agentVersions[agent] = every installed version
+ *   - literal `all`       → expand to all MCP-capable agents (each as `@all`)
+ *
+ * Throws VersionNotInstalledError for unknown specific versions so callers
+ * can prompt-and-install before retrying.
+ */
 function parseMcpAgentTargets(value) {
     const agents = [];
     const agentVersions = {};
-    const targets = value
+    const rawTargets = value
         .split(',')
         .map((item) => item.trim())
         .filter(Boolean);
+    // Expand literal `all` / `all@all` into per-agent @all. Skip agents with no
+    // installed versions so `all` is lenient — mirrors resolveAgentVersionTargets.
+    const targets = [];
+    for (const t of rawTargets) {
+        if (t === 'all' || t === 'all@all') {
+            for (const a of MCP_CAPABLE_AGENTS) {
+                if (listInstalledVersions(a).length > 0) {
+                    targets.push(`${a}@all`);
+                }
+            }
+        }
+        else {
+            targets.push(t);
+        }
+    }
     for (const target of targets) {
         const atIndex = target.indexOf('@');
         const agentToken = (atIndex === -1 ? target : target.slice(0, atIndex)).trim();
@@ -25,7 +54,7 @@ function parseMcpAgentTargets(value) {
             continue;
         }
         if (atIndex !== -1 && !versionToken) {
-            throw new Error(`Missing version in --agents entry '${target}'. Use agent@x.y.z or agent@default.`);
+            throw new Error(`Missing version in --agents entry '${target}'. Use agent@x.y.z, agent@default, or agent@all.`);
         }
         const agentId = resolveAgentName(agentToken);
         if (!agentId || !MCP_CAPABLE_AGENTS.includes(agentId)) {
@@ -50,11 +79,23 @@ function parseMcpAgentTargets(value) {
         if (installedVersions.length === 0) {
             throw new Error(`No managed versions are installed for ${AGENTS[agentId].name}. Run: agents add ${agentId}@latest`);
         }
+        if (versionToken === 'all') {
+            const versions = agentVersions[agentId] || [];
+            for (const ver of installedVersions) {
+                if (!versions.includes(ver))
+                    versions.push(ver);
+            }
+            agentVersions[agentId] = versions;
+            if (!agents.includes(agentId)) {
+                agents.push(agentId);
+            }
+            continue;
+        }
         const resolvedVersion = versionToken === 'latest'
             ? installedVersions[installedVersions.length - 1]
             : versionToken;
         if (!installedVersions.includes(resolvedVersion)) {
-            throw new Error(`Version ${resolvedVersion} is not installed for ${AGENTS[agentId].name}. Installed versions: ${installedVersions.join(', ')}`);
+            throw new VersionNotInstalledError(agentId, resolvedVersion, installedVersions);
         }
         const versions = agentVersions[agentId] || [];
         if (!versions.includes(resolvedVersion)) {
@@ -140,6 +181,8 @@ When to use:
         .option('-a, --agents <list>', 'Targets: claude, codex@0.116.0', MCP_CAPABLE_AGENTS.join(','))
         .option('-s, --scope <scope>', 'user (global) or project (repo-specific)', 'user')
         .option('-t, --transport <type>', 'stdio (default) or http', 'stdio')
+        .option('--names <list>', 'When source is a repo: MCP server names to install (comma-separated)')
+        .option('-y, --yes', 'Auto-install any missing agent versions without prompting')
         .option('-H, --header <header>', 'HTTP header as name:value (repeatable)', (val, acc) => {
         acc.push(val);
         return acc;
@@ -154,8 +197,22 @@ Examples:
 
   # Add to manifest only (register later)
   agents mcp add db-server -- uvx postgres-mcp
+
+  # Install all MCP server configs from a repo's mcp/*.yaml
+  agents mcp add gh:user/repo --agents claude@all
+
+  # Install specific servers by name
+  agents mcp add gh:phnx-labs/.agents-system --names notion,figma --agents claude
 `)
         .action(async (name, commandOrUrl, options) => {
+        // Repo-source form: `agents mcp add gh:user/repo [--names a,b] [--agents …]`
+        // Mirrors `agents skills add gh:…`. Discovers <repoPath>/mcp/*.yaml,
+        // copies to ~/.agents/mcp/, and syncs to selected agent versions.
+        const isRepoSource = /^(gh:|git:|ssh:|https?:\/\/)/.test(name);
+        if (isRepoSource && commandOrUrl.length === 0) {
+            await installMcpsFromRepoSource(name, options);
+            return;
+        }
         // Registry resolution: if the user just typed `agents mcp add <name>`,
         // try looking up `<name>` in any configured MCP registry (by default the
         // official MCP Registry at registry.modelcontextprotocol.io) and derive
@@ -195,6 +252,13 @@ Examples:
         const localPath = getUserAgentsDir();
         const manifest = readManifest(localPath) || createDefaultManifest();
         manifest.mcp = manifest.mcp || {};
+        // Pre-flight: prompt-and-install any requested agent@version that isn't
+        // installed yet, before parseMcpAgentTargets validates the selector.
+        const okInstall = await ensureAgentVersionsInstalled(options.agents, MCP_CAPABLE_AGENTS, { yes: options.yes });
+        if (!okInstall) {
+            console.log(chalk.gray('Cancelled.'));
+            return;
+        }
         const targetConfig = parseMcpAgentTargets(options.agents);
         if (transport === 'http') {
             const url = commandOrUrl[0];
@@ -459,6 +523,7 @@ Examples:
         .command('register [name]')
         .description('Apply MCP servers from manifest to agent config files')
         .option('-a, --agents <list>', 'Override manifest targets: claude, codex@0.116.0')
+        .option('-y, --yes', 'Auto-install any missing agent versions without prompting')
         .addHelpText('after', `
 Examples:
   # Register all servers from manifest
@@ -495,9 +560,18 @@ Examples:
                 continue;
             }
             console.log(`\n  ${chalk.cyan(mcpName)}:`);
-            const targets = options.agents
-                ? resolveInstalledAgentTargets(options.agents, MCP_CAPABLE_AGENTS)
-                : resolveConfiguredAgentTargets(config.agents, config.agentVersions, MCP_CAPABLE_AGENTS);
+            let targets;
+            if (options.agents) {
+                const resolved = await resolveInstalledAgentTargetsAutoInstalling(options.agents, MCP_CAPABLE_AGENTS, { yes: options.yes });
+                if (!resolved) {
+                    console.log(chalk.gray('  Cancelled.'));
+                    continue;
+                }
+                targets = resolved;
+            }
+            else {
+                targets = resolveConfiguredAgentTargets(config.agents, config.agentVersions, MCP_CAPABLE_AGENTS);
+            }
             const results = await registerMcpToTargets(targets, mcpName, commandOrUrl, config.scope || 'user', transport, { headers: config.headers });
             for (const result of results) {
                 if (result.success) {
@@ -513,6 +587,88 @@ Examples:
         }
     });
 }
+async function installMcpsFromRepoSource(source, options) {
+    const spinner = ora('Cloning repository...').start();
+    let localPath;
+    try {
+        const cloneResult = await cloneRepo(source);
+        localPath = cloneResult.localPath;
+    }
+    catch (err) {
+        spinner.fail(`Failed to clone: ${err.message}`);
+        process.exit(1);
+    }
+    spinner.succeed('Repository cloned');
+    let discovered = discoverMcpConfigsFromRepo(localPath);
+    if (discovered.length === 0) {
+        console.log(chalk.yellow('No MCP server configs found (looking for mcp/*.yaml)'));
+        return;
+    }
+    const requestedNames = parseCommaSeparatedList(options.names);
+    if (requestedNames.length > 0) {
+        const discoveredNames = new Set(discovered.map((s) => s.name));
+        const missing = requestedNames.filter((n) => !discoveredNames.has(n));
+        if (missing.length > 0) {
+            console.log(chalk.red(`\nMCP server(s) not found in source: ${missing.join(', ')}`));
+            console.log(chalk.gray(`Available: ${[...discoveredNames].join(', ')}`));
+            process.exit(1);
+        }
+        discovered = discovered.filter((s) => requestedNames.includes(s.name));
+    }
+    console.log(chalk.bold(`\nFound ${discovered.length} MCP server config(s):`));
+    for (const s of discovered) {
+        const summary = s.config.transport === 'stdio'
+            ? `${s.config.command}${s.config.args?.length ? ' ' + s.config.args.join(' ') : ''}`
+            : s.config.url ?? '';
+        console.log(`  ${chalk.cyan(s.name)}: ${chalk.gray(summary)}`);
+    }
+    const installSpinner = ora('Installing MCP configs to ~/.agents/mcp/...').start();
+    let installed = 0;
+    for (const s of discovered) {
+        const result = installMcpConfigCentrally(s.path);
+        if (result.success) {
+            installed++;
+        }
+        else {
+            installSpinner.stop();
+            console.log(chalk.red(`  Failed to install ${s.name}: ${result.error}`));
+            installSpinner.start();
+        }
+    }
+    installSpinner.succeed(`Installed ${installed} MCP config(s) to ~/.agents/mcp/`);
+    // Agent/version selection — same default as the non-repo form: every
+    // MCP-capable agent. Routes through resolveAgentTargetsAutoInstalling so
+    // a typo'd `claude@2.1.999` prompts to install (and --yes auto-installs).
+    const agentsValue = options.agents ?? MCP_CAPABLE_AGENTS.join(',');
+    let targets;
+    try {
+        const resolved = await resolveAgentTargetsAutoInstalling(agentsValue, MCP_CAPABLE_AGENTS, { yes: options.yes });
+        if (!resolved) {
+            console.log(chalk.gray('\nCancelled.'));
+            return;
+        }
+        targets = resolved;
+    }
+    catch (err) {
+        console.log(chalk.red(err.message));
+        process.exit(1);
+    }
+    if (targets.versionSelections.size === 0) {
+        console.log(chalk.gray('\nStored centrally; no agent versions selected for sync.'));
+        return;
+    }
+    const syncSpinner = ora('Syncing to agent versions...').start();
+    const mcpNames = discovered.map((s) => s.name);
+    let synced = 0;
+    for (const [agentId, versions] of targets.versionSelections) {
+        for (const version of versions) {
+            const result = syncResourcesToVersion(agentId, version, { mcp: mcpNames });
+            if (result.mcp.length > 0)
+                synced++;
+        }
+    }
+    syncSpinner.succeed(`Synced MCP configs to ${synced} agent version(s).`);
+}
 /** Enumerate (agent, version) pairs that support MCP and have a version home. */
 function iterMcpCapableVersions(filter) {
     const out = [];