@smartbear/mcp 0.11.0 → 0.12.1

package/dist/qmetry/client/tools/automation-tools.js

@@ -0,0 +1,290 @@
+import { QMetryToolsHandlers } from "../../config/constants.js";
+import { FetchAutomationStatusPayloadSchema, ImportAutomationResultsPayloadSchema, } from "../../types/common.js";
+export const AUTOMATION_TOOLS = [
+    {
+        handler: QMetryToolsHandlers.IMPORT_AUTOMATION_RESULTS,
+        title: "Import Automation Test Results",
+        summary: "Import/Publish automation test results from TestNG, JUnit, Cucumber, Robot, HPUFT, or QAF frameworks into QMetry",
+        purpose: "Upload and import automation test result files to create test suites, test cases, and execution records in QMetry",
+        inputSchema: ImportAutomationResultsPayloadSchema,
+        useCases: [
+            "1. Import TestNG XML results after CI/CD pipeline execution",
+            "2. Publish JUnit test results to QMetry for tracking and reporting",
+            "3. Upload Cucumber JSON results with custom test suite organization",
+            "4. Import Robot Framework results with specific release/cycle mapping",
+            "5. Link automation results to existing test suites for version tracking",
+            "6. Create new test suites with custom names and folder structures",
+            "7. Map test results to specific platforms (browsers, OS, devices)",
+            "8. Associate imported results with releases, cycles, and builds",
+            "9. Bulk import multiple test results from ZIP archive",
+            "10. Configure test case/suite fields and user-defined fields during import",
+        ],
+        examples: [
+            {
+                description: "Basic TestNG result import",
+                parameters: {
+                    file: "<base64_encoded_testng_xml_content>",
+                    fileName: "testng-results.xml",
+                    entityType: "TESTNG",
+                },
+                expectedOutput: "Auto-generated test suite created with UTC timestamp, test cases auto-linked, execution results updated, 'No Platform' linked",
+            },
+            {
+                description: "JUnit results with custom test suite name",
+                parameters: {
+                    file: "<base64_encoded_junit_xml_content>",
+                    fileName: "junit-results.xml",
+                    entityType: "JUNIT",
+                    testsuiteName: "Regression Suite - Build 123",
+                    automationHierarchy: "1",
+                },
+                expectedOutput: "Test suite 'Regression Suite - Build 123' created with Test Case-Test Step hierarchy",
+            },
+            {
+                description: "Cucumber results with platform and release mapping",
+                parameters: {
+                    file: "<base64_encoded_cucumber_json_content>",
+                    fileName: "cucumber-results.json",
+                    entityType: "CUCUMBER",
+                    platformID: "Chrome 120",
+                    releaseID: "Release 2.0",
+                    cycleID: "Sprint 15",
+                    testsuiteName: "API Automation Tests",
+                },
+                expectedOutput: "Test suite created, linked to Chrome platform, Release 2.0, and Sprint 15 cycle",
+            },
+            {
+                description: "Reuse existing test suite",
+                parameters: {
+                    file: "<base64_encoded_testng_xml_content>",
+                    fileName: "testng-regression.xml",
+                    entityType: "TESTNG",
+                    testsuiteId: "PROJ-TS-42",
+                },
+                expectedOutput: "Test cases auto-linked to existing test suite PROJ-TS-42, execution results updated",
+            },
+            {
+                description: "Import with folder organization",
+                parameters: {
+                    file: "<base64_encoded_junit_xml_content>",
+                    fileName: "junit-results.xml",
+                    entityType: "JUNIT",
+                    tsFolderPath: "/Automation/Regression",
+                    tcFolderPath: "/Automation/API Tests",
+                    testsuiteName: "API Regression Suite",
+                },
+                expectedOutput: "Test suite created in '/Automation/Regression' folder, test cases in '/Automation/API Tests' folder",
+            },
+            {
+                description: "Import with test case custom fields",
+                parameters: {
+                    file: "<base64_encoded_testng_xml_content>",
+                    fileName: "testng-results.xml",
+                    entityType: "TESTNG",
+                    testcase_fields: JSON.stringify({
+                        priority: "High",
+                        testCaseType: "Automated",
+                        component: ["API", "Backend"],
+                        testcaseOwner: "john.doe",
+                        estimatedTime: "2h:30m:0s",
+                    }),
+                },
+                expectedOutput: "Test cases created with High priority, Automated type, API and Backend components",
+            },
+            {
+                description: "Import ZIP file with multiple results",
+                parameters: {
+                    file: "<base64_encoded_zip_content>",
+                    fileName: "test-results.zip",
+                    entityType: "JUNIT",
+                    testsuiteName: "Full Regression Suite",
+                    skipWarning: "1",
+                },
+                expectedOutput: "Multiple test results imported from ZIP, summaries truncated if >255 chars",
+            },
+            {
+                description: "Import with custom hierarchy for JUnit",
+                parameters: {
+                    file: "<base64_encoded_junit_xml_content>",
+                    fileName: "junit-results.xml",
+                    entityType: "JUNIT",
+                    automationHierarchy: "3",
+                    projectID: "PROJ",
+                },
+                expectedOutput: "Multiple test suites created per <testsuite> tag, test cases per <testcase> tag",
+            },
+            {
+                description: "Import with build and platform mapping",
+                parameters: {
+                    file: "<base64_encoded_testng_xml_content>",
+                    fileName: "testng-results.xml",
+                    entityType: "TESTNG",
+                    buildID: "Build-1.2.3",
+                    platformID: "Safari 17",
+                    releaseID: "Release 1.2",
+                    cycleID: "QA Cycle",
+                },
+                expectedOutput: "Results linked to Build 1.2.3, Safari 17 platform, Release 1.2, QA Cycle",
+            },
+            {
+                description: "Import with test suite and test case fields",
+                parameters: {
+                    file: "<base64_encoded_cucumber_json_content>",
+                    fileName: "cucumber-results.json",
+                    entityType: "CUCUMBER",
+                    testsuite_fields: JSON.stringify({
+                        testSuiteState: "In Progress",
+                        testsuiteOwner: "jane.smith",
+                        description: "Sprint 15 automation results",
+                    }),
+                    testcase_fields: JSON.stringify({
+                        priority: "Medium",
+                        component: ["UI", "Frontend"],
+                        userDefinedFields: {
+                            reviewedDate: "11-20-2024",
+                            environment: "Staging",
+                        },
+                    }),
+                },
+                expectedOutput: "Test suite and test cases created with custom fields and UDFs",
+            },
+        ],
+        hints: [
+            "1. CRITICAL: User MUST upload a valid result file before calling this tool",
+            "2. USER FILE UPLOAD REQUIRED: Ask user to provide file in chat - system will convert to base64",
+            "3. FILE REQUIREMENTS:",
+            "   - Supported extensions: .json, .xml, .zip",
+            "   - Maximum size: 30 MB",
+            "   - ZIP files must contain files matching the specified entityType format",
+            "4. REQUIRED PARAMETERS:",
+            "   - file: Base64 encoded content or file path",
+            "   - fileName: Original filename with extension",
+            "   - entityType: TESTNG, CUCUMBER, JUNIT, HPUFT, QAF, or ROBOT",
+            "5. ENTITY TYPES:",
+            "   - TESTNG: TestNG XML format",
+            "   - JUNIT: JUnit XML format",
+            "   - CUCUMBER: Cucumber JSON format",
+            "   - ROBOT: Robot Framework XML format",
+            "   - HPUFT: HP UFT format",
+            "   - QAF: QAF format",
+            "6. AUTOMATION HIERARCHY (TestNG/JUnit only):",
+            "   - TestNG:",
+            "     * 1 (default): <class name> = Test Case, <test-method> = Test Step",
+            "     * 2: <test-method> = Test Case only",
+            "     * 3: <name> under <test> = Test Case, <test-method> = Test Step",
+            "   - JUnit:",
+            "     * 1 (default): <testsuite> = Test Case, <testcase> = Test Step",
+            "     * 2: <testcase> = Test Case only",
+            "     * 3: <testsuite> = Test Suite, <testcase> = Test Case (creates multiple test suites)",
+            "7. TEST SUITE OPTIONS:",
+            "   - testsuiteName: Custom name for new test suite",
+            "   - testsuiteId: Reuse existing test suite by ID or Entity Key (e.g., 'PROJ-TS-42')",
+            "   - tsFolderPath: Create test suite in specific folder (e.g., '/Automation/Regression')",
+            "   - Note: testsuiteName/testsuiteId ignored if automationHierarchy=3 for JUnit or =2 for ROBOT",
+            "8. TEST CASE OPTIONS:",
+            "   - tcFolderPath: Create test cases in specific folder (e.g., '/Automation/API Tests')",
+            "   - Folders created automatically if they don't exist",
+            "9. LINKING OPTIONS:",
+            "   - platformID: Platform ID or name (e.g., 'Chrome 120', 'Safari 17')",
+            "   - projectID: Project ID, key, or name (overrides header project)",
+            "   - releaseID: Release ID or name (requires projectID)",
+            "   - cycleID: Cycle ID or name (requires releaseID and projectID)",
+            "   - buildID: Build ID or name",
+            "10. GET IDs FROM OTHER TOOLS:",
+            "    - Platform IDs: Use 'Platform/List' API (FETCH_PLATFORMS tool)",
+            "    - Project IDs: Use 'Project/List' API (FETCH_PROJECTS tool)",
+            "    - Release IDs: Use 'Release/List' API (FETCH_RELEASES_CYCLES tool)",
+            "    - Cycle IDs: Use 'Cycle/List' API (FETCH_RELEASES_CYCLES tool)",
+            "    - Build IDs: Use 'Build/List' API (FETCH_BUILDS tool)",
+            "    - Test Suite IDs: Use 'Testsuite/Fetch' API (FETCH_TEST_SUITES tool)",
+            "11. CUSTOM FIELDS (testcase_fields):",
+            "    - JSON string with system fields and UDFs",
+            "    - System fields: component, priority, testCaseState, testCaseType, testcaseOwner, estimatedTime, description",
+            '    - Example: {"component":["API"], "priority":"High", "testcaseOwner":"user"}',
+            "    - Ignored if reusing existing test case",
+            "12. CUSTOM FIELDS (testsuite_fields):",
+            "    - JSON string with system fields and UDFs",
+            "    - System fields: testSuiteState, testsuiteOwner, description",
+            '    - Example: {"testSuiteState":"Open", "testsuiteOwner":"user"}',
+            "    - Ignored if reusing existing test suite",
+            "13. USER DEFINED FIELDS (UDFs):",
+            "    - Include in testcase_fields or testsuite_fields under 'userDefinedFields' key",
+            '    - Example: {"userDefinedFields": {"reviewedDate": "11-20-2024", "environment": "Staging"}}',
+            "    - UDF types: STRING, LARGETEXT, LOOKUPLIST, MULTILOOKUPLIST, DATEPICKER, NUMBER",
+            "    - See tool metadata for UDF validation rules and auto-create behavior",
+            "14. SKIP WARNING OPTIONS:",
+            "    - skipWarning='0' (default): Fail import if test case summary >255 characters",
+            "    - skipWarning='1': Truncate summary to 255 characters and continue import",
+            "15. MATCHING BEHAVIOR:",
+            "    - is_matching_required='true' (default): Create new TC/version if summary/steps don't match",
+            "    - is_matching_required='false': Reuse existing TC version if entity key or summary matches",
+            "16. IMPORT BEHAVIOR EXAMPLES:",
+            "    - Only file + entityType → Auto-generated test suite, 'No Platform', test cases auto-linked",
+            "    - file + entityType + platformID → Auto-generated test suite with specified platform",
+            "    - file + entityType + testsuiteId → Results updated in existing test suite",
+            "    - file + entityType + platformID + testsuiteId → Results updated in existing test suite with platform",
+            "17. FOLDER CREATION:",
+            "    - If tsFolderPath or tcFolderPath specified and doesn't exist, it will be created automatically",
+            "    - Use forward slashes for folder paths (e.g., '/Parent/Child')",
+            "18. ESTIMATED TIME FORMAT:",
+            "    - Format: '2h:30m:15s' or '4h' or '7m' or '0s'",
+            "    - Range: 0 to 99999 minutes",
+            "19. OWNER FIELDS:",
+            "    - Use userAlias (username) not display name",
+            "    - testcaseOwner: User must have Test Case module rights",
+            "    - testsuiteOwner: User must have Test Suite module rights",
+            "    - Owner not set if user not found or lacks permissions",
+            "20. LOOKUPLIST/MULTILOOKUPLIST BEHAVIOR:",
+            "    - If value doesn't exist and auto-create is ON: Value added to list",
+            "    - If value doesn't exist and auto-create is OFF: Field blank or default value",
+            "    - MULTILOOKUPLIST: New values added, old values persist",
+            "21. MANDATORY FIELD VALIDATION:",
+            "    - If mandatory system/UDF field missing:",
+            "      * Auto-create OFF + value doesn't exist = Import FAIL",
+            "      * Auto-create ON + value doesn't exist = Import SUCCESS (value created)",
+            "      * Value exists = Import SUCCESS",
+            "22. ERROR HANDLING:",
+            "    - Check file size before upload (must be ≤30 MB)",
+            "    - Validate file extension matches entityType",
+            "    - Ensure required dependencies: cycleID requires releaseID and projectID",
+            "    - If import fails, check QMetry UI for detailed error messages",
+            "23. WORKFLOW:",
+            "    Step 1: Ask user to upload result file in chat",
+            "    Step 2: System converts file to base64",
+            "    Step 3: Collect entityType and optional parameters",
+            "    Step 4: Call this tool with file data and configuration",
+            "    Step 5: QMetry processes file and creates/updates test artifacts",
+            "    Step 6: Return import results with test suite and execution details",
+            "24. USER INTERACTION REQUIRED:",
+            "    - ALWAYS ask user to upload file before calling this tool",
+            "    - Display supported formats: .json, .xml, .zip (up to 30 MB)",
+            "    - Ask for entityType (framework used)",
+            "    - Ask for optional parameters based on user's needs",
+            "25. PERFORMANCE TIPS:",
+            "    - For large imports, consider using ZIP files",
+            "    - Reusing existing test suites is faster than creating new ones",
+            "    - Use automationHierarchy wisely to control test case/suite structure",
+        ],
+    },
+    {
+        handler: QMetryToolsHandlers.FETCH_AUTOMATION_STATUS,
+        title: "Fetch Automation Status",
+        summary: "Fetches the status of an automation import job by request ID.",
+        purpose: "Track the progress and result of an automation import operation in QMetry.",
+        inputSchema: FetchAutomationStatusPayloadSchema,
+        useCases: [
+            "1. Check if an automation import job is completed or still in progress.",
+            "2. Retrieve status, progress, and details for a specific automation import request.",
+            "3. Monitor automation result processing for CI/CD integrations.",
+        ],
+        examples: [
+            {
+                description: "Fetch status for request ID 12345",
+                parameters: {
+                    requestID: 12345,
+                },
+                expectedOutput: "Status, progress, and details of the automation import job for request ID 12345.",
+            },
+        ],
+    },
+];

