@bridge_gpt/mcp-server 0.2.24 → 0.2.26

package/build/tool-surface-gating.js

@@ -0,0 +1,396 @@
+/**
+ * tool-surface-gating — the fail-open MCP tool-surface capability consumer
+ * (BAPI-641).
+ *
+ * This module owns the client-side half of dynamic capability gating. The
+ * backend `GET /jira/mcp/tool-surface` route (BAPI-640) reports the set of
+ * physical tool IDs it would hard-block for a repo right now. This module:
+ *
+ *   1. probes that endpoint under one absolute 500 ms deadline (`probeToolSurface`),
+ *      always resolving to a result union — never rejecting;
+ *   2. installs a custom `tools/list` handler that delegates to the SDK's own
+ *      handler and then SUBTRACTS the capability-hidden tool names, intersected
+ *      with the locally advertised profile surface (`createToolSurfaceGate`);
+ *   3. re-probes on a jittered 12–18 s poll and emits `tools/list_changed` only
+ *      when the effective visible-name set actually changes.
+ *
+ * Design invariants:
+ *   - FAIL-OPEN. A timeout, unreachable backend, non-2xx, malformed payload,
+ *     `complete: false`, or unsupported schema all advertise the FULL profile
+ *     surface (empty hidden set). The backend, not this module, is the
+ *     authoritative enforcement boundary.
+ *   - NEVER `.disable()`. Capability gating only subtracts from `tools/list`
+ *     projection. It must NEVER call `.disable()` or mutate the SDK `enabled`
+ *     flag, because doing so would ALSO block `tools/call` and the in-process
+ *     `TOOL_HANDLERS` dispatch — preventing a stale client call from reaching
+ *     the authoritative backend refusal.
+ *   - SECRET-SAFE. Logs and result unions carry only stable reason/subtype
+ *     vocabulary, secret-free tool IDs, counts, and catalog revisions — never
+ *     URLs, headers, response bodies, credentials, or raw exceptions.
+ */
+import { getMethodLiteral } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
+// ---------------------------------------------------------------------------
+// Protocol + timing constants
+// ---------------------------------------------------------------------------
+/** The `/mcp/tool-surface` surface-contract versions this consumer recognizes. */
+export const RECOGNIZED_TOOL_SURFACE_SCHEMA_VERSIONS = new Set([1]);
+/** The single recognized schema version (convenience export for tests). */
+export const TOOL_SURFACE_SCHEMA_VERSION = 1;
+/** Absolute end-to-end deadline for one probe (header resolve + fetch + parse). */
+export const TOOL_SURFACE_PROBE_DEADLINE_MS = 500;
+/** Inclusive lower bound of the recurring-poll jitter window. */
+export const TOOL_SURFACE_POLL_MIN_MS = 12_000;
+/** Inclusive upper bound of the recurring-poll jitter window. */
+export const TOOL_SURFACE_POLL_MAX_MS = 18_000;
+function timeoutResult() {
+    return { reason: "timeout", blockedTools: new Set() };
+}
+function malformedResult(subtype) {
+    return { reason: "malformed", subtype, blockedTools: new Set() };
+}
+/**
+ * Validate a parsed JSON body against the exact backend contract. Returns a
+ * `blocked` decision for a valid, complete, recognized response (including one
+ * with zero blocked tools) or a fail-open `malformed` decision with a sanitized
+ * subtype. An unfamiliar `catalog_revision` is INFORMATIONAL and never a
+ * fail-open trigger.
+ */
+export function validateToolSurfacePayload(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return malformedResult("invalid-shape");
+    }
+    const p = body;
+    if (typeof p.schema_version !== "number" ||
+        !Number.isInteger(p.schema_version)) {
+        return malformedResult("invalid-shape");
+    }
+    if (!RECOGNIZED_TOOL_SURFACE_SCHEMA_VERSIONS.has(p.schema_version)) {
+        return malformedResult("unsupported-schema");
+    }
+    if (typeof p.complete !== "boolean") {
+        return malformedResult("invalid-shape");
+    }
+    if (typeof p.evaluated_tool_count !== "number" ||
+        !Number.isInteger(p.evaluated_tool_count) ||
+        p.evaluated_tool_count < 0) {
+        return malformedResult("invalid-shape");
+    }
+    if (typeof p.catalog_revision !== "string") {
+        return malformedResult("invalid-shape");
+    }
+    if (!Array.isArray(p.blocked_tools) ||
+        !p.blocked_tools.every((t) => typeof t === "string")) {
+        return malformedResult("invalid-shape");
+    }
+    if (!p.complete) {
+        return malformedResult("incomplete");
+    }
+    // A complete response MUST carry a non-empty catalog revision.
+    if (p.catalog_revision.length === 0) {
+        return malformedResult("invalid-shape");
+    }
+    // Insertion-preserving set; duplicates collapse harmlessly. Unknown physical
+    // IDs remain valid at the probe boundary — the later projection intersects
+    // them with the locally advertised surface.
+    const blockedTools = new Set(p.blocked_tools);
+    return {
+        reason: "blocked",
+        catalogRevision: p.catalog_revision,
+        evaluatedToolCount: p.evaluated_tool_count,
+        blockedTools,
+    };
+}
+/**
+ * Issue ONE authenticated GET to the tool-surface endpoint and classify the
+ * result under a single absolute deadline that covers async header resolution,
+ * the fetch, response-body consumption, JSON parsing, and validation.
+ *
+ * This function NEVER rejects: every failure — timeout, lifecycle abort, network
+ * error, non-2xx, invalid JSON, invalid shape, incomplete evaluation, or
+ * unsupported schema — resolves to a fail-open result union. That contract lets
+ * the non-awaited startup probe run without risking an unhandled rejection.
+ */
+export async function probeToolSurface(options) {
+    const deadlineMs = options.deadlineMs ?? TOOL_SURFACE_PROBE_DEADLINE_MS;
+    // Combined abort controller: the deadline timer OR the lifecycle signal aborts
+    // an in-flight fetch. Composing manually (rather than AbortSignal.any) keeps
+    // the runtime floor low and the abort wiring explicit.
+    const controller = new AbortController();
+    const onLifecycleAbort = () => controller.abort();
+    if (options.abortSignal) {
+        if (options.abortSignal.aborted)
+            controller.abort();
+        else
+            options.abortSignal.addEventListener("abort", onLifecycleAbort, {
+                once: true,
+            });
+    }
+    let timer;
+    const deadlinePromise = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            resolve(timeoutResult());
+        }, deadlineMs);
+    });
+    // Resolve promptly to timeout on any abort, regardless of which async phase is
+    // pending (header resolution can never begin a fetch, so it needs this too).
+    const abortPromise = new Promise((resolve) => {
+        if (controller.signal.aborted) {
+            resolve(timeoutResult());
+            return;
+        }
+        controller.signal.addEventListener("abort", () => resolve(timeoutResult()), {
+            once: true,
+        });
+    });
+    const workPromise = (async () => {
+        try {
+            const headers = await options.resolveHeaders();
+            if (controller.signal.aborted)
+                return timeoutResult();
+            const resp = await options.fetchFn(options.url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
+            if (!resp.ok)
+                return malformedResult("non-2xx");
+            let parsed;
+            try {
+                parsed = await resp.json();
+            }
+            catch {
+                if (controller.signal.aborted)
+                    return timeoutResult();
+                return malformedResult("invalid-json");
+            }
+            return validateToolSurfacePayload(parsed);
+        }
+        catch {
+            // Abort (deadline or lifecycle) surfaces here as a rejected fetch. Any
+            // other rejection is a network-class failure. Raw exception text is never
+            // propagated into the result.
+            if (controller.signal.aborted)
+                return timeoutResult();
+            return malformedResult("network");
+        }
+    })();
+    try {
+        return await Promise.race([workPromise, deadlinePromise, abortPromise]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (options.abortSignal) {
+            options.abortSignal.removeEventListener("abort", onLifecycleAbort);
+        }
+    }
+}
+const defaultScheduler = {
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+    random: () => Math.random(),
+};
+/** Log a gating decision with secret-free fields only. */
+function logDecision(logger, result, hiddenCount, hiddenNames) {
+    const revision = result.reason === "blocked" ? result.catalogRevision : "n/a";
+    const subtype = result.reason === "malformed" ? result.subtype : "n/a";
+    logger(`tool-surface gating: reason=${result.reason} subtype=${subtype} ` +
+        `hidden=${hiddenCount} revision=${revision} ` +
+        `hidden_tools=[${hiddenNames.join(", ")}]`);
+}
+/**
+ * Build the capability gate. The gate wraps the SDK `tools/list` handler so the
+ * FIRST list awaits the stored startup probe, atomically applies the resulting
+ * hidden-set snapshot, delegates to the SDK handler, and filters ONLY the
+ * capability-hidden names out of the returned tools (preserving every SDK tool
+ * definition object, its order, and all non-`tools` response properties).
+ */
+export function createToolSurfaceGate(options) {
+    const { startupProbe, advertised, originalListHandler, freshProbe, notify, logger, lifecycleController, } = options;
+    const scheduler = options.scheduler ?? defaultScheduler;
+    const advertisedNames = new Set(advertised.map((r) => r.name));
+    // Immutable-replacement state. `hiddenNames` is always swapped as a whole
+    // snapshot so a list request or poll completion never observes a partial set.
+    let hiddenNames = new Set();
+    // The last visible-name set actually served to a client, or null before the
+    // first list. Notifications are suppressed until a client has been served.
+    let lastServedVisible = null;
+    let catalogRevision = null;
+    let startupApplied = false;
+    let timer;
+    let closed = false;
+    /** Derive the effective hidden set: backend IDs ∩ advertised names. */
+    function deriveHidden(result) {
+        if (result.reason !== "blocked" || result.blockedTools.size === 0) {
+            return new Set();
+        }
+        const hidden = new Set();
+        for (const id of result.blockedTools) {
+            if (advertisedNames.has(id))
+                hidden.add(id);
+        }
+        return hidden;
+    }
+    /**
+     * Derive the visible-name set: advertised registrations that are BOTH
+     * currently SDK-enabled AND not capability-hidden. This intersects profile
+     * registration (advertised), current enabled state, and capability hiding.
+     */
+    function deriveVisible(hidden) {
+        const visible = new Set();
+        for (const reg of advertised) {
+            if (!reg.isEnabled())
+                continue;
+            if (hidden.has(reg.name))
+                continue;
+            visible.add(reg.name);
+        }
+        return visible;
+    }
+    /**
+     * Apply a probe decision as an immutable snapshot: swap `hiddenNames`, log,
+     * and track catalog-revision transitions. Does NOT notify — callers decide.
+     */
+    function applyDecision(result) {
+        const nextHidden = deriveHidden(result);
+        hiddenNames = nextHidden;
+        logDecision(logger, result, nextHidden.size, Array.from(nextHidden));
+        if (result.reason === "blocked" && result.catalogRevision !== catalogRevision) {
+            if (catalogRevision !== null) {
+                logger(`tool-surface gating: catalog_revision ${catalogRevision} -> ${result.catalogRevision}`);
+            }
+            catalogRevision = result.catalogRevision;
+        }
+    }
+    /** Project the SDK list result, subtracting only capability-hidden names. */
+    function projectList(original) {
+        const tools = original.tools.filter((tool) => !hiddenNames.has(tool.name));
+        return { ...original, tools };
+    }
+    const handleList = async (request, extra) => {
+        // First list awaits the SAME stored startup promise, then applies its
+        // snapshot exactly once (concurrent first calls both await; only the first
+        // to run after resolution applies — JS runs applyDecision without preemption).
+        const startupResult = await startupProbe;
+        if (!startupApplied) {
+            startupApplied = true;
+            applyDecision(startupResult);
+        }
+        const original = await originalListHandler(request, extra);
+        const projected = projectList(original);
+        // Record the first served visible-name baseline (from what we actually
+        // serve). Subsequent lists refresh it so poll-driven notifications compare
+        // against the latest served surface.
+        lastServedVisible = new Set(projected.tools.map((t) => t.name));
+        return projected;
+    };
+    /** One poll cycle: fresh probe, apply, notify only on a real visible change. */
+    async function pollOnce() {
+        let result;
+        try {
+            result = await freshProbe();
+        }
+        catch {
+            // freshProbe is contracted never to reject, but stay fail-open regardless.
+            result = timeoutResult();
+        }
+        if (closed)
+            return;
+        const previousVisibleServed = lastServedVisible;
+        applyDecision(result);
+        const nextVisible = deriveVisible(hiddenNames);
+        // Suppress notifications before any client has received its first list.
+        if (previousVisibleServed === null)
+            return;
+        if (!setsEqual(previousVisibleServed, nextVisible)) {
+            // The served surface changes; update the baseline BEFORE notifying so a
+            // notification-driven re-list compares against the new baseline.
+            lastServedVisible = nextVisible;
+            try {
+                notify();
+            }
+            catch {
+                // A notification failure must not revert state or stop future polls.
+                logger("tool-surface gating: notification failed (suppressed)");
+            }
+        }
+    }
+    /** Schedule the next poll after the previous one settles (recursive setTimeout). */
+    function scheduleNext() {
+        if (closed)
+            return;
+        const span = TOOL_SURFACE_POLL_MAX_MS - TOOL_SURFACE_POLL_MIN_MS;
+        const delay = Math.round(TOOL_SURFACE_POLL_MIN_MS + scheduler.random() * span);
+        timer = scheduler.setTimeout(() => {
+            // Run one probe to completion, THEN schedule the next — never overlapping.
+            void pollOnce().finally(() => {
+                scheduleNext();
+            });
+        }, delay);
+        // Do not let the poll timer keep the process alive.
+        if (timer && typeof timer.unref === "function")
+            timer.unref();
+    }
+    function startPolling() {
+        if (closed)
+            return;
+        scheduleNext();
+    }
+    function close() {
+        if (closed)
+            return;
+        closed = true;
+        if (timer) {
+            scheduler.clearTimeout(timer);
+            timer = undefined;
+        }
+        if (!lifecycleController.signal.aborted)
+            lifecycleController.abort();
+    }
+    return { handleList, startPolling, close };
+}
+/** Value-equality for two string sets. */
+function setsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const v of a) {
+        if (!b.has(v))
+            return false;
+    }
+    return true;
+}
+/** Fixed, sanitized boot error (never includes map contents or config). */
+const COMPAT_ERROR = "tool-surface gating: incompatible MCP SDK — the tools/list handler could not be resolved for override.";
+/**
+ * Install the custom `tools/list` handler over the SDK's, returning the captured
+ * original handler for delegation. Resolves the method literal from the schema
+ * and asserts it is exactly `tools/list`; asserts a present, callable existing
+ * handler; then overwrites via `setRequestHandler`. Throws the fixed sanitized
+ * boot error (no private map contents, config, or credentials) on any mismatch.
+ */
+export function installToolSurfaceListOverride(protocolServer, listSchema, customHandler) {
+    let method;
+    try {
+        method = getMethodLiteral(listSchema);
+    }
+    catch {
+        throw new Error(COMPAT_ERROR);
+    }
+    if (method !== "tools/list") {
+        throw new Error(COMPAT_ERROR);
+    }
+    const handlers = protocolServer?._requestHandlers;
+    if (!handlers || typeof handlers.get !== "function") {
+        throw new Error(COMPAT_ERROR);
+    }
+    const original = handlers.get(method);
+    if (typeof original !== "function") {
+        throw new Error(COMPAT_ERROR);
+    }
+    // Overwrite in place. We deliberately do NOT rely on removeRequestHandler's
+    // return value and do not remove the handler first — setRequestHandler
+    // replaces the existing entry.
+    protocolServer.setRequestHandler(listSchema, customHandler);
+    return original;
+}

