@bridge_gpt/mcp-server 0.2.25 → 0.2.27

package/build/doctor.js

@@ -20,7 +20,11 @@ import os from "os";
 import path from "path";
 import { createDefaultStartTicketsDeps } from "./start-tickets.js";
 import { VERSION } from "./version.generated.js";
-import { collectInstallStatusChecks, formatInstallStatusReport, } from "./install-doctor.js";
+import { collectInstallStatusChecks, formatInstallStatusReport, resolveInstallDoctorTarget, } from "./install-doctor.js";
+import { parseDefaultOnEnvFlag } from "./env-flags.js";
+import { createBridgeApiUrls } from "./bridge-api-urls.js";
+import { probeToolSurface } from "./tool-surface-gating.js";
+import { resolveBapiCredentials } from "./credential-store.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { getDoctorPrereqDescriptors, probePrerequisite, } from "./start-tickets-prereqs.js";
 import { resolveProfiles } from "./mcp-profile.js";
@@ -51,6 +55,14 @@ export function getDoctorUsage() {
         "bootstrap-field completeness, and repository-indexing state. It performs",
         "read-only GETs only and never affects the exit code.",
         "",
+        "It also includes an advisory 'MCP tool surface' section (BAPI-641): what",
+        "dynamic capability gating would advertise for this repo. It performs at most",
+        "one read-only GET to /jira/mcp/tool-surface (none under the kill switch) and",
+        "is advisory/fail-open — a timeout or malformed response is reported as",
+        "'fail-open to full surface' and never affects the exit code. Clients that",
+        "ignore notifications/tools/list_changed must reconnect or start a new MCP",
+        "session to observe surface changes; no project MCP config change is required.",
+        "",
         "Conductor ledger / native-module diagnostics (the SQLite ledger's native",
         "binding load status and Node-version skew) live under a separate command:",
         "  conductor doctor",
@@ -363,6 +375,111 @@ export function formatLauncherCacheReport(inspections) {
     }
     return lines.join("\n");
 }
+/**
+ * Collect the read-only tool-surface diagnostic. Evaluates the kill switch first
+ * and returns without any network request when disabled. For an enabled flag and
+ * a resolved repo/credential, performs ONE 500 ms `probeToolSurface()` GET to the
+ * deployed route. Credential values live ONLY in the request headers and never in
+ * the returned result. Never throws.
+ */
+export async function collectToolSurfaceDiagnostic(deps) {
+    const enabled = parseDefaultOnEnvFlag(deps.env.BAPI_MCP_TOOL_SURFACE_GATING_ENABLED);
+    if (!enabled) {
+        return { enabled: false, reason: "kill-switch" };
+    }
+    const target = await resolveInstallDoctorTarget(deps);
+    if (!target.repoName) {
+        return {
+            enabled: true,
+            reason: "unresolved",
+            detail: "no BAPI_REPO_NAME in the environment or project-local MCP configs",
+        };
+    }
+    const credDeps = {
+        env: deps.env,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        stat: deps.stat,
+        stderr: () => { },
+    };
+    const cred = await resolveBapiCredentials(target.repoName, credDeps);
+    if (!cred.ok) {
+        return {
+            enabled: true,
+            reason: "unresolved",
+            detail: `no Bridge API credential resolved (${cred.kind})`,
+        };
+    }
+    const apiKey = cred.credentials.apiKey;
+    const urls = createBridgeApiUrls(target.baseUrl);
+    const url = urls.buildGetUrl("/mcp/tool-surface", {
+        repo_name: target.repoName,
+    });
+    const result = await probeToolSurface({
+        url,
+        resolveHeaders: async () => ({ "X-API-Key": apiKey }),
+        fetchFn: deps.fetch,
+    });
+    if (result.reason === "blocked") {
+        return {
+            enabled: true,
+            reason: "blocked",
+            blockedTools: Array.from(result.blockedTools),
+            catalogRevision: result.catalogRevision,
+            evaluatedToolCount: result.evaluatedToolCount,
+        };
+    }
+    if (result.reason === "timeout") {
+        return { enabled: true, reason: "timeout" };
+    }
+    return { enabled: true, reason: "malformed", subtype: result.subtype };
+}
+/**
+ * Render the advisory "MCP tool surface" section (pure formatting — no probing).
+ * States the kill-switch state, probe reachability, decision reason/subtype,
+ * fail-open behavior when applicable, blocked IDs/count/revision for a valid
+ * response, and clarifies that blocked IDs are intersected with the locally
+ * active profile and SDK-enabled baseline only when an MCP session starts.
+ */
+export function formatToolSurfaceDiagnosticReport(diag) {
+    const lines = ["", "MCP tool surface (dynamic capability gating — advisory)", ""];
+    lines.push(`Kill switch: ${diag.enabled ? "ENABLED (gating active)" : "DISABLED (full surface)"}`);
+    switch (diag.reason) {
+        case "kill-switch":
+            lines.push("Reason: kill-switch — BAPI_MCP_TOOL_SURFACE_GATING_ENABLED is off, so the full profile surface is advertised and no probe is performed.");
+            break;
+        case "unresolved":
+            lines.push(`Reason: unresolved — ${diag.detail ?? "repo/credential not resolved"}; the probe was skipped and the full surface is advertised (fail-open to full surface).`);
+            break;
+        case "blocked": {
+            const ids = diag.blockedTools ?? [];
+            lines.push("Reason: blocked — the backend returned a valid capability decision.");
+            lines.push(`Probe: reachable (HTTP 200, valid response).`);
+            lines.push(`Blocked tools (${ids.length}): [${ids.join(", ")}]`);
+            if (diag.catalogRevision)
+                lines.push(`Catalog revision: ${diag.catalogRevision}`);
+            if (typeof diag.evaluatedToolCount === "number") {
+                lines.push(`Evaluated tool count: ${diag.evaluatedToolCount}`);
+            }
+            break;
+        }
+        case "timeout":
+            lines.push("Reason: timeout — the 500 ms probe deadline elapsed; fail-open to full surface.");
+            break;
+        case "malformed":
+            lines.push(`Reason: malformed (${diag.subtype ?? "unknown"}) — fail-open to full surface.`);
+            break;
+    }
+    lines.push("");
+    lines.push("Blocked IDs are intersected with the locally active MCP profile and the current SDK-enabled");
+    lines.push("baseline only when an MCP session starts, so IDs unknown to this package or excluded by the");
+    lines.push("active profile have no effect. Capability-hidden tools remain registered and callable — the");
+    lines.push("backend is the enforcement boundary. This section is advisory and never changes the exit code.");
+    lines.push("Clients that ignore notifications/tools/list_changed must reconnect or start a new MCP session");
+    lines.push("to observe surface changes; no project MCP configuration change is required.");
+    return lines.join("\n");
+}
 /**
  * CLI entry for the read-only `doctor` subcommand. Returns a process exit code.
  * Help returns 0; parser errors return 1; otherwise it prints the report and
@@ -429,6 +546,36 @@ export async function runDoctorCli(argv, overrides = {}) {
             /* install-status diagnostics are advisory; never block the doctor report */
         }
     }