package/dist/qmetry/client/tools/index.js

@@ -1,8 +1,10 @@
+export { AUTOMATION_TOOLS } from "./automation-tools.js";
 export { ISSUE_TOOLS } from "./issue-tools.js";
 export { PROJECT_TOOLS } from "./project-tools.js";
 export { REQUIREMENT_TOOLS } from "./requirement-tools.js";
 export { TESTCASE_TOOLS } from "./testcase-tools.js";
 export { TESTSUITE_TOOLS } from "./testsuite-tools.js";
+import { AUTOMATION_TOOLS } from "./automation-tools.js";
 import { ISSUE_TOOLS } from "./issue-tools.js";
 import { PROJECT_TOOLS } from "./project-tools.js";
 import { REQUIREMENT_TOOLS } from "./requirement-tools.js";
@@ -14,4 +16,5 @@ export const TOOLS = [
     ...REQUIREMENT_TOOLS,
     ...TESTSUITE_TOOLS,
     ...ISSUE_TOOLS,
+    ...AUTOMATION_TOOLS,
 ];

package/dist/qmetry/client/tools/issue-tools.js

@@ -197,7 +197,7 @@ export const ISSUE_TOOLS = [
             },
             {
                 description: "Get issues with manual viewId (skip auto-resolution)",
-                parameters: { projectKey: "MAC", viewId: 166065 },
+                parameters: { projectKey: "MAC", viewId: 166065 }, // This is an example viewId, must be resolved per project IS viewId
                 expectedOutput: "Issues using manually specified viewId 166065",
             },
             {

package/dist/qmetry/client/tools/project-tools.js

@@ -1,5 +1,5 @@
 import { QMetryToolsHandlers } from "../../config/constants.js";
-import { BuildArgsSchema, PlatformArgsSchema, ProjectArgsSchema, ProjectListArgsSchema, ReleasesCyclesArgsSchema, } from "../../types/common.js";
+import { BuildArgsSchema, CreateCycleArgsSchema, CreateReleaseArgsSchema, PlatformArgsSchema, ProjectArgsSchema, ProjectListArgsSchema, ReleasesCyclesArgsSchema, UpdateCycleArgsSchema, } from "../../types/common.js";
 export const PROJECT_TOOLS = [
     {
         title: "Fetch QMetry list Projects",
@@ -345,4 +345,314 @@ export const PROJECT_TOOLS = [
         idempotent: true,
         openWorld: false,
     },
+    {
+        title: "Create Release",
+        summary: "Create a new release in QMetry with optional cycle for test planning and execution tracking",
+        handler: QMetryToolsHandlers.CREATE_RELEASE,
+        inputSchema: CreateReleaseArgsSchema,
+        purpose: "Create a new release in QMetry to organize test execution phases. " +
+            "Releases represent major versions or milestones in your project. " +
+            "Optionally create a cycle within the release for more granular test execution planning. " +
+            "This tool helps establish the test planning hierarchy and enables better test execution tracking.",
+        useCases: [
+            "Create a new release for a major product version (e.g., v2.0, Q1 Release)",
+            "Create a release with an initial cycle for immediate test planning",
+            "Set up release dates for sprint planning and milestone tracking",
+            "Organize test execution by product versions and cycles",
+            "Create release hierarchy for better test planning and reporting",
+            "Establish test execution phases with releases and cycles",
+        ],
+        examples: [
+            {
+                description: "Create a basic release with just a name",
+                parameters: {
+                    release: {
+                        name: "Release 2.0",
+                    },
+                },
+                expectedOutput: "Release 'Release 2.0' created successfully with generated release ID",
+            },
+            {
+                description: "Create a release with description and dates",
+                parameters: {
+                    release: {
+                        name: "Q1 2024 Release",
+                        description: "First quarter release for 2024",
+                        startDate: "01-01-2024",
+                        targetDate: "31-03-2024",
+                    },
+                },
+                expectedOutput: "Release 'Q1 2024 Release' created with start date 01-01-2024 and target date 31-03-2024",
+            },
+            {
+                description: "Create a release with an initial cycle",
+                parameters: {
+                    release: {
+                        name: "Release 3.0",
+                        description: "Major product update",
+                    },
+                    cycle: {
+                        name: "Sprint 1",
+                        isLocked: false,
+                        isArchived: false,
+                    },
+                },
+                expectedOutput: "Release 'Release 3.0' created with cycle 'Sprint 1' for test execution planning",
+            },
+            {
+                description: "Create a release with all details",
+                parameters: {
+                    release: {
+                        name: "Summer 2024 Release",
+                        description: "Summer product release with new features",
+                        startDate: "01-06-2024",
+                        targetDate: "31-08-2024",
+                    },
+                    cycle: {
+                        name: "Beta Testing Cycle",
+                        isLocked: false,
+                    },
+                },
+                expectedOutput: "Release 'Summer 2024 Release' created with dates and 'Beta Testing Cycle' for test execution",
+            },
+        ],
+        hints: [
+            "CRITICAL: release.name is REQUIRED - must provide a name for the release",
+            "Date format depends on QMetry instance configuration: DD-MM-YYYY or MM-DD-YYYY",
+            "Check your QMetry instance settings to determine the correct date format",
+            "If dates are in wrong format, QMetry will return an error - verify format with admin",
+            "projectID is optional in the release object - it will be auto-resolved from the project key if not provided",
+            "To explicitly set projectID, first call FETCH_PROJECT_INFO to get the numeric project ID",
+            "cycle parameter is completely optional - omit it if you only want to create a release",
+            "If providing cycle, cycle.name is REQUIRED",
+            "cycle.isLocked defaults to false if not provided - set to true to prevent modifications",
+            "cycle.isArchived defaults to false if not provided - set to true to archive immediately (rare)",
+            "Releases can have multiple cycles added later using other tools",
+            "Use descriptive release names like 'Release 2.0', 'Q1 2024', 'Sprint 15' for better organization",
+            "startDate and targetDate help with sprint planning and milestone tracking",
+            "Creating a release with a cycle is useful for immediate test planning after release creation",
+            "Release hierarchy: Project → Release → Cycle → Test Execution",
+            "After creating a release, you can associate test suites and test cases with it",
+            "Use FETCH_RELEASES_CYCLES tool after creation to verify the release was created successfully",
+        ],
+        outputDescription: "JSON object containing the created release ID, release details, and cycle information if provided",
+        readOnly: false,
+        idempotent: false,
+    },
+    {
+        title: "Create Cycle",
+        summary: "Create a new cycle within an existing release in QMetry for test execution planning",
+        handler: QMetryToolsHandlers.CREATE_CYCLE,
+        inputSchema: CreateCycleArgsSchema,
+        purpose: "Create a new cycle within an existing release to organize test execution phases. " +
+            "Cycles represent specific testing iterations, sprints, or phases within a release. " +
+            "This tool requires an existing release and creates a cycle associated with it. " +
+            "Essential for granular test planning and sprint-based test execution tracking.",
+        useCases: [
+            "Create a new test cycle for a sprint within an existing release",
+            "Add additional testing phases to an existing release",
+            "Set up regression testing cycles for a specific release",
+            "Organize test execution by sprints, phases, or iterations",
+            "Create cycles with specific date ranges for milestone tracking",
+            "Establish test execution phases within release planning",
+        ],
+        examples: [
+            {
+                description: "Create a basic cycle with just a name in a release",
+                parameters: {
+                    cycle: {
+                        name: "Sprint 2",
+                        releaseID: 12345,
+                    },
+                },
+                expectedOutput: "Cycle 'Sprint 2' created successfully in release ID 12345",
+            },
+            {
+                description: "Create a cycle with description and dates",
+                parameters: {
+                    cycle: {
+                        name: "Regression Testing Cycle",
+                        description: "Full regression testing for release 2.0",
+                        startDate: "15-01-2024",
+                        targetDate: "31-01-2024",
+                        releaseID: 12345,
+                    },
+                },
+                expectedOutput: "Cycle 'Regression Testing Cycle' created with start date 15-01-2024 and target date 31-01-2024 in release 12345",
+            },
+            {
+                description: "Create a locked cycle to prevent modifications",
+                parameters: {
+                    cycle: {
+                        name: "Final QA Cycle",
+                        description: "Locked cycle for final QA testing",
+                        isLocked: true,
+                        isArchived: false,
+                        releaseID: 12345,
+                    },
+                },
+                expectedOutput: "Locked cycle 'Final QA Cycle' created in release 12345 to prevent modifications",
+            },
+            {
+                description: "Create a cycle with all details including project ID and dates",
+                parameters: {
+                    cycle: {
+                        name: "Sprint 3 - Feature Testing",
+                        description: "Testing new features for Sprint 3",
+                        startDate: "01-02-2024",
+                        targetDate: "15-02-2024",
+                        isLocked: false,
+                        isArchived: false,
+                        projectID: 67890,
+                        releaseID: 12345,
+                    },
+                },
+                expectedOutput: "Cycle 'Sprint 3 - Feature Testing' created with dates and project context in release 12345",
+            },
+        ],
+        hints: [
+            "CRITICAL: cycle.releaseID is REQUIRED - must provide the release ID to associate this cycle with",
+            "CRITICAL: cycle.name is REQUIRED - must provide a name for the cycle",
+            "HOW TO GET releaseID:",
+            "1. Call FETCH_RELEASES_CYCLES tool to get all releases and their IDs",
+            "2. From the response, get value from projects.releases[<index>].releaseID",
+            "3. Use that numeric releaseID in the cycle.releaseID parameter",
+            "Example: Release 'Q1 2024' might have releaseID: 12345",
+            "CRITICAL WORKFLOW - IF USER PROVIDES RELEASE NAME:",
+            "1. User says: 'Create cycle Sprint 2 in release Q1 2024'",
+            "2. You MUST first call FETCH_RELEASES_CYCLES tool to get all releases",
+            "3. Search the response for release with name 'Q1 2024'",
+            "4. Extract projects.releases[<index>].releaseID from matching release",
+            "5. Use that releaseID in cycle.releaseID parameter",
+            "6. If release name not found, inform user and list available releases",
+            "Example workflow:",
+            "- User request: 'Create cycle Sprint 2 in Release 2.0'",
+            "- Step 1: Call FETCH_RELEASES_CYCLES",
+            "- Step 2: Find release where name = 'Release 2.0', get its releaseID (e.g., 12345)",
+            "- Step 3: Call CREATE_CYCLE with cycle.releaseID = 12345",
+            "RELEASE NAME RESOLUTION:",
+            "- NEVER assume or guess release IDs - always fetch from API",
+            "- Release names are user-defined strings (e.g., 'Q1 2024', 'Release 2.0', 'Sprint 15')",
+            "- Release IDs are numeric identifiers assigned by QMetry (e.g., 12345, 67890)",
+            "- Match release names case-insensitively when searching",
+            "- If multiple releases match the name, ask user to clarify or use the most recent one",
+            "- FETCH_RELEASES_CYCLES returns: projects.releases[] array with name and releaseID fields",
+            "Date format depends on QMetry instance configuration: DD-MM-YYYY or MM-DD-YYYY",
+            "Check your QMetry instance settings to determine the correct date format",
+            "If dates are in wrong format, QMetry will return an error - verify format with admin",
+            "projectID is optional in the cycle object - it will be auto-resolved from the project key if not provided",
+            "To explicitly set projectID, first call FETCH_PROJECT_INFO to get the numeric project ID",
+            "cycle.isLocked defaults to false if not provided - set to true to prevent modifications",
+            "cycle.isArchived defaults to false if not provided - set to true to archive immediately (rare)",
+            "Use descriptive cycle names like 'Sprint 2', 'Regression Cycle', 'Alpha Testing' for better organization",
+            "startDate and targetDate help with sprint planning and milestone tracking",
+            "Cycle hierarchy: Project → Release → Cycle → Test Execution",
+            "After creating a cycle, you can associate test suites and test cases with it",
+            "Use FETCH_RELEASES_CYCLES tool after creation to verify the cycle was created successfully",
+            "DIFFERENCE FROM CREATE_RELEASE: This tool creates a cycle in an EXISTING release, while CREATE_RELEASE can create a release with an optional cycle",
+            "If you need to create both a release and a cycle together, use CREATE_RELEASE tool instead",
+            "If release doesn't exist yet, create it first with CREATE_RELEASE, then add more cycles with this tool",
+        ],
+        outputDescription: "JSON object containing the created cycle ID, cycle details, and association with the release",
+        readOnly: false,
+        idempotent: false,
+    },
+    {
+        title: "Update Cycle",
+        summary: "Update an existing cycle in QMetry for test execution planning",
+        handler: QMetryToolsHandlers.UPDATE_CYCLE,
+        inputSchema: UpdateCycleArgsSchema,
+        purpose: "Update an existing cycle within a release to modify test execution phase details. " +
+            "Cycles represent specific testing iterations, sprints, or phases within a release. " +
+            "This tool requires buildID and releaseID to identify the cycle to update. " +
+            "Essential for maintaining accurate test planning and sprint-based test execution tracking.",
+        useCases: [
+            "Update cycle name for better organization",
+            "Modify cycle dates to reflect schedule changes",
+            "Adjust testing phase timelines within a release",
+            "Update cycle metadata for sprint tracking",
+            "Revise milestone dates for test execution planning",
+            "Rename cycles to match updated sprint naming conventions",
+        ],
+        examples: [
+            {
+                description: "Update cycle name",
+                parameters: {
+                    cycle: {
+                        name: "Alpha_v1_Updated",
+                        buildID: 1494,
+                        releaseID: 3729,
+                    },
+                },
+                expectedOutput: "Cycle updated successfully with new name 'Alpha_v1_Updated'",
+            },
+            {
+                description: "Update cycle dates",
+                parameters: {
+                    cycle: {
+                        startDate: "10-10-2018",
+                        targetDate: "11-11-2018",
+                        buildID: 1494,
+                        releaseID: 3729,
+                    },
+                },
+                expectedOutput: "Cycle dates updated successfully with new start date 10-10-2018 and target date 11-11-2018",
+            },
+            {
+                description: "Update cycle name and dates together",
+                parameters: {
+                    cycle: {
+                        name: "Sprint 2 - Updated",
+                        startDate: "15-01-2024",
+                        targetDate: "31-01-2024",
+                        buildID: 1494,
+                        releaseID: 3729,
+                    },
+                },
+                expectedOutput: "Cycle updated with new name and dates successfully",
+            },
+        ],
+        hints: [
+            "CRITICAL: cycle.buildID is REQUIRED - must provide the build ID to identify the cycle to update",
+            "CRITICAL: cycle.releaseID is REQUIRED - must provide the release ID to identify the cycle to update",
+            "HOW TO GET buildID and releaseID:",
+            "1. Call FETCH_RELEASES_CYCLES tool (API: 'Cycle/List') to get all cycles",
+            "2. From the response, get buildID from projects.releases[<index>].builds[<index>].buildID",
+            "3. From the response, get releaseID from projects.releases[<index>].releaseID",
+            "4. Use those numeric IDs in cycle.buildID and cycle.releaseID parameters",
+            "Example: Cycle 'Sprint 2' might have buildID: 1494 and releaseID: 3729",
+            "CRITICAL WORKFLOW - IF USER PROVIDES CYCLE NAME:",
+            "1. User says: 'Update cycle Sprint 2 to change dates'",
+            "2. You MUST first call FETCH_RELEASES_CYCLES tool to get all cycles",
+            "3. Search the response for cycle with matching name 'Sprint 2'",
+            "4. Extract buildID and releaseID from the matching cycle",
+            "5. Use those IDs in cycle.buildID and cycle.releaseID parameters",
+            "6. If cycle name not found, inform user and list available cycles",
+            "Example workflow:",
+            "- User request: 'Update cycle Alpha_v1 name to Alpha_v1_Updated'",
+            "- Step 1: Call FETCH_RELEASES_CYCLES",
+            "- Step 2: Find cycle where name = 'Alpha_v1', get its buildID (e.g., 1494) and releaseID (e.g., 3729)",
+            "- Step 3: Call UPDATE_CYCLE with cycle.buildID = 1494 and cycle.releaseID = 3729",
+            "CYCLE IDENTIFICATION:",
+            "- NEVER assume or guess buildID or releaseID - always fetch from API",
+            "- Cycle names are user-defined strings (e.g., 'Sprint 2', 'Alpha_v1', 'Regression Cycle')",
+            "- buildID and releaseID are numeric identifiers assigned by QMetry",
+            "- Match cycle names case-insensitively when searching",
+            "- If multiple cycles match the name, ask user to clarify or use the most recent one",
+            "- FETCH_RELEASES_CYCLES returns: projects.releases[].builds[] array with name, buildID, and releaseID",
+            "Date format depends on QMetry instance configuration: DD-MM-YYYY or MM-DD-YYYY",
+            "Check your QMetry instance settings to determine the correct date format",
+            "NOTE: To verify/update the Date Format - Go to QMetry -> User Profile",
+            "If dates are in wrong format, QMetry will return an error - verify format with admin",
+            "You can update name, startDate, or targetDate independently or together",
+            "Only include the fields you want to update - other fields will remain unchanged",
+            "startDate and targetDate help with sprint planning and milestone tracking",
+            "Cycle hierarchy: Project → Release → Cycle → Test Execution",
+            "After updating a cycle, you can verify changes using FETCH_RELEASES_CYCLES tool",
+            "DIFFERENCE FROM CREATE_CYCLE: This tool updates an EXISTING cycle, while CREATE_CYCLE creates a new one",
+        ],
+        outputDescription: "JSON object containing the updated cycle details and confirmation of update",
+        readOnly: false,
+        idempotent: true,
+    },
 ];

package/dist/qmetry/client/tools/requirement-tools.js

@@ -30,7 +30,7 @@ export const REQUIREMENT_TOOLS = [
                 description: "Get requirements with manual viewId (skip auto-resolution)",
                 parameters: {
                     projectKey: "MAC",
-                    viewId: 7397,
+                    viewId: 7397, // This is an example viewId, must be resolved per project RQ viewId
                     folderPath: "/APIARY 88",
                 },
                 expectedOutput: "Requirements using manually specified viewId 7397",