@indigoai-us/hq-cli 5.49.0 → 5.50.1

package/src/commands/pack-install.ts

@@ -53,9 +53,19 @@ import semverValid from 'semver/functions/valid.js';
 import semverValidRange from 'semver/ranges/valid.js';
 import semverGt from 'semver/functions/gt.js';
 import { findHqRoot } from '../utils/manifest.js';
-import { readHqVersion } from '../utils/pack-contributions.js';
+import { readHqVersion, routeContribution } from '../utils/pack-contributions.js';
+import { CONTRIBUTION_TABLE, payloadFor } from '../utils/contribution-table.js';
 import { safeExtractTarball } from './safe-extract.js';
 import { vaultApiFetchPublic } from '../utils/vault-api.js';
+import {
+  redactSecrets,
+  SECRET_REDACTION,
+  registerMcpServers,
+  McpManifestError,
+  type McpManifest,
+  type SecretResolver,
+} from './mcp-registration.js';
+import { readCache, listSecretCacheScopes } from '../utils/secrets-cache.js';
 import type { PackManifest, PackContributeKey } from '../types.js';
 
 // ---------------------------------------------------------------------------
@@ -978,6 +988,165 @@ export function verifyArtifact(input: VerifyArtifactInput): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// MCP per-server manifest validation (US-005, the TS counterpart of the bash
+// `validate_mcp_manifest` arm in core/scripts/scan-packages.sh).
+//
+// The `mcp` contributes key is `wire: 'merge'` — its per-server manifests are
+// NEVER symlinked; they are validated here and (US-006) merged into the agent
+// configs via registerMcpServers. This function MIRRORS the bash transport
+// rules hand-coded against the draft-07 schema
+// (repos/public/knowledge-hq-core/mcp-manifest.schema.json). There is no `ajv`
+// dependency in hq-cli; the schema file is single-source documentation, so the
+// rules are replicated here (dependency-free, robust if the schema is absent).
+// ---------------------------------------------------------------------------
+
+/** Allowed top-level keys (schema `additionalProperties: false`). */
+const MCP_ALLOWED_KEYS = ['type', 'url', 'headers', 'command', 'args', 'env', 'tools'];
+
+/** Schema `$id` for an at-a-glance error reference (kept inline; no file read). */
+const MCP_SCHEMA_ID = 'mcp-manifest.schema.json';
+
+/** True iff a header/env value carries a `${secret:NAME}` reference. */
+function hasSecretRef(value: string): boolean {
+  return /\$\{secret:/.test(value);
+}
+
+/**
+ * Validate that a record (`headers` or `env`) is an object of STRING values,
+ * pushing one error per offending entry into `errs`. Mirrors the schema's
+ * `additionalProperties: { type: 'string' }`.
+ */
+function checkStringMap(
+  errs: string[],
+  label: 'headers' | 'env',
+  value: unknown,
+): void {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    errs.push(`${label} must be an object`);
+    return;
+  }
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof v !== 'string') {
+      errs.push(`${label} "${k}" value must be a string`);
+    }
+  }
+}
+
+/**
+ * Parse + shape-validate one pack's per-server MCP manifest (`mcp/{item}.json`),
+ * mirroring the bash `validate_mcp_manifest` arm. EXPORTED so the acceptance
+ * test (and US-006's registration engine) can call it directly.
+ *
+ * Throws an `Error` (whose message names the pack-relative payload path, e.g.
+ * `mcp/foo.json`) when the file does not parse as JSON or violates a transport
+ * rule:
+ *   - `type` required, one of `http|stdio|sse`;
+ *   - no unknown top-level keys (allowed: {@link MCP_ALLOWED_KEYS});
+ *   - http/sse: `url` required + `^https?://`; `command`/`args`/`env` forbidden;
+ *   - stdio: non-empty `command` required; `url`/`headers` forbidden;
+ *   - `headers`/`env` (if present) are objects of string values;
+ *   - NO inline literal `Bearer ` secret — such a value MUST carry a
+ *     `${secret:NAME}` reference, never a literal token.
+ *
+ * @param payloadDir the pack payload root (holds `mcp/{item}.json`)
+ * @param item       the bare server name declared under `contributes.mcp`
+ */
+export function validateMcpManifest(payloadDir: string, item: string): void {
+  const rel = payloadFor('mcp', item); // mcp/{item}.json
+  const abs = path.join(payloadDir, rel);
+
+  // EXISTS — the existsSync gate in validateManifest already covers this, but
+  // re-check so the helper is safe to call standalone (tests, US-006).
+  if (!fs.existsSync(abs)) {
+    throw new Error(`MCP manifest missing: ${rel} (declared under contributes.mcp but no such file)`);
+  }
+
+  // PARSE — a non-JSON file is a hard error that names the file.
+  let doc: unknown;
+  try {
+    doc = JSON.parse(fs.readFileSync(abs, 'utf-8'));
+  } catch (e) {
+    throw new Error(`MCP manifest malformed: ${rel} is not valid JSON (failed to parse: ${(e as Error).message})`);
+  }
+  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+    throw new Error(`MCP manifest malformed: ${rel} must be a JSON object`);
+  }
+  const m = doc as Record<string, unknown>;
+  const errs: string[] = [];
+
+  // type: required + enum.
+  const type = m.type;
+  if (!('type' in m)) {
+    errs.push('missing required field: type');
+  } else if (type !== 'http' && type !== 'stdio' && type !== 'sse') {
+    errs.push(`type must be one of http|stdio|sse (got: ${JSON.stringify(type)})`);
+  }
+
+  // No unknown top-level keys (schema additionalProperties: false).
+  for (const k of Object.keys(m)) {
+    if (!MCP_ALLOWED_KEYS.includes(k)) {
+      errs.push(`unknown top-level key: ${k}`);
+    }
+  }
+
+  // http / sse transport: url required (^https?://); command/args/env forbidden.
+  if (type === 'http' || type === 'sse') {
+    if (!('url' in m)) {
+      errs.push(`${type} transport requires a url`);
+    } else if (typeof m.url !== 'string' || !/^https?:\/\//.test(m.url)) {
+      errs.push('url must be an absolute http(s) URL');
+    }
+    for (const forbidden of ['command', 'args', 'env'] as const) {
+      if (forbidden in m) errs.push(`${type} transport forbids: ${forbidden}`);
+    }
+  }
+
+  // stdio transport: non-empty command required; url/headers forbidden.
+  if (type === 'stdio') {
+    if (typeof m.command !== 'string' || m.command.length === 0) {
+      errs.push('stdio transport requires a non-empty command');
+    }
+    for (const forbidden of ['url', 'headers'] as const) {
+      if (forbidden in m) errs.push(`stdio transport forbids: ${forbidden}`);
+    }
+  }
+
+  // headers / env values must be strings.
+  if ('headers' in m) checkStringMap(errs, 'headers', m.headers);
+  if ('env' in m) checkStringMap(errs, 'env', m.env);
+
+  if (errs.length > 0) {
+    throw new Error(
+      `MCP manifest fails shape validation: ${rel} (schema: ${MCP_SCHEMA_ID})\n` +
+        errs.map((e) => `  - ${e}`).join('\n'),
+    );
+  }
+
+  // Reject INLINE LITERAL Bearer secrets. A header/env value containing
+  // 'Bearer ' MUST use a ${secret:NAME} reference, never a literal token baked
+  // into a synced/committed artifact.
+  const bad: string[] = [];
+  for (const [label, mapVal] of [
+    ['header', m.headers],
+    ['env', m.env],
+  ] as const) {
+    if (mapVal === null || typeof mapVal !== 'object' || Array.isArray(mapVal)) continue;
+    for (const [k, v] of Object.entries(mapVal as Record<string, unknown>)) {
+      if (typeof v === 'string' && v.includes('Bearer ') && !hasSecretRef(v)) {
+        bad.push(`${label} "${k}"`);
+      }
+    }
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      `MCP manifest contains an inline literal Bearer secret: ${rel} (${bad.join(', ')}) — ` +
+        'a \'Bearer \' header/env value MUST use a ${secret:NAME} reference, never a literal token ' +
+        '(a resolved secret is never written to a synced/committed artifact)',
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Manifest validation (spec §Validation, 10 checks)
 // ---------------------------------------------------------------------------
@@ -1040,26 +1209,33 @@ export function validateManifest(
   if (!nonEmpty) {
     throw new Error('contributes must have at least one non-empty subfield');
   }
-  // 10. payload files exist (hooks check happens separately in step 8)
-  const subpaths: Record<PackContributeKey, (item: string) => string> = {
-    workers:    (i) => path.join('workers', i),
-    knowledge:  (i) => path.join('knowledge', i),
-    skills:     (i) => path.join('skills', i),
-    commands:   (i) => path.join('commands', `${i}.md`),
-    hooks:      (i) => path.join('hooks', `${i}.sh`),
-    policies:   (i) => path.join('policies', `${i}.md`),
-    scripts:    (i) => path.join('scripts', i),
-  };
-  for (const [key, items] of Object.entries(contributes) as [PackContributeKey, string[]][]) {
+  // 10. payload files exist (hooks check happens separately in step 8).
+  // Payload paths are READ from the single-source CONTRIBUTION_TABLE (US-003)
+  // via payloadFor -- no restated `subpaths` record. An unknown key (not in the
+  // table) is rejected here so a typo can't silently install unwired.
+  for (const [key, items] of Object.entries(contributes) as [string, unknown][]) {
+    if (!(key in CONTRIBUTION_TABLE)) {
+      throw new Error(`contributes.${key} is not a known contribution type`);
+    }
     if (!Array.isArray(items)) continue;
     for (const item of items) {
-      const rel = subpaths[key](item);
+      const rel = payloadFor(key as PackContributeKey, item as string);
       const abs = path.join(payloadDir, rel);
       if (!fs.existsSync(abs)) {
         throw new Error(
           `contributes.${key} declares "${item}" but payload file missing: ${rel}`
         );
       }
+      // The `mcp` key (wire: 'merge') is NOT existsSync-only: after the file is
+      // confirmed present it must PARSE + SHAPE-validate against the per-server
+      // MCP schema (US-005), mirroring the bash validate_mcp_manifest arm. Other
+      // (symlink) keys keep their existsSync-only behavior. We dispatch on the
+      // ROUTE from the single-source table (not a hardcoded key) so the merge
+      // path is table-driven; the merge itself (registering into the agent
+      // configs via registerMcpServers, US-006) is NEVER a symlink.
+      if (routeContribution(key as PackContributeKey) === 'merge') {
+        validateMcpManifest(payloadDir, item as string);
+      }
     }
   }
   // author + capabilities (US-001) — both OPTIONAL and backwards-compatible.
@@ -1200,6 +1376,148 @@ async function confirmHooks(
   return /^(y|yes)$/i.test(answer.trim());
 }
 
+// ---------------------------------------------------------------------------
+// MCP confirmation (US-010)
+//
+// The MCP equivalent of confirmHooks. MCP servers are a high-trust surface: an
+// http/sse server points your agent at a REMOTE endpoint (typosquat / phishing
+// risk — the FULL url is disclosed verbatim so the operator can eyeball it), and
+// a stdio server runs a LOCAL binary with your shell permissions. We GATE on a
+// non-empty `contributes.mcp` (NEVER the advisory `capabilities` field, which is
+// reserved/unenforced — gating on it would let a pack omit a capability to dodge
+// the prompt) and render per-server transport + url-or-command + a count of ALL
+// servers being added.
+//
+// REDACTION: header/env VALUES are never printed. The manifests use
+// `${secret:NAME}` references (never literal Bearers), but we STILL run the
+// rendered prompt through `redactSecrets` against the raw header/env values so
+// that even a LITERAL secret could not leak. We show header KEY names with a
+// redacted value marker.
+//
+// FAIL-SAFE: a manifest that fails to load/parse here is NOT a bypass — we
+// surface the server name with a `[manifest unreadable]` note and STILL require
+// confirmation (a malformed manifest should make the operator MORE cautious).
+// ---------------------------------------------------------------------------
+
+/**
+ * Render one declared MCP server's prompt line, redacting every header/env value.
+ * EXPORTED so the acceptance/redaction self-test can assert no secret/Bearer
+ * substring ever appears in the rendered output.
+ */
+export function renderMcpServerLine(payloadDir: string, item: string): string {
+  let manifest: McpManifest;
+  try {
+    const abs = path.join(payloadDir, payloadFor('mcp', item));
+    manifest = JSON.parse(fs.readFileSync(abs, 'utf-8')) as McpManifest;
+    if (manifest === null || typeof manifest !== 'object') throw new Error('not an object');
+  } catch {
+    // Fail-safe: do not crash the prompt; flag the server and keep requiring
+    // confirmation.
+    return `  - ${item}  [manifest unreadable] — could not load mcp/${item}.json; treat with caution`;
+  }
+
+  const transport = manifest.type;
+  // Accumulate every raw header/env value so a final redactSecrets pass scrubs
+  // even a literal token that slipped past `${secret:}` (defense in depth — we
+  // already replace the values with the redaction marker below).
+  const rawValues = new Set<string>();
+  for (const v of Object.values(manifest.headers ?? {})) rawValues.add(v);
+  for (const v of Object.values(manifest.env ?? {})) rawValues.add(v);
+
+  // Header KEYS shown, VALUES always redacted (never the raw value).
+  const headerKeys = Object.keys(manifest.headers ?? {});
+  const headerStr =
+    headerKeys.length > 0
+      ? `   headers: { ${headerKeys.map((k) => `${k}: ${SECRET_REDACTION}`).join(', ')} }`
+      : '';
+
+  let line: string;
+  if (transport === 'http' || transport === 'sse') {
+    // FULL url verbatim — typosquat disclosure is the whole point.
+    line =
+      `  - ${item}  [${transport}]  url: ${manifest.url ?? '(missing)'}` +
+      headerStr +
+      `   (contacts a remote endpoint)`;
+  } else {
+    // stdio — local binary with shell permissions.
+    const args = manifest.args ?? [];
+    const argsStr = args.length > 0 ? `  args: [${args.join(', ')}]` : '';
+    line =
+      `  - ${item}  [stdio] command: ${manifest.command ?? '(missing)'}` +
+      argsStr +
+      headerStr +
+      `   (runs a local binary with your shell permissions)`;
+  }
+
+  // Final defense-in-depth scrub: even though values are already replaced with
+  // the marker above, run the whole line through redactSecrets so a stray
+  // literal token (e.g. inside command/args) can never reach the terminal.
+  return redactSecrets(line, rawValues);
+}
+
+/**
+ * Install-time MCP trust prompt. EXPORTED so the acceptance test can drive the
+ * gate / bypass / non-TTY branches directly (capture stdout, assert no secret
+ * substring leaks, assert deny returns false). See {@link confirmHooks} for the
+ * voice/shape this mirrors.
+ */
+export async function confirmMcp(
+  pkg: PackManifest,
+  payloadDir: string,
+  allowMcp: boolean,
+): Promise<boolean> {
+  // GATE on non-empty `contributes.mcp` — mirrors confirmHooks. Never on the
+  // advisory `capabilities` field.
+  const servers = pkg.contributes.mcp ?? [];
+  if (servers.length === 0) return true;
+
+  if (allowMcp) {
+    console.log(
+      chalk.yellow(
+        `--allow-mcp set; registering ${servers.length} MCP server(s) without prompting.`,
+      ),
+    );
+    return true;
+  }
+
+  console.log('');
+  console.log(
+    chalk.yellow(
+      `Pack ${pkg.publisher}/${pkg.name} declares ${servers.length} MCP server(s):`,
+    ),
+  );
+  for (const item of servers) {
+    console.log(chalk.yellow(renderMcpServerLine(payloadDir, item)));
+  }
+  console.log(
+    chalk.yellow(
+      'These servers will be registered into your Claude and Codex agent configs.',
+    ),
+  );
+
+  // Non-TTY guard (mirrors the secrets.ts pattern): do NOT call rl.question in a
+  // non-interactive shell — it would hang. Instruct the operator to re-run with
+  // --allow-mcp and DENY (return false -> abort, no partial state).
+  if (!process.stdin.isTTY) {
+    console.log(
+      chalk.red(
+        `Refusing to register ${servers.length} MCP server(s) without confirmation ` +
+          'in a non-interactive shell. Re-run with --allow-mcp to approve.',
+      ),
+    );
+    return false;
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer: string = await new Promise((resolve) => {
+    rl.question('Install anyway? [y/N] ', (a) => {
+      rl.close();
+      resolve(a);
+    });
+  });
+  return /^(y|yes)$/i.test(answer.trim());
+}
+
 // ---------------------------------------------------------------------------
 // Conditional predicate
 //
@@ -1246,6 +1564,130 @@ function evalConditional(expr: string): boolean {
   return r.status === 0;
 }
 
+// ---------------------------------------------------------------------------
+// MCP registration wiring (US-007) — call registerMcpServers from installPack.
+//
+// The registration CORE + Claude/Codex emitters live in mcp-registration.ts and
+// are fully unit-tested; this is the install-time SEAM that feeds them a real
+// manifest loader and a production, vault-backed secret resolver, with per-server
+// secret-deferral so a fresh install (before `/connect-shopify` has minted the
+// key) still SUCCEEDS, skipping only the server whose secret is not yet present.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the install-time {@link SecretResolver} bound to the HQ vault's local
+ * secrets-cache (`~/.hq/secrets-cache/<scope>/<NAME>`, AES-256-GCM, 0600, TTL'd).
+ *
+ * Active-company resolution at install time is INDIRECT by design: `hq install`
+ * has no `--company` flag and runs OFFLINE (no token), so we cannot resolve a
+ * single active company UID the way `hq run` / `hq secrets` do (via
+ * `getEntityUid` over the network). Instead we probe EVERY cached scope
+ * (`cmp_*`/`prs_*` — whichever has minted secrets locally) for the requested
+ * name and return the first hit. This naturally resolves to whichever company
+ * context just provisioned the secret (e.g. the one `/connect-shopify` minted
+ * `VYG_API_KEY` under), without guessing, and works whether the vault scoped the
+ * key under a company or person entity.
+ *
+ * On MISS across all scopes (no cache, expired TTL, or key never minted) it
+ * returns `null` — which is exactly what {@link registerMcpServers}'s
+ * unresolvable-secret path keys off to defer that server gracefully. With no
+ * cached scopes at all (`listSecretCacheScopes()` → `[]`) it simply returns
+ * `null` for every name, the desired graceful-deferral behavior.
+ */
+export function makeInstallSecretResolver(): SecretResolver {
+  return (name: string): string | null => {
+    for (const scope of listSecretCacheScopes()) {
+      const value = readCache(scope, name);
+      if (value !== null) return value;
+    }
+    return null;
+  };
+}
+
+/**
+ * Load + shape-validate + parse a pack's per-server MCP manifest from disk.
+ * `validateMcpManifest(destDir, name)` is the SAME shape gate `validateManifest`
+ * runs at install; it returns void and THROWS on bad shape, so we call it first
+ * (re-using one source of truth), then parse `mcp/<name>.json` and return it
+ * typed as {@link McpManifest}. `destDir` is the installed pack root
+ * (`core/packages/<pkg>/`), the realpath `registerMcpServers` emits from.
+ */
+function loadMcpManifestFrom(destDir: string, name: string): McpManifest {
+  validateMcpManifest(destDir, name); // throws on bad shape (void on success)
+  const abs = path.join(destDir, 'mcp', `${name}.json`);
+  return JSON.parse(fs.readFileSync(abs, 'utf-8')) as McpManifest;
+}
+
+/**
+ * Derive the per-server "needs secret" remedy command from the pack's
+ * `initialization.entrypoint` (e.g. the vyg pack's `connect-shopify` →
+ * `/connect-shopify`). Falls back to a generic "provision the secret then re-run
+ * `hq install`" when the pack declares no entrypoint.
+ */
+function mcpSecretRemedy(initialization: PackManifest['initialization']): string {
+  const entrypoint = initialization?.entrypoint;
+  if (typeof entrypoint === 'string' && entrypoint.trim() !== '') {
+    const command = '/' + entrypoint.trim().replace(/^\/+/, '');
+    return `run \`${command}\` to provision it, then re-run \`hq install\``;
+  }
+  return 'provision the secret then re-run `hq install`';
+}
+
+/** Pull the `${secret:NAME}` token out of a `cannot resolve ${secret:NAME}` error message. */
+function extractDeferredSecretName(message: string): string {
+  const m = /\$\{secret:([^}]+)\}/.exec(message);
+  return m ? m[1] : 'a required secret';
+}
+
+/**
+ * Register one pack's `contributes.mcp` servers into the shared Claude/Codex
+ * agent configs, PER SERVER, so a single unresolvable `${secret:NAME}` defers
+ * ONLY that server instead of aborting the whole install. Returns the registered
+ * and skipped (deferred) server-name lists for the one-line summary.
+ *
+ * Per-server policy:
+ *   - SUCCESS                       → push to `registered`.
+ *   - McpManifestError matching
+ *     `/cannot resolve \$\{secret:/` → SKIP (push to `skipped`), warn on stderr,
+ *     install still succeeds (the key gets minted later, then a re-install wires it).
+ *   - ANY OTHER error               → RE-THROW (abort install). Only the
+ *     unresolvable-secret case is swallowed.
+ */
+function wireMcpServers(
+  pkg: PackManifest,
+  destDir: string,
+): { registered: string[]; skipped: string[] } {
+  const resolveSecret = makeInstallSecretResolver();
+  const loadManifest = (name: string): McpManifest => loadMcpManifestFrom(destDir, name);
+  const registered: string[] = [];
+  const skipped: string[] = [];
+
+  for (const name of pkg.contributes.mcp ?? []) {
+    try {
+      // Per-server call: registerMcpServers throws on the FIRST unresolvable
+      // secret, so calling it one name at a time lets us catch + continue.
+      registerMcpServers(pkg.name, [name], { loadManifest, resolveSecret });
+      registered.push(name);
+    } catch (e) {
+      const isUnresolvableSecret =
+        e instanceof McpManifestError && /cannot resolve \$\{secret:/.test(e.message);
+      if (!isUnresolvableSecret) {
+        // ConfigParseError / ConfigPermissionError / McpNameCollisionError / a
+        // malformed-manifest McpManifestError / etc. — propagate, abort install.
+        throw e;
+      }
+      skipped.push(name);
+      const secret = extractDeferredSecretName(e.message);
+      // Always stderr (never suppressed by --quiet): the user must see WHY a
+      // server was deferred and exactly how to finish wiring it.
+      process.stderr.write(
+        `MCP server '${name}' needs secret ${secret} — ${mcpSecretRemedy(pkg.initialization)}.\n`,
+      );
+    }
+  }
+  return { registered, skipped };
+}
+
 // ---------------------------------------------------------------------------
 // Move into core/packages/ + run core/scripts/scan-packages.sh
 // ---------------------------------------------------------------------------
@@ -1398,6 +1840,13 @@ export function runScanPackages(hqRoot: string, opts: { quiet?: boolean } = {}):
 
 export interface InstallPackOptions {
   allowHooks?: boolean;
+  /**
+   * US-010 install-time MCP trust prompt bypass (CI/ambient-trust). Mirrors
+   * `allowHooks`: when set, `confirmMcp` skips the prompt and prints a yellow
+   * notice. Absent/false → the operator is prompted (or, in a non-TTY shell,
+   * the install is refused with a "re-run with --allow-mcp" hint).
+   */
+  allowMcp?: boolean;
   followBranch?: boolean;
   /**
    * Route this function's human output to stderr (and silence scan-packages
@@ -1497,6 +1946,22 @@ export async function installPack(
       return;
     }
 
+    // US-010 — install-time MCP trust prompt. Positioned AFTER confirmHooks and
+    // BEFORE installToPackages so a deny aborts with NO partial state (no config
+    // written, no pack moved into core/packages, no registerMcpServers call). The
+    // actual registration (US-007) now fires AFTER installToPackages +
+    // runScanPackages below (pack on disk + symlinks wired), once this gate has
+    // confirmed the servers — so a deny here means registration never runs.
+    const mcpConfirmed = await confirmMcp(
+      pkg,
+      fetched.payloadDir,
+      opts.allowMcp ?? false,
+    );
+    if (!mcpConfirmed) {
+      say(chalk.red('Install aborted (MCP servers denied).'));
+      return;
+    }
+
     const destDir = installToPackages(fetched.payloadDir, pkg, hqRoot);
     // Under the v12+ HQ layout, packs live at `core/packages/<name>/` and
     // are tracked by filesystem presence — no `modules.yaml` write (that
@@ -1516,6 +1981,25 @@ export async function installPack(
     stampInstallSource(destDir, stampedSource);
     runScanPackages(hqRoot, { quiet: opts.quiet });
 
+    // US-007 — register `contributes.mcp` servers into the shared Claude/Codex
+    // agent configs. Fires HERE (after installToPackages + runScanPackages, i.e.
+    // pack on disk + symlinks wired) and only once the confirmMcp gate above
+    // approved them. The `mcp` key is wire:'merge' — NEVER symlinked; this merge
+    // is its only wiring path. registerMcpServers honors the
+    // HQ_DISABLE_MCP_REGISTRATION kill-switch internally, so we never re-check it.
+    // Per-server secret-deferral keeps a fresh install (key not yet minted) at
+    // exit 0, deferring only the unresolvable server (see wireMcpServers).
+    if (Array.isArray(pkg.contributes.mcp) && pkg.contributes.mcp.length > 0) {
+      const { registered, skipped } = wireMcpServers(pkg, destDir);
+      // One-line summary (server NAMES only — never resolved secret VALUES).
+      say(
+        chalk.dim(
+          `  MCP servers: registered [${registered.join(', ')}]; ` +
+            `skipped [${skipped.join(', ')}].`
+        )
+      );
+    }
+
     say(
       chalk.green(
         `\nOK Installed ${pkg.name}@${pkg.version} -> ${path.relative(hqRoot, destDir)}/`

package/src/commands/packs.ts

@@ -40,6 +40,7 @@ import {
   listInstalledPacks,
   readPackManifest,
   unwirePack,
+  unwirePackMcp,
   readHqVersion,
   readRecommendedPackages,
   packagesDir,
@@ -303,6 +304,7 @@ interface UpdateOpts extends CommonOpts {
   checkOnly?: boolean;
   yes?: boolean;
   allowHooks?: boolean;
+  allowMcp?: boolean;
   branch?: boolean;
 }
 
@@ -359,6 +361,7 @@ async function runUpdate(name: string | undefined, opts: UpdateOpts): Promise<Up
       try {
         await installPack(source, {
           allowHooks: opts.yes || opts.allowHooks,
+          allowMcp: opts.yes || opts.allowMcp,
           followBranch: opts.branch,
           quiet: wantsJson(opts),
         });
@@ -413,6 +416,27 @@ async function runUninstall(name: string, opts: UninstallOpts): Promise<Uninstal
   // 1. Un-wire only our symlinks.
   const { unlinked, skipped } = unwirePack(hqRoot, packDir, contributes);
 
+  // 1b. Un-register the pack's MCP (`wire: 'merge'`) servers — invisible to the
+  // symlink unwire above. Provenance-scoped: removes ONLY entries stamped with this
+  // pack's `_hqPack`, and skip-and-warns on any foreign/unstamped same-named entry.
+  // Tolerant of a Codex-less host / absent config; idempotent on re-run.
+  try {
+    const mcp = unwirePackMcp(name, contributes);
+    for (const server of mcp.servers) {
+      if ('skipped' in server.claude) continue; // (claude is always inspected; never skipped)
+      if (server.claude.outcome === 'skipped-foreign' && server.claude.reason) {
+        warnings.push(server.claude.reason);
+      }
+      if (!('skipped' in server.codex) && server.codex.outcome === 'skipped-foreign' && server.codex.reason) {
+        warnings.push(server.codex.reason);
+      }
+    }
+  } catch (e) {
+    // Never let an MCP un-registration failure abort the rest of the uninstall
+    // (symlink unwire already ran; the pack dir still gets archived). Surface it.
+    warnings.push(`MCP un-registration encountered an error: ${(e as Error).message}`);
+  }
+
   // 2. Archive (or delete) the pack dir -- BEFORE re-scan so it isn't re-wired.
   let archived: string | null = null;
   if (opts.archive === false) {
@@ -495,8 +519,9 @@ export function registerPacksCommand(parent: Command): void {
     .option('--json', 'Machine-readable JSON output')
     .option('--hq-root <path>', 'HQ root (default: auto-detect)')
     .option('--check-only', 'Report availability without installing')
-    .option('-y, --yes', 'Non-interactive (implies --allow-hooks)')
+    .option('-y, --yes', 'Non-interactive (implies --allow-hooks and --allow-mcp)')
     .option('--allow-hooks', 'Install pack hooks without prompting')
+    .option('--allow-mcp', 'Register pack MCP servers without prompting')
     .option('--branch', 'Follow the source branch instead of SHA-pinning')
     .action(async (name: string | undefined, opts: UpdateOpts) => {
       try {

package/src/commands/pkg-install.ts

@@ -43,16 +43,18 @@ export function registerPackageInstallCommand(parent: Command): void {
     )
     .option('--company <co>', 'Scope the package to a specific company (registry flow only)')
     .option('--allow-hooks', 'Skip the hooks confirmation prompt (content-pack flow)')
+    .option('--allow-mcp', 'Skip the MCP server confirmation prompt (content-pack flow)')
     .option('--branch', 'Follow a ref instead of SHA-pinning (git content-pack flow)')
     .action(
       async (
         source: string,
-        opts: { company?: string; allowHooks?: boolean; branch?: boolean }
+        opts: { company?: string; allowHooks?: boolean; allowMcp?: boolean; branch?: boolean }
       ) => {
         try {
           if (sourceMatchesPackPattern(source)) {
             await installPack(source, {
               allowHooks: opts.allowHooks,
+              allowMcp: opts.allowMcp,
               followBranch: opts.branch,
             });
           } else {
@@ -62,6 +64,7 @@ export function registerPackageInstallCommand(parent: Command): void {
             // listings transport — the live install path — instead.
             await installPack(`${MARKETPLACE_PREFIX}${source}`, {
               allowHooks: opts.allowHooks,
+              allowMcp: opts.allowMcp,
               followBranch: opts.branch,
             });
           }