+    // Advisory MCP tool-surface capability section (BAPI-641). Strictly read-only:
+    // one 500 ms GET (or none, under the kill switch). Any timeout, malformed
+    // response, or unexpected throw degrades to a "fail-open to full surface" line
+    // and never affects the exit code, exactly like install-status above.
+    if (overrides.toolSurface !== false) {
+        try {
+            const injectedFs = deps;
+            const toolSurfaceDeps = {
+                env: overrides.toolSurface?.env ?? deps.env,
+                cwd: overrides.toolSurface?.cwd ?? deps.cwd,
+                platform: overrides.toolSurface?.platform ?? deps.platform,
+                homedir: overrides.toolSurface?.homedir ?? injectedFs.homedir ?? os.homedir,
+                readFile: overrides.toolSurface?.readFile ??
+                    injectedFs.readFile ??
+                    ((p) => readFile(p, "utf-8")),
+                stat: overrides.toolSurface?.stat ?? injectedFs.stat ?? ((p) => stat(p)),
+                fetch: overrides.toolSurface?.fetch ?? ((...args) => fetch(...args)),
+            };
+            const diagnostic = await collectToolSurfaceDiagnostic(toolSurfaceDeps);
+            log(formatToolSurfaceDiagnosticReport(diagnostic));
+        }
+        catch {
+            // Any unexpected failure still degrades to a sanitized advisory section.
+            log(formatToolSurfaceDiagnosticReport({
+                enabled: parseDefaultOnEnvFlag(deps.env.BAPI_MCP_TOOL_SURFACE_GATING_ENABLED),
+                reason: "malformed",
+                subtype: "unexpected",
+            }));
+        }
+    }
     if (!collection.ok)
         return 1;
     return collection.results.some((r) => !r.found) ? 1 : 0;

package/build/env-flags.js

@@ -0,0 +1,31 @@
+/**
+ * env-flags — shared parsing for default-ON boolean environment flags.
+ *
+ * Extracted from `index.ts` (BAPI-641) so normal server startup and the
+ * `doctor` diagnostic share ONE implementation of the default-on semantics.
+ * A default-on flag is enabled unless explicitly set to a recognized off-token,
+ * so an unknown value fails OPEN (enabled) rather than silently disabling a
+ * feature.
+ */
+/** The recognized, case-insensitive off-tokens for a default-on flag. */
+const OFF_TOKENS = new Set([
+    "false",
+    "0",
+    "no",
+    "off",
+    "disabled",
+]);
+/**
+ * Parse a default-ON boolean env flag. `undefined` / blank → true; the
+ * normalized off-tokens (`false`, `0`, `no`, `off`, `disabled`) → false; any
+ * other value → true (preserving default-on / fail-open behavior). Matching is
+ * case-insensitive and trims surrounding whitespace.
+ */
+export function parseDefaultOnEnvFlag(value) {
+    if (value === undefined)
+        return true;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "")
+        return true;
+    return !OFF_TOKENS.has(normalized);
+}