@bridge_gpt/mcp-server 0.1.17 → 0.2.0

package/build/mcp-invoke.js

@@ -0,0 +1,417 @@
+/**
+ * `mcp-invoke` — internal worktree shim subcommand.
+ *
+ * Resolves an MCP target's launch command + environment from an explicit
+ * absolute `--project-root` (NEVER from `process.cwd()`), then spawns the real
+ * MCP server as a child of the current Node process with inherited stdio and
+ * forwarded signals/exit codes. Secrets are passed to the child ONLY through its
+ * environment — never in argv, logs, or error messages.
+ *
+ * Two target families:
+ *   - `bapi` — resolves Bridge API repo identity + `BAPI_API_KEY`, overlays the
+ *     three `BAPI_*` values, and spawns this same Node script (the real Bridge
+ *     API MCP server).
+ *   - any Tier-2 target declared in `.bridge/config` (e.g. `sfcc`) — reads the
+ *     manifest entry, resolves the target's required env overlay atomically from
+ *     the secret store, and spawns the manifest `command`/`args`.
+ *
+ * This file is the highest-risk surface of the worktree-credentials work: the
+ * stdio passthrough plus the signal/exit-code contract is covered exhaustively
+ * by its unit tests.
+ */
+import { spawn, execFile } from "child_process";
+import { stat, readFile } from "fs/promises";
+import path from "path";
+import os from "os";
+import { resolveRepoNameForProjectRoot, readBridgeConfig, validateMcpTarget, } from "./bridge-config.js";
+import { resolveBapiCredentials } from "./credential-store.js";
+import { getThirdPartyTargetDefinition, resolveThirdPartyTargetEnv, validateThirdPartyTargetManifestEntry, } from "./third-party-mcp-targets.js";
+// ---------------------------------------------------------------------------
+// Usage / argument parsing
+// ---------------------------------------------------------------------------
+export function getMcpInvokeUsage() {
+    return [
+        "Usage:",
+        "  npx -y @bridge_gpt/mcp-server mcp-invoke --target <target> --project-root <ABS_WORKTREE_PATH>",
+        "",
+        "Internal worktree shim: resolves the target's launch command and credentials",
+        "from the given project root, then spawns the real MCP server over stdio.",
+        "",
+        "Flags:",
+        "  --target <target>            MCP target to launch. 'bapi' launches the Bridge",
+        "                               API server; a configured third-party target from",
+        "                               .bridge/config (e.g. sfcc) launches that server.",
+        "  --project-root <ABS_PATH>    Absolute path to the worktree (required)",
+        "  -h, --help                   Show this help",
+    ].join("\n");
+}
+const KNOWN_FLAGS = new Set(["--target", "--project-root"]);
+/**
+ * Parse `--target` and `--project-root` (split or `=` form). Rejects unknown
+ * flags, positional arguments, missing values, and duplicates. Requires a safe
+ * non-empty `--target` identifier and a host-platform-absolute `--project-root`.
+ */
+export function parseMcpInvokeArgs(argv) {
+    let target;
+    let projectRoot;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "-h" || token === "--help") {
+            return { status: "help", usage: getMcpInvokeUsage() };
+        }
+        let flag = token;
+        let value;
+        const eq = token.indexOf("=");
+        if (token.startsWith("--") && eq !== -1) {
+            flag = token.slice(0, eq);
+            value = token.slice(eq + 1);
+        }
+        if (!KNOWN_FLAGS.has(flag)) {
+            if (token.startsWith("-")) {
+                return { status: "error", message: `Unknown flag: ${flag}` };
+            }
+            return { status: "error", message: `Unexpected positional argument: ${token}` };
+        }
+        if (value === undefined) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("-")) {
+                return { status: "error", message: `Missing value for ${flag}` };
+            }
+            value = next;
+            i++;
+        }
+        if (flag === "--target") {
+            if (target !== undefined) {
+                return { status: "error", message: "Duplicate --target flag" };
+            }
+            target = value;
+        }
+        else {
+            if (projectRoot !== undefined) {
+                return { status: "error", message: "Duplicate --project-root flag" };
+            }
+            projectRoot = value;
+        }
+    }
+    if (target === undefined) {
+        return { status: "error", message: "Missing required --target flag" };
+    }
+    const targetValidation = validateMcpTarget(target);
+    if (!targetValidation.ok) {
+        return { status: "error", message: `Invalid --target: ${targetValidation.error}` };
+    }
+    if (projectRoot === undefined) {
+        return { status: "error", message: "Missing required --project-root flag" };
+    }
+    if (!path.isAbsolute(projectRoot)) {
+        return { status: "error", message: "--project-root must be an absolute path" };
+    }
+    return { status: "ok", target: targetValidation.value, projectRoot };
+}
+// ---------------------------------------------------------------------------
+// Validation, env construction, signals
+// ---------------------------------------------------------------------------
+/** Fail fast when `--project-root` does not exist or is not a directory. */
+export async function validateProjectRootDirectory(projectRoot, statFn) {
+    try {
+        const result = await statFn(projectRoot);
+        if (!result.isDirectory()) {
+            return { ok: false, error: `--project-root is not a directory: ${projectRoot}` };
+        }
+        return { ok: true };
+    }
+    catch {
+        return { ok: false, error: `--project-root does not exist: ${projectRoot}` };
+    }
+}
+/**
+ * Build the child environment: start from the parent env, overlay an arbitrary
+ * set of resolved values. The parent env object is never mutated; unrelated
+ * parent values (`BAPI_BASE_URL`, `BAPI_DOCS_DIR`, proxy variables, Node env)
+ * pass through unchanged. Overlay values are typically secrets and must only
+ * ever reach the child through this env object — never argv or logs.
+ */
+export function buildChildEnv(parentEnv, overlay) {
+    return { ...parentEnv, ...overlay };
+}
+/** Map a terminating signal to a conventional `128 + signum` exit code. */
+export function signalExitCode(signal) {
+    if (signal === "SIGINT")
+        return 130;
+    if (signal === "SIGTERM")
+        return 143;
+    const signals = os.constants.signals;
+    const num = signals[signal];
+    if (typeof num === "number")
+        return 128 + num;
+    return 1;
+}
+// ---------------------------------------------------------------------------
+// Child server spawn
+// ---------------------------------------------------------------------------
+/**
+ * Spawn an MCP server child with the given command/args, inherited stdio, and
+ * the merged child env. SIGINT/SIGTERM received by the shim are forwarded to the
+ * child; the returned promise resolves once the child closes, propagating its
+ * numeric exit code (or the signal exit code). Signal handlers are registered
+ * after spawn and removed exactly once on close.
+ */
+export function spawnMcpCommand(deps) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = deps.spawn(deps.command, deps.args, {
+                stdio: "inherit",
+                env: deps.env,
+            });
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        const signals = ["SIGINT", "SIGTERM"];
+        const handlers = {};
+        let cleaned = false;
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            for (const sig of signals)
+                deps.offSignal(sig, handlers[sig]);
+        };
+        for (const sig of signals) {
+            const handler = () => {
+                try {
+                    child.kill(sig);
+                }
+                catch {
+                    /* best-effort forward; the close handler still resolves */
+                }
+            };
+            handlers[sig] = handler;
+            deps.onSignal(sig, handler);
+        }
+        child.on("error", (err) => {
+            cleanup();
+            reject(err);
+        });
+        child.on("close", (...args) => {
+            cleanup();
+            const code = args[0];
+            const signal = args[1];
+            if (typeof code === "number") {
+                resolve(code);
+            }
+            else if (signal) {
+                resolve(signalExitCode(signal));
+            }
+            else {
+                resolve(0);
+            }
+        });
+    });
+}
+/**
+ * Back-compat wrapper: spawn the real Bridge API MCP server as
+ * `node <thisScript>` (no `mcp-invoke` subcommand args, so the child enters the
+ * normal no-subcommand startup path). Delegates to {@link spawnMcpCommand}.
+ */
+export function spawnRealMcpServer(deps) {
+    return spawnMcpCommand({
+        spawn: deps.spawn,
+        command: deps.execPath,
+        args: [deps.scriptPath],
+        env: deps.env,
+        onSignal: deps.onSignal,
+        offSignal: deps.offSignal,
+    });
+}
+// ---------------------------------------------------------------------------
+// Default production runners (used when overrides are not supplied)
+// ---------------------------------------------------------------------------
+function defaultRunCommand(file, args, options) {
+    return new Promise((resolve) => {
+        execFile(file, args, { cwd: options?.cwd }, (err, stdout, stderr) => {
+            if (err) {
+                const code = typeof err.code === "number"
+                    ? (err.code)
+                    : 1;
+                resolve({
+                    stdout: stdout?.toString() ?? "",
+                    stderr: stderr?.toString() ?? err.message,
+                    exitCode: code,
+                });
+            }
+            else {
+                resolve({ stdout: stdout.toString(), stderr: stderr.toString(), exitCode: 0 });
+            }
+        });
+    });
+}
+/**
+ * Resolve the Bridge API invocation: derive repo identity, resolve the API key
+ * (env→store), and overlay the three `BAPI_*` values onto the parent env. The
+ * spawned command is `process.execPath` with `[scriptPath]` (no subcommand args
+ * — the child runs the normal server). Secret-free errors on any failure.
+ */
+export async function resolveBapiInvocation(projectRoot, deps) {
+    const repoResult = await deps.resolveRepoName(projectRoot);
+    if (!repoResult.ok) {
+        return { ok: false, error: `failed to resolve repo identity: ${repoResult.error}` };
+    }
+    const repoName = repoResult.value;
+    const credResult = await deps.resolveCredentials(repoName, projectRoot);
+    if (!credResult.ok) {
+        return { ok: false, error: `failed to resolve credentials: ${credResult.error}` };
+    }
+    const env = buildChildEnv(deps.env, {
+        BAPI_API_KEY: credResult.credentials.apiKey,
+        BAPI_PROJECT_ROOT: projectRoot,
+        BAPI_REPO_NAME: repoName,
+    });
+    return {
+        ok: true,
+        invocation: { command: deps.execPath, args: [deps.scriptPath], env },
+    };
+}
+/**
+ * Resolve a Tier-2 third-party invocation: read `.bridge/config`, locate the
+ * requested target entry, resolve the target's required env overlay atomically
+ * from the secret store, and return the manifest `command`/`args` plus the
+ * overlaid child env. Credentials never enter argv. Secret-free errors.
+ */
+export async function resolveThirdPartyInvocation(target, projectRoot, deps) {
+    const definition = deps.getTargetDefinition(target);
+    if (!definition) {
+        return {
+            ok: false,
+            error: `unsupported MCP target '${target}'; not a known third-party target`,
+        };
+    }
+    const read = await deps.readBridgeConfig(projectRoot);
+    if (!read.ok) {
+        if (read.kind === "missing") {
+            return { ok: false, error: `target '${target}' requires a .bridge/config; none was found` };
+        }
+        return { ok: false, error: `unable to read .bridge/config for target '${target}'` };
+    }
+    const entry = read.manifest.mcp.find((m) => m.target === target);
+    if (!entry) {
+        return {
+            ok: false,
+            error: `target '${target}' is not declared in .bridge/config`,
+        };
+    }
+    const entryValidation = validateThirdPartyTargetManifestEntry(entry);
+    if (!entryValidation.ok) {
+        return { ok: false, error: entryValidation.error };
+    }
+    // After validation these are guaranteed present.
+    const command = entry.command;
+    const args = entry.args;
+    const secretBundle = entry.secretBundle;
+    const envResult = await deps.resolveTargetEnv(definition, secretBundle);
+    if (!envResult.ok) {
+        return { ok: false, error: `failed to resolve credentials for '${target}': ${envResult.error}` };
+    }
+    const env = buildChildEnv(deps.env, envResult.env);
+    return { ok: true, invocation: { command, args, env } };
+}
+/**
+ * Run the `mcp-invoke` subcommand. Returns a process exit code (never calls
+ * `process.exit`). Parses args BEFORE any validation/resolution; validates the
+ * project root; dispatches `bapi` to {@link resolveBapiInvocation} and any other
+ * target to {@link resolveThirdPartyInvocation}; then spawns. Any failure prints
+ * an actionable, secret-free message to stderr and returns non-zero without
+ * spawning.
+ */
+export async function runMcpInvokeCli(argv, overrides = {}) {
+    const log = overrides.log ?? ((m) => process.stdout.write(`${m}\n`));
+    const stderr = overrides.stderr ?? ((m) => process.stderr.write(`${m}\n`));
+    const env = overrides.env ?? process.env;
+    const parsed = parseMcpInvokeArgs(argv);
+    if (parsed.status === "help") {
+        log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        stderr(`Error: ${parsed.message}`);
+        stderr("");
+        stderr(getMcpInvokeUsage());
+        return 1;
+    }
+    const { target, projectRoot } = parsed;
+    const statFn = overrides.stat ?? ((p) => stat(p));
+    const dirCheck = await validateProjectRootDirectory(projectRoot, statFn);
+    if (!dirCheck.ok) {
+        stderr(`Error: ${dirCheck.error}`);
+        return 1;
+    }
+    const credentialDeps = {
+        env,
+        homedir: os.homedir,
+        platform: process.platform,
+        readFile: (p) => readFile(p, "utf-8"),
+        stat: (p) => stat(p),
+        stderr,
+    };
+    if (target === "bapi") {
+        const resolveRepoName = overrides.resolveRepoName ??
+            ((pr) => resolveRepoNameForProjectRoot(pr, {
+                readFile: (p) => readFile(p, "utf-8"),
+                runCommand: defaultRunCommand,
+            }));
+        const resolveCredentials = overrides.resolveCredentials ??
+            ((rn) => resolveBapiCredentials(rn, credentialDeps));
+        const resolved = await resolveBapiInvocation(projectRoot, {
+            env,
+            execPath: process.execPath,
+            scriptPath: process.argv[1],
+            resolveRepoName,
+            resolveCredentials,
+        });
+        if (!resolved.ok) {
+            stderr(`Error: ${resolved.error}`);
+            return 1;
+        }
+        return spawnInvocation(resolved.invocation, overrides);
+    }
+    // Tier-2 third-party target.
+    const readConfig = overrides.readBridgeConfig ??
+        ((pr) => readBridgeConfig(pr, { readFile: (p) => readFile(p, "utf-8") }));
+    const getTargetDefinition = overrides.getTargetDefinition ?? getThirdPartyTargetDefinition;
+    const resolveTargetEnv = overrides.resolveThirdPartyEnv ??
+        ((definition, secretBundle) => resolveThirdPartyTargetEnv(definition, secretBundle, credentialDeps));
+    const resolved = await resolveThirdPartyInvocation(target, projectRoot, {
+        env,
+        readBridgeConfig: readConfig,
+        getTargetDefinition,
+        resolveTargetEnv,
+    });
+    if (!resolved.ok) {
+        stderr(`Error: ${resolved.error}`);
+        return 1;
+    }
+    return spawnInvocation(resolved.invocation, overrides);
+}
+/** Spawn a resolved invocation, honoring the legacy and generic spawn overrides. */
+function spawnInvocation(invocation, overrides) {
+    if (overrides.spawnMcpCommand) {
+        return overrides.spawnMcpCommand(invocation);
+    }
+    if (overrides.spawnRealMcpServer) {
+        return overrides.spawnRealMcpServer(invocation.env);
+    }
+    return spawnMcpCommand({
+        spawn: spawn,
+        command: invocation.command,
+        args: invocation.args,
+        env: invocation.env,
+        onSignal: (s, h) => {
+            process.on(s, h);
+        },
+        offSignal: (s, h) => {
+            process.off(s, h);
+        },
+    });
+}

