@smartbear/mcp 0.5.0 → 0.6.0

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

@@ -0,0 +1,89 @@
+import { EndpointMatcherSchema, MatcherRecommendationInputSchema, } from "./ai.js";
+import { OADMatcherPrompt } from "./prompts.js";
+/**
+ * Get OpenAPI matcher recommendations using sampling.
+ *
+ * @param openAPI The OpenAPI document to analyze.
+ * @param server The SmartBear MCP server instance.
+ * @returns A promise that resolves to the matcher recommendations.
+ * @throws Error if unable to parse recommendations.
+ */
+export async function getOADMatcherRecommendations(openAPI, server) {
+    const matcherResponse = await server.createMessage({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: OADMatcherPrompt.replace("{0}", JSON.stringify(openAPI)),
+                },
+            },
+        ],
+        maxTokens: 1000,
+    });
+    const regex = /```json[c5]?([\s\S]*?)```/i;
+    const match = regex.exec(matcherResponse.content.text);
+    if (match) {
+        const jsonText = match[1].trim();
+        const parsed = JSON.parse(jsonText);
+        const matcherRecommendations = MatcherRecommendationInputSchema.parse(parsed);
+        return matcherRecommendations;
+    }
+    else {
+        throw new Error("Unable to parse recommendations please provide OpenAPI matchers manually.");
+    }
+}
+/**
+ * Get user selection for matcher recommendations.
+ *
+ * @param recommendations The list of matcher recommendations.
+ * @param getInput The function to get user input.
+ * @returns The selected endpoint matcher.
+ */
+export async function getUserMatcherSelection(recommendations, getInput) {
+    const recommendationsMap = new Map();
+    recommendations.forEach((rec, index) => {
+        recommendationsMap.set(`Recommendation ${index + 1}`, JSON.stringify(rec));
+    });
+    const result = await getInput({
+        message: `Select one of the generated matchers you would want to use \n\n ${recommendations
+            .map((rec, index) => `\n\nRecommendation ${index + 1}: \n\n\n ${JSON.stringify(rec)}`)
+            .join("\n\n")}`,
+        requestedSchema: {
+            type: "object",
+            properties: {
+                generatedMatchers: {
+                    type: "string",
+                    title: "Generated Matchers",
+                    description: "Use the matchers generated for the OpenAPI document",
+                    enum: recommendations.map((_, index) => `Recommendation ${index + 1}`),
+                },
+            },
+            required: ["generatedMatchers"],
+        },
+    });
+    if (result.action === "accept") {
+        return EndpointMatcherSchema.parse(JSON.parse(recommendationsMap.get(result.content?.generatedMatchers) ||
+            ""));
+    }
+    else {
+        const result = await getInput({
+            message: "Enter the matchers you would want to use for the OpenAPI document",
+            requestedSchema: {
+                type: "object",
+                properties: {
+                    enteredMatchers: {
+                        type: "string",
+                        title: "Enter the matchers you would want to use for the OpenAPI document",
+                        description: "Enter the matchers you would want to use for the OpenAPI document",
+                    },
+                },
+                required: ["enteredMatchers"],
+            },
+        });
+        if (result.action === "accept") {
+            return EndpointMatcherSchema.parse(JSON.parse(result.content?.enteredMatchers));
+        }
+        return {};
+    }
+}

package/dist/pactflow/client/prompts.js

