@smartbear/mcp 0.5.0 → 0.7.0

package/dist/pactflow/client.js

@@ -1,4 +1,6 @@
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../common/info.js";
+import { getOADMatcherRecommendations, getUserMatcherSelection, } from "./client/prompt-utils.js";
+import { PROMPTS } from "./client/prompts.js";
 import { TOOLS } from "./client/tools.js";
 // Tool definitions for PactFlow AI API client
 export class PactflowClient {
@@ -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,25 @@ 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 +74,18 @@ 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 +98,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",
@@ -80,6 +134,9 @@ export class PactflowClient {
             isComplete: response.status === 200,
         };
     }
+    get requestHeaders() {
+        return this.headers;
+    }
     async getResult(resultUrl) {
         const response = await fetch(resultUrl, {
             method: "GET",
@@ -111,7 +168,7 @@ export class PactflowClient {
         throw new Error(`${operationName} timed out after ${timeout / 1000} seconds`);
     }
     // PactFlow / Pact_Broker client methods
-    async getProviderStates({ provider }) {
+    async getProviderStates({ provider, }) {
         const uri_encoded_provider_name = encodeURIComponent(provider);
         const response = await fetch(`${this.baseUrl}/pacts/provider/${uri_encoded_provider_name}/provider-states`, {
             method: "GET",
@@ -153,19 +210,90 @@ export class PactflowClient {
             return (await response.json());
         }
         catch (error) {
-            console.error("[CanIDeploy] Unexpected error:", error);
+            console.error(`[CanIDeploy] Unexpected error: ${error}\n`);
+            throw error;
+        }
+    }
+    /**
+     * 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;
         }
     }
-    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
+    /**
+     * 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;
             register(toolparams, async (args, _extra) => {
                 const handler_fn = this[handler];
                 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 +305,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/dist/qmetry/client/api/client-api.js

@@ -0,0 +1,39 @@
+import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../../../common/info.js";
+import { QMETRY_DEFAULTS } from "../../config/constants.js";
+export async function qmetryRequest({ method = "GET", path, token, project, baseUrl, body, }) {
+    const url = `${baseUrl}${path}`;
+    const headers = {
+        apikey: token,
+        project: project || QMETRY_DEFAULTS.PROJECT_KEY,
+        "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`,
+    };
+    if (body) {
+        headers["Content-Type"] = "application/json";
+    }
+    const init = {
+        method,
+        headers,
+    };
+    if (body && ["POST", "PUT", "PATCH"].includes(method)) {
+        init.body = JSON.stringify(body);
+    }
+    const res = await fetch(url, init);
+    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}`);
+    }
+    return (await res.json());
+}

package/dist/qmetry/client/handlers.js

@@ -0,0 +1,11 @@
+import { QMetryToolsHandlers } from "../config/constants.js";
+import { getProjectInfo } from "./project.js";
+import { fetchTestCaseDetails, fetchTestCaseSteps, fetchTestCases, fetchTestCaseVersionDetails, } from "./testcase.js";
+export const QMETRY_HANDLER_MAP = {
+    [QMetryToolsHandlers.SET_PROJECT_INFO]: getProjectInfo,
+    [QMetryToolsHandlers.FETCH_PROJECT_INFO]: getProjectInfo,
+    [QMetryToolsHandlers.FETCH_TEST_CASES]: fetchTestCases,
+    [QMetryToolsHandlers.FETCH_TEST_CASE_DETAILS]: fetchTestCaseDetails,
+    [QMetryToolsHandlers.FETCH_TEST_CASE_VERSION_DETAILS]: fetchTestCaseVersionDetails,
+    [QMetryToolsHandlers.FETCH_TEST_CASE_STEPS]: fetchTestCaseSteps,
+};

package/dist/qmetry/client/project.js

@@ -0,0 +1,27 @@
+import { QMETRY_DEFAULTS } from "../config/constants.js";
+import { QMETRY_PATHS } from "../config/rest-endpoints.js";
+import { qmetryRequest } from "./api/client-api.js";
+/**
+ * Retrieves project information from QMetry
+ *
+ * This function serves dual purpose:
+ * 1. SET_PROJECT_INFO - Sets/switches the current project context
+ * 2. FETCH_PROJECT_INFO - Retrieves project details and configuration
+ *
+ * Both operations use the same API endpoint as QMetry handles project context
+ * switching and information retrieval through the same GET request.
+ *
+ * @param token - QMetry API authentication token
+ * @param baseUrl - QMetry instance base URL (defaults to configured URL)
+ * @param project - Project key to retrieve info for (defaults to configured project)
+ * @returns Promise resolving to project information including viewIds, folders, and configuration
+ */
+export async function getProjectInfo(token, baseUrl, project) {
+    return qmetryRequest({
+        method: "GET",
+        path: QMETRY_PATHS.PROJECT.GET_INFO,
+        token,
+        baseUrl: baseUrl || QMETRY_DEFAULTS.BASE_URL,
+        project: project || QMETRY_DEFAULTS.PROJECT_KEY,
+    });
+}

package/dist/qmetry/client/testcase.js

@@ -0,0 +1,104 @@
+import { QMETRY_DEFAULTS } from "../config/constants.js";
+import { QMETRY_PATHS } from "../config/rest-endpoints.js";
+import { DEFAULT_FETCH_TESTCASE_DETAILS_PAYLOAD, DEFAULT_FETCH_TESTCASE_STEPS_PAYLOAD, DEFAULT_FETCH_TESTCASE_VERSION_DETAILS_PAYLOAD, DEFAULT_FETCH_TESTCASES_PAYLOAD, } from "../types/testcase.js";
+import { qmetryRequest } from "./api/client-api.js";
+function resolveDefaults(baseUrl, project) {
+    return {
+        resolvedBaseUrl: baseUrl || QMETRY_DEFAULTS.BASE_URL,
+        resolvedProject: project || QMETRY_DEFAULTS.PROJECT_KEY,
+    };
+}
+/**
+ * Fetches a list of test cases.
+ * @throws If `viewId` or `folderPath` are missing/invalid.
+ */
+export async function fetchTestCases(token, baseUrl, project, payload) {
+    const { resolvedBaseUrl, resolvedProject } = resolveDefaults(baseUrl, project);
+    const body = {
+        ...DEFAULT_FETCH_TESTCASES_PAYLOAD,
+        ...payload,
+    };
+    if (typeof body.viewId !== "number") {
+        throw new Error("[fetchTestCases] Missing or invalid required parameter: 'viewId'.");
+    }
+    if (typeof body.folderPath !== "string") {
+        throw new Error("[fetchTestCases] Missing or invalid required parameter: 'folderPath'.");
+    }
+    return qmetryRequest({
+        method: "POST",
+        path: QMETRY_PATHS.TESTCASE.GET_TC_LIST,
+        token,
+        project: resolvedProject,
+        baseUrl: resolvedBaseUrl,
+        body,
+    });
+}
+/**
+ * Fetches a test case details.
+ * @throws If `tcID` is missing/invalid.
+ */
+export async function fetchTestCaseDetails(token, baseUrl, project, payload) {
+    const { resolvedBaseUrl, resolvedProject } = resolveDefaults(baseUrl, project);
+    const body = {
+        ...DEFAULT_FETCH_TESTCASE_DETAILS_PAYLOAD,
+        ...payload,
+    };
+    if (typeof body.tcID !== "number") {
+        throw new Error("[fetchTestCaseDetails] Missing or invalid required parameter: 'tcID'.");
+    }
+    return qmetryRequest({
+        method: "POST",
+        path: QMETRY_PATHS.TESTCASE.GET_TC_DETAILS,
+        token,
+        project: resolvedProject,
+        baseUrl: resolvedBaseUrl,
+        body,
+    });
+}
+/**
+ * Fetches a test case details by version.
+ * @throws If `id` is missing/invalid.
+ */
+export async function fetchTestCaseVersionDetails(token, baseUrl, project, payload) {
+    const { resolvedBaseUrl, resolvedProject } = resolveDefaults(baseUrl, project);
+    const body = {
+        ...DEFAULT_FETCH_TESTCASE_VERSION_DETAILS_PAYLOAD,
+        ...payload,
+    };
+    if (!body.id) {
+        throw new Error("[fetchTestCaseVersionDetails] Missing or invalid required parameter: 'id'.");
+    }
+    if (typeof body.version !== "number") {
+        throw new Error("[fetchTestCaseVersionDetails] Missing or invalid required parameter: 'version'.");
+    }
+    return qmetryRequest({
+        method: "POST",
+        path: QMETRY_PATHS.TESTCASE.GET_TC_DETAILS_BY_VERSION,
+        token,
+        project: resolvedProject,
+        baseUrl: resolvedBaseUrl,
+        body,
+    });
+}
+/**
+ * Fetches a test case steps.
+ * @throws If `id` is missing/invalid.
+ */
+export async function fetchTestCaseSteps(token, baseUrl, project, payload) {
+    const { resolvedBaseUrl, resolvedProject } = resolveDefaults(baseUrl, project);
+    const body = {
+        ...DEFAULT_FETCH_TESTCASE_STEPS_PAYLOAD,
+        ...payload,
+    };
+    if (typeof body.id !== "number") {
+        throw new Error("[fetchTestCaseSteps] Missing or invalid required parameter: 'id'.");
+    }
+    return qmetryRequest({
+        method: "POST",
+        path: QMETRY_PATHS.TESTCASE.GET_TC_STEPS,
+        token,
+        project: resolvedProject,
+        baseUrl: resolvedBaseUrl,
+        body,
+    });
+}

package/dist/qmetry/client/tools.js

@@ -0,0 +1,222 @@
+import { QMetryToolsHandlers } from "../config/constants.js";
+import { ProjectArgsSchema, TestCaseDetailsArgsSchema, TestCaseListArgsSchema, TestCaseStepsArgsSchema, TestCaseVersionDetailsArgsSchema, } from "../types/common.js";
+export const TOOLS = [
+    {
+        title: "Set QMetry Project Info",
+        summary: "Set current QMetry project for your account",
+        handler: QMetryToolsHandlers.SET_PROJECT_INFO,
+        zodSchema: ProjectArgsSchema,
+        purpose: "Switch the active QMetry project context for the current session. " +
+            "This tool sets the default project that will be used for all subsequent QMetry operations. " +
+            "Essential for multi-project QMetry instances where you need to work with specific projects.",
+        useCases: [
+            "Switch to a specific project before performing test case operations",
+            "Set project context for batch operations on test cases",
+            "Configure the default project for the current session",
+            "Validate access to a specific project before proceeding with operations",
+        ],
+        examples: [
+            {
+                description: "Set default project as active",
+                parameters: { projectKey: "default" },
+                expectedOutput: "Project context set to 'default' with confirmation of project details",
+            },
+            {
+                description: "Switch to UT project",
+                parameters: { projectKey: "UT" },
+                expectedOutput: "Project context switched to 'UT' project with available configurations",
+            },
+            {
+                description: "Set MAC project as active for test case operations",
+                parameters: { projectKey: "MAC" },
+                expectedOutput: "Project context set to 'MAC' with viewIds and folder structure",
+            },
+        ],
+        hints: [
+            "Always set the project context before performing test case operations in multi-project environments",
+            "Use the same project key that you'll use in subsequent test case operations",
+            "Common project keys include 'default', 'UT', 'MAC', 'VT' - check with your QMetry admin for available projects",
+            "This operation must be performed before fetching test cases if working with non-default projects",
+            "The project context persists for the current session until changed again",
+        ],
+        outputFormat: "JSON object containing project configuration details, confirmation of project switch, and available project metadata",
+        readOnly: false,
+        idempotent: true,
+    },
+    {
+        title: "Fetch QMetry Project Info",
+        summary: "Fetch QMetry project information including viewId and folderPath needed for other operations",
+        handler: QMetryToolsHandlers.FETCH_PROJECT_INFO,
+        zodSchema: ProjectArgsSchema,
+        purpose: "Prerequisite tool that provides project configuration data required by other QMetry operations. " +
+            "The project key to fetch info for. Use 'default' if not specified. " +
+            "Common project keys include 'UT', 'VT', 'MAC', etc. " +
+            "If user doesn't specify a project key, this tool will use 'default' automatically.",
+        useCases: [
+            "Get project configuration before fetching test cases",
+            "Retrieve available viewIds for test case listing",
+            "Get folderPath information for project navigation",
+            "Validate project access and permissions",
+        ],
+        examples: [
+            {
+                description: "Get default project info",
+                parameters: {},
+                expectedOutput: "Project configuration with viewIds, folderPaths, and project details",
+            },
+            {
+                description: "Get specific project info",
+                parameters: { projectKey: "MAC" },
+                expectedOutput: "MAC project configuration with available views and folders",
+            },
+        ],
+        hints: [
+            "Always call this first when user doesn't provide viewId or folderPath",
+            "Use 'default' project key when user doesn't specify one",
+            "Extract viewId from latestViews.TC.viewId for test case operations",
+            "Use empty string '' as folderPath for root directory",
+        ],
+        outputFormat: "JSON object containing project details, viewIds, folderPaths, and project configuration",
+        readOnly: true,
+        idempotent: true,
+    },
+    {
+        title: "Fetch Test Cases",
+        summary: "Fetch QMetry test cases - automatically handles viewId resolution based on project",
+        handler: QMetryToolsHandlers.FETCH_TEST_CASES,
+        zodSchema: TestCaseListArgsSchema,
+        purpose: "Get test cases from QMetry. System automatically gets correct viewId from project info if not provided.",
+        useCases: [
+            "List all test cases in a project",
+            "Search for specific test cases using filters",
+            "Browse test cases in specific folders",
+            "Get paginated test case results",
+        ],
+        examples: [
+            {
+                description: "Get all test cases from default project - system will auto-fetch viewId",
+                parameters: {},
+                expectedOutput: "List of test cases from default project with auto-resolved viewId",
+            },
+            {
+                description: "Get all test cases from UT project - system will auto-fetch UT project's viewId",
+                parameters: { projectKey: "UT" },
+                expectedOutput: "List of test cases from UT project using UT's specific TC viewId",
+            },
+            {
+                description: "Get test cases with manual viewId (skip auto-resolution)",
+                parameters: { projectKey: "MAC", viewId: 167136, folderPath: "" },
+                expectedOutput: "Test cases using manually specified viewId 167136",
+            },
+            {
+                description: "List test cases from specific project (ex: project key can be anything (VT, UT, PROJ1, TEST9)",
+                parameters: {
+                    projectKey: "use specific given project key",
+                    viewId: "fetch specific project given projectKey Test Case ViewId",
+                    folderPath: "",
+                },
+                expectedOutput: "Test cases using manually specified viewId 167136 or projectKey",
+            },
+        ],
+        hints: [
+            "CRITICAL WORKFLOW: Always use the SAME projectKey for both project info and test case fetching",
+            "Step 1: If user specifies projectKey (like 'UT', 'MAC'), use that EXACT projectKey for project info",
+            "Step 2: Get project info using that projectKey, extract latestViews.TC.viewId",
+            "Step 3: Use the SAME projectKey and the extracted TC viewId for fetching test cases",
+            "Step 4: If user doesn't specify projectKey, use 'default' for both project info and test case fetching",
+            "NEVER mix project keys - if user says 'MAC project', use projectKey='MAC' for everything",
+            'For search by test case key (like MAC-TC-1684), use filter: \'[{"type":"string","value":"MAC-TC-1684","field":"entityKeyId"}]\'',
+        ],
+        outputFormat: "JSON object with 'data' array containing test cases and pagination info",
+        readOnly: true,
+        idempotent: true,
+        openWorld: false,
+    },
+    {
+        title: "Fetch Test Case Details",
+        summary: "Get detailed information for a specific QMetry test case by numeric ID",
+        handler: QMetryToolsHandlers.FETCH_TEST_CASE_DETAILS,
+        zodSchema: TestCaseDetailsArgsSchema,
+        purpose: "Retrieve comprehensive test case information including metadata, status, and basic properties",
+        useCases: [
+            "Get test case details by numeric ID",
+            "Retrieve test case metadata for reporting",
+            "Get test case summary and properties",
+            "Fetch test case details before accessing steps or version details",
+        ],
+        examples: [
+            {
+                description: "Get test case details by numeric ID",
+                parameters: { tcID: 4468020 },
+                expectedOutput: "Detailed test case information including summary, description, status",
+            },
+        ],
+        hints: [
+            "⚠️ This API requires a numeric tcID parameter",
+            "If user provides entityKey (e.g., MAC-TC-1684), first call FETCH_TEST_CASES with a filter on entityKeyId to resolve the tcID",
+            "After resolving entityKey → tcID, call this tool with the resolved numeric tcID",
+            "This tool provides metadata and properties; use FETCH_TEST_CASE_STEPS for step-level details",
+        ],
+        outputFormat: "JSON object with test case details including ID, key, summary, description, and metadata",
+        readOnly: true,
+        idempotent: true,
+    },
+    {
+        title: "Fetch Test Case Version Details",
+        summary: "Get QMetry test case details for a specific version by numeric ID",
+        handler: QMetryToolsHandlers.FETCH_TEST_CASE_VERSION_DETAILS,
+        zodSchema: TestCaseVersionDetailsArgsSchema,
+        purpose: "Retrieve version-specific information for a test case including history and changes",
+        useCases: [
+            "Get specific version details of a test case",
+            "Compare different versions of a test case",
+            "Retrieve version history information",
+            "Audit changes made across test case versions",
+        ],
+        examples: [
+            {
+                description: "Get version 2 details for test case ID 123",
+                parameters: { id: 123, version: 2 },
+                expectedOutput: "Version 2 details for test case 123",
+            },
+        ],
+        hints: [
+            "⚠️ Requires numeric ID, not entityKey",
+            "If user provides entityKey (e.g., MAC-TC-1684), first resolve it to numeric ID using FETCH_TEST_CASES",
+            "Version defaults to 1 if not specified",
+            "Provides version-specific metadata and history",
+        ],
+        outputFormat: "JSON object with version-specific test case details",
+        readOnly: true,
+        idempotent: true,
+    },
+    {
+        title: "Fetch Test Case Steps",
+        summary: "Get detailed test case steps for a specific test case by numeric ID",
+        handler: QMetryToolsHandlers.FETCH_TEST_CASE_STEPS,
+        zodSchema: TestCaseStepsArgsSchema,
+        purpose: "Retrieve step-by-step instructions and expected results for manual execution of a test case",
+        useCases: [
+            "Get step-by-step instructions with expected results",
+            "Retrieve test case execution procedure for manual runs",
+            "Export or display detailed test steps for documentation",
+            "Fetch steps before automation mapping",
+        ],
+        examples: [
+            {
+                description: "Get steps for test case ID 123",
+                parameters: { id: 123 },
+                expectedOutput: "Detailed steps with actions and expected results for test case 123",
+            },
+        ],
+        hints: [
+            "⚠️ Requires numeric ID, not entityKey",
+            "If user provides entityKey (e.g., MAC-TC-1684), resolve it first via FETCH_TEST_CASES to get the numeric ID",
+            "Version defaults to 1 if not specified",
+            "Use pagination for test cases with many steps",
+        ],
+        outputFormat: "JSON object with array of test steps including step description, expected result, and order",
+        readOnly: true,
+        idempotent: true,
+    },
+];