package/build/mcp-provisioning.js

@@ -0,0 +1,249 @@
+/**
+ * Worktree MCP registration provisioning.
+ *
+ * After `start-tickets` creates a worktree, this module writes secret-free MCP
+ * registrations into both Claude (`.mcp.json`) and Cursor (`.cursor/mcp.json`)
+ * so the configured MCP servers are reachable from either editor. Every
+ * generated entry contains NO `env` block — it points at the `mcp-invoke` shim
+ * with an absolute `--project-root` and the target name; credentials are
+ * resolved at runtime by the shim, never written into the worktree.
+ *
+ * Registrations are driven by `.bridge/config`: the `bapi` target is always
+ * provisioned when present, and every supported Tier-2 target (e.g. `sfcc`) is
+ * provisioned as its own shim entry. Unsupported or incomplete non-`bapi`
+ * targets produce a non-fatal, secret-free warning.
+ *
+ * All filesystem access is dependency-injected so this is unit-testable, and the
+ * platform path API is resolved locally (never imported from `start-tickets.ts`)
+ * to avoid a runtime import cycle.
+ */
+import path from "path";
+import { VERSION } from "./version.generated.js";
+import { readBridgeConfig } from "./bridge-config.js";
+import { getThirdPartyTargetDefinition, validateThirdPartyTargetManifestEntry, } from "./third-party-mcp-targets.js";
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the path API for the target platform. Local (not imported from
+ * `start-tickets.ts`) to avoid a runtime cycle, since that module imports the
+ * provisioning entry point.
+ */
+export function pathApiForProvisioningPlatform(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+/**
+ * Normalize a worktree path to an absolute, platform-correct registration path.
+ * Absolute inputs are normalized; relative inputs are resolved against
+ * `deps.cwd`. A path that cannot be made absolute is a structured error.
+ */
+export function normalizeWorktreePathForRegistration(worktreePath, deps) {
+    const api = pathApiForProvisioningPlatform(deps.platform);
+    if (typeof worktreePath !== "string" || worktreePath.trim().length === 0) {
+        return { ok: false, error: "worktree path is empty" };
+    }
+    const resolved = api.isAbsolute(worktreePath)
+        ? api.normalize(worktreePath)
+        : api.resolve(deps.cwd, worktreePath);
+    if (!api.isAbsolute(resolved)) {
+        return { ok: false, error: `unable to resolve an absolute worktree path from "${worktreePath}"` };
+    }
+    return { ok: true, path: resolved };
+}
+/** Map an MCP target to its registration server name (`bapi` -> `bridge-api`). */
+export function serverNameForMcpTarget(target) {
+    return target === "bapi" ? "bridge-api" : target;
+}
+/**
+ * Build a secret-free shim entry for any target. `args` are version-pinned and
+ * carry the target name plus the absolute project root; there is intentionally
+ * no `env` block.
+ */
+export function buildShimMcpServerEntry(target, absoluteWorktreePath) {
+    return {
+        command: "npx",
+        args: [
+            "-y",
+            `@bridge_gpt/mcp-server@${VERSION}`,
+            "mcp-invoke",
+            "--target",
+            target,
+            "--project-root",
+            absoluteWorktreePath,
+        ],
+    };
+}
+/** Back-compat wrapper around `buildShimMcpServerEntry("bapi", ...)`. */
+export function buildBridgeApiShimMcpServerEntry(absoluteWorktreePath) {
+    return buildShimMcpServerEntry("bapi", absoluteWorktreePath);
+}
+/**
+ * Convert all supported manifest `mcp` entries into a map of server name -> shim
+ * entry. `bapi` is always supported; a Tier-2 target is supported only when it
+ * has a known target definition AND its manifest entry is complete. Unsupported
+ * or incomplete non-`bapi` targets are skipped with a secret-free warning (they
+ * never appear in the returned entries).
+ */
+export function buildMcpServerEntriesForManifest(manifest, absoluteWorktreePath) {
+    const entries = {};
+    const warnings = [];
+    for (const mcp of manifest.mcp) {
+        if (mcp.target === "bapi") {
+            entries[serverNameForMcpTarget("bapi")] = buildShimMcpServerEntry("bapi", absoluteWorktreePath);
+            continue;
+        }
+        const definition = getThirdPartyTargetDefinition(mcp.target);
+        if (!definition) {
+            warnings.push(`MCP target '${mcp.target}' is not a supported third-party target; skipping its registration.`);
+            continue;
+        }
+        const validation = validateThirdPartyTargetManifestEntry(mcp);
+        if (!validation.ok) {
+            warnings.push(`MCP target '${mcp.target}' registration skipped: ${validation.error}.`);
+            continue;
+        }
+        entries[serverNameForMcpTarget(mcp.target)] = buildShimMcpServerEntry(mcp.target, absoluteWorktreePath);
+    }
+    return { entries, warnings };
+}
+/** Both registration files written for every provisioned worktree. */
+export function getWorktreeMcpRegistrationTargets(worktreePath, platform) {
+    const api = pathApiForProvisioningPlatform(platform);
+    return [
+        { filePath: api.join(worktreePath, ".mcp.json"), topLevelKey: "mcpServers" },
+        { filePath: api.join(worktreePath, ".cursor", "mcp.json"), topLevelKey: "mcpServers" },
+    ];
+}
+/**
+ * Merge multiple shim entries into an existing parsed registration document.
+ * Unrelated top-level fields and unrelated MCP servers are preserved; only the
+ * generated server names are replaced. Any legacy secret-embedded entry for a
+ * generated server name is force-upgraded to the secret-free shim shape.
+ */
+export function mergeMcpRegistrations(existing, topLevelKey, entries) {
+    const result = existing && typeof existing === "object" && !Array.isArray(existing)
+        ? { ...existing }
+        : {};
+    const current = result[topLevelKey];
+    const servers = current && typeof current === "object" && !Array.isArray(current)
+        ? { ...current }
+        : {};
+    for (const [name, entry] of Object.entries(entries)) {
+        servers[name] = entry;
+    }
+    result[topLevelKey] = servers;
+    return result;
+}
+/**
+ * Back-compat single-entry merge. Sets only `mcpServers["bridge-api"]`; unrelated
+ * top-level fields and servers are preserved.
+ */
+export function mergeBridgeApiMcpRegistration(existing, topLevelKey, entry) {
+    return mergeMcpRegistrations(existing, topLevelKey, { "bridge-api": entry });
+}
+// ---------------------------------------------------------------------------
+// Filesystem writes
+// ---------------------------------------------------------------------------
+/**
+ * Write or merge a single registration file with the given entries. A missing
+ * file is created (with parent directories); an existing valid file is merged; an
+ * existing file with malformed JSON is left untouched and reported as a failure.
+ * JSON is written with two-space indentation and a trailing newline.
+ */
+export async function writeMcpRegistrationFile(target, entries, deps) {
+    const api = pathApiForProvisioningPlatform(deps.platform);
+    let existing;
+    try {
+        const raw = await deps.readFile(target.filePath);
+        try {
+            existing = JSON.parse(raw);
+        }
+        catch {
+            return {
+                ok: false,
+                error: `existing ${target.filePath} contains malformed JSON; not overwriting`,
+            };
+        }
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        if (code !== "ENOENT") {
+            return { ok: false, error: `unable to read ${target.filePath}` };
+        }
+        // ENOENT: create a fresh document below.
+    }
+    const merged = mergeMcpRegistrations(existing, target.topLevelKey, entries);
+    try {
+        await deps.mkdir(api.dirname(target.filePath), { recursive: true });
+        await deps.writeFile(target.filePath, `${JSON.stringify(merged, null, 2)}\n`);
+    }
+    catch {
+        return { ok: false, error: `failed to write ${target.filePath}` };
+    }
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Per-worktree orchestration
+// ---------------------------------------------------------------------------
+function withWarning(row, warning) {
+    return { ...row, warnings: [...(row.warnings ?? []), warning] };
+}
+function withWarnings(row, warnings) {
+    if (warnings.length === 0)
+        return row;
+    return { ...row, warnings: [...(row.warnings ?? []), ...warnings] };
+}
+/**
+ * Provision MCP registrations for one created worktree row.
+ *
+ * - Non-`created` rows and rows without a path are returned unchanged.
+ * - A missing / malformed manifest yields a non-fatal warning and leaves the row
+ *   status unchanged.
+ * - A valid manifest writes BOTH Claude and Cursor registration files with a
+ *   shim entry for every supported target (`bapi` + complete Tier-2 targets),
+ *   regardless of the selected agent. Unsupported/incomplete non-`bapi` targets
+ *   add a secret-free warning but never abort provisioning.
+ * - A required write failure (or a malformed existing registration file) marks
+ *   only this row `spawn-failed` with a descriptive error; other rows continue.
+ */
+export async function provisionMcpRegistrationForWorktree(row, deps) {
+    if (row.status !== "created" || !row.path) {
+        return row;
+    }
+    const read = await readBridgeConfig(row.path, { readFile: deps.readFile });
+    if (!read.ok) {
+        if (read.kind === "missing") {
+            return withWarning(row, "MCP provisioning skipped: .bridge/config is missing in the worktree.");
+        }
+        return withWarning(row, "MCP provisioning skipped: .bridge/config is malformed or invalid.");
+    }
+    const normalized = normalizeWorktreePathForRegistration(row.path, deps);
+    if (!normalized.ok) {
+        return { ...row, status: "spawn-failed", error: `MCP provisioning failed: ${normalized.error}` };
+    }
+    const built = buildMcpServerEntriesForManifest(read.manifest, normalized.path);
+    if (Object.keys(built.entries).length === 0) {
+        // Nothing supported to write (e.g. a manifest with no bapi target and no
+        // supported Tier-2 targets). Surface any warnings but leave status unchanged.
+        return withWarnings(withWarning(row, "MCP registration skipped: .bridge/config declares no supported MCP targets."), built.warnings);
+    }
+    const targets = getWorktreeMcpRegistrationTargets(normalized.path, deps.platform);
+    for (const target of targets) {
+        const result = await writeMcpRegistrationFile(target, built.entries, deps);
+        if (!result.ok) {
+            return { ...row, status: "spawn-failed", error: `MCP provisioning failed: ${result.error}` };
+        }
+    }
+    return withWarnings(row, built.warnings);
+}
+/**
+ * Provision MCP registrations for every created worktree row, in order.
+ * Per-row failures are isolated — a failed row never aborts later rows.
+ */
+export async function provisionMcpRegistrationsForCreatedWorktrees(rows, deps) {
+    const out = [];
+    for (const row of rows) {
+        out.push(await provisionMcpRegistrationForWorktree(row, deps));
+    }
+    return out;
+}