@smartbear/mcp 0.10.0 → 0.12.0

package/dist/bugsnag/input-schemas.js

@@ -0,0 +1,59 @@
+import z from "zod";
+const filterValueSchema = z.object({
+    type: z.enum(["eq", "ne", "empty"]),
+    value: z.union([z.string(), z.boolean(), z.number()]),
+});
+const filtersSchema = z.record(z.array(filterValueSchema));
+/**
+ * A collection of input parameter schemas for reuse between tools.
+ * Add new entries when common parameters are identified.
+ */
+export const toolInputParameters = {
+    empty: z.object({}).describe("No parameters are required for this tool"),
+    buildId: z.string().describe("Unique identifier of the app build"),
+    errorId: z.string().describe("Unique identifier of the error"),
+    eventId: z.string().describe("Unique identifier of the event"),
+    projectId: z
+        .string()
+        .optional()
+        .describe("Unique identifier of the project. This is optional if a current project is set and is used to set the current project for BugSnag tools."),
+    releaseId: z.string().describe("Unique identifier of the app release"),
+    direction: z
+        .enum(["asc", "desc"])
+        .describe("Sort direction for ordering results")
+        .default("desc"),
+    performanceFilters: filtersSchema
+        .describe("Apply filters to narrow down the span group list. Use the List Trace Fields tool to discover available filter fields. " +
+        "Time filters support extended ISO 8601 format (e.g. 2018-05-20T00:00:00Z) or relative format (e.g. 7d, 24h).")
+        .default({
+        "span.since": [{ type: "eq", value: "7d" }],
+    }),
+    filters: filtersSchema
+        .describe("Apply filters to narrow down the error list. Use the List Project Event Filters tool to discover available filter fields. " +
+        "Time filters support extended ISO 8601 format (e.g. 2018-05-20T00:00:00Z) or relative format (e.g. 7d, 24h).")
+        .default({
+        "event.since": [{ type: "eq", value: "30d" }],
+        "error.status": [{ type: "eq", value: "open" }],
+    }),
+    nextUrl: z
+        .string()
+        .describe("URL for retrieving the next page of results. Use the value in the previous response to get the next page when more results are available. " +
+        "Only values provided in the output from this tool can be used. Do not attempt to construct it manually.")
+        .optional(),
+    page: z.number().describe("Page number to return (starts from 1)").default(1),
+    perPage: z
+        .number()
+        .describe("How many results to return per page.")
+        .min(1)
+        .max(100)
+        .default(30),
+    releaseStage: z
+        .string()
+        .describe("Filter releases by this stage (e.g. production, staging), defaults to 'production'")
+        .default("production"),
+    sort: z
+        .enum(["first_seen", "last_seen", "events", "users", "unsorted"])
+        .describe("Field to sort the errors by")
+        .default("last_seen"),
+    spanGroupId: z.string().describe("ID of the span group"),
+};

package/dist/collaborator/client.js

@@ -1,14 +1,24 @@
 import { z } from "zod";
