@smartbear/mcp 0.19.2 → 0.21.1

package/dist/qtm4j/tool/project/set-project-context.js

@@ -0,0 +1,99 @@
+import { Tool, ToolError } from "../../../common/tools.js";
+import { TOOL_NAMES, ENDPOINTS, PAGINATION, RESPONSE_FIELDS } from "../../config/constants.js";
+import { SetProjectContextResponse, SetProjectContextBody, GetProjectsResponse } from "../../schema/project.schema.js";
+const PROJECT_SEARCH_MAX_RESULTS = 10;
+const ERRORS = {
+  PROJECT_NOT_FOUND: (key) => `Project with key '${key}' not found. Use the get_projects tool to list available projects.`,
+  NO_EXACT_MATCH: (key, candidates) => `No exact match for project key '${key}'. Did you mean one of: ${candidates.join(", ")}? Please provide the exact project key.`
+};
+class SetProjectContext extends Tool {
+  specification = {
+    title: TOOL_NAMES.SET_PROJECT_CONTEXT.TITLE,
+    summary: TOOL_NAMES.SET_PROJECT_CONTEXT.SUMMARY,
+    readOnly: false,
+    idempotent: true,
+    inputSchema: SetProjectContextBody,
+    outputSchema: SetProjectContextResponse,
+    purpose: "Set the active QTM4J project for the current session. This tool MUST be called before performing ANY project-specific operation. NEVER auto-select a project — if the user has not specified a project key, call get_projects first, show the list to the user, and ask them to choose.",
+    useCases: [
+      "Set the active project at the start of a new conversation",
+      "Switch to a different project mid-conversation",
+      "Validate that a project key exists before performing operations",
+      "Establish project context required by all project-specific tools"
+    ],
+    examples: [
+      {
+        description: "Set SCRUM project as active",
+        parameters: { projectKey: "SCRUM" },
+        expectedOutput: "Project context set to SCRUM (ID: 10000)"
+      },
+      {
+        description: "Switch to AD project",
+        parameters: { projectKey: "AD" },
+        expectedOutput: "Project context switched to AD"
+      }
+    ],
+    hints: [
+      "CRITICAL: This tool MUST be called before ANY project-specific tool.",
+      "NEVER auto-select a project. If the user does not specify a project key, call get_projects first, present the list to the user and ask them to choose. Do NOT pick one on their behalf.",
+      "The project key must be an exact match (e.g., 'SCRUM', not 'scrum project').",
+      "After calling this tool, use the availableFields in the response to map user input via NLP (e.g. user says 'Major' → send 'High', user says 'Critical' → send 'Blocker').",
+      "Switching projects clears the cached field metadata of the previous project only.",
+      "If this tool is called again in the same session, it resets the context to the new project."
+    ],
+    outputDescription: "JSON object with projectId, projectKey, projectName, confirmation message, and availableFields. availableFields contains priority and status options for NLP mapping in subsequent tool calls."
+  };
+  handle = async (rawArgs) => {
+    const { projectKey } = SetProjectContextBody.parse(rawArgs);
+    const apiClient = this.client.getApiClient();
+    const body = {
+      [RESPONSE_FIELDS.START_AT]: PAGINATION.DEFAULT_START_AT,
+      [RESPONSE_FIELDS.MAX_RESULTS]: PROJECT_SEARCH_MAX_RESULTS,
+      search: projectKey
+    };
+    const response = await apiClient.post(ENDPOINTS.PROJECTS, body);
+    const parsed = GetProjectsResponse.parse(response);
+    if (parsed.data.length === 0) {
+      throw new ToolError(ERRORS.PROJECT_NOT_FOUND(projectKey));
+    }
+    const exactMatch = parsed.data.find(
+      (p) => p.key.toLowerCase() === projectKey.toLowerCase()
+    );
+    if (!exactMatch) {
+      const candidates = parsed.data.map((p) => `${p.key} (${p.name})`);
+      throw new ToolError(ERRORS.NO_EXACT_MATCH(projectKey, candidates));
+    }
+    const fieldResolver = this.client.getResolverRegistry();
+    try {
+      const previousContext = fieldResolver.requireProjectContext();
+      if (previousContext.projectKey !== exactMatch.key) {
+        fieldResolver.clearProjectCache(previousContext.projectKey);
+      }
+    } catch {
+    }
+    fieldResolver.setProjectContext({
+      projectId: exactMatch.id,
+      projectKey: exactMatch.key,
+      projectName: exactMatch.name
+    });
+    let availableFields = {};
+    try {
+      availableFields = await fieldResolver.getCommonAttributeResolver().preload(exactMatch.key, exactMatch.id);
+    } catch {
+    }
+    const result = {
+      projectId: exactMatch.id,
+      projectKey: exactMatch.key,
+      projectName: exactMatch.name,
+      message: `Project context set to '${exactMatch.key}' (${exactMatch.name}, ID: ${exactMatch.id}). You can now perform project-specific operations.`,
+      availableFields
+    };
+    return {
+      structuredContent: SetProjectContextResponse.parse(result),
+      content: []
+    };
+  };
+}
+export {
+  SetProjectContext
+};

