@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/mcp-host-targets.js

@@ -25,6 +25,44 @@ function joinPath(base, rel) {
     return `${trimmedBase}/${trimmedRel}`;
 }
 // ---------------------------------------------------------------------------
+// Adapters — the exhaustive physical-format map every HostKind must resolve.
+// `satisfies` (rather than an explicit `Record<HostKind, HostAdapter>`
+// annotation) keeps each adapter's literal field types narrow while still
+// making an incomplete map a compile error.
+// ---------------------------------------------------------------------------
+export const HOST_ADAPTERS = {
+    "claude-code-json": {
+        format: "json",
+        topLevelKey: "mcpServers",
+        transportType: undefined, // Claude Code omits `type`.
+    },
+    "cursor-json": {
+        format: "json",
+        topLevelKey: "mcpServers",
+        transportType: "stdio",
+    },
+    "vscode-json": {
+        format: "json",
+        topLevelKey: "servers",
+        transportType: "stdio",
+    },
+    "codex-toml": {
+        format: "toml",
+        topLevelKey: "mcp_servers",
+        transportType: undefined, // TOML table shape has no `type`.
+    },
+    "copilot-cli": {
+        format: "json",
+        topLevelKey: "mcpServers",
+        transportType: "local",
+        extraEntryKeys: { tools: ["*"] },
+    },
+};
+/** Pure typed lookup from a target's declared {@link HostKind} to its adapter. */
+export function hostAdapterForTarget(target) {
+    return HOST_ADAPTERS[target.hostKind];
+}
+// ---------------------------------------------------------------------------
 // Registry — additive; add a new entry (and a PlatformId member) per platform.
 // ---------------------------------------------------------------------------
 /**
@@ -38,9 +76,7 @@ export const MCP_HOST_TARGETS = {
         scope: "project",
         relPath: ".mcp.json",
         displayPath: ".mcp.json",
-        format: "json",
-        topLevelKey: "mcpServers",
-        transportType: undefined, // Claude Code omits `type`.
+        hostKind: "claude-code-json",
         vendorCli: { bin: "claude", kind: "claude-add-json" },
         launchAgent: "claude",
         worktreeSupported: true,
@@ -54,9 +90,7 @@ export const MCP_HOST_TARGETS = {
         scope: "project",
         relPath: ".cursor/mcp.json",
         displayPath: ".cursor/mcp.json",
-        format: "json",
-        topLevelKey: "mcpServers",
-        transportType: "stdio",
+        hostKind: "cursor-json",
         launchAgent: "cursor-agent",
         worktreeSupported: true,
         writeStrategy: "direct",
@@ -70,9 +104,7 @@ export const MCP_HOST_TARGETS = {
         scope: "project",
         relPath: ".vscode/mcp.json",
         displayPath: ".vscode/mcp.json",
-        format: "json",
-        topLevelKey: "servers",
-        transportType: "stdio",
+        hostKind: "vscode-json",
         worktreeSupported: false,
         writeStrategy: "direct",
         detect: (ctx) => ctx.exists(joinPath(ctx.cwd, ".vscode")),
@@ -83,10 +115,7 @@ export const MCP_HOST_TARGETS = {
         scope: "global",
         absPathResolver: (homedir) => joinPath(homedir, ".copilot/mcp-config.json"),
         displayPath: "~/.copilot/mcp-config.json",
-        format: "json",
-        topLevelKey: "mcpServers",
-        transportType: "local",
-        extraEntryKeys: { tools: ["*"] },
+        hostKind: "copilot-cli",
         vendorCli: { bin: "copilot", kind: "copilot-add" },
         worktreeSupported: false,
         writeStrategy: "vendor-first",
@@ -99,9 +128,7 @@ export const MCP_HOST_TARGETS = {
         scope: "global",
         absPathResolver: (homedir) => joinPath(homedir, ".codex/config.toml"),
         displayPath: "~/.codex/config.toml",
-        format: "toml",
-        topLevelKey: "mcp_servers",
-        transportType: undefined, // TOML table shape has no `type`.
+        hostKind: "codex-toml",
         vendorCli: { bin: "codex", kind: "codex-add" },
         worktreeSupported: false,
         writeStrategy: "vendor-first",
@@ -113,10 +140,7 @@ export const MCP_HOST_TARGETS = {
         scope: "global",
         absPathResolver: (homedir) => joinPath(homedir, ".codeium/windsurf/mcp_config.json"),
         displayPath: "~/.codeium/windsurf/mcp_config.json",
-        format: "json",
-        topLevelKey: "mcpServers",
-        // Windsurf historically renders with no `type` (like Claude); preserve that.
-        transportType: undefined,
+        hostKind: "claude-code-json", // Windsurf uses the Claude-compatible JSON shape.
         worktreeSupported: false,
         // Preserve current behavior: never auto-modify the global Windsurf file.
         writeStrategy: "manual-instructions",
@@ -164,7 +188,7 @@ export function getWorktreeHostTargets() {
 }
 /** Project-scoped JSON targets (used by init, launcher-token merge, doctor). */
 export function getProjectJsonTargets() {
-    return allHostTargets().filter((t) => t.scope === "project" && t.format === "json");
+    return allHostTargets().filter((t) => t.scope === "project" && hostAdapterForTarget(t).format === "json");
 }
 /** Targets written automatically (vendor-first or direct). */
 export function getAutomaticHostTargets() {

package/build/mcp-identity.js

@@ -0,0 +1,92 @@
+/**
+ * Single TypeScript source of truth for the current MCP server identity
+ * (BAPI-806) and for permanent legacy-name compatibility (BAPI-807).
+ *
+ * Every production reader, writer, doctor, and display string must import
+ * these constants rather than duplicating the server name or npm package
+ * literal. This module is intentionally stateless and dependency-free so it
+ * can be imported from anywhere in `mcp_server/src` without introducing a
+ * require cycle.
+ *
+ * The registration key and the npm package are DIFFERENT identities. Flipping
+ * the host-facing key from `bridge-api` to `bridge` leaves
+ * {@link MCP_PACKAGE_NAME}, the `bridge-api-mcp-server` bin names, the
+ * `bapi:<repo>` credential namespace, `mcp-invoke --target bapi`, and every
+ * `BAPI_*` environment variable untouched.
+ */
+/** The current host-facing MCP server registration name. */
+export const MCP_SERVER_NAME = "bridge";
+/** The current published npm package name for the MCP server. */
+export const MCP_PACKAGE_NAME = "@bridge_gpt/mcp-server";
+/** The README resource URI served by the MCP server. */
+export const MCP_README_URI = `${MCP_SERVER_NAME}://readme`;
+/**
+ * Registration names that are recognized FOREVER when reading an existing host
+ * configuration, and never written for a fresh registration (BAPI-807).
+ *
+ * This is a PERMANENT compatibility surface, not a migration window. Bridge does
+ * not rename, migrate, or repair an existing `bridge-api` registration: someone
+ * whose config was written before the rename keeps working indefinitely, and
+ * every reader — `init`, `upgrade`, `doctor`, install, and worktree provisioning
+ * — must treat a legacy key as a first-class existing registration rather than
+ * as absence. Do not add a deprecation date, a removal plan, or an automatic
+ * rewrite; the whole point is that no user is ever required to act.
+ */
+export const LEGACY_SERVER_NAMES = ["bridge-api"];
+/**
+ * Every recognized key, canonical FIRST. Readers that need to enumerate keys
+ * (the Codex table matcher, the Claude scope inspector) build their candidate
+ * list from this rather than restating the literals.
+ */
+export const RECOGNIZED_SERVER_NAMES = [
+    MCP_SERVER_NAME,
+    ...LEGACY_SERVER_NAMES,
+];
+/** True for a string that is one of Bridge's recognized registration keys. */
+export function isRecognizedServerName(value) {
+    return (typeof value === "string" &&
+        RECOGNIZED_SERVER_NAMES.includes(value));
+}
+/**
+ * Resolve which registration key a caller should read or write in a servers map.
+ *
+ * Two properties are load-bearing and must not be "simplified" away:
+ *
+ *  - **Own properties only.** A `bridge` or `bridge-api` inherited from
+ *    `Object.prototype` (or from a JSON-parsed object's prototype chain in a
+ *    polluted runtime) is NOT a registration. Resolving one would let prototype
+ *    pollution redirect a write.
+ *  - **Presence, not validity.** Two present keys are a conflict even when one
+ *    entry is `null`, an array, or otherwise malformed. Picking the "valid
+ *    looking" one would silently choose which of a user's two registrations
+ *    wins, which is exactly the decision a human has to make.
+ *
+ * A non-object input (missing servers section, `null`, an array) resolves to
+ * `absent`: there is nothing there to update, and a fresh write is canonical.
+ */
+export function resolveRegistrationKey(servers) {
+    const absent = { state: "absent", writeKey: MCP_SERVER_NAME };
+    if (typeof servers !== "object" || servers === null || Array.isArray(servers)) {
+        return absent;
+    }
+    const present = RECOGNIZED_SERVER_NAMES.filter((name) => Object.prototype.hasOwnProperty.call(servers, name));
+    if (present.length === 0)
+        return absent;
+    if (present.length > 1)
+        return { state: "conflict", keys: present };
+    const [only] = present;
+    return only === MCP_SERVER_NAME
+        ? { state: "canonical", key: MCP_SERVER_NAME }
+        : { state: "legacy", key: only };
+}
+/**
+ * The key an EXISTING registration lives under, or `null` when there is none or
+ * the state is ambiguous. Convenience for readers that already handled — or
+ * deliberately do not care about — the absent and conflict branches.
+ */
+export function existingRegistrationKey(servers) {
+    const resolution = resolveRegistrationKey(servers);
+    return resolution.state === "canonical" || resolution.state === "legacy"
+        ? resolution.key
+        : null;
+}

package/build/mcp-install-state.js

@@ -7,7 +7,8 @@
  * per-developer and is gitignored before it is written.
  *
  * SECURITY: the state is strictly SECRET-FREE. It stores only a validated
- * platform roster and repo-relative project config paths. It never contains API
+ * platform roster, repo-relative project config paths, home-relative generated
+ * service-unit locators, and identifiers from a closed capability vocabulary. It never contains API
  * keys, env blocks, absolute home paths, or vendor command payloads. Reads
  * validate every stored platform ID against {@link MCP_HOST_TARGETS}; writes
  * serialize only the schema-approved fields.
@@ -21,6 +22,22 @@ import { HOST_PLATFORM_ORDER, isHostPlatformId, } from "./mcp-host-targets.js";
 export const MCP_INSTALL_STATE_VERSION = 1;
 /** The relative path of the state file within a project. */
 export const MCP_INSTALL_STATE_RELPATH = ".bridge/install-state.json";
+/**
+ * The conductor capabilities `install conductor` may record (BAPI-775).
+ *
+ * A CLOSED vocabulary, validated on read and on write: install state is a
+ * diagnostic inventory of what this tool provisioned, so an arbitrary
+ * caller-supplied string must never become a recorded capability.
+ */
+export const MCP_INSTALL_CAPABILITY_IDS = [
+    "conductor_local_observability",
+    "conductor_tool_visibility",
+];
+/** Whether a value is one of the ratified capability identifiers. */
+export function isMcpInstallCapabilityId(value) {
+    return (typeof value === "string" &&
+        MCP_INSTALL_CAPABILITY_IDS.includes(value));
+}
 // ---------------------------------------------------------------------------
 // Path helpers (POSIX-normalized; avoids node:path so tests are deterministic).
 // ---------------------------------------------------------------------------
@@ -60,6 +77,23 @@ function normalizeProjectPaths(paths) {
     out.sort();
     return out;
 }
+/**
+ * Validate, dedupe, and stably order capability identifiers (BAPI-775).
+ *
+ * Unknown identifiers are DROPPED rather than failing the document, matching the
+ * executor-locator rule below: a capability nobody can act on must not take the
+ * platform roster down with it.
+ */
+function normalizeCapabilities(values) {
+    const wanted = new Set();
+    for (const value of values) {
+        if (isMcpInstallCapabilityId(value))
+            wanted.add(value);
+    }
+    // Registry order, not insertion order, so two runs recording the same pair
+    // serialize identically.
+    return MCP_INSTALL_CAPABILITY_IDS.filter((id) => wanted.has(id));
+}
 // ---------------------------------------------------------------------------
 // Executor service-unit locators (BAPI-779)
 // ---------------------------------------------------------------------------
@@ -193,6 +227,12 @@ export async function readMcpInstallState(cwd, deps) {
     if (rawUnitPaths !== undefined && !Array.isArray(rawUnitPaths)) {
         return { status: "invalid", reason: "executorServiceUnitPaths is not an array" };
     }
+    // Same absent-vs-wrong-type rule as the field above (BAPI-775): every document
+    // written before conductor capabilities existed simply lacks the key.
+    const rawCapabilities = doc.capabilities;
+    if (rawCapabilities !== undefined && !Array.isArray(rawCapabilities)) {
+        return { status: "invalid", reason: "capabilities is not an array" };
+    }
     return {
         status: "valid",
         state: {
@@ -203,6 +243,7 @@ export async function readMcpInstallState(cwd, deps) {
             // failing the read: they cannot be acted on, and losing the whole
             // document over one bad entry would take the platform roster with it.
             executorServiceUnitPaths: normalizeExecutorServiceUnitPaths(Array.isArray(rawUnitPaths) ? rawUnitPaths : []),
+            capabilities: normalizeCapabilities(Array.isArray(rawCapabilities) ? rawCapabilities : []),
         },
     };
 }
@@ -211,6 +252,8 @@ export async function readMcpInstallState(cwd, deps) {
 // ---------------------------------------------------------------------------
 /** Serialize an install-state document deterministically (stable key order). */
 export function serializeMcpInstallState(state) {
+    // Re-normalized here for the same last-gate reason as the locators below.
+    const capabilities = normalizeCapabilities(state.capabilities ?? []);
     // Explicit key order — do not rely on object insertion order for stability.
     const ordered = {
         version: state.version,
@@ -220,6 +263,12 @@ export function serializeMcpInstallState(state) {
         // this function is the last gate before bytes hit disk, and a caller could
         // hand it a hand-built state carrying an arbitrary path.
         executorServiceUnitPaths: normalizeExecutorServiceUnitPaths(state.executorServiceUnitPaths ?? []),
+        // BAPI-775: emitted ONLY when a capability was actually recorded. An empty
+        // roster and an absent key mean the same thing to every reader (the read
+        // path treats an absent array as empty), and omitting it keeps a document
+        // that predates conductor capabilities byte-identical after a rewrite —
+        // additive on disk, not merely additive in the schema.
+        ...(capabilities.length > 0 ? { capabilities } : {}),
     };
     return JSON.stringify(ordered, null, 2) + "\n";
 }
@@ -233,6 +282,7 @@ export function serializeMcpInstallState(state) {
 export async function writeMcpInstallState(cwd, input, deps) {
     const existing = await readMcpInstallState(cwd, deps);
     const priorUnitPaths = existing.status === "valid" ? existing.state.executorServiceUnitPaths : [];
+    const priorCapabilities = existing.status === "valid" ? (existing.state.capabilities ?? []) : [];
     const state = {
         version: MCP_INSTALL_STATE_VERSION,
         selectedPlatforms: normalizePlatforms(input.selectedPlatforms),
@@ -241,6 +291,10 @@ export async function writeMcpInstallState(cwd, input, deps) {
             ...priorUnitPaths,
             ...(input.executorServiceUnitPaths ?? []),
         ]),
+        // Preserved for the same reason as the unit locators above: a whole-document
+        // rewrite by a caller that knows nothing about capabilities must not erase
+        // them (BAPI-775).
+        capabilities: normalizeCapabilities(priorCapabilities),
     };
     const finalPath = installStatePath(cwd);
     return persistMcpInstallState(cwd, state, finalPath, deps);
@@ -298,6 +352,7 @@ export async function recordInstalledProjectArtifact(cwd, relPath, deps) {
         // executor units a previous conductor run recorded (the same additive rule
         // that motivated this helper for the platform roster).
         executorServiceUnitPaths: normalizeExecutorServiceUnitPaths(priorUnitPaths),
+        capabilities: normalizeCapabilities(existing.status === "valid" ? (existing.state.capabilities ?? []) : []),
     };
     return persistMcpInstallState(cwd, state, installStatePath(cwd), deps);
 }
@@ -332,6 +387,44 @@ export async function recordInstalledExecutorServiceUnit(cwd, unitPath, homeDir,
         selectedPlatforms: normalizePlatforms(priorPlatforms),
         projectConfigPaths: normalizeProjectPaths(priorPaths),
         executorServiceUnitPaths: normalizeExecutorServiceUnitPaths([...priorUnitPaths, locator]),
+        capabilities: normalizeCapabilities(existing.status === "valid" ? (existing.state.capabilities ?? []) : []),
+    };
+    return persistMcpInstallState(cwd, state, installStatePath(cwd), deps);
+}
+/**
+ * Record a provisioned conductor capability WITHOUT clobbering existing state
+ * (BAPI-775).
+ *
+ * The third member of the additive-recorder family, and it follows the same rule
+ * the other two do: read the current document, write back the union of every
+ * dimension. Recording tool visibility must not drop the workflow artifact path,
+ * the platform roster, or an executor unit a previous run recorded.
+ *
+ * The capability id is validated against the closed
+ * {@link MCP_INSTALL_CAPABILITY_IDS} vocabulary BEFORE any read or write, so an
+ * unrecognized identifier is refused with an advisory result and touches
+ * nothing — never silently dropped after a rewrite. Repeating a capability is a
+ * set-style no-op, so re-running `install conductor` cannot duplicate an entry.
+ */
+export async function recordInstalledConductorCapability(cwd, capability, deps) {
+    if (!isMcpInstallCapabilityId(capability)) {
+        return {
+            ok: false,
+            error: "unknown conductor capability identifier; nothing was recorded " +
+                `(expected one of: ${MCP_INSTALL_CAPABILITY_IDS.join(", ")}).`,
+        };
+    }
+    const existing = await readMcpInstallState(cwd, deps);
+    const priorPlatforms = existing.status === "valid" ? existing.state.selectedPlatforms : [];
+    const priorPaths = existing.status === "valid" ? existing.state.projectConfigPaths : [];
+    const priorUnitPaths = existing.status === "valid" ? existing.state.executorServiceUnitPaths : [];
+    const priorCapabilities = existing.status === "valid" ? (existing.state.capabilities ?? []) : [];
+    const state = {
+        version: MCP_INSTALL_STATE_VERSION,
+        selectedPlatforms: normalizePlatforms(priorPlatforms),
+        projectConfigPaths: normalizeProjectPaths(priorPaths),
+        executorServiceUnitPaths: normalizeExecutorServiceUnitPaths(priorUnitPaths),
+        capabilities: normalizeCapabilities([...priorCapabilities, capability]),
     };
     return persistMcpInstallState(cwd, state, installStatePath(cwd), deps);
 }

package/build/mcp-invoke.js

@@ -26,6 +26,7 @@ import os from "os";
 import { resolveRepoNameForProjectRoot, readBridgeConfig, validateMcpTarget, } from "./bridge-config.js";
 import { resolveBapiCredentials } from "./credential-store.js";
 import { describeBaseUrlRejection, validateHttpBaseUrl } from "./base-url.js";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 import { getThirdPartyTargetDefinition, resolveThirdPartyTargetEnv, validateThirdPartyTargetManifestEntry, } from "./third-party-mcp-targets.js";
 // ---------------------------------------------------------------------------
 // Usage / argument parsing
@@ -36,7 +37,7 @@ export function getMcpInvokeUsage() {
         "  node <abs>/mcp_server/build/index.js mcp-invoke --target <target> --project-root <ABS_WORKTREE_PATH>",
         "",
         "  (npm-channel fallback may invoke the same shim through a package spec, e.g.",
-        "   npx -y @bridge_gpt/mcp-server@latest mcp-invoke --target <target> --project-root <ABS_WORKTREE_PATH>)",
+        `   npx -y ${MCP_PACKAGE_NAME}@latest 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.",

package/build/mcp-provisioning.js

@@ -24,6 +24,8 @@ import path from "path";
 import { readBridgeConfig } from "./bridge-config.js";
 import { getThirdPartyTargetDefinition, validateThirdPartyTargetManifestEntry, } from "./third-party-mcp-targets.js";
 import { buildMcpShimCommand, } from "./mcp-server-invocation.js";
+import { getWorktreeHostTargets, hostAdapterForTarget } from "./mcp-host-targets.js";
+import { existingRegistrationKey, MCP_SERVER_NAME } from "./mcp-identity.js";
 // ---------------------------------------------------------------------------
 // Pure helpers
 // ---------------------------------------------------------------------------
@@ -53,9 +55,9 @@ export function normalizeWorktreePathForRegistration(worktreePath, deps) {
     }
     return { ok: true, path: resolved };
 }
-/** Map an MCP target to its registration server name (`bapi` -> `bridge-api`). */
+/** Map an MCP target to its registration server name (`bapi` -> the canonical Bridge key). */
 export function serverNameForMcpTarget(target) {
-    return target === "bapi" ? "bridge-api" : target;
+    return target === "bapi" ? MCP_SERVER_NAME : target;
 }
 /**
  * Build a secret-free shim entry for any target from a structured invocation.
@@ -136,10 +138,10 @@ export function buildMcpServerEntriesForManifest(manifest, absoluteWorktreePath,
 /** 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" },
-    ];
+    return getWorktreeHostTargets().map((target) => ({
+        filePath: api.join(worktreePath, target.relPath),
+        topLevelKey: hostAdapterForTarget(target).topLevelKey,
+    }));
 }
 /**
  * Absolute path to the worktree's Claude local settings file
@@ -183,8 +185,18 @@ export function mergeEnabledMcpjsonServers(existing, serverNames) {
  *
  * Deliberately UNCHANGED by BAPI-727: because a generated name is replaced rather
  * than merged field-by-field, re-provisioning an existing worktree automatically
- * upgrades an older `bridge-api` entry that lacks `--base-url` to the URL-bearing
+ * upgrades an older Bridge entry that lacks `--base-url` to the URL-bearing
  * one. No migration step is needed.
+ *
+ * BAPI-807 keeps that force-upgrade working across the registration rename. The
+ * Bridge entry is written under the key that ALREADY exists in the document
+ * (`bridge` or the permanently-supported `bridge-api`), not blindly under the
+ * generated canonical name. Writing the canonical name unconditionally would
+ * leave a pre-rename `bridge-api` entry sitting untouched beside the new one —
+ * and because a legacy entry can carry an embedded `BAPI_API_KEY`, that stale
+ * entry would preserve a secret this function exists to strip. Tier-2 targets
+ * (`sfcc`, …) are unaffected: they are not Bridge's own registration and are
+ * always written under their own name.
  */
 export function mergeMcpRegistrations(existing, topLevelKey, entries) {
     const result = existing && typeof existing === "object" && !Array.isArray(existing)
@@ -194,18 +206,39 @@ export function mergeMcpRegistrations(existing, topLevelKey, entries) {
     const servers = current && typeof current === "object" && !Array.isArray(current)
         ? { ...current }
         : {};
+    // Resolve ONCE against the pre-merge document, so a legacy entry is replaced
+    // in place rather than duplicated.
+    const bridgeKey = existingRegistrationKey(servers);
     for (const [name, entry] of Object.entries(entries)) {
-        servers[name] = entry;
+        const writeKey = name === MCP_SERVER_NAME && bridgeKey !== null && bridgeKey !== MCP_SERVER_NAME
+            ? bridgeKey
+            : name;
+        servers[writeKey] = entry;
     }
     result[topLevelKey] = servers;
     return result;
 }
 /**
- * Back-compat single-entry merge. Sets only `mcpServers["bridge-api"]`; unrelated
- * top-level fields and servers are preserved.
+ * Back-compat single-entry merge for the Bridge shim. Unrelated top-level fields
+ * and servers are preserved.
+ *
+ * BAPI-807: the write key is RESOLVED from the existing document rather than
+ * assumed canonical. A worktree whose registration was provisioned before the
+ * rename keeps its `bridge-api` key — reprovisioning updates that entry in place
+ * instead of adding a second `bridge` one beside it, which would leave the
+ * worktree with two shims pointing at the same server. A fresh worktree, and any
+ * document with no recognized key, gets {@link MCP_SERVER_NAME}.
+ *
+ * A both-key document resolves to the canonical key here rather than refusing:
+ * this path only ever REPLACES one generated shim entry, both entries are
+ * Bridge's own generated shims, and the worktree registration doctor
+ * (`probeWorktreeMcpRegistration`) is the surface that reports the duplicate.
+ * Refusing here would leave a worktree unable to reprovision at all.
  */
 export function mergeBridgeApiMcpRegistration(existing, topLevelKey, entry) {
-    return mergeMcpRegistrations(existing, topLevelKey, { "bridge-api": entry });
+    // `mergeMcpRegistrations` now resolves the Bridge key itself, so passing the
+    // canonical name is sufficient — and keeps ONE place that decides the key.
+    return mergeMcpRegistrations(existing, topLevelKey, { [MCP_SERVER_NAME]: entry });
 }
 // ---------------------------------------------------------------------------
 // Filesystem writes
@@ -310,7 +343,7 @@ function withWarnings(row, warnings) {
  * FAIL-OPEN, and BAPI-790 makes that posture worth stating explicitly, because a
  * fail-CLOSED requirement now sits directly downstream of it. This function
  * ATTEMPTS the write and degrades to warnings; the executor then separately
- * VERIFIES that a usable `.mcp.json` exists and registers `bridge-api`, and
+ * VERIFIES that a usable `.mcp.json` exists and registers a recognized Bridge key, and
  * refuses to spawn when it does not (`verifyRequiredWorktreeMcpRegistration` in
  * `executor/job-runner.ts`). The split is deliberate: a provisioning hiccup on a
  * Tier-2 target must not kill a job, but a worker that loads MCP servers strictly

package/build/mcp-registration-doctor.js

@@ -7,6 +7,9 @@
  * the sole injected dependency is `readFile`.
  */
 import path from "path";
+import { getWorktreeHostTargets, hostAdapterForTarget } from "./mcp-host-targets.js";
+import { MCP_SERVER_NAME, MCP_PACKAGE_NAME, resolveRegistrationKey, } from "./mcp-identity.js";
+import { DUPLICATE_REGISTRATION_GUIDANCE } from "./launcher-config-inspection.js";
 /**
  * Read and parse a JSON file.
  *
@@ -72,7 +75,7 @@ export function isBridgeApiShimEntry(entry, worktreeRoot) {
     const args = candidate.args.filter((a) => typeof a === "string");
     if (candidate.command === "npx") {
         // npm-channel fallback: must reference the package spec.
-        if (!args.some((a) => a.startsWith("@bridge_gpt/mcp-server")))
+        if (!args.some((a) => a.startsWith(MCP_PACKAGE_NAME)))
             return false;
     }
     else {
@@ -90,36 +93,55 @@ export function isBridgeApiShimEntry(entry, worktreeRoot) {
 }
 /**
  * Inspect both `<worktreeRoot>/.mcp.json` and `<worktreeRoot>/.cursor/mcp.json`.
- * Reports `found` when at least one registration file contains a valid
- * `bridge-api` shim entry pointing at this worktree; otherwise `found: false`
- * with an actionable, secret-free hint. Never spawns anything.
+ * Reports `found` when at least one registration file contains a valid Bridge
+ * shim entry — under EITHER the canonical or a permanently supported legacy key
+ * (BAPI-807) — pointing at this worktree; otherwise `found: false` with an
+ * actionable, secret-free hint. Never spawns anything.
+ *
+ * A file carrying BOTH recognized keys is a FAULT, not a healthy registration:
+ * which shim the agent actually loads is undefined, so it is reported with
+ * repair guidance rather than silently accepted because one of the two happened
+ * to validate.
  */
 export async function probeWorktreeMcpRegistration(worktreeRoot, deps) {
-    const targets = [
-        path.join(worktreeRoot, ".mcp.json"),
-        path.join(worktreeRoot, ".cursor", "mcp.json"),
-    ];
-    for (const filePath of targets) {
+    const targets = getWorktreeHostTargets().map((target) => ({
+        filePath: path.join(worktreeRoot, target.relPath),
+        topLevelKey: hostAdapterForTarget(target).topLevelKey,
+    }));
+    for (const { filePath, topLevelKey } of targets) {
         const read = await readJsonIfPresent(filePath, deps);
         if (read.state !== "present")
             continue;
         const doc = read.value;
         if (!doc || typeof doc !== "object" || Array.isArray(doc))
             continue;
-        const servers = doc.mcpServers;
+        const servers = doc[topLevelKey];
         if (!servers || typeof servers !== "object" || Array.isArray(servers))
             continue;
-        const entry = servers["bridge-api"];
+        const displayPath = path.basename(path.dirname(filePath)) === ".cursor" ? ".cursor/mcp.json" : ".mcp.json";
+        const resolution = resolveRegistrationKey(servers);
+        if (resolution.state === "conflict") {
+            return {
+                found: false,
+                detail: `${displayPath}: ${DUPLICATE_REGISTRATION_GUIDANCE}`,
+            };
+        }
+        if (resolution.state === "absent")
+            continue;
+        const entry = servers[resolution.key];
         if (isBridgeApiShimEntry(entry, worktreeRoot)) {
+            // A legacy-key shim is HEALTHY. It is identified as such so an operator
+            // reading the report knows why the key differs and that nothing is wrong.
+            const legacyNote = resolution.state === "legacy" ? " (supported legacy registration)" : "";
             return {
                 found: true,
-                detail: `bridge-api shim registered in ${path.basename(path.dirname(filePath)) === ".cursor" ? ".cursor/mcp.json" : ".mcp.json"}`,
+                detail: `${resolution.key} shim registered in ${displayPath}${legacyNote}`,
             };
         }
     }
     return {
         found: false,
-        detail: "No worktree .mcp.json or .cursor/mcp.json points at the bridge-api mcp-invoke shim. " +
+        detail: `No worktree .mcp.json or .cursor/mcp.json points at the ${MCP_SERVER_NAME} mcp-invoke shim. ` +
             "Re-run start-tickets to provision the worktree MCP registration.",
     };
 }

package/build/mcp-server-invocation.js

@@ -21,13 +21,15 @@
  * re-plumbing argv construction.
  */
 import path from "node:path";
-export const MCP_SERVER_PACKAGE_NAME = "@bridge_gpt/mcp-server";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+/** Compatibility alias — `executor/service-unit.ts` still imports this name. */
+export const MCP_SERVER_PACKAGE_NAME = MCP_PACKAGE_NAME;
 /**
  * Resolvable npm-channel fallback spec. Deliberately a moving channel (`@latest`)
  * rather than an exact generated version pin, so the fallback path can never
  * reintroduce the ETARGET/404 failure the absolute-path form exists to remove.
  */
-export const DEFAULT_MCP_SERVER_NPM_CHANNEL_SPEC = "@bridge_gpt/mcp-server@latest";
+export const DEFAULT_MCP_SERVER_NPM_CHANNEL_SPEC = `${MCP_PACKAGE_NAME}@latest`;
 /**
  * Build the concrete `{ command, args }` launch pair for a target + worktree from
  * a structured invocation. Pure — no filesystem or process access. The