@@ -0,0 +1,133 @@
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { EndpointMatcherSchema } from "./ai.js";
+const OADMatcherPromptOpenAPIDocExample = {
+    openapi: "3.1.0",
+    info: {
+        title: "My API",
+        version: "1.0.0",
+        description: "A sample API for demonstration purposes.",
+    },
+    paths: {
+        "/users": {
+            get: {
+                summary: "Get all users",
+                responses: {
+                    "200": {
+                        description: "A list of users",
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "array",
+                                    items: {
+                                        $ref: "#/components/schemas/User",
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+    components: {
+        schemas: {
+            User: {
+                type: "object",
+                properties: {
+                    id: {
+                        type: "integer",
+                        format: "int64",
+                    },
+                    name: {
+                        type: "string",
+                    },
+                },
+            },
+        },
+    },
+};
+const OADMatcherPromptRecommendationExample = [
+    {
+        path: "/users",
+        methods: ["GET"],
+        statusCodes: [200, "2XX"],
+        operationId: "get*",
+    },
+    {
+        path: "/users/*",
+        methods: ["GET"],
+        statusCodes: ["2XX"],
+        operationId: "*User*",
+    },
+    {
+        path: "/users",
+        methods: ["GET"],
+        statusCodes: [200],
+        operationId: "getAllUsers",
+    },
+    {
+        path: "/users/**",
+        methods: ["GET"],
+        statusCodes: ["2XX", 404],
+        operationId: "get*",
+    },
+];
+export const OADMatcherPrompt = `
+
+Generate a list of recommendations(maximum of 5) in JSON to use with an OpenAPI matcher.
+Zod Schema for the matcher to be generated is provided below in the markdown block of javascript use this to generate the recommendations for the matcher. Recommendations should contain all the fields from the schema and only output the JSON in a markdown formatted block.
+
+\`\`\`javascript
+const EndpointMatcherSchema = ${JSON.stringify(zodToJsonSchema(EndpointMatcherSchema))};
+\`\`\`
+
+Example OpenAPI document:-
+
+if OpenAPI document provided is:-
+
+\`\`\`json
+${JSON.stringify(OADMatcherPromptOpenAPIDocExample, null, 2)}
+\`\`\`
+
+Generated recommendations are:-
+
+\`\`\`json
+${JSON.stringify(OADMatcherPromptRecommendationExample, null, 2)}
+\`\`\`
+
+Actual OpenAPI document:-
+
+Now provided the below OpenAPI document:-
+
+\`\`\`json
+{0}
+\`\`\`
+
+Give JSON recommendations only provide the JSON block in markdown don't include any additional text.
+`;
+export const PROMPTS = [
+    {
+        name: "OpenAPI Matcher recommendations",
+        params: {
+            description: "Get OpenAPI matcher recommendations using sampling",
+            title: "OpenAPI Matcher recommendations",
+            argsSchema: {
+                openAPI: z.string(),
+            },
+        },
+        callback: function ({ openAPI }) {
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: OADMatcherPrompt.replace("{0}", openAPI),
+                        },
+                    },
+                ],
+            };
+        },
+    },
+];

package/dist/pactflow/client/tools.js

@@ -10,8 +10,8 @@
  * and registered with their corresponding handler.
  */
 import { z } from "zod";
-import { GenerationInputSchema, RefineInputSchema } from "./ai.js";
-import { CanIDeploySchema } from "./base.js";
+import { GenerationInputSchema, RefineInputSchema, } from "./ai.js";
+import { CanIDeploySchema, MatrixSchema } from "./base.js";
 export const TOOLS = [
     {
         title: "Generate Pact Tests",
@@ -20,6 +20,7 @@ export const TOOLS = [
         zodSchema: GenerationInputSchema,
         handler: "generate",
         clients: ["pactflow"], // ONLY pactflow
+        enableElicitation: true,
     },
     {
         title: "Review Pact Tests",
@@ -27,7 +28,8 @@ export const TOOLS = [
         purpose: "Review Pact tests for API interactions",
         zodSchema: RefineInputSchema,
         handler: "review",
-        clients: ["pactflow"]
+        clients: ["pactflow"],
+        enableElicitation: true,
     },
     {
         title: "Get Provider States",
@@ -51,5 +53,35 @@ export const TOOLS = [
         zodSchema: CanIDeploySchema,
         handler: "canIDeploy",
         clients: ["pactflow", "pact_broker"]
+    },
+    {
+        title: "Matrix",
+        summary: "Retrieve the comprehensive contract verification matrix that shows the relationship between consumer and provider versions, their associated pact files, and verification results stored in the Pact Broker or Pactflow. The matrix provides detailed visibility into which consumer and provider versions have been successfully verified against each other, and highlights failures with detailed information about the cause.",
+        purpose: "The Matrix serves as a powerful tool for teams to understand the state of their contract testing ecosystem. It enables tracking of all interactions between consumer and provider versions over time, with detailed insights into verification successes and failures. This helps teams rapidly identify compatibility issues, understand why specific verifications failed, and make informed decisions about deployments. Matrix offers a more intuitive and consolidated view of the verification status, making it easier to spot trends or problematic versions. Additionally, the Matrix supports complex queries using selectors, and can answer specific 'can-i-deploy' questions, ensuring that only compatible versions are deployed to production environments.",
+        useCases: [
+            "Quickly identify which consumer and provider version combinations have passed or failed verification.",
+            "Diagnose and investigate why a particular consumer-provider verification failed.",
+            "Visualize the overall contract compatibility across two pacticipants / services.",
+            "Perform advanced queries using selectors to understand compatibility within specific branches, environments, or version ranges.",
+            "Support informed deployment decisions by answering 'can I deploy version X of this service to production?'",
+            "Expose contract verification details to non-frequent API users in a more accessible format."
+        ],
+        zodSchema: MatrixSchema,
+        handler: "getMatrix",
+        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.",
+        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"
+        ],
+        handler: "getAIStatus",
+        clients: ["pactflow"]
     }
 ];

package/dist/pactflow/client.js

@@ -1,5 +1,7 @@
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../common/info.js";
 import { TOOLS } from "./client/tools.js";
+import { getOADMatcherRecommendations, getUserMatcherSelection } from "./client/prompt-utils.js";
+import { PROMPTS } from "./client/prompts.js";
 // Tool definitions for PactFlow AI API client
 export class PactflowClient {
     name = "Contract Testing";
@@ -8,7 +10,16 @@ export class PactflowClient {
     aiBaseUrl;
     baseUrl;
     clientType;
-    constructor(auth, baseUrl, clientType) {
+    server;
+    /**
+     * Creates an instance of the PactflowClient.
+     *
+     * @param auth The authentication token or credentials.
+     * @param baseUrl The base URL for the API.
+     * @param clientType The type of client (e.g., PactFlow, Pact Broker).
+     * @param server The SmartBear MCP server instance.
+     */
+    constructor(auth, baseUrl, clientType, server) {
         // Set headers based on the type of auth provided
         if (typeof auth === "string") {
             this.headers = {
@@ -28,16 +39,23 @@ export class PactflowClient {
         this.baseUrl = baseUrl;
         this.aiBaseUrl = `${this.baseUrl}/api/ai`;
         this.clientType = clientType;
+        this.server = server;
     }
     // PactFlow AI client methods
     /**
      * Generate new Pact tests based on the provided input.
      *
      * @param toolInput The input data for the generation process.
+     * @param getInput Function to get additional input from the user if needed.
      * @returns The result of the generation process.
      * @throws Error if the HTTP request fails or the operation times out.
      */
-    async generate(toolInput) {
+    async generate(toolInput, getInput) {
+        if (toolInput.openapi?.document && (!toolInput.openapi?.matcher || Object.keys(toolInput.openapi.matcher).length === 0)) {
+            const matcherResponse = await getOADMatcherRecommendations(toolInput.openapi.document, this.server);
+            const userSelection = await getUserMatcherSelection(matcherResponse, getInput);
+            toolInput.openapi.matcher = userSelection;
+        }
         // Submit the generation request
         const response = await fetch(`${this.aiBaseUrl}/generate`, {
             method: "POST",
@@ -54,10 +72,16 @@ export class PactflowClient {
      * Review the provided Pact tests and suggest improvements.
      *
      * @param toolInput The input data for the review process.
+     * @param getInput Function to get additional input from the user if needed.
      * @returns The result of the review process.
      * @throws Error if the HTTP request fails or the operation times out.
      */
-    async review(toolInput) {
+    async review(toolInput, getInput) {
+        if (toolInput.openapi?.document && (!toolInput.openapi?.matcher || Object.keys(toolInput.openapi.matcher).length === 0)) {
+            const matcherResponse = await getOADMatcherRecommendations(toolInput.openapi.document, this.server);
+            const userSelection = await getUserMatcherSelection(matcherResponse, getInput);
+            toolInput.openapi.matcher = userSelection;
+        }
         // Submit review request
         const response = await fetch(`${this.aiBaseUrl}/review`, {
             method: "POST",
@@ -70,6 +94,32 @@ export class PactflowClient {
         const status_response = await response.json();
         return await this.pollForCompletion(status_response, "Review Pacts");
     }
+    /**
+     * Retrieves AI status information for the current user
+     * and organization.
+     *
+     * @returns Entitlement containing AI status information, organization
+     *   entitlements, and user entitlements.
+     * @throws Error if the request fails or returns a non-OK response.
+     */
+    async getAIStatus() {
+        const url = `${this.aiBaseUrl}/entitlement`;
+        try {
+            const response = await fetch(url, {
+                method: "GET",
+                headers: this.headers,
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                throw new Error(`PactFlow AI Status Request Failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            process.stderr.write(`[GetAICredits] Unexpected error: ${error}\n`);
+            throw error;
+        }
+    }
     async getStatus(statusUrl) {
         const response = await fetch(statusUrl, {
             method: "HEAD",
@@ -153,11 +203,76 @@ export class PactflowClient {
             return (await response.json());
         }
         catch (error) {
-            console.error("[CanIDeploy] Unexpected error:", error);
+            console.error(`[CanIDeploy] Unexpected error: ${error}\n`);
             throw error;
         }
     }
-    registerTools(register, _getInput) {
+    /**
+     * Retrieves the matrix of pact verification results for the specified pacticipants.
+     * This allows you to see which consumer/provider combinations have been verified
+     * and make deployment decisions based on contract test results.
+     *
+     * @param body - Matrix query parameters including pacticipants, versions, environments, etc.
+     * @returns MatrixResponse containing the verification matrix, notices, and summary
+     * @throws Error if the request fails or returns a non-OK response
+     */
+    async getMatrix(body) {
+        const { q, latestby, limit } = body;
+        // Build query parameters manually to avoid URL encoding of square brackets
+        const queryParts = [];
+        // Add optional parameters
+        if (latestby) {
+            queryParts.push(`latestby=${encodeURIComponent(latestby)}`);
+        }
+        if (limit !== undefined) {
+            queryParts.push(`limit=${limit}`);
+        }
+        // Add the q parameters (pacticipant selectors)
+        q.forEach((selector) => {
+            queryParts.push(`q[]pacticipant=${encodeURIComponent(selector.pacticipant)}`);
+            if (selector.version) {
+                queryParts.push(`q[]version=${encodeURIComponent(selector.version)}`);
+            }
+            if (selector.branch) {
+                queryParts.push(`q[]branch=${encodeURIComponent(selector.branch)}`);
+            }
+            if (selector.environment) {
+                queryParts.push(`q[]environment=${encodeURIComponent(selector.environment)}`);
+            }
+            if (selector.latest !== undefined) {
+                queryParts.push(`q[]latest=${selector.latest}`);
+            }
+            if (selector.tag) {
+                queryParts.push(`q[]tag=${encodeURIComponent(selector.tag)}`);
+            }
+            if (selector.mainBranch !== undefined) {
+                queryParts.push(`q[]mainBranch=${selector.mainBranch}`);
+            }
+        });
+        const url = `${this.baseUrl}/matrix?${queryParts.join('&')}`;
+        try {
+            const response = await fetch(url, {
+                method: "GET",
+                headers: this.headers,
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                throw new Error(`Matrix Request Failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            console.error("[GetMatrix] Unexpected error:", error);
+            throw error;
+        }
+    }
+    /**
+     * Registers tools with the provided register function.
+     *
+     * @param register - The function used to register tools.
+     * @param getInput - The function used to get input for tools.
+     */
+    registerTools(register, getInput) {
         for (const tool of TOOLS.filter(t => t.clients.includes(this.clientType))) {
             const { handler, clients: _, formatResponse, ...toolparams } = tool; // eslint-disable-line @typescript-eslint/no-unused-vars
             register(toolparams, async (args, _extra) => {
@@ -165,7 +280,13 @@ export class PactflowClient {
                 if (typeof handler_fn !== "function") {
                     throw new Error(`Handler '${handler}' not found on PactClient`);
                 }
-                const result = await handler_fn.call(this, args);
+                let result;
+                if (tool.enableElicitation) {
+                    result = await handler_fn.call(this, args, getInput);
+                }
+                else {
+                    result = await handler_fn.call(this, args);
+                }
                 // Use custom response formatter if provided
                 if (formatResponse) {
                     return formatResponse(result);
@@ -177,4 +298,14 @@ export class PactflowClient {
             });
         }
     }
+    /**
+     * Registers prompts with the provided register function.
+     *
+     * @param register - The function used to register prompts.
+     */
+    registerPrompts(register) {
+        PROMPTS.forEach(prompt => {
+            register(prompt.name, prompt.params, prompt.callback);
+        });
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartbear/mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server for interacting SmartBear Products",
   "keywords": [
     "smartbear",
@@ -11,6 +11,7 @@
     "pactflow"
   ],
   "homepage": "https://developer.smartbear.com/smartbear-mcp",
+  "mcpName": "com.smartbear/smartbear-mcp",
   "repository": {
     "type": "git",
     "url": "git@github.com:SmartBear/smartbear-mcp.git"
@@ -45,7 +46,8 @@
     "@modelcontextprotocol/sdk": "^1.15.0",
     "node-cache": "^5.1.2",
     "swagger-client": "^3.35.6",
-    "zod": "^3"
+    "zod": "^3",
+    "zod-to-json-schema": "^3.24.6"
   },
   "devDependencies": {
     "@eslint/js": "^9.29.0",