@smartbear/mcp 0.19.2 → 0.20.0

package/README.md

@@ -38,6 +38,19 @@ See individual guides for suggested prompts and supported tools and resources:
 - [Zephyr](https://developer.smartbear.com/smartbear-mcp/docs/zephyr-integration) - Zephyr Test Management capabilities
 - [Collaborator](https://developer.smartbear.com/smartbear-mcp/docs/collaborator-integration) - Review and Remote System Configuration management capabilities
 
+## Remote MCP Servers
+
+For BugSnag, Swagger, and Zephyr, SmartBear hosts Remote MCP Servers that you can connect to directly from your MCP client via a URL — no installation, Node.js, or API tokens required. Authentication is handled through an OAuth browser flow.
+
+| Product | Server URL |
+|---|---|
+| **Swagger** | `https://swagger.mcp.smartbear.com/mcp` |
+| **BugSnag** | `https://bugsnag.mcp.smartbear.com/mcp` |
+| **Zephyr** | `https://zephyr.mcp.smartbear.com/mcp` |
+
+See the [Remote MCP Servers guide](https://developer.smartbear.com/smartbear-mcp/docs/remote-mcp-servers) for per-client setup instructions. You can connect to multiple remote servers at the same time.
+
+> **Need Reflect, QMetry, PactFlow, or Collaborator?** These products are only available via the local npm package below, which bundles all products into a single MCP server.
 
 ## Prerequisites
 
@@ -45,9 +58,9 @@ See individual guides for suggested prompts and supported tools and resources:
 - Access to SmartBear products (BugSnag, Reflect, Swagger, QMetry, or Zephyr)
 - Valid API tokens for the products you want to integrate
 
-## Installation
+## Local MCP Server Installation (npm)
 
-The MCP server is distributed as an npm package [`@smartbear/mcp`](https://www.npmjs.com/package/@smartbear/mcp), making it easy to integrate into your development workflow.
+For all products — or if you prefer running the server locally — the MCP server is distributed as an npm package [`@smartbear/mcp`](https://www.npmjs.com/package/@smartbear/mcp), making it easy to integrate into your development workflow.
 
 The server is started with the API key or auth token that you use with your SmartBear product(s). They are optional and can be removed from your configuration if you aren't using the product. For BugSnag, if you provide a project API key it will narrow down all searches to a single project in your BugSnag dashboard. Leave this field blank if you wish to interact across multiple projects at a time.
 

package/dist/bugsnag/client.js

@@ -70,7 +70,7 @@ class BugsnagClient {
     return this._appEndpoint;
   }
   name = "BugSnag";
-  toolPrefix = "bugsnag";
+  capabilityPrefix = "bugsnag";
   configPrefix = "Bugsnag";
   config = ConfigurationSchema;
   async configure(server, config) {
@@ -329,17 +329,24 @@ class BugsnagClient {
       register(tool.specification, tool.handle);
     }
   }
-  registerResources(register) {
-    register("event", "{id}", async (uri, variables, _extra) => {
-      return {
-        contents: [
-          {
-            uri: uri.href,
-            text: JSON.stringify(await this.getEvent(variables.id))
-          }
-        ]
-      };
-    });
+  async registerResources(register) {
+    register(
+      {
+        title: "Event",
+        path: "{id}",
+        description: "Retrieve a specific event by its ID."
+      },
+      async (uri, variables, _extra) => {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              text: JSON.stringify(await this.getEvent(variables.id))
+            }
+          ]
+        };
+      }
+    );
   }
 }
 export {

package/dist/collaborator/client.js

@@ -7,7 +7,7 @@ const ConfigurationSchema = z.object({
 });
 class CollaboratorClient {
   name = "Collaborator";
-  toolPrefix = "collaborator";
+  capabilityPrefix = "collaborator";
   configPrefix = "Collaborator";
   config = ConfigurationSchema;
   baseUrl;
@@ -63,7 +63,7 @@ class CollaboratorClient {
   async registerTools(register, _getInput) {
     register(
       {
-        title: "Find Collaborator Review By ID",
+        title: "Find Review By ID",
         summary: "Finds a review in Collaborator by its review ID.",
         inputSchema: z.object({
           reviewId: z.string().describe("The Collaborator review ID to find.")
@@ -85,7 +85,7 @@ class CollaboratorClient {
     );
     register(
       {
-        title: "Create Collaborator Review",
+        title: "Create Review",
         summary: "Creates a new review in Collaborator. All parameters are optional.",
         inputSchema: z.object({
           creator: z.string().optional().describe(
@@ -122,7 +122,7 @@ class CollaboratorClient {
     );
     register(
       {
-        title: "Reject Collaborator Review",
+        title: "Reject Review",
         summary: "Rejects a review in Collaborator by its review ID and reason.",
         inputSchema: z.object({
           reviewId: z.union([z.string(), z.number()]).describe("The Collaborator review ID to reject."),
@@ -171,7 +171,7 @@ class CollaboratorClient {
     );
     register(
       {
-        title: "Get Collaborator Reviews",
+        title: "Get Reviews",
         summary: "Retrieves reviews from Collaborator using ReviewService.getReviews. All parameters are optional and only provided ones are sent.",
         inputSchema: z.object({
           login: z.string().optional().describe("Collaborator username to filter reviews."),
@@ -207,7 +207,7 @@ class CollaboratorClient {
     );
     register(
       {
-        title: "Create Collaborator Remote System Configuration",
+        title: "Create Remote System Configuration",
         summary: "Creates a remote system configuration in Collaborator (e.g., Bitbucket, GitHub, etc).",
         inputSchema: z.object({
           token: z.string().describe("Remote system token, e.g., BITBUCKET, GITHUB, etc."),
@@ -238,7 +238,7 @@ class CollaboratorClient {
     );
     register(
       {
-        title: "Edit Collaborator Remote System Configuration",
+        title: "Edit Remote System Configuration",
         summary: "Edits parameters of an existing remote system configuration in Collaborator. Only title and config are editable after creation.",
         inputSchema: z.object({
           id: z.string().describe("ID of the remote system Configuration to edit."),
@@ -271,7 +271,7 @@ class CollaboratorClient {
     );
     register(
       {
-        title: "Delete Collaborator Remote System Configuration",
+        title: "Delete Remote System Configuration",
         summary: "Deletes a remote system configuration in Collaborator by its ID.",
         inputSchema: z.object({
           id: z.union([z.string(), z.number()]).describe("ID of the remote system Configuration to delete.")
@@ -295,7 +295,7 @@ class CollaboratorClient {
     );
     register(
       {
-        title: "Update Collaborator Remote System Configuration Webhook",
+        title: "Update Remote System Configuration Webhook",
         summary: "Updates the webhook for a remote system configuration in Collaborator by its ID.",
         inputSchema: z.object({
           id: z.union([z.string(), z.number()]).describe(
@@ -321,7 +321,7 @@ class CollaboratorClient {
     );
     register(
       {
-        title: "Test Collaborator Remote System Configuration Connection",
+        title: "Test Remote System Configuration Connection",
         summary: "Tests the connection for a remote system configuration in Collaborator by its ID.",
         inputSchema: z.object({
           id: z.union([z.string(), z.number()]).describe(

package/dist/common/client-registry.js

@@ -1,5 +1,5 @@
 import { ZodURL } from "zod";
-import { unwrapZodType, isOptionalType } from "./zod-utils.js";
+import { fullyUnwrapZodType, isOptionalType } from "./zod-utils.js";
 class ClientRegistry {
   entries = [];
   enabledClients = null;
@@ -35,7 +35,7 @@ class ClientRegistry {
    * @param value The actual config value to validate
    */
   validateAllowedEndpoint(zodType, value) {
-    if (unwrapZodType(zodType) instanceof ZodURL) {
+    if (fullyUnwrapZodType(zodType) instanceof ZodURL) {
       const allowedEndpoints = process.env.MCP_ALLOWED_ENDPOINTS?.split(",");
       if (allowedEndpoints) {
         for (const endpoint of allowedEndpoints) {

package/dist/common/server.js

@@ -1,11 +1,11 @@
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ZodObject, ZodIntersection, ZodOptional, ZodDefault, ZodRecord, ZodString, ZodNumber, ZodBoolean, ZodArray, ZodEnum, ZodLiteral, ZodUnion, ZodAny } from "zod";
+import { ZodObject, ZodIntersection } from "zod";
 import Bugsnag from "./bugsnag.js";
 import { CacheService } from "./cache.js";
 import { MCP_SERVER_VERSION, MCP_SERVER_NAME } from "./info.js";
 import { executeElicitationOrPolyfill, isElicitationPolyfillResult } from "./pollyfills.js";
 import { ToolError } from "./tools.js";
-import { unwrapZodType } from "./zod-utils.js";
+import { getTypeDescription, getDefaultValue, getReadableTypeName, isOptionalType } from "./zod-utils.js";
 class SmartBearMcpServer extends McpServer {
   cache;
   samplingSupported = false;
@@ -18,24 +18,15 @@ class SmartBearMcpServer extends McpServer {
         version: MCP_SERVER_VERSION
       },
       {
-        instructions: `When creating or editing a Reflect test using a connected recording session, follow these guidelines:
-
-1. After connecting to a session, get the list of segments for the session's platform type so you know what actions could be added via segments vs needing to create new steps. Do not list tests, only list segments.
-2. Before performing an action, take a screenshot to understand the current state of the application.
-3. Each add_prompt_step request should perform a single action or assertion. Do not combine multiple actions or assertions into a single step.
-4. Only perform one action at a time unless you're sure the action won't move the application to a different screen. For example, you can send multiple add_prompt_step requests to fill out individual form fields if those fields are visible on the current screen.
-5. Check the list of existing Segments to see if a Segment exists that achieves a similar goal to what you're trying to do next. If so, add the segment instead of creating new steps.
-6. If a step fails, use delete_previous_step to remove it and try a different approach.
-7. After completing a task, if the task required multiple prompt steps, add a final prompt step that validates the current state of the page based on what you see on the screen. In your validation, do not reference information that can change from run to run.`,
         capabilities: {
-          resources: { listChanged: true },
-          // Server supports dynamic resource lists
           tools: { listChanged: true },
           // Server supports dynamic tool lists
-          logging: {},
-          // Server supports logging messages
-          prompts: {}
+          resources: { listChanged: true },
+          // Server supports dynamic resource lists
+          prompts: { listChanged: true },
           // Server supports sending prompts to Host
+          logging: {}
+          // Server supports logging messages
         }
       }
     );
@@ -68,15 +59,20 @@ class SmartBearMcpServer extends McpServer {
     this.clients.push(client);
     await client.registerTools(
       (params, cb) => {
-        const toolName = `${client.toolPrefix}_${params.title.replace(/\s+/g, "_").toLowerCase()}`;
-        const toolTitle = `${client.name}: ${params.title}`;
+        const toolName = this.getCapabilityName(client, params.title);
+        const toolTitle = this.getCapabilityTitle(client, params.title);
+        if (toolName.length > 64) {
+          throw new ToolError(
+            `The tool name "${toolName}" is too long. Tool names must be 64 characters or fewer for client compatibility. https://github.com/anthropics/claude-code/issues/34960`
+          );
+        }
         return super.registerTool(
           toolName,
           {
             title: toolTitle,
             description: this.getDescription(params),
-            inputSchema: this.getInputSchema(params),
-            outputSchema: this.getOutputSchema(params),
+            inputSchema: params.inputSchema ? this.schemaToRawShape(params.inputSchema) : {},
+            outputSchema: this.schemaToRawShape(params.outputSchema),
             annotations: this.getAnnotations(toolTitle, params)
           },
           async (args, extra) => {
@@ -104,13 +100,10 @@ class SmartBearMcpServer extends McpServer {
                   ]
                 };
               } else {
-                Bugsnag.notify(
-                  e,
-                  (event) => {
-                    event.addMetadata("app", { tool: toolName });
-                    event.unhandled = true;
-                  }
-                );
+                Bugsnag.notify(e, (event) => {
+                  event.addMetadata("app", { tool: toolName });
+                  event.unhandled = true;
+                });
               }
               throw e;
             }
@@ -137,25 +130,30 @@ ${result.instructions}`
       }
     );
     if (client.registerResources) {
-      client.registerResources((name, path, cb) => {
-        const url = `${client.toolPrefix}://${name}/${path}`;
+      await client.registerResources((params, cb) => {
+        const resourceName = this.getCapabilityName(client, params.title);
+        const slug = params.title.replace(/\s+/g, "_").toLowerCase();
+        const url = `${client.capabilityPrefix}://${slug}/${params.path}`;
         return super.registerResource(
-          name,
+          resourceName,
           new ResourceTemplate(url, {
             list: void 0
           }),
-          {},
+          {
+            title: this.getCapabilityTitle(client, params.title),
+            description: params.description
+          },
           async (url2, variables, extra) => {
             try {
               return await cb(url2, variables, extra);
             } catch (e) {
-              Bugsnag.notify(
-                e,
-                (event) => {
-                  event.addMetadata("app", { resource: name, url: url2 });
-                  event.unhandled = true;
-                }
-              );
+              Bugsnag.notify(e, (event) => {
+                event.addMetadata("app", {
+                  resource: resourceName,
+                  url: url2
+                });
+                event.unhandled = true;
+              });
               throw e;
             }
           }
@@ -163,8 +161,28 @@ ${result.instructions}`
       });
     }
     if (client.registerPrompts) {
-      client.registerPrompts((name, config, cb) => {
-        return super.registerPrompt(name, config, cb);
+      await client.registerPrompts((params, cb) => {
+        return super.registerPrompt(
+          this.getCapabilityName(client, params.title),
+          {
+            title: this.getCapabilityTitle(client, params.title),
+            description: params.description,
+            argsSchema: this.schemaToRawShape(params.argsSchema) || {}
+          },
+          async (args, extra) => {
+            try {
+              return await cb(args, extra);
+            } catch (e) {
+              Bugsnag.notify(e, (event) => {
+                event.addMetadata("app", {
+                  prompt: this.getCapabilityName(client, params.title)
+                });
+                event.unhandled = true;
+              });
+              throw e;
+            }
+          }
+        );
       });
     }
   }
@@ -198,19 +216,6 @@ ${result.instructions}`
     };
     return annotations;
   }
-  getInputSchema(params) {
-    const args = {};
-    for (const param of params.parameters ?? []) {
-      args[param.name] = param.type;
-      if (param.description) {
-        args[param.name] = args[param.name].describe(param.description);
-      }
-      if (!param.required) {
-        args[param.name] = args[param.name].optional();
-      }
-    }
-    return { ...args, ...this.schemaToRawShape(params.inputSchema) };
-  }
   schemaToRawShape(schema) {
     if (schema) {
       if (schema instanceof ZodObject) {
@@ -228,34 +233,36 @@ ${result.instructions}`
     }
     return void 0;
   }
-  getOutputSchema(params) {
-    return this.schemaToRawShape(params.outputSchema);
+  getCapabilityTitle(client, title) {
+    return `${client.name}: ${title}`;
+  }
+  getCapabilityName(client, title) {
+    return `${client.capabilityPrefix}_${title.replace(/\s+/g, "_").toLowerCase()}`;
   }
   getDescription(params) {
     const {
       summary,
       useCases,
       examples,
-      parameters,
       inputSchema,
       hints,
       outputDescription
     } = params;
     let description = summary;
-    if ((parameters ?? []).length > 0) {
+    if (inputSchema && inputSchema instanceof ZodObject) {
+      let parameters = Object.keys(inputSchema.shape).map((key) => {
+        const field = inputSchema.shape[key];
+        const description2 = getTypeDescription(field);
+        const defaultValue = getDefaultValue(field);
+        return `- ${key} (${getReadableTypeName(field)})${isOptionalType(field) ? "" : " *required*"}${description2 ? `: ${description2}` : ""}${defaultValue !== null ? ` (default: ${JSON.stringify(defaultValue)})` : ""}`;
+      }).join("\n");
+      if (parameters.length === 0) {
+        parameters = "None";
+      }
       description += `
 
 **Parameters:**
-${parameters?.map(
-        (p) => `- ${p.name} (${this.getReadableTypeName(p.type)})${p.required ? " *required*" : ""}${p.description ? `: ${p.description}` : ""}${p.examples ? ` (e.g. ${p.examples.join(", ")})` : ""}${p.constraints ? `
-  - ${p.constraints.join("\n  - ")}` : ""}`
-      ).join("\n")}`;
-    }
-    if (inputSchema && inputSchema instanceof ZodObject) {
-      description += "\n\n**Parameters:**\n";
-      description += Object.keys(inputSchema.shape).map(
-        (key) => this.formatParameterDescription(key, inputSchema.shape[key])
-      ).join("\n");
+${parameters}`;
     }
     if (outputDescription) {
       description += `
@@ -286,50 +293,6 @@ Expected Output: ${ex.expectedOutput}` : ""}`
     }
     return description.trim();
   }
-  formatParameterDescription(key, field, description = null, isOptional = false, defaultValue = null) {
-    description = description ?? (field.description || null);
-    if (field instanceof ZodOptional) {
-      field = field.unwrap();
-      return this.formatParameterDescription(
-        key,
-        field,
-        description,
-        true,
-        defaultValue
-      );
-    }
-    if (field instanceof ZodDefault) {
-      defaultValue = JSON.stringify(
-        field.def.defaultValue
-      );
-      field = field.unwrap();
-      return this.formatParameterDescription(
-        key,
-        field,
-        description,
-        true,
-        defaultValue
-      );
-    }
-    return `- ${key} (${this.getReadableTypeName(field)})${isOptional ? "" : " *required*"}${description ? `: ${description}` : ""}${defaultValue ? ` (default: ${defaultValue})` : ""}`;
-  }
-  getReadableTypeName(zodType) {
-    zodType = unwrapZodType(zodType);
-    if (zodType instanceof ZodRecord) {
-      const record = zodType;
-      return `record<${this.getReadableTypeName(record.def.keyType)}, ${this.getReadableTypeName(record.def.valueType)}>`;
-    }
-    if (zodType instanceof ZodString) return "string";
-    if (zodType instanceof ZodNumber) return "number";
-    if (zodType instanceof ZodBoolean) return "boolean";
-    if (zodType instanceof ZodArray) return "array";
-    if (zodType instanceof ZodObject) return "object";
-    if (zodType instanceof ZodEnum) return "enum";
-    if (zodType instanceof ZodLiteral) return "literal";
-    if (zodType instanceof ZodUnion) return "union";
-    if (zodType instanceof ZodAny) return "any";
-    return "any";
-  }
 }
 export {
   SmartBearMcpServer

package/dist/common/shutdown.js

@@ -0,0 +1,165 @@
+const DEFAULT_TIMEOUT_MS = 25e3;
+function defaultTimeout() {
+  const fromEnv = process.env.MCP_SHUTDOWN_TIMEOUT_MS;
+  if (fromEnv) {
+    const parsed = Number.parseInt(fromEnv, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return DEFAULT_TIMEOUT_MS;
+}
+class ShutdownManager {
+  handlers = [];
+  state = "idle";
+  signalsInstalled = false;
+  installedSignalListeners = [];
+  signals;
+  timeoutMs;
+  proc;
+  exitFn;
+  logger;
+  constructor(options = {}) {
+    this.signals = options.signals ?? ["SIGTERM", "SIGINT"];
+    this.timeoutMs = options.timeoutMs ?? defaultTimeout();
+    this.proc = options.process ?? process;
+    this.exitFn = options.exit ?? ((code) => process.exit(code));
+    this.logger = options.logger ?? console;
+  }
+  /**
+   * Register a cleanup handler. Handlers run in LIFO order on shutdown,
+   * so subsystems registered later (closer to where they are used) tear
+   * down before subsystems registered earlier (closer to startup).
+   */
+  register(name, fn) {
+    if (this.state !== "idle") {
+      this.logger.warn(
+        `[MCP][shutdown] Refusing to register handler "${name}" — already ${this.state}`
+      );
+      return;
+    }
+    this.handlers.push({ name, fn });
+  }
+  /** True from the moment the first shutdown signal is received. */
+  isDraining() {
+    return this.state !== "idle";
+  }
+  /**
+   * Wire SIGTERM / SIGINT listeners. Idempotent — calling more than once
+   * is a no-op.
+   */
+  installSignalHandlers() {
+    if (this.signalsInstalled) return;
+    this.signalsInstalled = true;
+    for (const signal of this.signals) {
+      const listener = () => {
+        this.handleSignal(signal);
+      };
+      this.proc.on(signal, listener);
+      this.installedSignalListeners.push({ signal, listener });
+    }
+  }
+  /** Tear down installed signal listeners (test-only). */
+  uninstallSignalHandlers() {
+    for (const { signal, listener } of this.installedSignalListeners) {
+      this.proc.off(signal, listener);
+    }
+    this.installedSignalListeners = [];
+    this.signalsInstalled = false;
+  }
+  /**
+   * Run all registered handlers in LIFO order with the configured deadline.
+   * Returns the drain result without exiting the process — exposed for tests
+   * and for callers that want to log / report before exiting.
+   */
+  async drain() {
+    if (this.state === "complete") {
+      return { status: "clean", durationMs: 0, remainingHandlers: [] };
+    }
+    this.state = "draining";
+    const start = Date.now();
+    const reversed = [...this.handlers].reverse();
+    const remaining = new Set(reversed.map((h) => h.name));
+    this.logger.log(
+      `[MCP][shutdown] Draining ${reversed.length} handler(s), deadline ${this.timeoutMs}ms`
+    );
+    let timeoutHandle;
+    const drainPromise = (async () => {
+      for (const h of reversed) {
+        try {
+          await h.fn();
+        } catch (err) {
+          this.logger.error(
+            `[MCP][shutdown] Handler "${h.name}" threw during drain:`,
+            err
+          );
+        }
+        remaining.delete(h.name);
+      }
+    })();
+    const timeoutPromise = new Promise((resolve) => {
+      timeoutHandle = setTimeout(() => resolve("deadline"), this.timeoutMs);
+      timeoutHandle.unref?.();
+    });
+    const winner = await Promise.race([
+      drainPromise.then(() => "clean"),
+      timeoutPromise
+    ]);
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+    this.state = "complete";
+    const durationMs = Date.now() - start;
+    const remainingHandlers = [...remaining];
+    if (winner === "clean") {
+      this.logger.log(`[MCP][shutdown] Drained cleanly in ${durationMs}ms`);
+    } else {
+      this.logger.error(
+        `[MCP][shutdown] Deadline exceeded after ${durationMs}ms, ${remainingHandlers.length} handler(s) outstanding: ${remainingHandlers.join(", ") || "(none)"}`
+      );
+    }
+    return { status: winner, durationMs, remainingHandlers };
+  }
+  /** Exposed for tests; not part of the production call path. */
+  getState() {
+    return this.state;
+  }
+  handleSignal(signal) {
+    if (this.state === "draining") {
+      this.logger.warn(
+        `[MCP][shutdown] Received ${signal} while draining — forcing immediate exit(1)`
+      );
+      this.exitFn(1);
+      return;
+    }
+    if (this.state === "complete") {
+      this.exitFn(0);
+      return;
+    }
+    this.logger.log(`[MCP][shutdown] Received ${signal}, starting drain`);
+    this.drain().then((result) => {
+      this.exitFn(result.status === "clean" ? 0 : 1);
+    }).catch((err) => {
+      this.logger.error(
+        "[MCP][shutdown] Unexpected error from drain():",
+        err
+      );
+      this.exitFn(1);
+    });
+  }
+}
+const shutdownManager = new ShutdownManager();
+function registerShutdownHandler(name, fn) {
+  shutdownManager.register(name, fn);
+}
+function installSignalHandlers() {
+  shutdownManager.installSignalHandlers();
+}
+function isDraining() {
+  return shutdownManager.isDraining();
+}
+export {
+  ShutdownManager,
+  installSignalHandlers,
+  isDraining,
+  registerShutdownHandler,
+  shutdownManager
+};