package/dist/qtm4j/tool/test-case/create-test-case.js

@@ -0,0 +1,113 @@
+import { Tool } from "../../../common/tools.js";
+import { TOOL_NAMES, ENDPOINTS } from "../../config/constants.js";
+import { ResolverKeys, InputField } from "../../config/field-resolution.types.js";
+import { CreateTestCaseResponse, CreateTestCaseBody } from "../../schema/test-case.schema.js";
+const FIELD_CONFIG = {
+  [InputField.PRIORITY]: ResolverKeys.CommonAttribute.PRIORITY,
+  [InputField.STATUS]: ResolverKeys.CommonAttribute.TESTCASE_STATUS,
+  [InputField.FOLDER]: ResolverKeys.CommonAttribute.TESTCASE_FOLDER,
+  [InputField.COMPONENTS]: ResolverKeys.SearchableField.COMPONENTS,
+  [InputField.LABELS]: ResolverKeys.SearchableField.LABEL
+};
+class CreateTestCase extends Tool {
+  // ─── Tool Specification ────────────────────────────────────────────────────
+  specification = {
+    title: TOOL_NAMES.CREATE_TEST_CASE.TITLE,
+    summary: TOOL_NAMES.CREATE_TEST_CASE.SUMMARY,
+    readOnly: false,
+    idempotent: false,
+    inputSchema: CreateTestCaseBody,
+    outputSchema: CreateTestCaseResponse,
+    purpose: "Create a new test case in QTM4J with steps, metadata, and field auto-resolution. For priority and status, use the names returned by set_project_context and map via NLP. For labels and components, provide exact names — resolved on demand. PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "Create a basic test case with just a summary",
+      "Create a test case with priority and status using names from set_project_context response",
+      "Create a test case with labels and components by exact name",
+      "Add detailed test steps with step descriptions, test data, and expected results",
+      "Create a test case in a specific folder using folderId",
+      "Set assignee and reporter using Jira account IDs",
+      "Create test cases for manual testing with step-by-step instructions",
+      "Create test cases with all metadata fields for comprehensive test management"
+    ],
+    examples: [
+      {
+        description: "Create a simple test case (project must be set via set_project_context first)",
+        parameters: { summary: "Search Functionality" },
+        expectedOutput: "Test case created with key 'SCRUM-TC-xxx'"
+      },
+      {
+        description: "Create a test case with priority and status",
+        parameters: {
+          summary: "Search Functionality",
+          description: "Verify search functionality works correctly",
+          priority: "High",
+          status: "To Do"
+        },
+        expectedOutput: "Test case created with resolved priority and status IDs"
+      },
+      {
+        description: "Create a test case with labels, components, and steps",
+        parameters: {
+          summary: "Search Functionality",
+          description: "Search Functionality Test",
+          priority: "High",
+          status: "To Do",
+          labels: ["Release_1", "Sprint 1"],
+          components: ["UI", "Cloud"],
+          steps: [
+            {
+              stepDetails: "Enter a keyword in the search box",
+              testData: 'Keyword = "Test"',
+              expectedResult: "The keyword should be visible in the search box"
+            },
+            {
+              stepDetails: "Click on the Search button",
+              testData: "Click on Search Button",
+              expectedResult: "Search results matching the keyword should be displayed"
+            },
+            {
+              stepDetails: "Verify the search results",
+              testData: "Expected results list",
+              expectedResult: "Results should be relevant to the entered keyword"
+            }
+          ]
+        },
+        expectedOutput: "Test case created with resolved labels/components/priority/status and 3 steps"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "Priority and status values were returned by set_project_context. Use NLP to map user input (e.g., 'Major' → 'High', 'Critical' → 'Blocker').",
+      "If priority or status name is not found, the operation proceeds without that field and a warning is returned.",
+      "Labels and components are resolved on demand. If a name is not found, it is skipped with a warning.",
+      "Steps: ALWAYS include all three fields — stepDetails, testData, and expectedResult. Generate reasonable values if not provided.",
+      "folderId is optional. assignee and reporter accept Jira account IDs."
+    ],
+    outputDescription: "JSON object with test case ID, key, version number, and summary. Warnings included if any fields were skipped."
+  };
+  // ─── Handle Implementation ──────────────────────────────────────────────────
+  handle = async (rawArgs) => {
+    const fieldResolver = this.client.getResolverRegistry();
+    const context = fieldResolver.requireProjectContext();
+    const body = {
+      ...CreateTestCaseBody.parse(rawArgs),
+      projectId: String(context.projectId),
+      folderId: "MCP Generated"
+    };
+    const warnings = [];
+    await Promise.all(
+      Object.entries(FIELD_CONFIG).map(
+        ([inputField, resolverKey]) => fieldResolver.getResolver(resolverKey).resolve(inputField, resolverKey, body, context, warnings)
+      )
+    );
+    const response = await this.client.getApiClient().post(ENDPOINTS.CREATE_TEST_CASE, body);
+    const validated = CreateTestCaseResponse.parse(response);
+    return {
+      structuredContent: validated,
+      content: warnings.length > 0 ? [{ type: "text", text: `Note: ${warnings.join(" | ")}` }] : []
+    };
+  };
+}
+export {
+  CreateTestCase
+};

