@debugbundle/mcp 1.6.0 → 1.6.2

package/README.md

@@ -1,10 +1,10 @@
 # @debugbundle/mcp
 
-Model Context Protocol server for DebugBundle.
+MCP server for production debugging bundles and incident workflows for AI agents. DebugBundle lets agents inspect incidents, deterministic bundles, reproductions, probes, hosted health checks, alerts, webhooks, projects, and setup state through the same management surface as the API and CLI.
 
 ## Install
 
-Run directly with npm:
+Run the stdio server directly with npm:
 
 ```bash
 npx @debugbundle/mcp
@@ -19,7 +19,7 @@ debugbundle-mcp
 
 Supported Node.js versions: 22.x through 26.x.
 
-## MCP Client Configuration
+## MCP Client Config
 
 ```json
 {
@@ -32,11 +32,65 @@ Supported Node.js versions: 22.x through 26.x.
 }
 ```
 
-The server uses stdio transport and exposes the same DebugBundle incident, incident-context, bundle, hosted health-check, 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, hosted health-check triage can start with `list_health_checks`, and `doctor` accepts `privacy: true` to return the same deterministic redaction preview as `debugbundle doctor --privacy`.
+Use `npx -y @debugbundle/mcp` in clients that require noninteractive package execution.
+
+## Install Matrix
+
+| Environment | Recommended path | Notes |
+| --- | --- | --- |
+| Generic local MCP client | `npx @debugbundle/mcp` | stdio transport |
+| Claude Desktop local MCP | local MCP server config | uses local machine auth/config |
+| Cursor | MCP config with `npx @debugbundle/mcp` | stdio transport |
+| VS Code / GitHub MCP Registry | `com.debugbundle/mcp` | official registry metadata |
+| OpenClaw / ClawHub | DebugBundle skill plus MCP config | use the published skill for workflow guidance |
+| CI/headless agents | `DEBUGBUNDLE_MEMBER_TOKEN` | never use a project token |
+| Self-hosted DebugBundle | `DEBUGBUNDLE_API_URL` plus member auth | points the server at your API base URL |
+
+DebugBundle does not expose a hosted remote MCP endpoint today; this package is the local stdio path.
 
 ## Authentication
 
-Local use reuses CLI auth state from `~/.debugbundle/auth.json` when available. Headless or marketplace-managed clients can set `DEBUGBUNDLE_MEMBER_TOKEN` in the MCP server environment. Individual tool calls can still pass `bearerToken` explicitly when needed.
+| Mode | Use | Notes |
+| --- | --- | --- |
+| CLI auth state | Local developer machines | Reuses `~/.debugbundle/auth.json` when available. |
+| `DEBUGBUNDLE_MEMBER_TOKEN` | Headless or marketplace-managed clients | Member tokens are for CLI/API/MCP read and management operations. |
+| Per-tool `bearerToken` | Explicit advanced automation | Overrides default auth for that call only. |
+| Project token | SDK ingestion only | Do not use project tokens for MCP retrieval or management. |
+
+## What Agents Can Do
+
+- List active incidents and fetch full incident context.
+- Fetch deterministic debug bundles and reproduction artifacts.
+- Inspect hosted health checks, probes, alerts, webhooks, projects, members, billing, capture policy, and GitHub automation state.
+- Run local and hosted verification through tools such as `verify_local`, `verify_cloud`, `doctor`, `smoke`, and `analyze`.
+- Resolve or reopen incidents after verification.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Node.js launch failure | Use Node.js 22.x through 26.x. Configure the client to use a supported `node` or `npx` runtime. |
+| Missing local auth | Run `debugbundle login`, or set `DEBUGBUNDLE_MEMBER_TOKEN` for headless and managed clients. |
+| Invalid token | Use a `dbundle_mem_` member token. Project tokens are SDK ingestion-only credentials. |
+| Wrong API host | Leave `DEBUGBUNDLE_API_URL` unset for DebugBundle Cloud; set it only for self-hosted or non-default API hosts. |
+| Local repo not initialized | Run `debugbundle setup` before local-only diagnostics, local bundle analysis, or generated project-skill workflows. |
+
+## Links
+
+- Docs: https://debugbundle.com/docs/mcp
+- Agent workflows: https://debugbundle.com/docs/agent-workflows
+- LLM index: https://debugbundle.com/llms.txt
+- MCP tool schema: https://debugbundle.com/schemas/mcp-tools.json
+- Official MCP Registry metadata: https://github.com/debugbundle/debugbundle/blob/main/apps/mcp/server.json
+
+## Security And Trust
+
+- Official MCP Registry name: `com.debugbundle/mcp`.
+- Official npm package: `@debugbundle/mcp`.
+- Source repository: https://github.com/debugbundle/debugbundle/tree/main/apps/mcp
+- License: AGPL-3.0-only.
+- The server uses stdio transport and local process credentials. It does not include hidden hosted management auth.
+- Public examples must use placeholders only; never paste real member tokens, project tokens, webhook secrets, or customer configuration into marketplace listings.
 
 ## License
 

package/dist/main.cjs

@@ -14467,6 +14467,7 @@ var AlertConditionTypeSchema = external_exports.enum([
   "severity_threshold",
   "regression_after_deploy"
 ]);
+var AlertSeverityLifecycleScopeSchema = external_exports.enum(["new_incident", "incident_regressed", "both"]);
 var AlertSchema = external_exports.object({
   alert_id: external_exports.string(),
   project_id: external_exports.string(),
@@ -14475,6 +14476,7 @@ var AlertSchema = external_exports.object({
   channel: AlertChannelSchema,
   condition_type: AlertConditionTypeSchema,
   severity_min: external_exports.enum(["low", "medium", "high", "critical"]).nullable(),
+  severity_lifecycle_scope: AlertSeverityLifecycleScopeSchema.nullable().optional().default(null),
   cooldown_seconds: external_exports.number().int().min(0),
   config: external_exports.record(external_exports.string(), external_exports.unknown()),
   is_enabled: external_exports.boolean(),
@@ -14562,6 +14564,9 @@ function createAlertApi(client) {
       if (input.severityMin !== void 0) {
         body.severity_min = input.severityMin;
       }
+      if (input.severityLifecycleScope !== void 0) {
+        body.severity_lifecycle_scope = input.severityLifecycleScope;
+      }
       if (input.cooldownSeconds !== void 0) {
         body.cooldown_seconds = input.cooldownSeconds;
       }
@@ -14591,6 +14596,9 @@ function createAlertApi(client) {
       if (input.severityMin !== void 0) {
         body.severity_min = input.severityMin;
       }
+      if (input.severityLifecycleScope !== void 0) {
+        body.severity_lifecycle_scope = input.severityLifecycleScope;
+      }
       if (input.cooldownSeconds !== void 0) {
         body.cooldown_seconds = input.cooldownSeconds;
       }
@@ -18061,9 +18069,12 @@ function buildSkill() {
     "description: >-",
     "  Investigate runtime incidents, inspect debug bundles, generate reproductions,",
     "  run improvement analysis, and inspect operational controls using the DebugBundle",
-    "  CLI and local project scaffold. Use when the user reports a bug, runtime",
-    "  failure, production incident, endpoint downtime, health-check issue, missing",
-    "  notification, webhook delivery failure, probe request, or noisy incident.",
+    "  CLI and local project scaffold. Use when runtime errors/failures or captured",
+    "  operational evidence are relevant: production/customer-facing incidents,",
+    "  endpoint downtime, health-check failures, notification or webhook failures,",
+    "  probes, noisy captured incidents, or explicit DebugBundle artifact requests. Do not use for",
+    "  deterministic local source, UI, layout, copy, calculation, refactor, or",
+    "  test-only issues unless runtime evidence is needed.",
     "metadata:",
     "  author: debugbundle",
     '  version: "1.0"',
@@ -18071,11 +18082,22 @@ function buildSkill() {
     "",
     "# DebugBundle",
     "",
-    "Use DebugBundle before starting a fresh bug investigation.",
+    "Use DebugBundle when runtime evidence is relevant to the task.",
+    "",
+    "## When To Use DebugBundle",
+    "",
+    "Use the incident/artifact workflow when the user reports:",
+    "",
+    "- production or customer-facing incidents, runtime failures, regressions, broken deploys, or unknown errors likely to have generated captured events",
+    "- endpoint downtime or a failing hosted health check",
+    "- missing, duplicate, or failed alerts, webhooks, GitHub dispatches, probes, or other operational delivery",
+    "- a specific DebugBundle incident id, bundle, reproduction, report, or noisy captured incident",
+    "",
+    "For deterministic local source-code, UI, layout, copy, calculation, refactor, or test-only issues, inspect source and tests first. Do not check DebugBundle incidents unless the user asks, the issue involves live runtime behavior, or captured evidence is needed.",
     "",
     "## Investigation Quickstart",
     "",
-    "When the user reports a bug, runtime failure, production incident, regression, broken deploy, or unknown error, start here before reading arbitrary source files.",
+    "When the issue matches the runtime/incident criteria above, start here before reading arbitrary source files.",
     "",
     "1. Run `debugbundle doctor --json` to learn whether the project is local-only or connected and whether the local scaffold is healthy.",
     "2. If `debugbundle doctor --json` reports `mode=local-only`, start with `debugbundle incidents --source local --status active --json`.",
@@ -18095,7 +18117,7 @@ function buildSkill() {
     "",
     "## Core Workflow",
     "",
-    "1. Check DebugBundle incidents first to avoid re-investigating a known failure.",
+    "1. For qualifying runtime/incident work, check DebugBundle incidents first to avoid re-investigating a known failure.",
     "2. Inspect the incident bundle and reproduction artifact before proposing a fix.",
     "3. Run `debugbundle analyze --type improvement --local` after local processing when you need a deterministic change plan.",
     "4. Apply the narrowest fix, then validate it with the repository test workflow from `.debugbundle/profile.json`.",
@@ -18150,6 +18172,7 @@ function buildSkill() {
     "- Availability checks: `https://debugbundle.com/docs/availability-checks`",
     "- Probes: `https://debugbundle.com/docs/probes`",
     "- Capture policy and rules: `https://debugbundle.com/docs/capture-policy`",