package/build/version.generated.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.2.24";
+export const VERSION = "0.2.26";

package/docs/install/github-app.md

@@ -35,14 +35,63 @@ long-lived GitHub token.
 
 ---
 
-## Option A — Connect GitHub button (recommended)
+## Option A — `connect-github` from your terminal (recommended)
 
-This is the normal path. Bridge captures the installation automatically — you never copy
-an ID by hand.
+If you already have a Bridge API key configured (you ran `install-bridge`), you can
+connect GitHub without opening the Bridge web UI at all:
 
-1. Open your project's **Get Started** page in the Bridge web UI.
-2. Click **Connect GitHub**. Bridge mints a short-lived, single-use link scoped to your
-   project and sends you to GitHub's app-install screen.
+```bash
+npx -y @bridge_gpt/mcp-server@latest connect-github --repo <repo_name>
+```
+
+Omit `--repo` and the command infers the project from the current directory, asking you
+to confirm.
+
+What happens:
+
+1. The command opens the GitHub App install screen in your browser.
+2. On GitHub, choose the **account or organization** that owns the repository, pick the
+   repositories under **Repository access** (see [Choosing
+   repositories](#choosing-repositories)), and click **Install**.
+3. GitHub returns to a page that just says *"GitHub connection received — return to your
+   terminal."* That page is intentionally blank of detail; your terminal is where the
+   flow continues.
+4. Back in the terminal, the command shows the repositories your installation covers and
+   asks which one to connect. **Every connection is confirmed by hand** — even when the
+   installation contains exactly one repository. There is no `--yes` flag.
+5. Choose one, and it prints the connected `owner/repo`.
+
+**You are never asked for a GitHub token, password, or installation ID.** You
+authenticate to GitHub in your own browser; the terminal only ever carries a short-lived
+Bridge-issued handle. Bridge never sees a GitHub credential.
+
+**If you decline at the confirmation prompt**, nothing is connected and nothing is
+changed — re-run the command whenever you like.
+
+**If it times out or fails**, no connection is made. Re-run the command; the request
+expires after about 15 minutes, so a stale attempt is never left half-applied.
+
+### Organization approval
+
+If an organization owns the repository and you are not an owner, GitHub sends an
+**approval request** to an owner instead of installing the app. That approval happens
+entirely on GitHub's side and **does not return to your terminal**, so `connect-github`
+cannot wait for it — the original request expires. This is a real limitation, not a bug.
+
+Once an owner has approved the install, finish the connection with
+[Option C](#option-c--manual-install--installation-id-fallback) below.
+
+---
+
+## Option B — Connect GitHub button (web UI)
+
+Bridge captures the installation automatically — you never copy an ID by hand.
+
+1. Open your project's **Get Started** page in the Bridge web UI. The page opens directly
+   on the GitHub connection task — connecting your repository is what the page is for.
+2. In the **1. Connect GitHub** panel, click **Connect GitHub**. Bridge mints a
+   short-lived, single-use link scoped to your project and sends you to GitHub's
+   app-install screen.
 3. On GitHub, choose the **account or organization** that owns the repository.
 4. Under **Repository access**, choose **Only select repositories** and pick the repo(s)
    you want Bridge to cover (or **All repositories**). See
@@ -54,16 +103,26 @@ an ID by hand.
    installation covers exactly one repo — or one repo clearly matches your project —
    Bridge binds it for you; otherwise it shows a short **repository picker** so you can
    confirm which repo maps to this project.
+7. The outcome appears in the **1. Connect GitHub** panel itself — you should see
+   **GitHub connected** naming the repository Bridge linked.
 
 That's it — no manual ID entry. If the automatic link fails for any reason, Bridge tells
-you and points you to Option B.
+you in that same panel and points you to Option C.
+
+Connecting an editor over MCP is **optional** and is not a prerequisite for any of the
+above. If you need it, the Get Started page keeps that setup in a collapsed
+**"Need to connect an editor to the MCP?"** drawer below the GitHub panel — open it only
+if you want it.
 
 ---
 
-## Option B — Manual install + Installation ID (fallback)
+## Option C — Manual install + Installation ID (fallback)
 
-Use this if the Connect GitHub button isn't available to you, or automatic linking
-failed.
+This is the **advanced fallback**, not the normal path — use it only if neither the
+`connect-github` command (Option A) nor the one-click **Connect GitHub** button (Option B)
+is available to you (for example an org admin-approval or GitHub Marketplace install), or
+if automatic linking failed. Get Started links to it from the manual-fallback note under
+the GitHub panel.
 
 ### 1. Install the app
 
@@ -72,7 +131,7 @@ selecting the repository/repositories you want Bridge to access:
 
 <https://github.com/apps/bridge-gpt-ai-tools-for-sfcc/installations/new>
 
-(Same repository-selection and permissions-review screen as Option A, steps 3–5.)
+(Same repository-selection and permissions-review screen as Option B, steps 3–5.)
 
 ### 2. Find the Installation ID
 
@@ -99,7 +158,7 @@ settings.
 
 ## Choosing repositories
 
-When installing (either option), GitHub asks which repositories the app may access:
+When installing (any option), GitHub asks which repositories the app may access:
 
 - **All repositories** — the app can access every current and future repo on the account.
 - **Only select repositories** — pick specific repos from the **Select repositories**
@@ -139,7 +198,7 @@ After linking, confirm Bridge can act on the repo:
   a VCS connection.)
 
 If a GitHub-dependent tool refuses, the installation isn't linked to that project yet —
-re-run Option A, or set the Installation ID via Option B.
+re-run Option A, or set the Installation ID via Option C.
 
 ## Managing or removing the app
 
@@ -174,10 +233,14 @@ installation. Webhook endpoints used by the integration include the code-review
 (e.g. `https://<deployment-host>/github/code-review`); configure these on the app to match
 your deployment host.
 
-> **Note:** an older placeholder app slug (`bridge-gpt-code-reviewer`) still appears as a
-> stale default string in the codebase. The runtime install URL and App ID always come
-> from `GITHUB_APP_INSTALL_URL` / `GIT_APP_ID`, so set those to the `954077` /
-> `bridge-gpt-ai-tools-for-sfcc` values above rather than relying on the code default.
+> **Note:** the install URL is published from two independent places, and only one reads
+> the environment. `GITHUB_APP_INSTALL_URL` drives the get-started **Connect GitHub**
+> button. The setup *instructions* — the install-instructions API, the capability report's
+> `configure_in`, and the generated README region — come from the `GITHUB_APP_INSTALL_URL`
+> constant in `api/library/config/integration_instructions.py`, which is **not**
+> env-overridable. Setting the env var alone will not correct the instructions. Keep the
+> two in sync; after editing the constant, regenerate the README with
+> `python scripts/sync_integration_readme.py`.
 
 ## See also
 

package/docs/install/mcp-tool-integrations.md

@@ -163,7 +163,7 @@ by tier.
 | `generate_image` | — none beyond an image provider |
 | `visual_diff` | — none (`LOCAL` render + pixel diff; needs a reachable `target_url`) |
 | `request_deep_research` / `get_deep_research` | Deep-research flag **[BLOCK]** (403 if `deep_research_enabled` off) |
-| `request_brainstorm` / `get_brainstorm` | Code index **[BLOCK] for `technical`/`discovery` modes**; **— none for `design` mode** |
+| `request_council` / `get_council` | Code index **[BLOCK] for `technical`/`discovery` modes**; **— none for `design` mode** |
 
 ### VCS & CI
 
@@ -279,7 +279,7 @@ sandbox-only and destructive.
 | **Ticket backend** (jira mode) | `create_ticket`, `get_ticket(s)`, `update_ticket_description`, `update_jira_status`, `get_jira_transitions`, and every AI generator (they read the ticket) | — |
 | **Jira (only)** | `get_comments`, `add_comment`, `attachment`, `estimate_epic` | — |
 | **Version control (VCS)** | `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, `materialize_fresh_base`, `parse_repository`, `regenerate_directory_map`, `wait_for_done_gate`; **Tier-3** `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `request_reimplement_context`/`get_reimplement_context`, `create_doc`(tdd/architecture) | **Tier-4** `request_clarifying_questions`, `request_ticket_critique`, `request_ticket_review`, `request_prd`, `create_doc`(prd/fsd) |
-| **Code index** (succeeded parse) | Tier-3 plan/architecture/reimplement/`create_doc`(tdd/architecture); `request_brainstorm` in `technical`/`discovery` modes | Tier-4 clarifying-questions/critique/review/prd/fsd |
+| **Code index** (succeeded parse) | Tier-3 plan/architecture/reimplement/`create_doc`(tdd/architecture); `request_council` in `technical`/`discovery` modes | Tier-4 clarifying-questions/critique/review/prd/fsd |
 | **SFCC OCAPI** | `check_permissions` + all 16 SFCC read/write tools | — |
 | **SFCC WebDAV logs** | `sfcc_log_query` | — |
 | **Deep-research flag** | `request_deep_research`, `get_deep_research` | — |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge_gpt/mcp-server",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "description": "Bridge API MCP server — exposes Jira endpoints as MCP tools for Claude Code agents",
   "license": "MIT",
   "type": "module",
@@ -27,14 +27,14 @@
     "check:version-generated": "node scripts/bundle-version.js && node scripts/check-version-generated.js",
     "postbuild": "node scripts/prepend-shebang.cjs",
     "start": "node build/index.js",
-    "test": "node --test --test-force-exit build/pipeline-utils.test.js build/backend-warnings.test.js build/update-check.test.js build/cli-upgrade.test.js build/decision-page-schema.test.js build/decision-page-template.test.js build/bundle-pipelines.test.js build/instructions-contract.test.js build/pipeline-orchestrator-persistence.test.js build/pipeline-orchestrator-execution.test.js build/pipeline-orchestrator-integration.test.js build/index-static.test.js build/config-fields.static.test.js build/execute-plan-instructions.static.test.js build/index-resolvers.test.js build/index-project-root.test.js build/index-pipelines.test.js build/index.test.js build/bridge-config.test.js build/credential-store.test.js build/agent-config-credential-migration.test.js build/mcp-invoke.test.js build/mcp-provisioning.test.js build/mcp-server-invocation.test.js build/third-party-mcp-targets.test.js build/git-ignore-utils.test.js build/credential-materialization.test.js build/mcp-registration-doctor.test.js build/secret-safety.test.js build/base-ref.test.js build/pr-base-contract.test.js build/start-tickets.test.js build/review-tickets.test.js build/start-tickets-base-branch.test.js build/agent-registry.test.js build/agent-registry.model-routing.test.js build/start-tickets.shell-model-routing.test.js build/start-tickets.bridge-api-model-routing.test.js build/start-tickets.tier-fetch-model-routing.test.js build/start-tickets.resolve-model-routing.test.js build/start-tickets.orchestrate-model-routing.test.js build/start-tickets.routing-diagnostics.test.js build/start-tickets-repo.test.js build/start-tickets-credential-invariants.static.test.js build/credentials-cli.test.js build/start-tickets-prereqs.test.js build/regression-check.test.js build/doctor.test.js build/install-doctor.test.js build/install-bridge.test.js build/install-bridge-invite.test.js build/install-bridge-prompt.test.js build/init.test.js build/resolveUploadAttachment.test.js build/package-static.test.js build/chain-utils.test.js build/chain-orchestrator.test.js build/scheduler-backends/types.test.js build/scheduler-backends/escaping.test.js build/scheduler-backends/launchd.test.js build/scheduler-backends/task-scheduler.test.js build/scheduler-backends/systemd-user.test.js build/scheduler-backends/at-fallback.test.js build/scheduler-backends/index.test.js build/command-catalog.test.js build/scheduled-prompt.test.js build/agent-launchers/claude.test.js build/agent-launchers/cursor.test.js build/agent-launchers/index.test.js build/schedule-store.test.js build/schedule-run.test.js build/setup-epic.test.js build/agent-capabilities/cli.test.js build/agent-capabilities/runner.test.js build/agent-capabilities/probes.test.js build/agent-capabilities/probe-context.test.js build/agent-capabilities/reporter.test.js build/conductor/taxonomy-and-errors.test.js build/conductor/github-mergeability.test.js build/conductor/merge-conflict-routing.test.js build/conductor/redaction-normalization.test.js build/conductor/claude-hook.test.js build/conductor/git-ci-types.test.js build/conductor/done-gate.test.js build/conductor/git-ci-taxonomy-payload.test.js build/conductor/bridge-api-client.test.js build/conductor/plan.test.js build/conductor/producer-ledger.test.js build/conductor/spec-review-producer.test.js build/conductor/git-producer.test.js build/conductor/git-hooks.test.js build/conductor/store-migration.test.js build/conductor/pr-discovery.test.js build/conductor/pr-ci-producer.test.js build/conductor/pr-review-producer.test.js build/conductor/doctor.test.js build/conductor/deny-enforcement-preflight.test.js build/conductor/errors.test.js build/conductor/store.test.js build/conductor/index-poll-ci-producer.test.js build/start-tickets-conductor.test.js build/start-tickets-conductor.spawn.test.js build/start-tickets-conductor-node-propagation.test.js build/start-tickets.non-mutating-base.test.js build/start-tickets-live-source-guard.test.js build/conductor/worker-ledger-cli.test.js build/conductor/supervisor-config.test.js build/conductor/supervisor-ledger.test.js build/conductor/supervisor-state-reducer.test.js build/conductor/supervisor-housekeeping-projection.test.js build/conductor/supervisor-escalation.test.js build/conductor/supervisor-retired-judgment.static.test.js build/conductor/supervisor-runtime.test.js build/conductor/supervisor-store-projection.test.js build/conductor/supervisor-cli.test.js build/conductor/supervisor-start-tickets.test.js build/conductor/supervisor-message-relay.test.js build/conductor/supervisor-state-message-events.test.js build/conductor/store-message-relay.test.js build/start-tickets-message-relay.test.js build/conductor/event-accessors.test.js build/conductor/merge-ledger.test.js build/conductor/deterministic-completion.static.test.js build/conductor/deterministic-completion.integration.test.js build/conductor/local-merge.test.js build/conductor/local-merge.static.test.js build/conductor/supervisor-merge.test.js build/conductor/bridge-api-merge-client.test.js build/conductor/bridge-api-epic-client.test.js build/conductor/supervisor-merge-runtime-state.test.js build/conductor/epic-state.test.js build/executor/claude-settings.test.js build/executor/cli.test.js build/executor/credentials.test.js build/executor/echo-acceptance.test.js build/executor/env.test.js build/executor/base-branch.test.js build/executor/heartbeat.test.js build/executor/http-client.test.js build/executor/job-runner.test.js build/executor/job-runner.payload-timeout.test.js build/executor/worker-finalization.test.js build/executor/job-runner.static.test.js build/executor/prompt-spec.test.js build/executor/job-types.test.js build/executor/recovery-job.static.test.js build/executor/observation.test.js build/executor/permissions.test.js build/executor/preflight.test.js build/executor/process.test.js build/executor/results.test.js build/executor/runner.test.js build/executor/terminal-mutation.test.js build/executor/worker-command.test.js build/executor/worktree-core.test.js build/executor/worktree.test.js build/executor/job-errors.test.js build/executor/worktree-inspection.test.js build/executor/resume-pre-spawn.test.js build/executor/verdict-artifact.test.js build/executor/worker-log.test.js build/executor/job-log-registry.test.js build/executor/viewer-tabs.test.js build/executor/watch-cli.test.js build/executor/merge-job.test.js build/executor/job-runner.merge.test.js build/executor/worktree-gc.test.js build/executor/runner.job-behaviors.test.js build/conductor/cli-freeze.test.js build/conductor/epic-reconcile.test.js build/conductor/epic-runtime.test.js build/conductor/epic-tick-sequence.test.js build/conductor/epic-runtime-post-action.test.js build/conductor/file-scope-guard.test.js build/conductor/file-scope-guard.integration.test.js build/mcp-profile.test.js build/mcp-profile-registration.test.js build/tools-budget.test.js build/visual-diff-worker.test.js build/visual-diff.test.js build/estimate-epic.test.js build/integration/measure-tools.test.js build/sfcc/config.test.js build/sfcc/ocapi-shape.test.js build/sfcc/output.test.js build/sfcc/credentials.test.js build/sfcc/ocapi-write-faults.test.js build/sfcc/write-guard.test.js build/sfcc/write-grants.test.js build/sfcc/write-result.test.js build/sfcc/writes.test.js build/sfcc/writes-system-object-payloads.test.js build/sfcc/writes-payloads.test.js build/sfcc/log-gate.test.js build/sfcc/log-query.test.js && node --experimental-test-module-mocks --test --test-force-exit build/index-heavy-read-truncation.test.js build/index-artifacts.test.js build/index.review-rounds.test.js build/index-brainstorm-filenames.test.js build/index-output-path.test.js build/index-generate-decision-page.test.js build/index-generate-decision-page.integration.test.js build/visual-diff.registration.test.js build/visual-diff.attachment-adapter.test.js build/attachment-download.test.js build/attachment-upload.test.js build/conductor/paths.test.js build/conductor/store-lifecycle.test.js build/conductor/store-queries.test.js build/conductor/tools.test.js build/conductor/cli.test.js build/conductor/security-regressions.test.js build/conductor/git-inspection.test.js build/conductor/tools-done-gate.test.js build/conductor/pr-ci-producer-emit-seam.test.js build/conductor/cli-git-hooks.test.js build/sfcc/client.test.js build/sfcc/tool-wrapper.test.js build/sfcc/setup-status.test.js build/sfcc/permissions.test.js build/sfcc/register.test.js build/sfcc/reads-system-object.test.js build/sfcc/reads-custom-object-def.test.js build/sfcc/reads-site-preference.test.js build/sfcc/writes-system-object.test.js build/sfcc/writes-custom-object-def.test.js build/sfcc/writes-site-preference.test.js",
-    "test:integration": "node --test build/integration/refresh-main.integration.test.js build/integration/start-tickets.integration.test.js build/integration/doctor.integration.test.js build/integration/agent-capabilities.integration.test.js build/integration/conductor-producer.integration.test.js build/integration/conductor-message-relay.integration.test.js build/integration/executor-http-runner.integration.test.js build/integration/executor-job-behaviors.integration.test.js build/integration/executor-recovery-jobs.integration.test.js build/integration/executor-spec-review-prompt.integration.test.js build/integration/resume-pre-spawn.git.integration.test.js build/integration/worker-finalization-origin.integration.test.js build/integration/post-remediation-merge-ci-wait.integration.test.js build/integration/executor-merge-supervision.integration.test.js build/integration/attachment-binary-roundtrip.integration.test.js build/integration/dependent-ticket-fresh-base.integration.test.js build/integration/execute-plan-instructions.integration.test.js build/integration/install-bridge-repo-resolution.integration.test.js",
+    "test": "node --test --test-force-exit build/pipeline-utils.test.js build/backend-warnings.test.js build/update-check.test.js build/cli-upgrade.test.js build/decision-page-schema.test.js build/decision-page-template.test.js build/bundle-pipelines.test.js build/instructions-contract.test.js build/pipeline-orchestrator-persistence.test.js build/pipeline-orchestrator-execution.test.js build/pipeline-orchestrator-integration.test.js build/index-static.test.js build/config-fields.static.test.js build/request-brainstorm.static.test.js build/execute-plan-instructions.static.test.js build/index-resolvers.test.js build/index-project-root.test.js build/index-pipelines.test.js build/index.test.js build/bridge-config.test.js build/credential-store.test.js build/agent-config-credential-migration.test.js build/mcp-invoke.test.js build/mcp-provisioning.test.js build/mcp-server-invocation.test.js build/third-party-mcp-targets.test.js build/git-ignore-utils.test.js build/credential-materialization.test.js build/mcp-registration-doctor.test.js build/mcp-host-targets.test.js build/mcp-install-state.test.js build/mcp-host-config.test.js build/secret-safety.test.js build/base-ref.test.js build/pr-base-contract.test.js build/start-tickets.test.js build/review-tickets.test.js build/start-tickets-base-branch.test.js build/agent-registry.test.js build/agent-registry.model-routing.test.js build/start-tickets.shell-model-routing.test.js build/start-tickets.bridge-api-model-routing.test.js build/start-tickets.tier-fetch-model-routing.test.js build/start-tickets.resolve-model-routing.test.js build/start-tickets.orchestrate-model-routing.test.js build/start-tickets.routing-diagnostics.test.js build/start-tickets-repo.test.js build/start-tickets-credential-invariants.static.test.js build/credentials-cli.test.js build/start-tickets-prereqs.test.js build/regression-check.test.js build/doctor.test.js build/install-doctor.test.js build/install-bridge.test.js build/install-bridge-invite.test.js build/install-bridge-prompt.test.js build/install-bridge-tools.test.js build/init.test.js build/init-docs.test.js build/resolveUploadAttachment.test.js build/package-static.test.js build/chain-utils.test.js build/chain-orchestrator.test.js build/scheduler-backends/types.test.js build/scheduler-backends/escaping.test.js build/scheduler-backends/launchd.test.js build/scheduler-backends/task-scheduler.test.js build/scheduler-backends/systemd-user.test.js build/scheduler-backends/at-fallback.test.js build/scheduler-backends/index.test.js build/command-catalog.test.js build/scheduled-prompt.test.js build/agent-launchers/claude.test.js build/agent-launchers/cursor.test.js build/agent-launchers/index.test.js build/schedule-store.test.js build/schedule-run.test.js build/setup-epic.test.js build/conductor-bundle-artifacts.test.js build/conductor-bundle-cli.test.js build/agent-capabilities/cli.test.js build/agent-capabilities/runner.test.js build/agent-capabilities/probes.test.js build/agent-capabilities/probe-context.test.js build/agent-capabilities/reporter.test.js build/conductor/taxonomy-and-errors.test.js build/conductor/github-mergeability.test.js build/conductor/merge-conflict-routing.test.js build/conductor/redaction-normalization.test.js build/conductor/claude-hook.test.js build/conductor/git-ci-types.test.js build/conductor/done-gate.test.js build/conductor/git-ci-taxonomy-payload.test.js build/conductor/bridge-api-client.test.js build/conductor/plan.test.js build/conductor/producer-ledger.test.js build/conductor/spec-review-producer.test.js build/conductor/git-producer.test.js build/conductor/git-hooks.test.js build/conductor/store-migration.test.js build/conductor/pr-discovery.test.js build/conductor/pr-ci-producer.test.js build/conductor/pr-review-producer.test.js build/conductor/doctor.test.js build/conductor/deny-enforcement-preflight.test.js build/conductor/errors.test.js build/conductor/store.test.js build/conductor/index-poll-ci-producer.test.js build/start-tickets-conductor.test.js build/start-tickets-conductor.spawn.test.js build/start-tickets-conductor-node-propagation.test.js build/start-tickets.non-mutating-base.test.js build/start-tickets-live-source-guard.test.js build/conductor/worker-ledger-cli.test.js build/conductor/supervisor-config.test.js build/conductor/supervisor-ledger.test.js build/conductor/supervisor-state-reducer.test.js build/conductor/supervisor-housekeeping-projection.test.js build/conductor/supervisor-escalation.test.js build/conductor/supervisor-retired-judgment.static.test.js build/conductor/supervisor-runtime.test.js build/conductor/supervisor-store-projection.test.js build/conductor/supervisor-cli.test.js build/conductor/supervisor-start-tickets.test.js build/conductor/supervisor-message-relay.test.js build/conductor/supervisor-state-message-events.test.js build/conductor/store-message-relay.test.js build/start-tickets-message-relay.test.js build/conductor/event-accessors.test.js build/conductor/merge-ledger.test.js build/conductor/deterministic-completion.static.test.js build/conductor/deterministic-completion.integration.test.js build/conductor/local-merge.test.js build/conductor/local-merge.static.test.js build/conductor/supervisor-merge.test.js build/conductor/bridge-api-merge-client.test.js build/conductor/bridge-api-epic-client.test.js build/conductor/supervisor-merge-runtime-state.test.js build/conductor/epic-state.test.js build/executor/claude-settings.test.js build/executor/cli.test.js build/executor/credentials.test.js build/executor/echo-acceptance.test.js build/executor/env.test.js build/executor/base-branch.test.js build/executor/heartbeat.test.js build/executor/http-client.test.js build/executor/job-runner.test.js build/executor/job-runner.payload-timeout.test.js build/executor/worker-finalization.test.js build/executor/job-runner.static.test.js build/executor/prompt-spec.test.js build/executor/job-types.test.js build/executor/recovery-job.static.test.js build/executor/observation.test.js build/executor/permissions.test.js build/executor/preflight.test.js build/executor/process.test.js build/executor/results.test.js build/executor/runner.test.js build/executor/terminal-mutation.test.js build/executor/worker-command.test.js build/executor/worktree-core.test.js build/executor/worktree.test.js build/executor/job-errors.test.js build/executor/worktree-inspection.test.js build/executor/resume-pre-spawn.test.js build/executor/verdict-artifact.test.js build/executor/worker-log.test.js build/executor/job-log-registry.test.js build/executor/viewer-tabs.test.js build/executor/watch-cli.test.js build/executor/merge-job.test.js build/executor/job-runner.merge.test.js build/executor/worktree-gc.test.js build/executor/runner.job-behaviors.test.js build/conductor/cli-freeze.test.js build/conductor/epic-reconcile.test.js build/conductor/epic-runtime.test.js build/conductor/epic-tick-sequence.test.js build/conductor/epic-runtime-post-action.test.js build/conductor/file-scope-guard.test.js build/conductor/file-scope-guard.integration.test.js build/mcp-profile.test.js build/mcp-profile-registration.test.js build/env-flags.test.js build/bridge-api-urls.test.js build/tool-surface-gating.test.js build/tools-budget.test.js build/visual-diff-worker.test.js build/visual-diff.test.js build/estimate-epic.test.js build/integration/measure-tools.test.js build/sfcc/config.test.js build/sfcc/ocapi-shape.test.js build/sfcc/output.test.js build/sfcc/credentials.test.js build/sfcc/ocapi-write-faults.test.js build/sfcc/write-guard.test.js build/sfcc/write-grants.test.js build/sfcc/write-result.test.js build/sfcc/writes.test.js build/sfcc/writes-system-object-payloads.test.js build/sfcc/writes-payloads.test.js build/sfcc/log-gate.test.js build/sfcc/log-query.test.js && node --experimental-test-module-mocks --test --test-force-exit build/index-heavy-read-truncation.test.js build/index-artifacts.test.js build/automation-progress.test.js build/index.review-rounds.test.js build/index-brainstorm-filenames.test.js build/index-output-path.test.js build/index-generate-decision-page.test.js build/index-generate-decision-page.integration.test.js build/visual-diff.registration.test.js build/visual-diff.attachment-adapter.test.js build/attachment-download.test.js build/attachment-upload.test.js build/conductor/paths.test.js build/conductor/store-lifecycle.test.js build/conductor/store-queries.test.js build/conductor/tools.test.js build/conductor/cli.test.js build/conductor/security-regressions.test.js build/conductor/git-inspection.test.js build/conductor/tools-done-gate.test.js build/conductor/pr-ci-producer-emit-seam.test.js build/conductor/cli-git-hooks.test.js build/sfcc/client.test.js build/sfcc/tool-wrapper.test.js build/sfcc/setup-status.test.js build/sfcc/permissions.test.js build/sfcc/register.test.js build/sfcc/reads-system-object.test.js build/sfcc/reads-custom-object-def.test.js build/sfcc/reads-site-preference.test.js build/sfcc/writes-system-object.test.js build/sfcc/writes-custom-object-def.test.js build/sfcc/writes-site-preference.test.js build/connect-github.test.js",
+    "test:integration": "node --test build/integration/refresh-main.integration.test.js build/integration/start-tickets.integration.test.js build/integration/start-tickets-tier-handoff.integration.test.js build/integration/doctor.integration.test.js build/integration/agent-capabilities.integration.test.js build/integration/conductor-producer.integration.test.js build/integration/conductor-message-relay.integration.test.js build/integration/executor-http-runner.integration.test.js build/integration/executor-job-behaviors.integration.test.js build/integration/executor-recovery-jobs.integration.test.js build/integration/executor-spec-review-prompt.integration.test.js build/integration/resume-pre-spawn.git.integration.test.js build/integration/worker-finalization-origin.integration.test.js build/integration/post-remediation-merge-ci-wait.integration.test.js build/integration/executor-merge-supervision.integration.test.js build/integration/attachment-binary-roundtrip.integration.test.js build/integration/dependent-ticket-fresh-base.integration.test.js build/integration/execute-plan-instructions.integration.test.js build/integration/conductor-bundle-artifacts.integration.test.js build/integration/install-bridge-repo-resolution.integration.test.js build/integration/capability-report-contract.integration.test.js build/integration/request-brainstorm-general.integration.test.js",
     "test:smoke": "node --test build/integration/packaged-cli-smoke.test.js",
     "prepublishOnly": "node scripts/bundle-assets.js && npm run build && node scripts/verify-shebang.cjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "pixelmatch": "^6.0.0",
+    "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
     "zod": "^4.4.3"
   },
@@ -47,7 +47,7 @@
     "@types/node": "^26.0.1",
     "@types/pngjs": "^6.0.5",
     "esbuild": "^0.28.1",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=18.0.0"