package/dist/qtm4j/tool/test-case/get-test-cases.js

@@ -0,0 +1,295 @@
+import { Tool } from "../../../common/tools.js";
+import { TOOL_NAMES, RESPONSE_FIELDS, ENDPOINTS } from "../../config/constants.js";
+import { SearchTestCaseResponse, SearchTestCaseBody } from "../../schema/get-test-case.schema.js";
+class GetTestCases extends Tool {
+  specification = {
+    title: TOOL_NAMES.SEARCH_TEST_CASES.TITLE,
+    summary: TOOL_NAMES.SEARCH_TEST_CASES.SUMMARY,
+    readOnly: true,
+    idempotent: true,
+    inputSchema: SearchTestCaseBody,
+    outputSchema: SearchTestCaseResponse,
+    purpose: "Search and filter test cases in a QTM4J project. The filter object is sent in the request body; fields, sort, startAt, and maxResults are sent as URL query parameters. All filter values accept string names directly (e.g., status: ['Done'], priority: ['High'], labels: ['Release_1']). PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "Search all test cases in a project",
+      "Filter test cases by status (e.g., 'Done', 'To Do', 'In Progress')",
+      "Filter test cases by priority (e.g., 'High', 'Medium', 'Low')",
+      "Filter test cases by labels and components",
+      "Search test cases by text in summary and description",
+      "Filter test cases by assignee or reporter",
+      "Filter test cases by creation/update date ranges",
+      "Filter test cases by automation status",
+      "Request only specific fields to reduce response size",
+      "Sort results using the sort query param (e.g., 'created:desc', 'priority:asc')",
+      "Paginate through large result sets using startAt and maxResults",
+      "Combine multiple filters for complex queries",
+      "Find all failed test cases that need attention (by status and execution date)",
+      "Get test cases for sprint planning (filter by sprint and status)",
+      "Audit test coverage by searching for untested areas (filter by executed date)",
+      "Find all manual test cases assigned to a specific tester",
+      "Generate test reports by filtering and sorting test cases",
+      "Track test case changes over time (filter by update date range)",
+      "Identify high-priority test cases pending review",
+      "Search for test cases related to specific features (using searchText)",
+      "Find duplicate or similar test cases (using searchText)",
+      "Get automated vs manual test distribution (filter by isAutomated)",
+      "Monitor test execution trends (filter by executed date ranges)",
+      "Prepare test execution schedules (filter by assignee and priority)"
+    ],
+    examples: [
+      {
+        description: "Search all test cases in the project",
+        parameters: {},
+        expectedOutput: "Paginated list of all test cases with all fields (first 50 results)"
+      },
+      {
+        description: "Filter test cases by status",
+        parameters: {
+          filter: {
+            status: ["Done"]
+          }
+        },
+        expectedOutput: "List of test cases with 'Done' status"
+      },
+      {
+        description: "Filter by multiple statuses and priorities with specific fields",
+        parameters: {
+          filter: {
+            status: ["Done", "To Do"],
+            priority: ["High", "Medium"]
+          },
+          fields: ["key", "summary", "status", "priority", "assignee"]
+        },
+        expectedOutput: "Test cases matching the filters with only the selected fields returned"
+      },
+      {
+        description: "Search test cases by text in summary/description",
+        parameters: {
+          filter: {
+            searchText: "login functionality"
+          }
+        },
+        expectedOutput: "Test cases containing 'login functionality' in summary or description"
+      },
+      {
+        description: "Filter by labels and components",
+        parameters: {
+          filter: {
+            labels: ["Release_1", "Sprint 1"],
+            components: ["UI", "Cloud"]
+          }
+        },
+        expectedOutput: "Test cases tagged with the specified labels and components"
+      },
+      {
+        description: "Filter by assignee and automation status",
+        parameters: {
+          filter: {
+            assignee: ["712020:ddc8e24b-2de7-404b-b9ed-3d7b241e2ced"],
+            isAutomated: false
+          }
+        },
+        expectedOutput: "Manual test cases assigned to the specified user"
+      },
+      {
+        description: "Filter by creation date range",
+        parameters: {
+          filter: {
+            createdOnFrom: "01/Jan/2026",
+            createdOnTo: "31/Dec/2026"
+          }
+        },
+        expectedOutput: "Test cases created during 2026"
+      },
+      {
+        description: "Paginate and sort by creation date (newest first)",
+        parameters: {
+          filter: {
+            status: ["Done"]
+          },
+          startAt: 0,
+          maxResults: 50,
+          sort: "created:desc"
+        },
+        expectedOutput: "First 50 'Done' test cases sorted by creation date, newest first"
+      },
+      {
+        description: "Get all available fields for test cases",
+        parameters: {
+          filter: {},
+          fields: [
+            "key",
+            "summary",
+            "description",
+            "priority",
+            "status",
+            "assignee",
+            "isAutomated",
+            "reporter",
+            "estimatedTime",
+            "labels",
+            "components",
+            "fixVersions",
+            "sprint",
+            "folders",
+            "updated",
+            "created",
+            "executed",
+            "flakyScore",
+            "passRateScore",
+            "aiGenerated",
+            "precondition",
+            "orderNo",
+            "seqNo",
+            "version"
+          ]
+        },
+        expectedOutput: "Test cases with all available fields explicitly requested"
+      },
+      {
+        description: "Filter by folder and fix version",
+        parameters: {
+          filter: {
+            folders: [123, 456],
+            fixVersions: [789]
+          }
+        },
+        expectedOutput: "Test cases in the specified folders and fix versions"
+      },
+      {
+        description: "Complex filter: multiple criteria combined with multi-field sort",
+        parameters: {
+          filter: {
+            status: ["Done", "In Progress"],
+            priority: ["High"],
+            labels: ["Release_1"],
+            isAutomated: false,
+            createdOnFrom: "01/Apr/2026",
+            createdOnTo: "30/Apr/2026"
+          },
+          fields: ["key", "summary", "status", "priority", "created"],
+          sort: "priority:asc,created:desc"
+        },
+        expectedOutput: "High-priority manual test cases created in April 2026 with 'Done' or 'In Progress' status, sorted by priority ascending then creation date descending"
+      },
+      {
+        description: "Find all automated test cases for CI/CD pipeline",
+        parameters: {
+          filter: {
+            isAutomated: true,
+            status: ["Done", "In Progress"]
+          },
+          fields: ["key", "summary", "status", "labels", "components"]
+        },
+        expectedOutput: "Up to 50 automated test cases ready for execution in CI/CD"
+      },
+      {
+        description: "Sprint planning: get pending test cases for a team, sorted by priority",
+        parameters: {
+          filter: {
+            status: ["To Do", "In Progress"],
+            assignee: [
+              "712020:ddc8e24b-2de7-404b-b9ed-3d7b241e2ced",
+              "712020:b8479b55-6d23-478c-a2ad-4c8ce176e1fc"
+            ],
+            priority: ["High", "Medium"]
+          },
+          fields: [
+            "key",
+            "summary",
+            "status",
+            "priority",
+            "assignee",
+            "estimatedTime"
+          ],
+          sort: "priority:desc"
+        },
+        expectedOutput: "Pending high and medium priority test cases assigned to the team, sorted by priority descending"
+      },
+      {
+        description: "Test coverage report: find completed cases sorted oldest first",
+        parameters: {
+          filter: {
+            status: ["Done"]
+          },
+          fields: ["key", "summary", "priority", "created", "assignee"],
+          sort: "created:asc"
+        },
+        expectedOutput: "Completed test cases sorted by creation date, oldest first"
+      },
+      {
+        description: "Find test cases by keyword for regression testing",
+        parameters: {
+          filter: {
+            searchText: "authentication login",
+            status: ["Done"]
+          },
+          fields: ["key", "summary", "description", "labels", "components"]
+        },
+        expectedOutput: "All completed test cases related to authentication/login functionality"
+      },
+      {
+        description: "Weekly test execution summary",
+        parameters: {
+          filter: {
+            executedOnFrom: "27/Apr/2026",
+            executedOnTo: "03/May/2026"
+          },
+          fields: [
+            "key",
+            "summary",
+            "status",
+            "executed",
+            "passRateScore",
+            "flakyScore"
+          ],
+          sort: "executed:desc"
+        },
+        expectedOutput: "Test cases executed in the past week with their pass rates and flaky scores, sorted most-recent first"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "REQUEST STRUCTURE: filter goes in the request body; fields, sort, startAt, and maxResults are URL query parameters.",
+      "The 'projectId' inside filter is auto-populated from the active project context if not provided.",
+      "All filter values accept string names directly — no ID resolution needed (e.g., status: ['Done'], priority: ['High']).",
+      "FIELDS: Pass as an array (sent as comma-separated URL param). Example: { fields: ['key', 'summary', 'status'] }. Omit to return all fields.",
+      "Available fields: key, summary, description, priority, status, assignee, isAutomated, reporter, estimatedTime, labels, components, fixVersions, sprint, folders, updated, created, executed, flakyScore, passRateScore, aiGenerated, precondition, orderNo, seqNo, version",
+      "SORTING: Use 'sort' with format 'fieldName:order' (asc/desc). Multiple fields: 'priority:asc,created:desc'. Sortable fields: key, summary, created, updated, status, priority, executed.",
+      "PAGINATION: startAt (default: 0) and maxResults (default: 50, max: 50) are sent as URL query params. Increment startAt by 50 to get the next page. Stop when startAt >= total.",
+      "Date format for all filter date fields: 'dd/MMM/yyyy' (e.g., '17/Apr/2026', '01/Jan/2026'). Case-sensitive.",
+      "FILTER LOGIC: Multiple values within one filter field use OR (status: ['Done', 'To Do'] = Done OR To Do).",
+      "FILTER LOGIC: Different filter fields are combined with AND (status + priority = both must match).",
+      "The 'searchText' filter searches both summary and description fields (case-insensitive). To get details of a specific test case by its key (e.g., 'SCRUM-TC-145'), pass the key as filter.searchText — there is no separate key filter field.",
+      "For assignee/reporter filters, use Jira account IDs (format: '712020:uuid'). Multiple IDs = OR logic.",
+      "Omitting filter entirely returns all test cases in the active project (paginated)."
+    ],
+    outputDescription: "JSON object with total (total matching test cases), startAt, maxResults, and data (array of test case objects for this page)."
+  };
+  handle = async (rawArgs) => {
+    const args = SearchTestCaseBody.parse(rawArgs);
+    const context = this.client.getResolverRegistry().requireProjectContext();
+    if (!args.filter) {
+      args.filter = {};
+    }
+    if (!args.filter.projectId) {
+      args.filter.projectId = String(context.projectId);
+    }
+    const params = new URLSearchParams();
+    if (args.fields?.length)
+      params.set(RESPONSE_FIELDS.FIELDS, args.fields.join(","));
+    if (args.sort) params.set(RESPONSE_FIELDS.SORT, args.sort);
+    params.set(RESPONSE_FIELDS.START_AT, String(args.startAt));
+    params.set(RESPONSE_FIELDS.MAX_RESULTS, String(args.maxResults));
+    const endpoint = `${ENDPOINTS.SEARCH_TEST_CASES}?${params.toString()}`;
+    const response = await this.client.getApiClient().post(endpoint, { filter: args.filter });
+    const validated = SearchTestCaseResponse.parse(response);
+    return {
+      structuredContent: validated,
+      content: []
+    };
+  };
+}
+export {
+  GetTestCases
+};

