@smartbear/mcp 0.7.0 → 0.9.0

package/dist/common/server.js

@@ -1,7 +1,8 @@
 import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ZodAny, ZodArray, ZodBoolean, ZodEnum, ZodLiteral, ZodNumber, ZodObject, ZodString, ZodUnion, } from "zod";
+import { ZodAny, ZodArray, ZodBoolean, ZodEnum, ZodLiteral, ZodNumber, ZodObject, ZodOptional, ZodString, ZodUnion, } from "zod";
 import Bugsnag from "../common/bugsnag.js";
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "./info.js";
+import { ToolError } from "./types.js";
 export class SmartBearMcpServer extends McpServer {
     constructor() {
         super({
@@ -32,7 +33,24 @@ export class SmartBearMcpServer extends McpServer {
                     return await cb(args, extra);
                 }
                 catch (e) {
-                    Bugsnag.notify(e);
+                    // ToolErrors should not be reported to BugSnag
+                    if (e instanceof ToolError) {
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Error executing ${toolTitle}: ${e.message}`,
+                                },
+                            ],
+                        };
+                    }
+                    else {
+                        Bugsnag.notify(e, (event) => {
+                            event.addMetadata("app", { tool: toolName });
+                            event.unhandled = true;
+                        });
+                    }
                     throw e;
                 }
             });
@@ -41,14 +59,18 @@ export class SmartBearMcpServer extends McpServer {
         });
         if (client.registerResources) {
             client.registerResources((name, path, cb) => {
-                return super.registerResource(name, new ResourceTemplate(`${client.prefix}://${name}/${path}`, {
+                const url = `${client.prefix}://${name}/${path}`;
+                return super.registerResource(name, new ResourceTemplate(url, {
                     list: undefined,
                 }), {}, async (url, variables, extra) => {
                     try {
                         return await cb(url, variables, extra);
                     }
                     catch (e) {
-                        Bugsnag.notify(e);
+                        Bugsnag.notify(e, (event) => {
+                            event.addMetadata("app", { resource: name, url: url });
+                            event.unhandled = true;
+                        });
                         throw e;
                     }
                 });
@@ -142,6 +164,9 @@ export class SmartBearMcpServer extends McpServer {
             `${key === "constraints" && field instanceof ZodEnum ? `\n  - ${Object.keys(field.enum).join("\n  - ")}` : ""}`);
     }
     getReadableTypeName(zodType) {
+        if (zodType instanceof ZodOptional) {
+            zodType = zodType._def.innerType;
+        }
         if (zodType instanceof ZodString)
             return "string";
         if (zodType instanceof ZodNumber)

package/dist/common/types.js

@@ -1 +1,6 @@
-export {};
+/**
+ * Error class for tool-specific errors – these result in a response to the LLM with `isError: true`
+ * and are not reported to BugSnag
+ */
+export class ToolError extends Error {
+}

package/dist/index.js

@@ -7,6 +7,7 @@ import { SmartBearMcpServer } from "./common/server.js";
 import { PactflowClient } from "./pactflow/client.js";
 import { QmetryClient } from "./qmetry/client.js";
 import { ReflectClient } from "./reflect/client.js";
+import { ZephyrClient } from "./zephyr/client.js";
 // This is used to report errors in the MCP server itself
 // If you want to use your own BugSnag API key, set the MCP_SERVER_BUGSNAG_API_KEY environment variable
 const McpServerBugsnagAPIKey = process.env.MCP_SERVER_BUGSNAG_API_KEY;
@@ -24,6 +25,8 @@ async function main() {
     const pactBrokerPassword = process.env.PACT_BROKER_PASSWORD;
     const qmetryToken = process.env.QMETRY_API_KEY;
     const qmetryBaseUrl = process.env.QMETRY_BASE_URL;
+    const zephyrToken = process.env.ZEPHYR_API_TOKEN;
+    const zephyrBaseUrl = process.env.ZEPHYR_BASE_URL;
     let client_defined = false;
     if (reflectToken) {
         server.addClient(new ReflectClient(reflectToken));
@@ -56,8 +59,12 @@ async function main() {
         server.addClient(new QmetryClient(qmetryToken, qmetryBaseUrl));
         client_defined = true;
     }
+    if (zephyrToken) {
+        server.addClient(new ZephyrClient(zephyrToken, zephyrBaseUrl));
+        client_defined = true;
+    }
     if (!client_defined) {
-        console.error("Please set one of REFLECT_API_TOKEN, BUGSNAG_AUTH_TOKEN, API_HUB_API_KEY, QMETRY_API_KEY or PACT_BROKER_BASE_URL / (and relevant Pact auth) environment variables");
+        console.error("Please set one of REFLECT_API_TOKEN, BUGSNAG_AUTH_TOKEN, API_HUB_API_KEY, QMETRY_API_KEY, ZEPHYR_API_TOKEN, or PACT_BROKER_BASE_URL / (and relevant Pact auth) environment variables");
         process.exit(1);
     }
     const transport = new StdioServerTransport();

package/dist/pactflow/client/prompt-utils.js

@@ -1,3 +1,4 @@
+import { ToolError } from "../../common/types.js";
 import { EndpointMatcherSchema, MatcherRecommendationInputSchema, } from "./ai.js";
 import { OADMatcherPrompt } from "./prompts.js";
 /**
@@ -30,7 +31,7 @@ export async function getOADMatcherRecommendations(openAPI, server) {
         return matcherRecommendations;
     }
     else {
-        throw new Error("Unable to parse recommendations please provide OpenAPI matchers manually.");
+        throw new ToolError("Unable to parse recommendations please provide OpenAPI matchers manually.");
     }
 }
 /**

package/dist/pactflow/client/tools.js

@@ -71,17 +71,17 @@ export const TOOLS = [
         clients: ["pactflow", "pact_broker"],
     },
     {
-        title: "PactFlow AI Status",
-        summary: "Check PactFlow AI usage status, remaining credits, and eligibility",
-        purpose: "Retrieve the AI feature status for the PactFlow account, including whether AI is enabled, the number of remaining and consumed AI credits, and entitlement or permission issues preventing usage.",
+        title: "Check PactFlow AI Entitlements",
+        summary: "Check your PactFlow AI entitlements and credit balance if you encounter 401 Unauthorized errors or permission/credit issues when using PactFlow AI features.",
+        purpose: "Retrieve AI entitlement information when PactFlow AI operations fail with 401 unauthorized errors. Use this to diagnose permission issues, check remaining credits, and verify account eligibility for AI features.",
         useCases: [
-            "Verify if AI functionality is enabled for the account before attempting to use AI-powered features",
-            "Monitor remaining and consumed AI credits to manage usage and avoid unexpected disruptions",
-            "Detect entitlement or permission issues when a user tries to access AI features and guide corrective actions",
-            "Integrate into deployment pipelines to ensure the environment is correctly configured with necessary entitlements and sufficient credits before executing AI-driven tasks",
-            "Fetches usage and entitlement reports for auditing, budgeting, and compliance purposes",
+            "Diagnose 401 unauthorized errors when attempting to use PactFlow AI features",
+            "Check remaining AI credits when PactFlow AI operations are rejected due to insufficient credits",
+            "Verify account entitlements when users receive permission denied errors for PactFlow AI functionality",
+            "Troubleshoot PactFlow AI access issues by retrieving current entitlement status and credit balance",
+            "Provide detailed error context when PactFlow AI features are unavailable due to account limitations",
         ],
-        handler: "getAIStatus",
+        handler: "checkAIEntitlements",
         clients: ["pactflow"],
     },
 ];

package/dist/pactflow/client/utils.js

@@ -1,6 +1,7 @@
 import yaml from "js-yaml";
 // @ts-expect-error missing type declarations
 import Swagger from "swagger-client";
+import { ToolError } from "../../common/types.js";
 import { RemoteOpenAPIDocumentSchema, } from "./ai.js";
 /**
  * Resolve the OpenAPI specification from the provided input.
@@ -12,12 +13,12 @@ import { RemoteOpenAPIDocumentSchema, } from "./ai.js";
 export async function resolveOpenAPISpec(remoteOpenAPIDocument) {
     const openAPISchema = RemoteOpenAPIDocumentSchema.safeParse(remoteOpenAPIDocument);
     if (openAPISchema.error || !remoteOpenAPIDocument) {
-        throw new Error(`Invalid RemoteOpenAPIDocument: ${JSON.stringify(openAPISchema.error?.issues)}`);
+        throw new ToolError(`Invalid RemoteOpenAPIDocument: ${JSON.stringify(openAPISchema.error?.issues)}`);
     }
     const unresolvedSpec = await getRemoteSpecContents(openAPISchema.data);
     const resolvedSpec = await Swagger.resolve({ spec: unresolvedSpec });
     if (resolvedSpec.errors?.length) {
-        throw new Error(`Failed to resolve OpenAPI document: ${resolvedSpec.errors?.join(", ")}`);
+        throw new ToolError(`Failed to resolve OpenAPI document: ${resolvedSpec.errors?.join(", ")}`);
     }
     return resolvedSpec.spec;
 }
@@ -30,7 +31,7 @@ export async function resolveOpenAPISpec(remoteOpenAPIDocument) {
  */
 export async function getRemoteSpecContents(openAPISchema) {
     if (!openAPISchema.url) {
-        throw new Error("'url' must be provided.");
+        throw new ToolError("'url' must be provided.");
     }
     let headers = {};
     if (openAPISchema.authToken) {
@@ -51,7 +52,7 @@ export async function getRemoteSpecContents(openAPISchema) {
             return yaml.load(specRawBody);
         }
         catch (yamlError) {
-            throw new Error(`Unsupported Content-Type: ${remoteSpec.headers.get("Content-Type")} for remote OpenAPI document. Found following parse errors:-\nJSON parse error: ${jsonError}\nYAML parse error: ${yamlError}`);
+            throw new ToolError(`Unsupported Content-Type: ${remoteSpec.headers.get("Content-Type")} for remote OpenAPI document. Found following parse errors:-\nJSON parse error: ${jsonError}\nYAML parse error: ${yamlError}`);
         }
     }
 }

package/dist/pactflow/client.js

@@ -1,4 +1,5 @@
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../common/info.js";
+import { ToolError, } from "../common/types.js";
 import { getOADMatcherRecommendations, getUserMatcherSelection, } from "./client/prompt-utils.js";
 import { PROMPTS } from "./client/prompts.js";
 import { TOOLS } from "./client/tools.js";
@@ -65,7 +66,7 @@ export class PactflowClient {
             body: JSON.stringify(toolInput),
         });
         if (!response.ok) {
-            throw new Error(`HTTP error! status: ${response.status} - ${await response.text()}`);
+            throw new ToolError(`HTTP error! status: ${response.status} - ${await response.text()}`);
         }
         const status_response = await response.json();
         return await this.pollForCompletion(status_response, "Generation");
@@ -93,20 +94,21 @@ export class PactflowClient {
             body: JSON.stringify(toolInput),
         });
         if (!response.ok) {
-            throw new Error(`HTTP error! status: ${response.status} - ${await response.text()}`);
+            throw new ToolError(`HTTP error! status: ${response.status} - ${await response.text()}`);
         }
         const status_response = await response.json();
         return await this.pollForCompletion(status_response, "Review Pacts");
     }
     /**
-     * Retrieves AI status information for the current user
-     * and organization.
+     * Retrieve PactFlow AI entitlement information for the current user
+     * and organization when encountering 401 unauthorized errors.
+     * Use this to check AI entitlements and credits when AI operations fail.
      *
-     * @returns Entitlement containing AI status information, organization
+     * @returns Entitlement containing permissions, organization
      *   entitlements, and user entitlements.
      * @throws Error if the request fails or returns a non-OK response.
      */
-    async getAIStatus() {
+    async checkAIEntitlements() {
         const url = `${this.aiBaseUrl}/entitlement`;
         try {
             const response = await fetch(url, {
@@ -115,12 +117,12 @@ export class PactflowClient {
             });
             if (!response.ok) {
                 const errorText = await response.text().catch(() => "");
-                throw new Error(`PactFlow AI Status Request Failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
+                throw new ToolError(`PactFlow AI Entitlements Request Failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
             }
             return (await response.json());
         }
         catch (error) {
-            process.stderr.write(`[GetAICredits] Unexpected error: ${error}\n`);
+            process.stderr.write(`[CheckAIEntitlements] Unexpected error: ${error}\n`);
             throw error;
         }
     }
@@ -144,7 +146,7 @@ export class PactflowClient {
         });
         // Check if the response is OK (status 200)
         if (!response.ok) {
-            throw new Error(`HTTP error! status: ${response.status}`);
+            throw new ToolError(`HTTP error! status: ${response.status}`);
         }
         return response.json();
     }
@@ -160,12 +162,12 @@ export class PactflowClient {
                 return await this.getResult(status_response.result_url);
             }
             if (statusCheck.status !== 202) {
-                throw new Error(`${operationName} failed with status: ${statusCheck.status}`);
+                throw new ToolError(`${operationName} failed with status: ${statusCheck.status}`);
             }
             // Wait before next poll
             await new Promise((resolve) => setTimeout(resolve, pollInterval));
         }
-        throw new Error(`${operationName} timed out after ${timeout / 1000} seconds`);
+        throw new ToolError(`${operationName} timed out after ${timeout / 1000} seconds`);
     }
     // PactFlow / Pact_Broker client methods
     async getProviderStates({ provider, }) {
@@ -175,7 +177,7 @@ export class PactflowClient {
             headers: this.headers,
         });
         if (!response.ok) {
-            throw new Error(`HTTP error! status: ${response.status} - ${await response.text()}`);
+            throw new ToolError(`HTTP error! status: ${response.status} - ${await response.text()}`);
         }
         return response.json();
     }
@@ -205,7 +207,7 @@ export class PactflowClient {
             });
             if (!response.ok) {
                 const errorText = await response.text().catch(() => "");
-                throw new Error(`Can-I-Deploy Request Failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
+                throw new ToolError(`Can-I-Deploy Request Failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
             }
             return (await response.json());
         }
@@ -264,7 +266,7 @@ export class PactflowClient {
             });
             if (!response.ok) {
                 const errorText = await response.text().catch(() => "");
-                throw new Error(`Matrix Request Failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
+                throw new ToolError(`Matrix Request Failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
             }
             return (await response.json());
         }

package/dist/qmetry/client/api/client-api.js

@@ -1,5 +1,16 @@
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../../../common/info.js";
 import { QMETRY_DEFAULTS } from "../../config/constants.js";
+import { handleQMetryApiError, handleQMetryFetchError, } from "./error-handler.js";
+/**
+ * QMetry API request function with centralized error handling.
+ *
+ * Handles authentication, project access, CORS, and generic API errors with
+ * user-friendly messages and troubleshooting guidance.
+ *
+ * @param options Request configuration including authentication token
+ * @returns Parsed JSON response from QMetry API
+ * @throws User-friendly errors with detailed troubleshooting steps for various scenarios
+ */
 export async function qmetryRequest({ method = "GET", path, token, project, baseUrl, body, }) {
     const url = `${baseUrl}${path}`;
     const headers = {
@@ -17,23 +28,17 @@ export async function qmetryRequest({ method = "GET", path, token, project, base
     if (body && ["POST", "PUT", "PATCH"].includes(method)) {
         init.body = JSON.stringify(body);
     }
-    const res = await fetch(url, init);
+    let res;
+    try {
+        res = await fetch(url, init);
+    }
+    catch (error) {
+        // Handle fetch errors (CORS, network issues, SSL certificate issues, etc.)
+        handleQMetryFetchError(error instanceof Error ? error : new Error(String(error)), baseUrl, project, path);
+    }
     if (!res.ok) {
-        let errorText;
-        try {
-            const contentType = res.headers.get("content-type");
-            if (contentType?.includes("application/json")) {
-                const json = await res.json();
-                errorText = JSON.stringify(json);
-            }
-            else {
-                errorText = await res.text();
-            }
-        }
-        catch {
-            errorText = res.statusText;
-        }
-        throw new Error(`QMetry API request failed (${res.status}): ${errorText}`);
+        // Use centralized error handling
+        await handleQMetryApiError(res, baseUrl, project, path);
     }
     return (await res.json());
 }