@debugbundle/mcp 0.1.3 → 0.1.6

package/README.md

@@ -30,7 +30,7 @@ debugbundle-mcp
 }
 ```
 
-The server uses stdio transport and exposes the same DebugBundle incident, incident-context, bundle, webhook, alert, token, project, member, billing, GitHub, probe, and diagnostic tools documented at https://debugbundle.com/docs/mcp. Hosted verification supports the active V1 proof path through `verify_cloud` with `trigger5xx: true`, incident triage can start with the one-call `get_incident_context` tool, and `doctor` accepts `privacy: true` to return the same deterministic redaction preview as `debugbundle doctor --privacy`.
+The server uses stdio transport and exposes the same DebugBundle incident, incident-context, bundle, webhook, alert, token, project, member, billing, GitHub, probe, and diagnostic tools documented at https://debugbundle.com/docs/mcp. Hosted verification supports the active V1 proof path through `verify_cloud` with `trigger5xx: true` and the configured-client-error proof path with `trigger4xxStatus: 403`, incident triage can start with the one-call `get_incident_context` tool, and `doctor` accepts `privacy: true` to return the same deterministic redaction preview as `debugbundle doctor --privacy`.
 
 ## Authentication
 

package/dist/main.cjs

@@ -16276,6 +16276,31 @@ var CaptureProbeEventsValues = ["buffer_only", "standalone_when_activated"];
 var CaptureProbeEventsSchema = external_exports.enum(CaptureProbeEventsValues);
 var RequestSignalClassificationValues = ["incident_signal", "context_signal"];
 var RequestSignalClassificationSchema = external_exports.enum(RequestSignalClassificationValues);
+var RECOMMENDED_IMMEDIATE_CLIENT_ERROR_STATUSES = [401, 403, 409, 422];
+var ImmediateClientErrorStatusSchema = external_exports.number().int().min(400).max(499);
+function normalizeImmediateClientErrorStatuses(statuses) {
+  return Array.from(new Set(statuses)).sort((left, right) => left - right);
+}
+var ImmediateClientErrorStatusesSchema = external_exports.array(ImmediateClientErrorStatusSchema).max(12).transform((statuses) => normalizeImmediateClientErrorStatuses(statuses));
+var ResolvedCapturePolicySchema = external_exports.object({
+  preset: CapturePresetSchema,
+  capture_logs: CaptureLogsSchema,
+  capture_request_events: CaptureRequestEventsSchema,
+  capture_breadcrumbs: CaptureBreadcrumbsSchema,
+  capture_probe_events: CaptureProbeEventsSchema,
+  immediate_client_error_statuses: ImmediateClientErrorStatusesSchema
+});
+var CapturePolicyOverridesSchema = external_exports.object({
+  capture_logs: CaptureLogsSchema.nullable(),
+  capture_request_events: CaptureRequestEventsSchema.nullable(),
+  capture_breadcrumbs: CaptureBreadcrumbsSchema.nullable(),
+  capture_probe_events: CaptureProbeEventsSchema.nullable(),
+  immediate_client_error_statuses: ImmediateClientErrorStatusesSchema.nullable()
+});
+var CapturePolicyResponseSchema = external_exports.object({
+  policy: ResolvedCapturePolicySchema,
+  overrides: CapturePolicyOverridesSchema
+});
 var CapturePolicySchema = external_exports.object({
   project_id: external_exports.string().uuid(),
   preset: CapturePresetSchema,
@@ -16283,6 +16308,7 @@ var CapturePolicySchema = external_exports.object({
   capture_request_events: CaptureRequestEventsSchema.nullable(),
   capture_breadcrumbs: CaptureBreadcrumbsSchema.nullable(),
   capture_probe_events: CaptureProbeEventsSchema.nullable(),
+  immediate_client_error_statuses: ImmediateClientErrorStatusesSchema.nullable(),
   updated_at: external_exports.string().datetime()
 });
 var CapturePolicyUpdateSchema = external_exports.object({
@@ -16290,21 +16316,48 @@ var CapturePolicyUpdateSchema = external_exports.object({
   capture_logs: CaptureLogsSchema.nullable().optional(),
   capture_request_events: CaptureRequestEventsSchema.nullable().optional(),
   capture_breadcrumbs: CaptureBreadcrumbsSchema.nullable().optional(),
-  capture_probe_events: CaptureProbeEventsSchema.nullable().optional()
+  capture_probe_events: CaptureProbeEventsSchema.nullable().optional(),
+  immediate_client_error_statuses: ImmediateClientErrorStatusesSchema.nullable().optional()
 });
+var PRESET_DEFAULTS = {
+  minimal: {
+    capture_logs: "error",
+    capture_request_events: "failures_only",
+    capture_breadcrumbs: "local_only",
+    capture_probe_events: "buffer_only",
+    immediate_client_error_statuses: []
+  },
+  balanced: {
+    capture_logs: "warning",
+    capture_request_events: "failures_only",
+    capture_breadcrumbs: "exception_only",
+    capture_probe_events: "buffer_only",
+    immediate_client_error_statuses: []
+  },
+  investigative: {
+    capture_logs: "info",
+    capture_request_events: "all",
+    capture_breadcrumbs: "standalone",
+    capture_probe_events: "standalone_when_activated",
+    immediate_client_error_statuses: [...RECOMMENDED_IMMEDIATE_CLIENT_ERROR_STATUSES]
+  }
+};
 var BALANCED_IMMEDIATE_REQUEST_STATUSES = /* @__PURE__ */ new Set([408, 423, 424, 425, 429]);
 var INVESTIGATIVE_IMMEDIATE_REQUEST_STATUSES = /* @__PURE__ */ new Set([...BALANCED_IMMEDIATE_REQUEST_STATUSES, 409]);
 var BALANCED_STANDARD_ANOMALY_STATUSES = /* @__PURE__ */ new Set([401, 403, 404, 409, 422]);
 var BALANCED_HIGH_VOLUME_ANOMALY_STATUSES = /* @__PURE__ */ new Set([400, 410]);
 var INVESTIGATIVE_ANOMALY_STATUSES = /* @__PURE__ */ new Set([...BALANCED_STANDARD_ANOMALY_STATUSES, ...BALANCED_HIGH_VOLUME_ANOMALY_STATUSES]);
 function classifyRequestStatus(input) {
-  const { responseStatus, capturePreset } = input;
+  const { responseStatus, capturePreset, immediateClientErrorStatuses = [] } = input;
   if (responseStatus === null || !Number.isFinite(responseStatus)) {
     return "context_signal";
   }
   if (responseStatus >= 500) {
     return "incident_signal";
   }
+  if (immediateClientErrorStatuses.includes(responseStatus)) {
+    return "incident_signal";
+  }
   if (capturePreset === "investigative") {
     return INVESTIGATIVE_IMMEDIATE_REQUEST_STATUSES.has(responseStatus) ? "incident_signal" : "context_signal";
   }
@@ -17558,16 +17611,6 @@ function createCliHttpClient(input, dependencies) {
 }
 
 // ../cli/src/capture-policy-commands.ts
-var ResolvedCapturePolicySchema = external_exports.object({
-  preset: CapturePresetSchema,
-  capture_logs: CaptureLogsSchema,
-  capture_request_events: CaptureRequestEventsSchema,
-  capture_breadcrumbs: CaptureBreadcrumbsSchema,
-  capture_probe_events: CaptureProbeEventsSchema
-});
-var CapturePolicyResponseSchema = external_exports.object({
-  policy: ResolvedCapturePolicySchema
-});
 var CapturePolicyApiError = class extends Error {
   status;
   constructor(status, message) {
@@ -17597,7 +17640,7 @@ function createCapturePolicyApi(httpClient) {
       if (!parsed.success) {
         throw new CapturePolicyApiError(500, "Invalid capture policy response.");
       }
-      return parsed.data.policy;
+      return parsed.data;
     },
     async updateCapturePolicy(input) {
       const response = await httpClient.request({
@@ -17613,7 +17656,7 @@ function createCapturePolicyApi(httpClient) {
       if (!parsed.success) {
         throw new CapturePolicyApiError(500, "Invalid capture policy response.");
       }
-      return parsed.data.policy;
+      return parsed.data;
     }
   };
 }
@@ -18041,7 +18084,7 @@ function getRequestResponseStatus(payload) {
   const status = payload?.["response_status"];
   return typeof status === "number" && Number.isFinite(status) ? status : null;
 }
-function classifyEvent(eventType, logLevel, probeActivationId, payload, capturePreset = "minimal") {
+function classifyEvent(eventType, logLevel, probeActivationId, payload, capturePreset = "minimal", immediateClientErrorStatuses = []) {
   switch (eventType) {
     case "backend_exception":
     case "frontend_exception":
@@ -18053,7 +18096,7 @@ function classifyEvent(eventType, logLevel, probeActivationId, payload, captureP
       return "context_signal";
     case "request_event": {
       const responseStatus = getRequestResponseStatus(payload);
-      return classifyRequestStatus({ responseStatus, capturePreset });
+      return classifyRequestStatus({ responseStatus, capturePreset, immediateClientErrorStatuses });
     }
     case "frontend_breadcrumb":
     case "deploy_metadata":
@@ -18978,6 +19021,13 @@ var STORAGE_SCHEMA_MIGRATIONS = [
         ON slack_destinations (organization_id, is_active, created_at)
       `
     ]