package/dist/qtm4j/tool/test-case/get-test-steps.js

@@ -0,0 +1,111 @@
+import { Tool, ToolError } from "../../../common/tools.js";
+import { TOOL_NAMES, RESPONSE_FIELDS, ENDPOINTS } from "../../config/constants.js";
+import { ResolverKeys } from "../../config/field-resolution.types.js";
+import { GetTestStepsResponse, GetTestStepsBody } from "../../schema/get-test-steps.schema.js";
+class GetTestSteps extends Tool {
+  specification = {
+    title: TOOL_NAMES.GET_TEST_STEPS.TITLE,
+    summary: TOOL_NAMES.GET_TEST_STEPS.SUMMARY,
+    readOnly: true,
+    idempotent: true,
+    inputSchema: GetTestStepsBody,
+    outputSchema: GetTestStepsResponse,
+    purpose: "Retrieve the test steps for a specific test case version using the human-readable test case key. The key is automatically resolved to the internal test case UID via a dedicated batch API — no separate lookup required. Test steps describe the step-by-step actions (stepDetails), input data (testData), and expected results (expectedResult) for executing a test case. Steps may also reference shared (reusable) test cases, surfaced via the 'shareable' field. PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "View all steps of a test case before executing it",
+      "Review steps for a specific test case version",
+      "Filter steps by action text, test data, or expected result",
+      "Get steps for a test case found via search_test_cases",
+      "Inspect shared (reusable) steps embedded in a test case",
+      "Sort steps by sequence number to view them in execution order",
+      "Paginate through test cases that have a large number of steps"
+    ],
+    examples: [
+      {
+        description: "Get all steps for a test case (latest version)",
+        parameters: { key: "SCRUM-TC-145" },
+        expectedOutput: "All steps for SCRUM-TC-145 with stepDetails, testData, expectedResult, and any shared step blocks"
+      },
+      {
+        description: "Get steps for a specific version",
+        parameters: { key: "SCRUM-TC-145", versionNo: 2 },
+        expectedOutput: "Steps for version 2 of SCRUM-TC-145"
+      },
+      {
+        description: "Get steps in execution order",
+        parameters: { key: "SCRUM-TC-85", sort: "seqNo:asc" },
+        expectedOutput: "All steps sorted by sequence number ascending"
+      },
+      {
+        description: "Filter steps by action text",
+        parameters: {
+          key: "SCRUM-TC-32",
+          filter: { stepDetails: "Open the application" }
+        },
+        expectedOutput: "Steps whose stepDetails contain 'Open the application'"
+      },
+      {
+        description: "Filter steps by expected result",
+        parameters: {
+          key: "SCRUM-TC-65",
+          filter: { expectedResult: "logged in successfully" }
+        },
+        expectedOutput: "Steps whose expectedResult contains 'logged in successfully'"
+      },
+      {
+        description: "Filter steps by test data",
+        parameters: {
+          key: "SCRUM-TC-125",
+          filter: { testData: "Username: user1" }
+        },
+        expectedOutput: "Steps with testData containing 'Username: user1'"
+      },
+      {
+        description: "Paginate through many steps",
+        parameters: {
+          key: "SCRUM-TC-105",
+          startAt: 0,
+          maxResults: 10,
+          sort: "seqNo:asc"
+        },
+        expectedOutput: "First 10 steps in sequence order"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "KEY FORMAT: '{PROJECT_KEY}-TC-{number}' — e.g. 'SCRUM-TC-145'. PROJECT_KEY is the Jira project key; the number is the test case counter within that project (auto-incremented, not the same as seqNo).",
+      "VERSION: versionNo defaults to the latest version. Get the version number from search_test_cases response: version.versionNo.",
+      "Use search_test_cases to discover test case keys before calling this tool.",
+      "SHAREABLE STEPS: Steps with a non-null 'shareable' field are references to shared/reusable test cases. The 'shareable.shareableTestSteps' array contains the embedded sub-steps with decimal seqNo values (e.g. '1.1', '1.2').",
+      "FILTER: Each filter field is a substring match (case-insensitive). Multiple fields combine with AND.",
+      "SORT: 'seqNo:asc' shows steps in their natural execution order. Allowed sort fields: stepDetails, testData, seqNo, expectedResult.",
+      "PAGINATION: startAt and maxResults are URL query params. Default page size is 50, maximum is 100."
+    ],
+    outputDescription: "JSON object with total (total matching steps), startAt, maxResults, and data (array of step objects). Each step has: id, seqNo, stepDetails, testData, expectedResult, attachmentCount. Shared steps also have a 'shareable' object containing shareableTestcaseUID and shareableTestSteps array."
+  };
+  handle = async (rawArgs) => {
+    const args = GetTestStepsBody.parse(rawArgs);
+    const fieldResolver = this.client.getResolverRegistry();
+    const context = fieldResolver.requireProjectContext();
+    const resolved = await fieldResolver.getResolver(ResolverKeys.SearchableField.TEST_CASE_KEY_TO_UID).resolveAndReturn(context.projectId, [args.key]);
+    const entry = resolved[args.key];
+    if (!entry) {
+      throw new ToolError(
+        `Test case '${args.key}' not found in project '${context.projectKey}'. Verify the key using the search_test_cases tool.`
+      );
+    }
+    const versionNo = args.versionNo ?? entry.latestVersion;
+    const params = new URLSearchParams();
+    params.set(RESPONSE_FIELDS.START_AT, String(args.startAt));
+    params.set(RESPONSE_FIELDS.MAX_RESULTS, String(args.maxResults));
+    if (args.sort) params.set(RESPONSE_FIELDS.SORT, args.sort);
+    const endpoint = `${ENDPOINTS.TEST_STEPS(entry.uid, versionNo)}?${params.toString()}`;
+    const filterBody = args.filter && Object.keys(args.filter).length > 0 ? { filter: args.filter } : {};
+    const response = await this.client.getApiClient().post(endpoint, filterBody);
+    const validated = GetTestStepsResponse.parse(response);
+    return { structuredContent: validated, content: [] };
+  };
+}
+export {
+  GetTestSteps
+};