+    "- Managing noise: `https://debugbundle.com/docs/managing-noise`",
     "- Alerts: `https://debugbundle.com/docs/alerts` and `https://debugbundle.com/docs/cli/alerts`",
     "- Webhooks: `https://debugbundle.com/docs/webhooks` and `https://debugbundle.com/docs/cli/webhooks`",
     "- API ingestion: `https://debugbundle.com/docs/api/ingestion`",
@@ -18278,6 +18301,7 @@ function buildCliReference() {
     "- Webhooks: `https://debugbundle.com/docs/webhooks`, `https://debugbundle.com/docs/cli/webhooks`, and `https://debugbundle.com/docs/api/webhooks`",
     "- Probes: `https://debugbundle.com/docs/probes` and `https://debugbundle.com/docs/api/probes`",
     "- Capture policy and rules: `https://debugbundle.com/docs/capture-policy`",
+    "- Managing noise: `https://debugbundle.com/docs/managing-noise`",
     "- Availability checks: `https://debugbundle.com/docs/availability-checks`",
     "- MCP tool catalog: `https://debugbundle.com/docs/mcp/tools`",
     "",
@@ -18320,7 +18344,7 @@ function buildMcpReference() {
   return [
     "# DebugBundle MCP Reference",
     "",
-    "Use the same incident-first workflow through MCP when an agent is operating in connected mode.",
+    "Use the same runtime-evidence-gated workflow through MCP when an agent is operating in connected mode.",
     "",
     "## Investigation Tools",
     "",
@@ -18334,8 +18358,9 @@ function buildMcpReference() {
     "- `analyze` \u2014 run local agent-oriented analysis from local bundles and skill schemas.",
     "",
     "- Prefer bundle retrieval tools before reading raw repository files.",
-    "- Use MCP bundle access when the current issue originated in production.",
-    "- Resolve fixed or intentionally generated incidents with `resolve_incident` or `resolve_incidents` so open incidents stay actionable.",
+    "- Use MCP bundle access when the current issue originated in production or otherwise needs captured runtime evidence.",
+    "- For deterministic local source, UI, layout, copy, calculation, refactor, or test-only issues, inspect source and tests first unless the user asks for DebugBundle evidence.",
+    "- Resolve fixed or intentionally generated incidents with `resolve_incident` or `resolve_incidents` so active incidents stay actionable.",
     "- Fall back to local CLI processing when the project is local-only.",
     "",
     "## Noise and Capture Policy Tools",
@@ -18382,6 +18407,7 @@ function buildMcpReference() {
     "- Availability checks: `https://debugbundle.com/docs/availability-checks`",
     "- Probes: `https://debugbundle.com/docs/probes`",
     "- Capture policy and rules: `https://debugbundle.com/docs/capture-policy`",
+    "- Managing noise: `https://debugbundle.com/docs/managing-noise`",
     "- Alerts: `https://debugbundle.com/docs/alerts`",
     "- Webhooks: `https://debugbundle.com/docs/webhooks`",
     "- API ingestion: `https://debugbundle.com/docs/api/ingestion`",
@@ -18487,13 +18513,21 @@ function buildSkillEvals() {
       skill: "debugbundle",
       evaluations: [
         {
-          name: "incident_first_workflow",
+          name: "runtime_incident_workflow",
           prompt: "The user reports a production checkout failure. Confirm the skill tells the agent to inspect DebugBundle artifacts first.",
           expected_behavior: [
-            "Check incidents before reading arbitrary source files.",
+            "Check incidents before reading arbitrary source files for qualifying runtime or production incidents.",
             "Read the skill workflow before proposing a fix."
           ]
         },
+        {
+          name: "local_source_issue_gate",
+          prompt: "The user reports a deterministic UI calculation glitch in local code with no runtime incident or report. Confirm the skill avoids checking DebugBundle incidents by default.",
+          expected_behavior: [
+            "Inspect source and tests first for deterministic local UI, layout, copy, calculation, refactor, or test-only issues.",
+            "Do not check DebugBundle incidents unless the user asks, live runtime behavior is involved, or captured evidence is needed."
+          ]
+        },
         {
           name: "profile_validation_task",
           prompt: "The generated profile is shallow. Confirm the skill teaches the agent how to validate and enrich it.",
@@ -22122,11 +22156,19 @@ var STORAGE_BOOTSTRAP_STATEMENTS = [
       channel text NOT NULL,
       condition_type text NOT NULL,
       severity_min text,
+      severity_lifecycle_scope text,
       cooldown_seconds integer NOT NULL DEFAULT 0,
       config jsonb NOT NULL DEFAULT '{}'::jsonb,
       is_enabled boolean NOT NULL DEFAULT true,
       created_at timestamptz NOT NULL DEFAULT now(),
-      updated_at timestamptz NOT NULL DEFAULT now()
+      updated_at timestamptz NOT NULL DEFAULT now(),
+      CONSTRAINT alert_rules_severity_lifecycle_scope_check CHECK (
+        severity_lifecycle_scope IS NULL
+        OR (
+          condition_type = 'severity_threshold'
+          AND severity_lifecycle_scope IN ('new_incident', 'incident_regressed', 'both')
+        )
+      )
     )
   `,
   `
@@ -23681,6 +23723,36 @@ var STORAGE_SCHEMA_MIGRATIONS = [
         )
       `
     ]
+  }),
+  defineStorageSchemaMigration({
+    id: "202606260001_add_alert_severity_lifecycle_scope",
+    description: "Add lifecycle scope for severity-threshold alert rules so new incidents and regressions can notify independently.",
+    statements: [
+      "ALTER TABLE alert_rules ADD COLUMN IF NOT EXISTS severity_lifecycle_scope text",
+      `
+        UPDATE alert_rules
+        SET severity_lifecycle_scope = 'both'
+        WHERE condition_type = 'severity_threshold'
+          AND severity_lifecycle_scope IS NULL
+      `,
+      `
+        UPDATE alert_rules
+        SET severity_lifecycle_scope = NULL
+        WHERE condition_type <> 'severity_threshold'
+          AND severity_lifecycle_scope IS NOT NULL
+      `,
+      "ALTER TABLE alert_rules DROP CONSTRAINT IF EXISTS alert_rules_severity_lifecycle_scope_check",
+      `
+        ALTER TABLE alert_rules
+        ADD CONSTRAINT alert_rules_severity_lifecycle_scope_check CHECK (
+          severity_lifecycle_scope IS NULL
+          OR (
+            condition_type = 'severity_threshold'
+            AND severity_lifecycle_scope IN ('new_incident', 'incident_regressed', 'both')
+          )
+        )
+      `
+    ]
   })
 ];
 
@@ -27050,6 +27122,9 @@ function createAlertMcpTools(api) {
         if (typeof input["severityMin"] === "string") {
           requestInput.severityMin = input["severityMin"];
         }
+        if (typeof input["severityLifecycleScope"] === "string") {
+          requestInput.severityLifecycleScope = input["severityLifecycleScope"];
+        }
         if (typeof input["cooldownSeconds"] === "number") {
           requestInput.cooldownSeconds = input["cooldownSeconds"];
         }
@@ -27084,6 +27159,11 @@ function createAlertMcpTools(api) {
         } else if (input["severityMin"] === null) {
           requestInput.severityMin = null;
         }
+        if (typeof input["severityLifecycleScope"] === "string") {
+          requestInput.severityLifecycleScope = input["severityLifecycleScope"];
+        } else if (input["severityLifecycleScope"] === null) {
+          requestInput.severityLifecycleScope = null;
+        }
         if (typeof input["cooldownSeconds"] === "number") {
           requestInput.cooldownSeconds = input["cooldownSeconds"];
         }
@@ -30611,9 +30691,9 @@ var zodToJsonSchema = (schema, options) => {
 var package_default = {
   name: "@debugbundle/mcp",
   mcpName: "com.debugbundle/mcp",
-  version: "1.6.0",
+  version: "1.6.2",
   private: false,
-  description: "Model Context Protocol server for DebugBundle",
+  description: "MCP server for production debugging bundles and incident workflows for AI agents",
   license: "AGPL-3.0-only",
   repository: {
     type: "git",
@@ -30624,7 +30704,18 @@ var package_default = {
   bugs: {
     url: "https://github.com/debugbundle/debugbundle/issues"
   },
-  keywords: ["debugbundle", "debugging", "ai-agent", "mcp", "model-context-protocol"],
+  keywords: [
+    "debugbundle",
+    "debugging",
+    "production-debugging",
+    "incident-management",
+    "debug-bundles",
+    "ai-agent",
+    "ai-agent-debugging",
+    "mcp",
+    "model-context-protocol",
+    "observability"
+  ],
   engines: {
     node: ">=22 <27"
   },
@@ -31362,7 +31453,7 @@ var MCP_TOOL_CATALOG = [
   {
     name: "create_alert",
     group: "alerts",
-    description: "Create an alert rule.",
+    description: "Create an alert rule, including optional severity-threshold lifecycle scope.",
     inputSchema: external_exports.object({
       bearerToken: external_exports.string(),
       projectId: external_exports.string(),
@@ -31370,6 +31461,7 @@ var MCP_TOOL_CATALOG = [
       channel: external_exports.string(),
       conditionType: external_exports.string(),
       severityMin: external_exports.string().optional(),
+      severityLifecycleScope: external_exports.enum(["new_incident", "incident_regressed", "both"]).optional(),
       cooldownSeconds: external_exports.number().int().min(0).max(604800).optional(),
       config: jsonObjectSchema,
       isEnabled: external_exports.boolean().optional()
@@ -31378,7 +31470,7 @@ var MCP_TOOL_CATALOG = [
   {
     name: "update_alert",
     group: "alerts",
-    description: "Update an alert rule.",
+    description: "Update an alert rule, including optional severity-threshold lifecycle scope.",
     inputSchema: external_exports.object({
       bearerToken: external_exports.string(),
       projectId: external_exports.string(),
@@ -31387,6 +31479,7 @@ var MCP_TOOL_CATALOG = [
       channel: external_exports.string().optional(),
       conditionType: external_exports.string().optional(),
       severityMin: external_exports.string().nullable().optional(),
+      severityLifecycleScope: external_exports.enum(["new_incident", "incident_regressed", "both"]).nullable().optional(),
       cooldownSeconds: external_exports.number().int().min(0).max(604800).optional(),
       config: jsonObjectSchema.nullable().optional(),
       isEnabled: external_exports.boolean().optional()

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@debugbundle/mcp",
   "mcpName": "com.debugbundle/mcp",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "private": false,
-  "description": "Model Context Protocol server for DebugBundle",
+  "description": "MCP server for production debugging bundles and incident workflows for AI agents",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
@@ -14,7 +14,18 @@
   "bugs": {
     "url": "https://github.com/debugbundle/debugbundle/issues"
   },
-  "keywords": ["debugbundle", "debugging", "ai-agent", "mcp", "model-context-protocol"],
+  "keywords": [
+    "debugbundle",
+    "debugging",
+    "production-debugging",
+    "incident-management",
+    "debug-bundles",
+    "ai-agent",
+    "ai-agent-debugging",
+    "mcp",
+    "model-context-protocol",
+    "observability"
+  ],
   "engines": {
     "node": ">=22 <27"
   },

package/server.json

@@ -2,19 +2,19 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "com.debugbundle/mcp",
   "title": "DebugBundle",
-  "description": "Investigate DebugBundle incidents, bundles, reproductions, hosted health checks, probes, alerts, webhooks, projects, members, billing, GitHub automation, and local setup from MCP clients.",
+  "description": "DebugBundle MCP server for incidents, bundles, reproductions, health checks, probes, and ops.",
   "repository": {
     "url": "https://github.com/debugbundle/debugbundle",
     "source": "github",
     "subfolder": "apps/mcp"
   },
-  "version": "1.6.0",
+  "version": "1.6.2",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@debugbundle/mcp",
-      "version": "1.6.0",
+      "version": "1.6.2",
       "transport": {
         "type": "stdio"
       },