+const ConfigurationSchema = z.object({
+    base_url: z.string().url().describe("Collaborator server base URL"),
+    username: z.string().describe("Collaborator username for authentication"),
+    login_ticket: z
+        .string()
+        .describe("Collaborator login ticket for authentication"),
+});
 export class CollaboratorClient {
     name = "Collaborator";
-    prefix = "collaborator";
+    toolPrefix = "collaborator";
+    configPrefix = "Collaborator";
+    config = ConfigurationSchema;
     baseUrl;
     username;
     loginTicket;
-    constructor(baseUrl, username, loginTicket) {
-        this.baseUrl = baseUrl;
-        this.username = username;
-        this.loginTicket = loginTicket;
+    async configure(_server, config, _cache) {
+        this.baseUrl = config.base_url;
+        this.username = config.username;
+        this.loginTicket = config.login_ticket;
+        return true;
     }
     /**
      * Calls the Collaborator API with the given commands, prepending authentication automatically.
@@ -16,6 +26,9 @@ export class CollaboratorClient {
      * @returns Raw Collaborator API response
      */
     async call(commands) {
+        if (!this.baseUrl || !this.username || !this.loginTicket) {
+            throw new Error("Collaborator client not configured");
+        }
         const url = `${this.baseUrl}/services/json/v1`;
         // Always prepend authentication command automatically
         const body = [

package/dist/common/cache.js

@@ -0,0 +1,63 @@
+import NodeCache from "node-cache";
+/**
+ * Common cache service that can be shared across all clients.
+ * Wraps NodeCache and provides a way to disable caching entirely.
+ * Reads CACHE_ENABLED and CACHE_TTL environment variables for configuration.
+ */
+export class CacheService {
+    cache;
+    enabled;
+    constructor() {
+        // Read configuration from environment variables
+        this.enabled = process.env.CACHE_ENABLED !== "false";
+        const ttl = process.env.CACHE_TTL
+            ? Number.parseInt(process.env.CACHE_TTL, 10)
+            : 86400; // Default 24 hours
+        this.cache = this.enabled
+            ? new NodeCache({
+                stdTTL: ttl,
+            })
+            : null;
+    }
+    /**
+     * Get a value from the cache
+     */
+    get(key) {
+        if (!this.enabled || !this.cache) {
+            return undefined;
+        }
+        return this.cache.get(key);
+    }
+    /**
+     * Set a value in the cache
+     */
+    set(key, value) {
+        if (!this.enabled || !this.cache) {
+            return false;
+        }
+        return this.cache.set(key, value);
+    }
+    /**
+     * Delete a value from the cache
+     */
+    del(key) {
+        if (!this.enabled || !this.cache) {
+            return 0;
+        }
+        return this.cache.del(key);
+    }
+    /**
+     * Check if caching is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Clear all cache entries
+     */
+    flushAll() {
+        if (this.enabled && this.cache) {
+            this.cache.flushAll();
+        }
+    }
+}

package/dist/common/client-registry.js

@@ -0,0 +1,128 @@
+import { ZodOptional, ZodString } from "zod";
+/**
+ * Central registry for all MCP clients
+ * Add new clients here to make them automatically available
+ */
+class ClientRegistry {
+    entries = [];
+    enabledClients = null;
+    /**
+     * Configure which clients should be enabled based on MCP_CLIENTS env var
+     * If not set or empty, all clients are enabled
+     * If set, should be comma-separated list of client names (case-insensitive)
+     */
+    constructor() {
+        const enabledClientsEnv = process.env.MCP_CLIENTS?.trim();
+        if (!enabledClientsEnv) {
+            // Empty or not set = all clients enabled
+            this.enabledClients = null;
+            return;
+        }
+        // Parse comma-separated list and normalize to lowercase for comparison
+        this.enabledClients = new Set(enabledClientsEnv
+            .split(",")
+            .map((name) => name.trim().toLowerCase())
+            .filter((name) => name.length > 0));
+    }
+    /**
+     * Check if a client is enabled based on MCP_CLIENTS configuration
+     */
+    isClientEnabled(name) {
+        if (this.enabledClients === null) {
+            return true; // All clients enabled
+        }
+        return this.enabledClients.has(name.toLowerCase());
+    }
+    /**
+     * Validate if a config option is an Allowed Endpoint URL
+     * Supports both exact matches and regex patterns
+     * Patterns starting with / and ending with / are treated as regex
+     * @param zodType The Zod type definition for the config option
+     * @param value The actual config value to validate
+     */
+    validateAllowedEndpoint(zodType, value) {
+        if (zodType instanceof ZodOptional) {
+            zodType = zodType._def.innerType;
+        }
+        if (zodType instanceof ZodString) {
+            if (zodType.isURL) {
+                const allowedEndpoints = process.env.MCP_ALLOWED_ENDPOINTS?.split(",");
+                if (allowedEndpoints) {
+                    for (const endpoint of allowedEndpoints) {
+                        const trimmedEndpoint = endpoint.trim();
+                        // Check if this is a regex pattern (wrapped in /)
+                        if (trimmedEndpoint.startsWith("/") &&
+                            trimmedEndpoint.endsWith("/")) {
+                            try {
+                                const pattern = trimmedEndpoint.slice(1, -1); // Remove leading/trailing /
+                                const regex = new RegExp(pattern);
+                                if (regex.test(value)) {
+                                    return;
+                                }
+                            }
+                            catch (error) {
+                                console.warn(`Invalid regex pattern in MCP_ALLOWED_ENDPOINTS: ${trimmedEndpoint}, error: ${error}`);
+                            }
+                        }
+                        else {
+                            // Exact match
+                            if (value === trimmedEndpoint) {
+                                return;
+                            }
+                        }
+                    }
+                    throw new Error(`URL ${value} is not allowed`);
+                }
+            }
+        }
+    }
+    /**
+     * Register a client class
+     * @param name Display name for the client (for logging)
+     */
+    register(client) {
+        this.entries.push(client);
+    }
+    /**
+     * Get all registered clients (filtered by MCP_CLIENTS if configured)
+     */
+    getAll() {
+        return this.entries.filter((entry) => this.isClientEnabled(entry.name));
+    }
+    /**
+     * Configures all enabled clients on the given MCP server
+     * @param server The MCP server on which the client is registered
+     * @param getConfigValue A function that obtains a configuration value for the given client and requirement name
+     * @returns The number of clients successfully configured
+     */
+    async configure(server, getConfigValue) {
+        let configuredCount = 0;
+        entryLoop: for (const entry of this.getAll()) {
+            const config = {};
+            for (const configKey of Object.keys(entry.config.shape)) {
+                const value = getConfigValue(entry, configKey);
+                if (value !== null) {
+                    // validate if a config option is an Allowed Endpoint URL
+                    this.validateAllowedEndpoint(entry.config.shape[configKey], value);
+                    config[configKey] = value;
+                }
+                else if (!entry.config.shape[configKey].isOptional()) {
+                    continue entryLoop; // Skip configuring this client - missing required config
+                }
+            }
+            if (await entry.configure(server, config)) {
+                server.addClient(entry);
+                configuredCount++;
+            }
+        }
+        return configuredCount;
+    }
+    /**
+     * Clear all registrations (useful for testing)
+     */
+    clear() {
+        this.entries = [];
+    }
+}
+// Create and export the singleton registry
+export const clientRegistry = new ClientRegistry();

package/dist/common/register-clients.js

@@ -0,0 +1,31 @@
+/**
+ * Client registration module
+ *
+ * This file registers all available MCP clients with the client registry.
+ * To add a new client:
+ * 1. Import the client class
+ * 2. Call clientRegistry.register() with the client details
+ * 3. Specify if the client needs the MCP server instance or async initialization
+ */
+import { BugsnagClient } from "../bugsnag/client.js";
+import { CollaboratorClient } from "../collaborator/client.js";
+import { PactflowClient } from "../pactflow/client.js";
+import { QmetryClient } from "../qmetry/client.js";
+import { ReflectClient } from "../reflect/client.js";
+import { SwaggerClient } from "../swagger/client.js";
+import { ZephyrClient } from "../zephyr/client.js";
+import { clientRegistry } from "./client-registry.js";
+// Register Reflect client
+clientRegistry.register(new ReflectClient());
+// Register Bugsnag client
+clientRegistry.register(new BugsnagClient());
+// Register Swagger client
+clientRegistry.register(new SwaggerClient());
+// Register PactFlow/Pact Broker client
+clientRegistry.register(new PactflowClient());
+// Register QMetry client
+clientRegistry.register(new QmetryClient());
+// Register Zephyr client
+clientRegistry.register(new ZephyrClient());
+// Register Collaborator client
+clientRegistry.register(new CollaboratorClient());

package/dist/common/server.js

@@ -1,9 +1,11 @@
 import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ZodAny, ZodArray, ZodBoolean, ZodEnum, ZodIntersection, ZodLiteral, ZodNumber, ZodObject, ZodOptional, ZodString, ZodUnion, } from "zod";
+import { ZodAny, ZodArray, ZodBoolean, ZodDefault, ZodEnum, ZodIntersection, ZodLiteral, ZodNumber, ZodObject, ZodOptional, ZodRecord, ZodString, ZodUnion, } from "zod";
 import Bugsnag from "../common/bugsnag.js";
+import { CacheService } from "./cache.js";
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "./info.js";
 import { ToolError } from "./types.js";
 export class SmartBearMcpServer extends McpServer {
+    cache;
     constructor() {
         super({
             name: MCP_SERVER_NAME,
@@ -18,10 +20,14 @@ export class SmartBearMcpServer extends McpServer {
                 prompts: {}, // Server supports sending prompts to Host
             },
         });
+        this.cache = new CacheService();
+    }
+    getCache() {
+        return this.cache;
     }
     addClient(client) {
         client.registerTools((params, cb) => {
-            const toolName = `${client.prefix}_${params.title.replace(/\s+/g, "_").toLowerCase()}`;
+            const toolName = `${client.toolPrefix}_${params.title.replace(/\s+/g, "_").toLowerCase()}`;
             const toolTitle = `${client.name}: ${params.title}`;
             return super.registerTool(toolName, {
                 title: toolTitle,
@@ -65,7 +71,7 @@ export class SmartBearMcpServer extends McpServer {
         });
         if (client.registerResources) {
             client.registerResources((name, path, cb) => {
-                const url = `${client.prefix}://${name}/${path}`;
+                const url = `${client.toolPrefix}://${name}/${path}`;
                 return super.registerResource(name, new ResourceTemplate(url, {
                     list: undefined,
                 }), {}, async (url, variables, extra) => {
@@ -184,16 +190,31 @@ export class SmartBearMcpServer extends McpServer {
         }
         return description.trim();
     }
-    formatParameterDescription(key, field) {
+    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.removeDefault();
+            return this.formatParameterDescription(key, field, description, true, defaultValue);
+        }
         return (`- ${key} (${this.getReadableTypeName(field)})` +
-            `${field.isOptional() ? "" : " *required*"}` +
-            `${field.description ? `: ${field.description}` : ""}` +
-            `${key === "examples" && field instanceof ZodEnum ? ` (e.g. ${Object.keys(field.enum).join(", ")})` : ""}` +
-            `${key === "constraints" && field instanceof ZodEnum ? `\n  - ${Object.keys(field.enum).join("\n  - ")}` : ""}`);
+            `${isOptional ? "" : " *required*"}` +
+            `${description ? `: ${description}` : ""}` +
+            `${defaultValue ? ` (default: ${defaultValue})` : ""}`);
     }
     getReadableTypeName(zodType) {
         if (zodType instanceof ZodOptional) {
-            zodType = zodType._def.innerType;
+            return this.getReadableTypeName(zodType.unwrap());
+        }
+        if (zodType instanceof ZodDefault) {
+            return this.getReadableTypeName(zodType.removeDefault());
+        }
+        if (zodType instanceof ZodRecord) {
+            return `record<${this.getReadableTypeName(zodType.keySchema)}, ${this.getReadableTypeName(zodType.valueSchema)}>`;
         }
         if (zodType instanceof ZodString)
             return "string";