+  }),
+  defineStorageSchemaMigration({
+    id: "202605140001_add_capture_policy_immediate_client_error_statuses",
+    description: "Add nullable immediate client error status overrides to capture policies.",
+    statements: [
+      "ALTER TABLE capture_policies ADD COLUMN IF NOT EXISTS immediate_client_error_statuses jsonb"
+    ]
   })
 ];
 
@@ -21075,7 +21125,7 @@ function formatResult(input, exitCode, checks, errors, incidentId) {
   };
 }
 function buildCloudSuggestedActions(status, incidentId, mode = "passive_recent_incident") {
-  if (status === "healthy" && incidentId !== void 0 && mode === "active_5xx") {
+  if (status === "healthy" && incidentId !== void 0 && (mode === "active_5xx" || mode === "active_4xx")) {
     return [
       `Run debugbundle inspect ${incidentId} --source cloud to inspect why the incident fired.`,
       `Run debugbundle bundle ${incidentId} --source cloud to fetch the generated debug bundle.`
@@ -21145,11 +21195,11 @@ function localFailureStepName(checks) {
 function cloudVerificationRunId(now) {
   return now.toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
 }
-function requestFailureReason() {
+function requestFailureReason(responseStatus) {
   const incidentReason = deriveIncidentReasonFromSignal({
     event_type: "request_event",
     event_class: "incident_signal",
-    response_status: 503
+    response_status: responseStatus
   });
   if (incidentReason === null) {
     throw new Error("request_failure_reason_unavailable");
@@ -21158,6 +21208,9 @@ function requestFailureReason() {
 }
 function buildCloudVerificationEvent(input) {
   const runId = cloudVerificationRunId(input.now);
+  const is5xxVerification = input.responseStatus >= 500;
+  const routeTemplate = is5xxVerification ? "/debugbundle/verify/cloud" : `/debugbundle/verify/cloud/client-error/${input.responseStatus}`;
+  const verificationLabel = is5xxVerification ? "true" : `client-error-${input.responseStatus}`;
   return createEventEnvelope({
     event_type: "request_event",
     sdk_name: "debugbundle-cli",
@@ -21171,28 +21224,39 @@ function buildCloudVerificationEvent(input) {
     occurred_at: input.now.toISOString(),
     payload: {
       method: "GET",
-      path: "/debugbundle/verify/cloud",
-      route_template: "/debugbundle/verify/cloud",
+      path: routeTemplate,
+      route_template: routeTemplate,
       query: {
         debugbundle_verification: true,
-        run_id: runId
+        run_id: runId,
+        synthetic_status: input.responseStatus
       },
       headers: {
-        "x-debugbundle-verification": "true"
+        "x-debugbundle-verification": verificationLabel
       },
-      response_status: 503,
+      response_status: input.responseStatus,
       duration_ms: 37,
       response_headers: {
-        "x-debugbundle-verification": "true"
+        "x-debugbundle-verification": verificationLabel
       },
       response_body: {
-        error: "debugbundle_cloud_verification",
+        error: is5xxVerification ? "debugbundle_cloud_verification" : "debugbundle_cloud_client_error_verification",
         synthetic: true,
-        run_id: runId
+        run_id: runId,
+        response_status: input.responseStatus
       }
     }
   });
 }
+function validateActiveCloudVerificationInput(input) {
+  if (input.trigger5xx === true && input.trigger4xxStatus !== void 0) {
+    return "Choose either --trigger-5xx or --trigger-4xx, not both.";
+  }
+  if (input.trigger4xxStatus !== void 0 && (input.trigger4xxStatus < 400 || input.trigger4xxStatus > 499)) {
+    return "--trigger-4xx must be an integer status between 400 and 499.";
+  }
+  return null;
+}
 async function sendEventsToApi(input, dependencies = {}) {
   const fetchImpl = dependencies.fetchImpl ?? fetch;
   const baseUrl = input.baseUrl.endsWith("/") ? input.baseUrl.slice(0, -1) : input.baseUrl;
@@ -21384,6 +21448,15 @@ async function verifyCloudCommand(input, dependencies = {}) {
   const checks = [];
   const environment = input.environment ?? "production";
   const maxAgeMinutes = input.maxAgeMinutes ?? 15;
+  const activeInputError = validateActiveCloudVerificationInput(input);
+  if (activeInputError !== null) {
+    checks.push({
+      name: "trigger-input",
+      status: "error",
+      message: activeInputError
+    });
+    return formatCloudResult(input, 4, checks, [activeInputError]);
+  }
   const readAuthState = dependencies.readAuthState ?? readCliAuthState;
   let authState;
   try {
@@ -21416,7 +21489,7 @@ async function verifyCloudCommand(input, dependencies = {}) {
     requestInput,
     dependencies.fetchImpl === void 0 ? {} : { fetchImpl: dependencies.fetchImpl }
   ));
-  if (input.trigger5xx === true) {
+  if (input.trigger5xx === true || input.trigger4xxStatus !== void 0) {
     const verificationStartedAt = now();
     const runId = cloudVerificationRunId(verificationStartedAt);
     const serviceName = input.service ?? `debugbundle-verify-cloud-${runId}`;
@@ -21424,16 +21497,20 @@ async function verifyCloudCommand(input, dependencies = {}) {
     const pollAttempts = dependencies.pollAttempts ?? 6;
     const pollIntervalMs = dependencies.pollIntervalMs ?? 2e3;
     const sleep = dependencies.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    const responseStatus = input.trigger4xxStatus ?? 503;
+    const activeMode = input.trigger4xxStatus !== void 0 ? "active_4xx" : "active_5xx";
+    const activeCheckName = input.trigger4xxStatus !== void 0 ? "active-4xx-event" : "active-5xx-event";
+    const statusLabel = input.trigger4xxStatus !== void 0 ? `${responseStatus}` : "5xx";
     const verification = {
-      mode: "active_5xx",
+      mode: activeMode,
       bundle_status: "unknown",
-      classification_reason: requestFailureReason()
+      classification_reason: requestFailureReason(responseStatus)
     };
     const errors = [];
     let exitCode = 0;
     let tokenId = null;
     let incidentId;
-    let activeStep = "active-5xx-event";
+    let activeStep = activeCheckName;
     try {
       const token = await createProjectToken({
         bearerToken: authState.bearer_token,
@@ -21447,7 +21524,8 @@ async function verifyCloudCommand(input, dependencies = {}) {
       const event = buildCloudVerificationEvent({
         now: verificationStartedAt,
         serviceName,
-        environment
+        environment,
+        responseStatus
       });
       const ingestion = await sendEvents({
         baseUrl: authState.base_url,
@@ -21456,12 +21534,12 @@ async function verifyCloudCommand(input, dependencies = {}) {
       });
       verification.accepted_event_count = ingestion.accepted;
       if (ingestion.accepted < 1 || ingestion.rejected > 0 || ingestion.errors.length > 0) {
-        throw new Error(`Synthetic 5xx ingestion was not fully accepted: accepted=${ingestion.accepted}, rejected=${ingestion.rejected}.`);
+        throw new Error(`Synthetic ${statusLabel} ingestion was not fully accepted: accepted=${ingestion.accepted}, rejected=${ingestion.rejected}.`);
       }
       checks.push({
-        name: "active-5xx-event",
+        name: activeCheckName,
         status: "ok",
-        message: "Sent synthetic 5xx request_event through cloud ingestion."
+        message: `Sent synthetic ${statusLabel} request_event through cloud ingestion.`
       });
       activeStep = "incident-retrieval";
       for (let attempt = 1; attempt <= pollAttempts; attempt += 1) {
@@ -21479,7 +21557,7 @@ async function verifyCloudCommand(input, dependencies = {}) {
         if (candidate !== void 0) {
           incidentId = candidate.incident_id;
           verification.incident_id = candidate.incident_id;
-          verification.classification_reason = candidate.incident_reason ?? requestFailureReason();
+          verification.classification_reason = candidate.incident_reason ?? requestFailureReason(responseStatus);
           break;
         }
         if (attempt < pollAttempts) {
@@ -21487,12 +21565,12 @@ async function verifyCloudCommand(input, dependencies = {}) {
         }
       }
       if (incidentId === void 0) {
-        throw new Error("Synthetic 5xx request was accepted but no matching cloud incident was visible yet.");
+        throw new Error(`Synthetic ${statusLabel} request was accepted but no matching cloud incident was visible yet.`);
       }
       checks.push({
         name: "incident-retrieval",
         status: "ok",
-        message: `Retrieved cloud incident ${incidentId} for the synthetic 5xx request.`
+        message: `Retrieved cloud incident ${incidentId} for the synthetic ${statusLabel} request.`
       });
       activeStep = "bundle-status";
       const bundle = await getBundle({
@@ -22142,12 +22220,10 @@ function createCapturePolicyMcpTools(api) {
   return {
     async get_capture_policy(input) {
       try {
-        return {
-          policy: await api.getCapturePolicy({
-            bearerToken: String(input["bearerToken"]),
-            projectId: String(input["projectId"])
-          })
-        };
+        return await api.getCapturePolicy({
+          bearerToken: String(input["bearerToken"]),
+          projectId: String(input["projectId"])
+        });
       } catch (error) {
         mapMcpError4(error);
       }
@@ -22155,13 +22231,11 @@ function createCapturePolicyMcpTools(api) {
     async update_capture_policy(input) {
       try {
         const update = typeof input["update"] === "object" && input["update"] !== null ? input["update"] : {};
-        return {
-          policy: await api.updateCapturePolicy({
-            bearerToken: String(input["bearerToken"]),
-            projectId: String(input["projectId"]),
-            update
-          })
-        };
+        return await api.updateCapturePolicy({
+          bearerToken: String(input["bearerToken"]),
+          projectId: String(input["projectId"]),
+          update
+        });
       } catch (error) {
         mapMcpError4(error);
       }
@@ -23236,6 +23310,7 @@ function createSetupMcpTools(commands) {
           ...typeof input["environment"] === "string" ? { environment: input["environment"] } : {},
           ...typeof input["maxAgeMinutes"] === "number" ? { maxAgeMinutes: input["maxAgeMinutes"] } : {},
           ...input["trigger5xx"] === true ? { trigger5xx: true } : {},
+          ...typeof input["trigger4xxStatus"] === "number" ? { trigger4xxStatus: input["trigger4xxStatus"] } : {},
           ...typeof input["authFilePath"] === "string" ? { authFilePath: input["authFilePath"] } : {},
           json: true
         })
@@ -25008,13 +25083,14 @@ var MCP_TOOL_CATALOG = [
   {
     name: "verify_cloud",
     group: "setup",
-    description: "Verify that a hosted project is sending data to DebugBundle.",
+    description: "Verify hosted ingestion or actively prove hosted incident creation.",
     inputSchema: external_exports.object({
       projectId: external_exports.string(),
       service: external_exports.string().optional(),
       environment: external_exports.string().optional(),
       maxAgeMinutes: external_exports.number().optional(),
       trigger5xx: external_exports.boolean().optional(),
+      trigger4xxStatus: external_exports.number().int().min(400).max(499).optional(),
       authFilePath: external_exports.string().optional()
     })
   },
@@ -25533,7 +25609,8 @@ var MCP_TOOL_CATALOG = [
         capture_logs: external_exports.string().nullable().optional(),
         capture_request_events: external_exports.string().nullable().optional(),
         capture_breadcrumbs: external_exports.string().nullable().optional(),
-        capture_probe_events: external_exports.string().nullable().optional()
+        capture_probe_events: external_exports.string().nullable().optional(),
+        immediate_client_error_statuses: external_exports.array(external_exports.number().int().min(400).max(499)).nullable().optional()
       })
     })
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugbundle/mcp",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "private": false,
   "description": "Model Context Protocol server for DebugBundle",
   "license": "AGPL-3.0-only",