@testkase/test-management-mcp 0.0.0-stage → 2.4.0

package/build/index.js

@@ -0,0 +1,1678 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import axios from "axios";
+const config = {
+    apiBaseUrl: (process.env.TESTKASE_API_BASE_URL || "https://api.testkase.com").replace(/\/+$/, ""),
+    patToken: process.env.TESTKASE_PAT_TOKEN,
+    // Only needed when the PAT user belongs to more than one organization
+    organizationId: process.env.TESTKASE_ORGANIZATION_ID
+        ? Number(process.env.TESTKASE_ORGANIZATION_ID)
+        : undefined,
+    appUrl: process.env.TESTKASE_APP_URL?.replace(/\/+$/, ""),
+};
+const VERSION = "2.4.0";
+const REQUEST_TIMEOUT_MS = 60_000;
+// ─── Frontend URL helper ─────────────────────────────────────────────────────
+// Test management lives on its own subdomain
+const KNOWN_APP_HOSTS = {
+    "api.testkase.com": "https://test-management.testkase.com",
+    "apiqa.testkase.com": "https://test-management-qa.testkase.com",
+};
+function getFrontendBaseUrl() {
+    if (config.appUrl)
+        return config.appUrl;
+    const url = new URL(config.apiBaseUrl);
+    if (KNOWN_APP_HOSTS[url.hostname])
+        return KNOWN_APP_HOSTS[url.hostname];
+    url.hostname = url.hostname.replace(/^api\.?/, "");
+    return url.origin;
+}
+// ─── Auth helpers (reused from v1) ───────────────────────────────────────────
+function validateAuth() {
+    if (!config.patToken) {
+        throw new Error("Authentication required. Please set TESTKASE_PAT_TOKEN environment variable. " +
+            "Generate a Personal Access Token (PAT) from your TestKase account settings.");
+    }
+    if (!config.patToken.startsWith("xyz_")) {
+        throw new Error("Invalid PAT token format. TestKase PAT tokens must start with 'xyz_' prefix. " +
+            "Please generate a valid PAT from your TestKase account settings.");
+    }
+}
+function getApiHeaders() {
+    return {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.patToken}`,
+    };
+}
+// ─── Cached org ID (auto-resolved from PAT, never a tool param) ─────────────
+let cachedOrganizationId = null;
+async function getOrganizationId() {
+    if (config.organizationId && !isNaN(config.organizationId))
+        return config.organizationId;
+    if (cachedOrganizationId !== null)
+        return cachedOrganizationId;
+    validateAuth();
+    try {
+        const response = await axios.get(`${config.apiBaseUrl}/api/v1/organizations/my-organization`, { headers: getApiHeaders(), timeout: REQUEST_TIMEOUT_MS });
+        const orgData = response.data?.data || response.data;
+        if (orgData?.organization_id) {
+            cachedOrganizationId = orgData.organization_id;
+            return cachedOrganizationId;
+        }
+        throw new Error("Could not determine organization from PAT token");
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes("Could not determine"))
+            throw error;
+        const status = axios.isAxiosError(error) ? error.response?.status : undefined;
+        throw new Error(status === 401 || status === 403
+            ? `Failed to fetch organization (status ${status}). Your PAT token is invalid, expired or revoked.`
+            : `Failed to fetch organization${status ? ` (status ${status})` : ""}. Check TESTKASE_API_BASE_URL and your network.`);
+    }
+}
+// ─── API call helper ─────────────────────────────────────────────────────────
+async function callApi(method, path, options = {}) {
+    validateAuth();
+    const orgId = options.skipOrgId ? undefined : await getOrganizationId();
+    const queryParams = new URLSearchParams();
+    if (orgId)
+        queryParams.append("organizationId", orgId.toString());
+    if (options.query) {
+        for (const [key, val] of Object.entries(options.query)) {
+            if (val !== undefined && val !== null && val !== "") {
+                queryParams.append(key, String(val));
+            }
+        }
+    }
+    const qs = queryParams.toString();
+    const url = `${config.apiBaseUrl}/api/v1/${path}${qs ? `?${qs}` : ""}`;
+    const response = await axios({
+        method,
+        url,
+        headers: getApiHeaders(),
+        timeout: REQUEST_TIMEOUT_MS,
+        ...(options.body !== undefined && { data: options.body }),
+    });
+    // Some endpoints report "not found" as HTTP 200 with status "error"
+    const data = response.data;
+    if (data && typeof data === "object" && data.status === "error") {
+        const detail = data.message || data.success || data.error || "Request failed";
+        throw new Error(`API returned an error: ${String(detail).slice(0, 500)}`);
+    }
+    return data;
+}
+// ─── Error handler (reused) ──────────────────────────────────────────────────
+function handleApiError(error) {
+    if (axios.isAxiosError(error)) {
+        const e = error;
+        let msg = `API request failed: ${e.message}`;
+        if (e.response) {
+            msg += `\nStatus: ${e.response.status}`;
+            if (e.response.status === 401) {
+                cachedOrganizationId = null;
+            }
+            if (e.response.data) {
+                const d = e.response.data;
+                const safeMsg = d.message || d.error || (typeof d === "string" ? d : undefined);
+                if (safeMsg)
+                    msg += `\nDetails: ${String(safeMsg).slice(0, 500)}`;
+            }
+        }
+        return new Error(msg);
+    }
+    return error;
+}
+// ─── JSON response helper ────────────────────────────────────────────────────
+function jsonResponse(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+function safeJsonParse(raw, fieldName) {
+    if (typeof raw !== "string")
+        return raw;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON in ${fieldName}. Ensure the value is valid JSON.`);
+    }
+}
+function validateId(id, fieldName) {
+    const str = String(id);
+    if (!/^[a-zA-Z0-9_\-]+$/.test(str)) {
+        throw new Error(`Invalid ${fieldName}: contains disallowed characters`);
+    }
+    return str;
+}
+function toIdList(raw) {
+    return Array.isArray(raw) ? raw.join(",") : String(raw);
+}
+function toStringArray(raw) {
+    if (Array.isArray(raw))
+        return raw.map((v) => String(v).trim()).filter(Boolean);
+    return String(raw).split(",").map((s) => s.trim()).filter(Boolean);
+}
+// Normalise one test step; the backend requires `description` to be a string
+function normalizeStep(s) {
+    if (typeof s === "string")
+        return { description: s };
+    const step = {
+        description: s?.description ?? s?.step ?? s?.action ?? "",
+        test_data: s?.test_data ?? s?.testData,
+        expected_result: s?.expected_result ?? s?.expectedResult ?? s?.expected,
+    };
+    if (!step.description && !step.test_data && !step.expected_result) {
+        throw new Error("Each test step needs at least a description, test_data or expected_result");
+    }
+    return step;
+}
+function parseSteps(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return null;
+    const parsed = safeJsonParse(raw, "test_steps");
+    if (!Array.isArray(parsed))
+        throw new Error("test_steps must be a JSON array");
+    return parsed.map(normalizeStep);
+}
+// Steps are added one call each; collect failures instead of aborting
+async function addSteps(projectId, testcaseId, steps) {
+    let created = 0;
+    const errors = [];
+    for (const [i, step] of steps.entries()) {
+        try {
+            await callApi("post", `projects/testcases/teststeps/${projectId}/${testcaseId}`, { body: step });
+            created++;
+        }
+        catch (error) {
+            const err = axios.isAxiosError(error) ? handleApiError(error) : error;
+            errors.push(`step ${i + 1}: ${err.message}`);
+        }
+    }
+    return { created, errors };
+}
+// The list endpoints only accept array values inside the filters JSON
+function buildFilters(raw, extra = {}) {
+    const parsed = raw ? safeJsonParse(raw, "filters") : {};
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("filters must be a JSON object");
+    }
+    const merged = { ...parsed };
+    for (const [k, v] of Object.entries(extra)) {
+        if (v !== undefined && v !== null && v !== "")
+            merged[k] = v;
+    }
+    for (const k of Object.keys(merged)) {
+        if (k === "custom_fields" || k.startsWith("custom_fields."))
+            continue;
+        if (!Array.isArray(merged[k]))
+            merged[k] = [merged[k]];
+    }
+    return Object.keys(merged).length ? JSON.stringify(merged) : undefined;
+}
+// Builds the create/bulk-create payload from tool args (shared by both actions)
+async function buildTestcasePayload(projectId, tc) {
+    const data = { title: tc.title ?? tc.name };
+    const summary = tc.summary ?? tc.description;
+    if (summary)
+        data.summary = summary;
+    for (const f of ["priority", "status", "automated", "platform"]) {
+        if (tc[f])
+            data[f] = await coerceFieldValue(projectId, f, tc[f]);
+    }
+    const rawFolderId = tc.folder_id ?? tc.folderId;
+    if (rawFolderId !== undefined && rawFolderId !== null && rawFolderId !== "") {
+        const num = Number(rawFolderId);
+        if (isNaN(num))
+            throw new Error("folder_id must be a numeric folder ID");
+        data.folder_id = num;
+    }
+    if (tc.labels)
+        data.labels = toStringArray(tc.labels);
+    if (tc.features)
+        data.features = toStringArray(tc.features);
+    if (tc.environment)
+        data.environment = toStringArray(tc.environment);
+    for (const f of ["precondition", "test_data", "expected_result"]) {
+        if (tc[f])
+            data[f] = tc[f];
+    }
+    const ownerId = tc.owner_id ?? tc.ownerId;
+    if (ownerId) {
+        const num = Number(ownerId);
+        data.owner_id = isNaN(num) ? ownerId : num;
+    }
+    const customRaw = tc.custom_fields ?? tc.customFields;
+    if (customRaw) {
+        const parsed = safeJsonParse(customRaw, "custom_fields");
+        for (const key of Object.keys(parsed)) {
+            if (!Array.isArray(parsed[key]))
+                parsed[key] = [parsed[key]];
+        }
+        data.custom_fields = parsed;
+    }
+    return data;
+}
+function jsonResponseWithHints(data, hints) {
+    const json = JSON.stringify(data, null, 2);
+    const hintsBlock = hints.length > 0
+        ? `\n\n---\nHINTS:\n${hints.map((h) => `- ${h}`).join("\n")}`
+        : "";
+    return {
+        content: [{ type: "text", text: json + hintsBlock }],
+    };
+}
+// ─── Error enrichment ───────────────────────────────────────────────────────
+const ERROR_HINTS = [
+    { pattern: /Invalid value.*for field/i,
+        hint: "RECOVERY: Call get_project_structure(projectId, include='field_options') to discover allowed values for this field, then retry." },
+    { pattern: /must be a number/i,
+        hint: "RECOVERY: This field requires a numeric ID. Call get_project_structure(projectId) to find valid IDs." },
+    { pattern: /folder_id/i,
+        hint: "RECOVERY: folder_id must be a numeric folder ID. Call get_project_structure(projectId, include='folders') to list folders with their IDs." },
+    { pattern: /status.*(401|unauthorized)/i,
+        hint: "RECOVERY: PAT token may be expired. User needs to regenerate it from TestKase > API Keys." },
+    { pattern: /Status: 403/i,
+        hint: "RECOVERY: The user's project role does not allow this action (e.g. only owners and project admins can delete folders). If the project belongs to another organization, set TESTKASE_ORGANIZATION_ID." },
+    { pattern: /priority/i,
+        hint: "RECOVERY: Priority values are project-specific. Call get_project_structure(projectId, include='field_options') to discover allowed values." },
+];
+function enrichErrorMessage(errorMsg) {
+    for (const { pattern, hint } of ERROR_HINTS) {
+        if (pattern.test(errorMsg)) {
+            return `${errorMsg}\n\n${hint}`;
+        }
+    }
+    return errorMsg;
+}
+// ─── Field options cache (5-min TTL) ────────────────────────────────────────
+const fieldOptionsCache = new Map();
+const FIELD_OPTIONS_TTL = 5 * 60 * 1000; // 5 minutes
+async function getFieldOptions(projectId) {
+    const cached = fieldOptionsCache.get(projectId);
+    if (cached && Date.now() - cached.ts < FIELD_OPTIONS_TTL) {
+        return cached.data;
+    }
+    try {
+        const response = await callApi("get", `projects/fields/options/${projectId}`);
+        const options = response?.data || response || [];
+        fieldOptionsCache.set(projectId, { data: options, ts: Date.now() });
+        return options;
+    }
+    catch {
+        return cached?.data || [];
+    }
+}
+async function coerceFieldValue(projectId, fieldName, rawValue) {
+    if (rawValue === undefined || rawValue === null)
+        return rawValue;
+    const options = await getFieldOptions(projectId);
+    const fieldDef = options.find((f) => f.fieldName?.toLowerCase() === fieldName.toLowerCase());
+    if (!fieldDef?.values || !Array.isArray(fieldDef.values))
+        return rawValue;
+    const strValue = String(rawValue);
+    // Exact match
+    if (fieldDef.values.includes(strValue))
+        return strValue;
+    // Case-insensitive match
+    const match = fieldDef.values.find((v) => v.toLowerCase() === strValue.toLowerCase());
+    if (match)
+        return match;
+    // No match — return as-is, let API validate
+    return rawValue;
+}
+// ─── Param normalizer (handles camelCase / snake_case) ───────────────────────
+function p(args, ...names) {
+    for (const n of names) {
+        if (args[n] !== undefined)
+            return args[n];
+    }
+    return undefined;
+}
+function requireArg(args, name, aliases = []) {
+    const value = p(args, name, ...aliases);
+    if (value === undefined || value === null || value === "") {
+        throw new Error(`${name} is required for this action`);
+    }
+    return value;
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// TOOL DEFINITIONS (11 tools)
+// ═══════════════════════════════════════════════════════════════════════════════
+const LIST_PROJECTS_TOOL = {
+    name: "list_projects",
+    description: "List all projects the authenticated user has access to. " +
+        "Use this first to find a projectId, then pass it to other tools.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+        type: "object",
+        properties: {
+            page: { type: "number", description: "Page number (default: 1)" },
+            limit: { type: "number", description: "Items per page (default: 12)" },
+        },
+        required: [],
+    },
+};
+const GET_PROJECT_STRUCTURE_TOOL = {
+    name: "get_project_structure",
+    description: "Get the structure of a project: folders, labels, team members, and field options (allowed values for priority, status, etc.). " +
+        "IMPORTANT: Call this before create/update to discover allowed field values, which are project-specific.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: { type: "string", description: "Project ID (e.g. PRJ-1001)" },
+            section: {
+                type: "string",
+                enum: ["TESTCASE", "TEST_CYCLE", "TEST_PLAN"],
+                description: "Folder section (default: TESTCASE)",
+            },
+            include: {
+                type: "string",
+                description: "Comma-separated list of what to include: folders,labels,members,field_options (default: all)",
+            },
+        },
+        required: ["projectId"],
+    },
+};
+const SEARCH_TESTCASES_TOOL = {
+    name: "search_testcases",
+    description: "Search and list test cases in a project. Supports text search, folder filter, filters, sorting, and pagination.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: { type: "string", description: "Project ID" },
+            search: { type: "string", description: "Search text (ID, title, summary, field values)" },
+            folder_id: {
+                type: "number",
+                description: "Only test cases in this folder (sub-folders included). Use 0 for test cases with no folder.",
+            },
+            filters: {
+                type: "string",
+                description: 'JSON object of filters; every value is a list. Keys are field names (use the field_options names). ' +
+                    'Example: {"status":["Active"],"priority":["High","Critical"]}. Also supports "exclude_status".',
+            },
+            page: { type: "number", description: "Page number (default: 1)" },
+            limit: { type: "number", description: "Items per page (default: 20, max: 100)" },
+            sortBy: { type: "string", description: "Field to sort by (e.g. created_at, title)" },
+            sortOrder: { type: "string", enum: ["asc", "desc"], description: "Sort direction" },
+        },
+        required: ["projectId"],
+    },
+};
+const GET_TESTCASE_TOOL = {
+    name: "get_testcase",
+    description: "Get full details of a single test case including test steps (with step ids) and attachments.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: { type: "string", description: "Project ID" },
+            testcaseId: { type: "string", description: "Test case ID (e.g. TEST-123)" },
+        },
+        required: ["projectId", "testcaseId"],
+    },
+};
+const TESTCASE_FIELDS = "title, summary, precondition, priority, status, automated, test_data, expected_result, labels, features, platform, environment, custom_fields, owner_id, folder_id";
+const MANAGE_TESTCASE_TOOL = {
+    name: "manage_testcase",
+    description: "IMPORTANT: Before creating/updating, call get_project_structure(projectId) to discover folder IDs and allowed field values.\n\n" +
+        "Create, update or delete test cases and their test steps.\n\n" +
+        "ACTIONS:\n" +
+        "  create        - Create a single test case. Params: title (required), test_steps, and any of: " + TESTCASE_FIELDS + "\n" +
+        "  create_bulk   - Create up to 100 test cases in one go. Params: testcases (JSON array; each item takes the same fields as create, including test_steps)\n" +
+        "  update        - Update one field for test case(s). Params: ids, field, value (all required)\n" +
+        "  delete        - PERMANENTLY delete test case(s) with their steps, history and links. Params: ids (required)\n" +
+        "  add_steps     - Append steps to a test case. Params: testcaseId, test_steps\n" +
+        "  update_step   - Change one step. Params: testcaseId, step_id, and description/test_data/expected_result\n" +
+        "  delete_steps  - Delete steps. Params: testcaseId, step_ids (comma-separated)\n" +
+        "  reorder_steps - Set the step order. Params: testcaseId, step_ids (all step ids, in the new order)\n" +
+        "Step ids come from get_testcase.\n\n" +
+        "VALID UPDATE FIELDS: " + TESTCASE_FIELDS + "\n\n" +
+        "EXAMPLES:\n" +
+        "  Create:  { action: 'create', title: 'Verify login', test_steps: '[{\"description\":\"Open login page\",\"expected_result\":\"Form shown\"}]' }\n" +
+        "  Update:  { action: 'update', ids: 'TEST-1', field: 'priority', value: '<value from get_project_structure>' }\n" +
+        "  Delete:  { action: 'delete', ids: 'TEST-1,TEST-2' }",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: { type: "string", description: "Project ID" },
+            action: {
+                type: "string",
+                enum: ["create", "create_bulk", "update", "delete", "add_steps", "update_step", "delete_steps", "reorder_steps"],
+                description: "Action to perform",
+            },
+            // create params
+            title: { type: "string", description: "[create] Test case title" },
+            summary: { type: "string", description: "[create] Description/summary" },
+            priority: {
+                type: "string",
+                description: "[create] Priority. Values are project-specific — call get_project_structure(projectId, include='field_options') first to discover allowed values.",
+            },
+            folder_id: { type: "number", description: "[create] Folder ID to place the test case in" },
+            labels: {
+                type: "string",
+                description: "[create] Comma-separated label names",
+            },
+            test_steps: {
+                type: "string",
+                description: '[create/add_steps] JSON array of test steps: [{"description":"...","test_data":"...","expected_result":"..."}]. Every step needs a description.',
+            },
+            precondition: { type: "string", description: "[create] Preconditions for the test case" },
+            status: {
+                type: "string",
+                description: "[create] Status. Values are project-specific — call get_project_structure(projectId, include='field_options') first.",
+            },
+            automated: {
+                type: "string",
+                description: "[create] Automation status. Values are project-specific — call get_project_structure(projectId, include='field_options') first.",
+            },
+            test_data: { type: "string", description: "[create/update_step] Test data" },
+            expected_result: { type: "string", description: "[create/update_step] Expected result" },
+            platform: {
+                type: "string",
+                description: "[create] Platform. Values are project-specific — call get_project_structure(projectId, include='field_options') first.",
+            },
+            environment: { type: "string", description: "[create] Comma-separated environment values" },
+            features: { type: "string", description: "[create] Comma-separated feature/component names" },
+            owner_id: { type: "string", description: "[create] Owner user ID (a project member)" },
+            custom_fields: {
+                type: "string",
+                description: '[create] JSON object of custom field values (e.g. {"custom1": "value", "custom2": ["val1","val2"]})',
+            },
+            // create_bulk params
+            testcases: {
+                type: "string",
+                description: "[create_bulk] JSON array of test cases. Each item takes the create fields, e.g. " +
+                    '[{"title":"...","folder_id":12,"priority":"High","test_steps":[{"description":"...","expected_result":"..."}]}]',
+            },
+            // update/delete params
+            ids: {
+                type: "string",
+                description: "[update/delete] Test case IDs, comma-separated (e.g. 'TEST-1' or 'TEST-1,TEST-2')",
+            },
+            field: {
+                type: "string",
+                enum: TESTCASE_FIELDS.split(", "),
+                description: "[update] Field to update. For priority/status/automated/platform/environment, call get_project_structure(include='field_options') to get allowed values.",
+            },
+            value: { type: "string", description: "[update] New value. String for most fields. For labels/features/environment: comma-separated. For custom_fields: JSON object (e.g. {\"fieldName\": \"value\"})" },
+            // step params
+            testcaseId: { type: "string", description: "[add_steps/update_step/delete_steps/reorder_steps] Test case ID (e.g. TEST-123)" },
+            step_id: { type: "number", description: "[update_step] Step ID to change" },
+            description: { type: "string", description: "[update_step] Step description" },
+            step_ids: { type: "string", description: "[delete_steps/reorder_steps] Comma-separated step IDs" },
+        },
+        required: ["projectId", "action"],
+    },
+};
+const MANAGE_FOLDER_TOOL = {
+    name: "manage_folder",
+    description: "Create, rename, move, or delete folders. Works across all sections (TESTCASE, TEST_CYCLE, TEST_PLAN).\n\n" +
+        "ACTIONS:\n" +
+        "  create  - Create a folder. Params: name (required), section, parentId\n" +
+        "  rename  - Rename a folder. Params: folderId (required), name (required)\n" +
+        "  move    - Move a folder. Params: folderId (required), parentId (omit or null for root)\n" +
+        "  delete  - PERMANENTLY delete a folder, all its sub-folders AND every test case / cycle / plan inside them. " +
+        "Only owners and project admins can do this. Confirm with the user first. Params: folderId (required)",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: { type: "string", description: "Project ID" },
+            action: {
+                type: "string",
+                enum: ["create", "rename", "move", "delete"],
+                description: "Action to perform",
+            },
+            section: {
+                type: "string",
+                enum: ["TESTCASE", "TEST_CYCLE", "TEST_PLAN"],
+                description: "Folder section (default: TESTCASE)",
+            },
+            name: { type: "string", description: "[create/rename] Folder name (max 50 chars)" },
+            folderId: {
+                type: "number",
+                description: "[rename/move/delete] ID of the folder to modify",
+            },
+            parentId: {
+                type: "number",
+                description: "[create] Parent folder ID for subfolder. [move] New parent ID (null for root).",
+            },
+        },
+        required: ["projectId", "action"],
+    },
+};
+const SEARCH_TEST_CYCLES_TOOL = {
+    name: "search_test_cycles",
+    description: "List and search test cycles in a project with execution progress.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: { type: "string", description: "Project ID" },
+            search: { type: "string", description: "Search by title" },
+            folderId: { type: "number", description: "Filter by folder ID" },
+            status: { type: "string", enum: ["open", "in_progress", "completed"], description: "Filter by status" },
+            page: { type: "number", description: "Page number (default: 1)" },
+            limit: { type: "number", description: "Items per page (default: 20, max: 100)" },
+        },
+        required: ["projectId"],
+    },
+};
+const MANAGE_TEST_CYCLE_TOOL = {
+    name: "manage_test_cycle",
+    description: "Manage test cycles: create, update, delete, get details, list/link/unlink/assign test cases.\n\n" +
+        "ACTIONS:\n" +
+        "  create            - Create a cycle. Params: title (required), summary, status, planned_start_date, planned_end_date, folder_id\n" +
+        "  update            - Update a cycle. Params: cycleId (required), plus fields to change (title, summary, status, dates, folder_id)\n" +
+        "  delete            - Delete cycle(s). Params: ids (required, comma-separated)\n" +
+        "  get_details       - Get cycle details. Params: cycleId (required)\n" +
+        "  get_testcases     - List test cases in cycle. Params: cycleId (required), search, page, limit\n" +
+        "  link_testcases    - Link test cases to cycle. Params: cycleId (required), testcase_ids (required, comma-separated)\n" +
+        "  unlink_testcases  - Unlink test cases from cycle. Params: cycleId (required), testcase_ids (required, comma-separated)\n" +
+        "  assign_testcases  - Assign test cases to user. Params: cycleId (required), testcase_ids (required), assignee_id (required)\n\n" +
+        "VALID STATUSES: open, in_progress, completed",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: { type: "string", description: "Project ID" },
+            action: {
+                type: "string",
+                enum: [
+                    "create",
+                    "update",
+                    "delete",
+                    "get_details",
+                    "get_testcases",
+                    "link_testcases",
+                    "unlink_testcases",
+                    "assign_testcases",
+                ],
+                description: "Action to perform",
+            },
+            // Identifiers
+            cycleId: {
+                type: "string",
+                description: "Test cycle ID (e.g. TCYCLE-1). Required for update/delete/get_details/get_testcases/link/unlink/assign.",
+            },
+            // create/update fields
+            title: { type: "string", description: "[create/update] Cycle title" },
+            summary: { type: "string", description: "[create/update] Description" },
+            status: {
+                type: "string",
+                enum: ["open", "in_progress", "completed"],
+                description: "[create/update] Status",
+            },
+            planned_start_date: {
+                type: "string",
+                description: "[create/update] Start date (YYYY-MM-DD)",
+            },
+            planned_end_date: {
+                type: "string",
+                description: "[create/update] End date (YYYY-MM-DD)",
+            },
+            folder_id: {
+                type: "number",
+                description: "[create/update] Folder ID",
+            },
+            // delete
+            ids: {
+                type: "string",
+                description: "[delete] Comma-separated cycle IDs to delete",
+            },
+            // link/unlink/assign
+            testcase_ids: {
+                type: "string",
+                description: "[link_testcases/unlink_testcases/assign_testcases] Comma-separated test case IDs",
+            },
+            assignee_id: {
+                type: "number",
+                description: "[assign_testcases] User ID to assign",
+            },
+            // get_testcases params
+            search: { type: "string", description: "[get_testcases] Search text" },
+            page: { type: "number", description: "[get_testcases] Page number" },
+            limit: { type: "number", description: "[get_testcases] Items per page" },
+        },
+        required: ["projectId", "action"],
+    },
+};
+const EXECUTE_TESTS_TOOL = {
+    name: "execute_tests",
+    description: "Record test execution results for test cases in a test cycle. " +
+        "Pass a single result or an array of results. " +
+        "Valid execution statuses: pass, fail, blocked, not_executed. " +
+        "The test cases must already be linked to the cycle (manage_test_cycle link_testcases).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: { type: "string", description: "Project ID" },
+            cycleId: { type: "string", description: "Test cycle ID (e.g. TCYCLE-1)" },
+            results: {
+                type: "string",
+                description: 'JSON array of results: [{"testcase_id":"TEST-1","execution_status":"pass","actual_result":"Worked","environment":"staging"}]. ' +
+                    "Each object must have testcase_id and execution_status. actual_result and environment are optional.",
+            },
+            mode: {
+                type: "string",
+                enum: ["manual", "automation"],
+                description: "manual (default): each result is recorded like a tester setting it in the app — the new status replaces the old one. " +
+                    "automation: recorded as a CI/automation run, where a failure from any earlier automation run keeps the case failed. Use only for CI results.",
+            },
+        },
+        required: ["projectId", "cycleId", "results"],
+    },
+};
+const MANAGE_TEST_PLAN_TOOL = {
+    name: "manage_test_plan",
+    description: "Manage test plans: create, update, delete, list, get details, link/unlink cycles, get cycles, get test cases.\n\n" +
+        "ACTIONS:\n" +
+        "  create         - Create a plan. Params: title (required), summary, status, planned_start_date, planned_end_date, folder_id\n" +
+        "  update         - Update a plan. Params: planId (required), plus fields to change (title, summary, status, dates, folder_id)\n" +
+        "  delete         - Delete plan(s). Params: ids (required, comma-separated)\n" +
+        "  list           - List all plans. Params: search, page, limit\n" +
+        "  get_details    - Get plan details. Params: planId (required)\n" +
+        "  link_cycles    - Link cycles to plan. Params: planId (required), cycle_ids (required, comma-separated)\n" +
+        "  unlink_cycles  - Unlink cycles from plan. Params: planId (required), cycle_ids (required, comma-separated)\n" +
+        "  get_cycles     - List cycles in plan. Params: planId (required), search, page, limit\n" +
+        "  get_testcases  - List test cases in plan. Params: planId (required), search, page, limit\n\n" +
+        "VALID STATUSES: open, in_progress, completed",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: { type: "string", description: "Project ID" },
+            action: {
+                type: "string",
+                enum: [
+                    "create",
+                    "update",
+                    "delete",
+                    "list",
+                    "get_details",
+                    "link_cycles",
+                    "unlink_cycles",
+                    "get_cycles",
+                    "get_testcases",
+                ],
+                description: "Action to perform",
+            },
+            // Identifier
+            planId: {
+                type: "string",
+                description: "Test plan ID (e.g. TPLAN-1). Required for update/delete/get_details/link_cycles/unlink_cycles/get_cycles/get_testcases.",
+            },
+            // create/update fields
+            title: { type: "string", description: "[create/update] Plan title" },
+            summary: { type: "string", description: "[create/update] Description" },
+            status: { type: "string", enum: ["open", "in_progress", "completed"], description: "[create/update] Status" },
+            planned_start_date: {
+                type: "string",
+                description: "[create/update] Start date (YYYY-MM-DD)",
+            },
+            planned_end_date: {
+                type: "string",
+                description: "[create/update] End date (YYYY-MM-DD)",
+            },
+            folder_id: { type: "number", description: "[create/update] Folder ID" },
+            // delete
+            ids: {
+                type: "string",
+                description: "[delete] Comma-separated plan IDs to delete",
+            },
+            // link/unlink cycles
+            cycle_ids: {
+                type: "string",
+                description: "[link_cycles/unlink_cycles] Comma-separated test cycle IDs",
+            },
+            // list/get_cycles/get_testcases pagination
+            search: { type: "string", description: "[list/get_cycles/get_testcases] Search text" },
+            page: { type: "number", description: "[list/get_cycles/get_testcases] Page number" },
+            limit: { type: "number", description: "[list/get_cycles/get_testcases] Items per page" },
+        },
+        required: ["projectId", "action"],
+    },
+};
+const GET_REPORT_TOOL = {
+    name: "get_report",
+    description: "Get reports and analytics for a project. Covers execution, coverage, trends, team, defects, and insights " +
+        "(the insight reports are computed from your data; they do not use AI credits). " +
+        "Available report types: execution_summary, execution_by_cycle, execution_by_tester, execution_by_priority, " +
+        "execution_by_environment, execution_by_folder, requirement_coverage, traceability_matrix, " +
+        "failed_requirements, uncovered_requirements, testcase_coverage, unlinked_testcases, " +
+        "defects_by_folder, tester_workload, testcase_distribution, " +
+        "execution_trend, execution_burnup, execution_burndown, test_creation, cycle_comparison, " +
+        "scorecard_by_folder, scorecard_by_tester, created_vs_executed, execution_by_automation, " +
+        "defects_by_cycle, defects_by_tester, requirement_coverage_trend, " +
+        "flaky_tests, release_readiness, risk_heatmap_folder, risk_heatmap_feature, " +
+        "testcase_quality, predictive_failure, smart_prioritization, tester_effectiveness, " +
+        "stale_tests, defect_hotspots, cycle_health, suite_optimization, " +
+        "requirement_risk_matrix, execution_velocity, project_health.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectId: { type: "string", description: "Project ID" },
+            report_type: {
+                type: "string",
+                description: "Report type (see description for full list)",
+            },
+            test_cycle_id: {
+                type: "string",
+                description: "Only this test cycle (one ID, e.g. TCYCLE-3)",
+            },
+            test_plan_id: {
+                type: "string",
+                description: "Only this test plan (one ID, e.g. TPLAN-2)",
+            },
+            folder_id: { type: "number", description: "Only this folder" },
+            startDate: { type: "string", description: "Start date filter (YYYY-MM-DD)" },
+            endDate: { type: "string", description: "End date filter (YYYY-MM-DD)" },
+            granularity: {
+                type: "string",
+                enum: ["day", "week", "month"],
+                description: "Granularity for trend reports",
+            },
+            // cycle_comparison specific
+            cycle_ids: {
+                type: "string",
+                description: "[cycle_comparison] Comma-separated cycle IDs to compare",
+            },
+        },
+        required: ["projectId", "report_type"],
+    },
+};
+// ═══════════════════════════════════════════════════════════════════════════════
+// REPORT TYPE → ENDPOINT MAPPING
+// ═══════════════════════════════════════════════════════════════════════════════
+const REPORT_TYPE_MAP = {
+    // Execution
+    execution_summary: "execution/summary",
+    execution_by_cycle: "execution/by-cycle",
+    execution_by_tester: "execution/by-tester",
+    execution_by_priority: "execution/by-priority",
+    execution_by_environment: "execution/by-environment",
+    execution_by_folder: "execution/by-folder",
+    // Coverage
+    requirement_coverage: "coverage/requirement-coverage",
+    traceability_matrix: "coverage/traceability-matrix",
+    failed_requirements: "coverage/failed-requirements",
+    uncovered_requirements: "coverage/uncovered-requirements",
+    testcase_coverage: "coverage/testcase-coverage",
+    unlinked_testcases: "coverage/unlinked-testcases",
+    // Defects
+    defects_by_folder: "defects/by-folder",
+    // Team
+    tester_workload: "team/tester-workload",
+    testcase_distribution: "team/testcase-distribution",
+    // Trends
+    execution_trend: "trends/execution-trend",
+    execution_burnup: "trends/execution-burnup",
+    execution_burndown: "trends/execution-burndown",
+    test_creation: "trends/test-creation",
+    cycle_comparison: "trends/cycle-comparison",
+    scorecard_by_folder: "trends/scorecard-by-folder",
+    scorecard_by_tester: "trends/scorecard-by-tester",
+    created_vs_executed: "trends/created-vs-executed",
+    execution_by_automation: "trends/execution-by-automation",
+    defects_by_cycle: "trends/defects-by-cycle",
+    defects_by_tester: "trends/defects-by-tester",
+    requirement_coverage_trend: "trends/requirement-coverage-trend",
+    // AI Insights
+    flaky_tests: "ai/flaky-tests",
+    release_readiness: "ai/release-readiness",
+    risk_heatmap_folder: "ai/risk-heatmap-folder",
+    risk_heatmap_feature: "ai/risk-heatmap-feature",
+    testcase_quality: "ai/testcase-quality",
+    predictive_failure: "ai/predictive-failure",
+    smart_prioritization: "ai/smart-prioritization",
+    tester_effectiveness: "ai/tester-effectiveness",
+    stale_tests: "ai/stale-tests",
+    defect_hotspots: "ai/defect-hotspots",
+    cycle_health: "ai/cycle-health",
+    suite_optimization: "ai/suite-optimization",
+    requirement_risk_matrix: "ai/requirement-risk-matrix",
+    execution_velocity: "ai/execution-velocity",
+    project_health: "ai/project-health",
+};
+// ═══════════════════════════════════════════════════════════════════════════════
+// TOOL HANDLERS
+// ═══════════════════════════════════════════════════════════════════════════════
+// 1. list_projects
+async function handleListProjects(args) {
+    const data = await callApi("get", "projects/user/my-projects", {
+        query: {
+            page: p(args, "page"),
+            limit: p(args, "limit"),
+        },
+    });
+    return jsonResponseWithHints(data, [
+        "Next: call get_project_structure(projectId) to see folders, labels, and allowed field values.",
+    ]);
+}
+// 2. get_project_structure
+async function handleGetProjectStructure(args) {
+    const projectId = p(args, "projectId", "project_id");
+    if (!projectId)
+        throw new Error("projectId is required");
+    validateId(projectId, "projectId");
+    const section = p(args, "section") || "TESTCASE";
+    const includeRaw = p(args, "include") || "folders,labels,members,field_options";
+    const includes = includeRaw.split(",").map((s) => s.trim().toLowerCase());
+    const orgId = await getOrganizationId();
+    const result = {};
+    const promises = [];
+    if (includes.includes("folders")) {
+        promises.push(callApi("get", "folders/get-folders", {
+            query: { projectId, section },
+        }).then((data) => {
+            result.folders = data;
+        }));
+    }
+    if (includes.includes("labels")) {
+        promises.push(callApi("get", `projects/labels/get-label/${projectId}`).then((data) => {
+            result.labels = data;
+        }));
+    }
+    if (includes.includes("members")) {
+        promises.push(callApi("get", `projects/${projectId}/team-members`).then((data) => {
+            result.members = data;
+        }));
+    }
+    if (includes.includes("field_options")) {
+        promises.push(callApi("get", `projects/fields/options/${projectId}`).then((data) => {
+            result.field_options = data?.data || data;
+        }));
+    }
+    await Promise.all(promises);
+    return jsonResponseWithHints(result, [
+        "Use the field_options values above when creating/updating test cases.",
+    ]);
+}
+// 3. search_testcases
+async function handleSearchTestcases(args) {
+    const projectId = p(args, "projectId", "project_id");
+    if (!projectId)
+        throw new Error("projectId is required");
+    validateId(projectId, "projectId");
+    const folderId = p(args, "folder_id", "folderId");
+    if (folderId !== undefined && folderId !== null && folderId !== "" && isNaN(Number(folderId))) {
+        throw new Error("folder_id must be a numeric folder ID");
+    }
+    const filters = buildFilters(p(args, "filters"), {
+        folder_id: folderId === undefined || folderId === null || folderId === "" ? undefined : [Number(folderId)],
+    });
+    const data = await callApi("get", `projects/testcases/get-testcase/${projectId}`, {
+        query: {
+            search: p(args, "search"),
+            filters,
+            page: p(args, "page"),
+            limit: p(args, "limit"),
+            sortBy: p(args, "sortBy", "sort_by"),
+            sortOrder: p(args, "sortOrder", "sort_order"),
+        },
+    });
+    const baseUrl = getFrontendBaseUrl();
+    if (Array.isArray(data?.data)) {
+        data.data.forEach((tc) => {
+            if (tc.id)
+                tc.url = `${baseUrl}/${projectId}/testcases/${tc.id}`;
+        });
+    }
+    return jsonResponse(data);
+}
+// 4. get_testcase
+async function handleGetTestcase(args) {
+    const projectId = p(args, "projectId", "project_id");
+    const testcaseId = p(args, "testcaseId", "testcase_id", "id");
+    if (!projectId)
+        throw new Error("projectId is required");
+    if (!testcaseId)
+        throw new Error("testcaseId is required");
+    validateId(projectId, "projectId");
+    validateId(testcaseId, "testcaseId");
+    const data = await callApi("get", `projects/testcases/get-testcase-detail/${projectId}/${testcaseId}`);
+    if (data?.data?.testcase) {
+        data.data.testcase.url = `${getFrontendBaseUrl()}/${projectId}/testcases/${testcaseId}`;
+    }
+    return jsonResponse(data);
+}
+// 5. manage_testcase
+async function handleManageTestcase(args) {
+    const projectId = p(args, "projectId", "project_id");
+    const action = p(args, "action");
+    if (!projectId)
+        throw new Error("projectId is required");
+    if (!action)
+        throw new Error("action is required");
+    validateId(projectId, "projectId");
+    const orgId = await getOrganizationId();
+    switch (action) {
+        case "create": {
+            const title = p(args, "title", "name");
+            if (!title)
+                throw new Error("title is required for create action");
+            // Validate steps before creating anything, so a bad step can't leave a half-made test case
+            const testSteps = parseSteps(p(args, "test_steps", "testSteps", "steps"));
+            const testcaseData = await buildTestcasePayload(projectId, { ...args, title });
+            const createResult = await callApi("post", `projects/testcases/create-testcase/${projectId}`, { body: testcaseData });
+            const tcId = createResult?.testcaseId || createResult?.data?.id;
+            const hints = [
+                "To update fields, use manage_testcase(action='update', ids='<id>', field='<name>', value='<value>')",
+            ];
+            if (tcId) {
+                createResult.url = `${getFrontendBaseUrl()}/${projectId}/testcases/${tcId}`;
+                if (testSteps?.length) {
+                    const steps = await addSteps(projectId, tcId, testSteps);
+                    createResult.steps_created = steps.created;
+                    if (steps.errors.length) {
+                        createResult.step_errors = steps.errors;
+                        hints.push(`The test case ${tcId} WAS created; do not create it again. Add the missing steps with manage_testcase(action='add_steps', testcaseId='${tcId}').`);
+                    }
+                }
+            }
+            return jsonResponseWithHints(createResult, hints);
+        }
+        case "create_bulk": {
+            const rawTestcases = p(args, "testcases", "test_cases", "items");
+            if (!rawTestcases)
+                throw new Error("testcases is required for create_bulk action");
+            const testcases = safeJsonParse(rawTestcases, "testcases");
+            if (!Array.isArray(testcases) || testcases.length === 0) {
+                throw new Error("testcases must be a non-empty JSON array");
+            }
+            // Validate everything before creating anything
+            const items = [];
+            for (const [i, tc] of testcases.entries()) {
+                if (!tc?.title && !tc?.name)
+                    throw new Error(`testcases[${i}]: title is required`);
+                try {
+                    items.push({
+                        testcase: await buildTestcasePayload(projectId, tc),
+                        test_steps: parseSteps(tc.test_steps ?? tc.testSteps ?? tc.steps),
+                    });
+                }
+                catch (error) {
+                    throw new Error(`testcases[${i}]: ${error.message}`);
+                }
+            }
+            const bulkResult = await callApi("post", `projects/testcases/create-bulk-testcase/${projectId}`, { body: { testcases: items.map((t) => t.testcase) } });
+            // Add test steps for each created testcase
+            const results = bulkResult?.results || [];
+            let stepsCreated = 0;
+            const stepErrors = {};
+            for (const r of results) {
+                const steps = items[r.index ?? results.indexOf(r)]?.test_steps;
+                const tcId = r.testcaseId || r.id;
+                if (r.status !== "success" || !tcId || !steps?.length)
+                    continue;
+                const res = await addSteps(projectId, tcId, steps);
+                stepsCreated += res.created;
+                if (res.errors.length)
+                    stepErrors[tcId] = res.errors;
+            }
+            const response = { ...bulkResult, steps_created: stepsCreated };
+            if (Object.keys(stepErrors).length)
+                response.step_errors = stepErrors;
+            return jsonResponseWithHints(response, Object.keys(stepErrors).length
+                ? ["Some steps failed (see step_errors). The test cases WERE created; add the missing steps with manage_testcase(action='add_steps')."]
+                : []);
+        }
+        case "update": {
+            const ids = p(args, "ids", "testcase_ids", "testcaseIds");
+            const field = p(args, "field", "field_name", "fieldName");
+            const value = p(args, "value", "field_value", "fieldValue", "new_value");
+            if (!ids)
+                throw new Error("ids is required for update action");
+            if (!field)
+                throw new Error("field is required for update action");
+            if (value === undefined)
+                throw new Error("value is required for update action");
+            if (!TESTCASE_FIELDS.split(", ").includes(field)) {
+                throw new Error(`Invalid field: ${field}. Valid fields: ${TESTCASE_FIELDS}`);
+            }
+            const idsStr = toIdList(ids);
+            // Coerce field values for project-specific fields
+            const coercibleFields = ["priority", "status", "automated", "platform"];
+            // Parse value for fields that expect non-string types
+            let parsedValue = value;
+            if (field === "folder_id" || field === "owner_id") {
+                const num = Number(value);
+                parsedValue = isNaN(num) ? value : num;
+            }
+            else if (coercibleFields.includes(field)) {
+                parsedValue = await coerceFieldValue(projectId, field, value);
+            }
+            else if (field === "labels" || field === "features" || field === "environment") {
+                parsedValue = typeof value === "string" ? value.split(",").map((s) => s.trim()).filter(Boolean) : value;
+            }
+            else if (field === "custom_fields") {
+                const parsed = safeJsonParse(value, "custom_fields");
+                // Backend requires all custom field values as arrays
+                for (const key of Object.keys(parsed)) {
+                    if (!Array.isArray(parsed[key])) {
+                        parsed[key] = [parsed[key]];
+                    }
+                }
+                parsedValue = parsed;
+            }
+            const data = await callApi("patch", `projects/testcases/update-field/${projectId}`, {
+                body: { ids: idsStr, [field]: parsedValue },
+            });
+            return jsonResponse(data);
+        }
+        case "delete": {
+            const ids = p(args, "ids", "testcase_ids", "testcaseIds");
+            if (!ids)
+                throw new Error("ids is required for delete action");
+            const data = await callApi("delete", `projects/testcases/delete-testcase/${projectId}`, {
+                query: { ids: toIdList(ids) },
+            });
+            return jsonResponse(data);
+        }
+        case "add_steps": {
+            const tcId = validateId(requireArg(args, "testcaseId", ["testcase_id", "id"]), "testcaseId");
+            const steps = parseSteps(p(args, "test_steps", "testSteps", "steps"));
+            if (!steps?.length)
+                throw new Error("test_steps is required for add_steps action");
+            const res = await addSteps(projectId, tcId, steps);
+            if (res.created === 0)
+                throw new Error(`No steps were added:\n${res.errors.join("\n")}`);
+            return jsonResponse({ testcaseId: tcId, steps_created: res.created, step_errors: res.errors });
+        }
+        case "update_step": {
+            const tcId = validateId(requireArg(args, "testcaseId", ["testcase_id", "id"]), "testcaseId");
+            const stepId = Number(requireArg(args, "step_id", ["stepId"]));
+            if (isNaN(stepId))
+                throw new Error("step_id must be a number");
+            const body = { stepId };
+            for (const f of ["description", "test_data", "expected_result"]) {
+                if (args[f] !== undefined)
+                    body[f] = args[f];
+            }
+            // The backend requires a description string even when it is unchanged
+            if (body.description === undefined) {
+                const detail = await callApi("get", `projects/testcases/get-testcase-detail/${projectId}/${tcId}`);
+                const existing = (detail?.data?.steps || []).find((st) => Number(st.id) === stepId);
+                if (!existing)
+                    throw new Error(`Step ${stepId} not found on ${tcId}`);
+                body.description = existing.description ?? "";
+            }
+            const data = await callApi("post", `projects/testcases/teststeps/${projectId}/${tcId}`, { body });
+            return jsonResponse(data);
+        }
+        case "delete_steps": {
+            const tcId = validateId(requireArg(args, "testcaseId", ["testcase_id", "id"]), "testcaseId");
+            const stepIds = toIdList(requireArg(args, "step_ids", ["stepIds"]));
+            const data = await callApi("delete", `projects/testcases/teststeps/${tcId}`, {
+                query: { projectId },
+                body: { stepIds },
+            });
+            return jsonResponse(data);
+        }
+        case "reorder_steps": {
+            const tcId = validateId(requireArg(args, "testcaseId", ["testcase_id", "id"]), "testcaseId");
+            const stepIds = toStringArray(requireArg(args, "step_ids", ["stepIds"])).map(Number);
+            if (stepIds.some(isNaN))
+                throw new Error("step_ids must be numeric step IDs");
+            const data = await callApi("put", `projects/testcases/teststeps/${projectId}/${tcId}/reorder`, {
+                body: { stepIds },
+            });
+            return jsonResponse(data);
+        }
+        default:
+            throw new Error(`Unknown action: ${action}. Use: create, create_bulk, update, delete, add_steps, update_step, delete_steps, reorder_steps`);
+    }
+}
+// 6. manage_folder
+async function handleManageFolder(args) {
+    const projectId = p(args, "projectId", "project_id");
+    const action = p(args, "action");
+    if (!projectId)
+        throw new Error("projectId is required");
+    if (!action)
+        throw new Error("action is required");
+    validateId(projectId, "projectId");
+    const section = p(args, "section") || "TESTCASE";
+    const orgId = await getOrganizationId();
+    switch (action) {
+        case "create": {
+            const name = p(args, "name", "folder_name");
+            if (!name)
+                throw new Error("name is required for create action");
+            const body = {
+                organizationId: orgId,
+                projectId,
+                section,
+                name,
+            };
+            const parentId = p(args, "parentId", "parent_id");
+            if (parentId)
+                body.parentId = Number(parentId);
+            const data = await callApi("post", "folders/create-folders", { body, skipOrgId: true });
+            return jsonResponse(data);
+        }
+        case "rename": {
+            const folderId = p(args, "folderId", "folder_id", "id");
+            const name = p(args, "name", "folder_name");
+            if (!folderId)
+                throw new Error("folderId is required for rename action");
+            if (!name)
+                throw new Error("name is required for rename action");
+            validateId(folderId, "folderId");
+            const data = await callApi("patch", `folders/${folderId}`, {
+                query: { projectId, section },
+                body: { name },
+            });
+            return jsonResponse(data);
+        }
+        case "move": {
+            const folderId = p(args, "folderId", "folder_id", "id");
+            if (!folderId)
+                throw new Error("folderId is required for move action");
+            validateId(folderId, "folderId");
+            const parentId = p(args, "parentId", "parent_id");
+            const newParentId = parentId === undefined || parentId === null || parentId === "" ? null : Number(parentId);
+            if (newParentId !== null && isNaN(newParentId))
+                throw new Error("parentId must be a numeric folder ID");
+            const data = await callApi("patch", `folders/${folderId}/move`, {
+                query: { projectId, section },
+                body: { newParentId },
+            });
+            return jsonResponse(data);
+        }
+        case "delete": {
+            const folderId = p(args, "folderId", "folder_id", "id");
+            if (!folderId)
+                throw new Error("folderId is required for delete action");
+            validateId(folderId, "folderId");
+            const data = await callApi("delete", `folders/delete/${folderId}`, {
+                query: { projectId, section },
+            });
+            return jsonResponse(data);
+        }
+        default:
+            throw new Error(`Unknown action: ${action}. Use: create, rename, move, delete`);
+    }
+}
+// 7. search_test_cycles
+async function handleSearchTestCycles(args) {
+    const projectId = p(args, "projectId", "project_id");
+    if (!projectId)
+        throw new Error("projectId is required");
+    validateId(projectId, "projectId");
+    const folderId = p(args, "folderId", "folder_id");
+    const filters = buildFilters(undefined, {
+        status: p(args, "status"),
+        folder_id: folderId === undefined || folderId === null || folderId === "" ? undefined : Number(folderId),
+    });
+    const data = await callApi("get", `projects/test-cycles/get-test-cycles/${projectId}`, {
+        query: {
+            search: p(args, "search"),
+            filters,
+            page: p(args, "page"),
+            limit: p(args, "limit"),
+        },
+    });
+    const baseUrl = getFrontendBaseUrl();
+    if (Array.isArray(data?.data)) {
+        data.data.forEach((cycle) => {
+            const id = cycle.test_cycle_id || cycle.id;
+            if (id)
+                cycle.url = `${baseUrl}/${projectId}/testcycles/${id}`;
+        });
+    }
+    return jsonResponse(data);
+}
+// 8. manage_test_cycle
+async function handleManageTestCycle(args) {
+    const projectId = p(args, "projectId", "project_id");
+    const action = p(args, "action");
+    if (!projectId)
+        throw new Error("projectId is required");
+    if (!action)
+        throw new Error("action is required");
+    validateId(projectId, "projectId");
+    switch (action) {
+        case "create": {
+            const title = p(args, "title");
+            if (!title)
+                throw new Error("title is required for create action");
+            const body = { title };
+            if (p(args, "summary"))
+                body.summary = p(args, "summary");
+            if (p(args, "status"))
+                body.status = p(args, "status");
+            if (p(args, "planned_start_date", "plannedStartDate"))
+                body.planned_start_date = p(args, "planned_start_date", "plannedStartDate");
+            if (p(args, "planned_end_date", "plannedEndDate"))
+                body.planned_end_date = p(args, "planned_end_date", "plannedEndDate");
+            if (p(args, "folder_id", "folderId"))
+                body.folder_id = Number(p(args, "folder_id", "folderId"));
+            const data = await callApi("post", `projects/test-cycles/create-test-cycle/${projectId}`, { body });
+            return jsonResponse(data);
+        }
+        case "update": {
+            const cycleId = p(args, "cycleId", "cycle_id", "id");
+            if (!cycleId)
+                throw new Error("cycleId is required for update action");
+            const body = { id: cycleId };
+            if (p(args, "title"))
+                body.title = p(args, "title");
+            if (p(args, "summary"))
+                body.summary = p(args, "summary");
+            if (p(args, "status"))
+                body.status = p(args, "status");
+            if (p(args, "planned_start_date", "plannedStartDate"))
+                body.planned_start_date = p(args, "planned_start_date", "plannedStartDate");
+            if (p(args, "planned_end_date", "plannedEndDate"))
+                body.planned_end_date = p(args, "planned_end_date", "plannedEndDate");
+            if (p(args, "folder_id", "folderId"))
+                body.folder_id = Number(p(args, "folder_id", "folderId"));
+            const data = await callApi("post", `projects/test-cycles/create-test-cycle/${projectId}`, { body });
+            return jsonResponse(data);
+        }
+        case "delete": {
+            const ids = p(args, "ids", "cycleId", "cycle_id");
+            if (!ids)
+                throw new Error("ids (or cycleId) is required for delete action");
+            const idsStr = Array.isArray(ids) ? ids.join(",") : String(ids);
+            const data = await callApi("delete", `projects/test-cycles/delete-test-cycle/${projectId}`, { body: { ids: idsStr } });
+            return jsonResponse(data);
+        }
+        case "get_details": {
+            const cycleId = p(args, "cycleId", "cycle_id", "id");
+            if (!cycleId)
+                throw new Error("cycleId is required for get_details action");
+            validateId(cycleId, "cycleId");
+            const data = await callApi("get", `projects/test-cycles/get-test-cycle-details/${projectId}/${cycleId}`);
+            if (data?.data) {
+                data.data.url = `${getFrontendBaseUrl()}/${projectId}/testcycles/${cycleId}`;
+            }
+            return jsonResponse(data);
+        }
+        case "get_testcases": {
+            const cycleId = p(args, "cycleId", "cycle_id", "id");
+            if (!cycleId)
+                throw new Error("cycleId is required for get_testcases action");
+            validateId(cycleId, "cycleId");
+            const data = await callApi("get", `projects/test-cycles/testcases/${projectId}/${cycleId}`, {
+                query: {
+                    search: p(args, "search"),
+                    page: p(args, "page"),
+                    limit: p(args, "limit"),
+                },
+            });
+            return jsonResponse(data);
+        }
+        case "link_testcases": {
+            const cycleId = p(args, "cycleId", "cycle_id", "id");
+            const tcIds = p(args, "testcase_ids", "testcaseIds");
+            if (!cycleId)
+                throw new Error("cycleId is required for link_testcases action");
+            if (!tcIds)
+                throw new Error("testcase_ids is required for link_testcases action");
+            validateId(cycleId, "cycleId");
+            const idsStr = Array.isArray(tcIds) ? tcIds.join(",") : String(tcIds);
+            const data = await callApi("post", `projects/test-cycles/testcases/link/${projectId}/${cycleId}`, { body: { ids: idsStr } });
+            return jsonResponse(data);
+        }
+        case "unlink_testcases": {
+            const cycleId = p(args, "cycleId", "cycle_id", "id");
+            const tcIds = p(args, "testcase_ids", "testcaseIds");
+            if (!cycleId)
+                throw new Error("cycleId is required for unlink_testcases action");
+            if (!tcIds)
+                throw new Error("testcase_ids is required for unlink_testcases action");
+            validateId(cycleId, "cycleId");
+            const idsStr = Array.isArray(tcIds) ? tcIds.join(",") : String(tcIds);
+            const data = await callApi("delete", `projects/test-cycles/testcases/unlink/${projectId}/${cycleId}`, { body: { ids: idsStr } });
+            return jsonResponse(data);
+        }
+        case "assign_testcases": {
+            const cycleId = p(args, "cycleId", "cycle_id", "id");
+            const tcIds = p(args, "testcase_ids", "testcaseIds");
+            const assigneeId = p(args, "assignee_id", "assigneeId");
+            if (!cycleId)
+                throw new Error("cycleId is required for assign_testcases action");
+            if (!tcIds)
+                throw new Error("testcase_ids is required for assign_testcases action");
+            if (!assigneeId)
+                throw new Error("assignee_id is required for assign_testcases action");
+            validateId(cycleId, "cycleId");
+            const idsStr = Array.isArray(tcIds) ? tcIds.join(",") : String(tcIds);
+            const data = await callApi("patch", `projects/test-cycles/testcases/assign/${projectId}/${cycleId}`, { body: { ids: idsStr, assignee: Number(assigneeId) } });
+            return jsonResponse(data);
+        }
+        default:
+            throw new Error(`Unknown action: ${action}. Use: create, update, delete, get_details, get_testcases, link_testcases, unlink_testcases, assign_testcases`);
+    }
+}
+// 9. execute_tests
+async function handleExecuteTests(args) {
+    const projectId = p(args, "projectId", "project_id");
+    const cycleId = p(args, "cycleId", "cycle_id");
+    const resultsRaw = p(args, "results");
+    if (!projectId)
+        throw new Error("projectId is required");
+    if (!cycleId)
+        throw new Error("cycleId is required");
+    if (!resultsRaw)
+        throw new Error("results is required");
+    validateId(projectId, "projectId");
+    validateId(cycleId, "cycleId");
+    const results = safeJsonParse(resultsRaw, "results");
+    if (!Array.isArray(results) || results.length === 0) {
+        throw new Error("results must be a non-empty array");
+    }
+    const mode = p(args, "mode") || "manual";
+    if (mode !== "manual" && mode !== "automation") {
+        throw new Error("mode must be 'manual' or 'automation'");
+    }
+    // Validate all results before recording any
+    const normalized = results.map((r, i) => {
+        const testcaseId = r.testcase_id || r.testcaseId;
+        const status = r.execution_status || r.executionStatus;
+        if (!testcaseId)
+            throw new Error(`results[${i}]: testcase_id is required`);
+        if (!status) {
+            throw new Error(`results[${i}]: execution_status is required. Valid values: pass, fail, blocked, not_executed`);
+        }
+        const out = {
+            testcase_id: validateId(testcaseId, "testcase_id"),
+            execution_status: status,
+        };
+        const actual = r.actual_result || r.actualResult;
+        if (actual)
+            out.actual_result = actual;
+        if (r.environment)
+            out.environment = r.environment;
+        return out;
+    });
+    if (mode === "automation") {
+        const data = await callApi("post", `projects/test-cycles/execute-bulk/${projectId}/${cycleId}`, { body: { results: normalized } });
+        const errors = data?.data?.errors || data?.errors;
+        return jsonResponseWithHints(data, Array.isArray(errors) && errors.length
+            ? ["Some results were NOT recorded (see errors) — e.g. test cases not linked to this cycle."]
+            : []);
+    }
+    // Manual: same endpoint the app uses when a tester sets a result
+    const recorded = [];
+    const failed = [];
+    for (const { testcase_id, ...body } of normalized) {
+        try {
+            await callApi("patch", `projects/test-cycles/testcases/update-execution/${projectId}/${cycleId}/${testcase_id}`, { body });
+            recorded.push(testcase_id);
+        }
+        catch (error) {
+            const err = axios.isAxiosError(error) ? handleApiError(error) : error;
+            failed.push({ testcase_id, error: err.message });
+        }
+    }
+    if (recorded.length === 0) {
+        throw new Error(`No results were recorded:\n${failed.map((f) => `${f.testcase_id}: ${f.error}`).join("\n")}`);
+    }
+    return jsonResponseWithHints({ status: failed.length ? "partial_success" : "success", recorded, failed }, failed.length ? ["Some results were NOT recorded (see failed)."] : []);
+}
+// 10. manage_test_plan
+async function handleManageTestPlan(args) {
+    const projectId = p(args, "projectId", "project_id");
+    const action = p(args, "action");
+    if (!projectId)
+        throw new Error("projectId is required");
+    if (!action)
+        throw new Error("action is required");
+    validateId(projectId, "projectId");
+    switch (action) {
+        case "create": {
+            const title = p(args, "title");
+            if (!title)
+                throw new Error("title is required for create action");
+            const body = { title };
+            if (p(args, "summary"))
+                body.summary = p(args, "summary");
+            if (p(args, "status"))
+                body.status = p(args, "status");
+            if (p(args, "planned_start_date", "plannedStartDate"))
+                body.planned_start_date = p(args, "planned_start_date", "plannedStartDate");
+            if (p(args, "planned_end_date", "plannedEndDate"))
+                body.planned_end_date = p(args, "planned_end_date", "plannedEndDate");
+            if (p(args, "folder_id", "folderId"))
+                body.folder_id = Number(p(args, "folder_id", "folderId"));
+            const data = await callApi("post", `projects/test-plans/create-test-plan/${projectId}`, { body });
+            return jsonResponse(data);
+        }
+        case "update": {
+            const planId = p(args, "planId", "plan_id", "id");
+            if (!planId)
+                throw new Error("planId is required for update action");
+            const body = { id: planId };
+            if (p(args, "title"))
+                body.title = p(args, "title");
+            if (p(args, "summary"))
+                body.summary = p(args, "summary");
+            if (p(args, "status"))
+                body.status = p(args, "status");
+            if (p(args, "planned_start_date", "plannedStartDate"))
+                body.planned_start_date = p(args, "planned_start_date", "plannedStartDate");
+            if (p(args, "planned_end_date", "plannedEndDate"))
+                body.planned_end_date = p(args, "planned_end_date", "plannedEndDate");
+            if (p(args, "folder_id", "folderId"))
+                body.folder_id = Number(p(args, "folder_id", "folderId"));
+            const data = await callApi("post", `projects/test-plans/create-test-plan/${projectId}`, { body });
+            return jsonResponse(data);
+        }
+        case "delete": {
+            const ids = p(args, "ids", "planId", "plan_id");
+            if (!ids)
+                throw new Error("ids (or planId) is required for delete action");
+            const idsStr = Array.isArray(ids) ? ids.join(",") : String(ids);
+            const data = await callApi("delete", `projects/test-plans/delete-test-plan/${projectId}`, { body: { ids: idsStr } });
+            return jsonResponse(data);
+        }
+        case "list": {
+            const data = await callApi("get", `projects/test-plans/get-test-plans/${projectId}`, {
+                query: {
+                    search: p(args, "search"),
+                    page: p(args, "page"),
+                    limit: p(args, "limit"),
+                },
+            });
+            const baseUrl = getFrontendBaseUrl();
+            if (Array.isArray(data?.data)) {
+                data.data.forEach((plan) => {
+                    const id = plan.test_plan_id || plan.id;
+                    if (id)
+                        plan.url = `${baseUrl}/${projectId}/testplans/${id}`;
+                });
+            }
+            return jsonResponse(data);
+        }
+        case "get_details": {
+            const planId = p(args, "planId", "plan_id", "id");
+            if (!planId)
+                throw new Error("planId is required for get_details action");
+            validateId(planId, "planId");
+            const data = await callApi("get", `projects/test-plans/get-test-plan-details/${projectId}/${planId}`);
+            if (data?.data) {
+                data.data.url = `${getFrontendBaseUrl()}/${projectId}/testplans/${planId}`;
+            }
+            return jsonResponse(data);
+        }
+        case "link_cycles": {
+            const planId = p(args, "planId", "plan_id", "id");
+            const cycleIds = p(args, "cycle_ids", "cycleIds");
+            if (!planId)
+                throw new Error("planId is required for link_cycles action");
+            if (!cycleIds)
+                throw new Error("cycle_ids is required for link_cycles action");
+            validateId(planId, "planId");
+            const idsStr = Array.isArray(cycleIds) ? cycleIds.join(",") : String(cycleIds);
+            const data = await callApi("post", `projects/test-plans/testcycles/link/${projectId}/${planId}`, { body: { ids: idsStr } });
+            return jsonResponse(data);
+        }
+        case "unlink_cycles": {
+            const planId = p(args, "planId", "plan_id", "id");
+            const cycleIds = p(args, "cycle_ids", "cycleIds");
+            if (!planId)
+                throw new Error("planId is required for unlink_cycles action");
+            if (!cycleIds)
+                throw new Error("cycle_ids is required for unlink_cycles action");
+            validateId(planId, "planId");
+            const idsStr = Array.isArray(cycleIds) ? cycleIds.join(",") : String(cycleIds);
+            const data = await callApi("delete", `projects/test-plans/testcycles/unlink/${projectId}/${planId}`, { body: { ids: idsStr } });
+            return jsonResponse(data);
+        }
+        case "get_cycles": {
+            const planId = p(args, "planId", "plan_id", "id");
+            if (!planId)
+                throw new Error("planId is required for get_cycles action");
+            validateId(planId, "planId");
+            const data = await callApi("get", `projects/test-plans/testcycles/list/${projectId}/${planId}`, {
+                query: {
+                    search: p(args, "search"),
+                    page: p(args, "page"),
+                    limit: p(args, "limit"),
+                },
+            });
+            return jsonResponse(data);
+        }
+        case "get_testcases": {
+            const planId = p(args, "planId", "plan_id", "id");
+            if (!planId)
+                throw new Error("planId is required for get_testcases action");
+            validateId(planId, "planId");
+            const data = await callApi("get", `projects/test-plans/testcases/list/${projectId}/${planId}`, {
+                query: {
+                    search: p(args, "search"),
+                    page: p(args, "page"),
+                    limit: p(args, "limit"),
+                },
+            });
+            return jsonResponse(data);
+        }
+        default:
+            throw new Error(`Unknown action: ${action}. Use: create, update, delete, list, get_details, link_cycles, unlink_cycles, get_cycles, get_testcases`);
+    }
+}
+// 11. get_report
+async function handleGetReport(args) {
+    const projectId = p(args, "projectId", "project_id");
+    const reportType = p(args, "report_type", "reportType");
+    if (!projectId)
+        throw new Error("projectId is required");
+    validateId(projectId, "projectId");
+    if (!reportType)
+        throw new Error("report_type is required");
+    const endpointPath = REPORT_TYPE_MAP[reportType];
+    if (!endpointPath) {
+        throw new Error(`Unknown report_type: ${reportType}. Valid types: ${Object.keys(REPORT_TYPE_MAP).join(", ")}`);
+    }
+    const query = {};
+    // Common filters (the backend takes a single cycle / plan id)
+    const singleId = (value, name) => {
+        if (!value)
+            return undefined;
+        const list = toStringArray(value);
+        if (list.length > 1) {
+            throw new Error(`${name} takes one ID. Call get_report once per ID, or use cycle_comparison for several cycles.`);
+        }
+        return validateId(list[0], name);
+    };
+    query.testCycleId = singleId(p(args, "test_cycle_id", "test_cycle_ids", "testCycleId", "testCycleIds"), "test_cycle_id");
+    query.testPlanId = singleId(p(args, "test_plan_id", "test_plan_ids", "testPlanId", "testPlanIds"), "test_plan_id");
+    if (p(args, "folder_id", "folderId"))
+        query.folderId = String(p(args, "folder_id", "folderId"));
+    if (p(args, "startDate", "start_date", "dateFrom"))
+        query.dateFrom = p(args, "startDate", "start_date", "dateFrom");
+    const endDate = p(args, "endDate", "end_date", "dateTo");
+    // The backend compares with <=, so a bare date would stop at midnight and drop the end day
+    if (endDate)
+        query.dateTo = /^\d{4}-\d{2}-\d{2}$/.test(endDate) ? `${endDate}T23:59:59.999Z` : endDate;
+    if (p(args, "granularity"))
+        query.granularity = p(args, "granularity");
+    // cycle_comparison specific
+    if (p(args, "cycle_ids", "cycleIds"))
+        query.cycleIds = p(args, "cycle_ids", "cycleIds");
+    const data = await callApi("get", `projects/reports/${endpointPath}/${projectId}`, {
+        query,
+    });
+    return jsonResponse(data);
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// SERVER SETUP
+// ═══════════════════════════════════════════════════════════════════════════════
+const server = new Server({ name: "testkase-test-management", version: VERSION }, { capabilities: { tools: {} } });
+// List all 11 tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        LIST_PROJECTS_TOOL,
+        GET_PROJECT_STRUCTURE_TOOL,
+        SEARCH_TESTCASES_TOOL,
+        GET_TESTCASE_TOOL,
+        MANAGE_TESTCASE_TOOL,
+        MANAGE_FOLDER_TOOL,
+        SEARCH_TEST_CYCLES_TOOL,
+        MANAGE_TEST_CYCLE_TOOL,
+        EXECUTE_TESTS_TOOL,
+        MANAGE_TEST_PLAN_TOOL,
+        GET_REPORT_TOOL,
+    ],
+}));
+// Route tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "list_projects":
+                return await handleListProjects(args);
+            case "get_project_structure":
+                return await handleGetProjectStructure(args);
+            case "search_testcases":
+                return await handleSearchTestcases(args);
+            case "get_testcase":
+                return await handleGetTestcase(args);
+            case "manage_testcase":
+                return await handleManageTestcase(args);
+            case "manage_folder":
+                return await handleManageFolder(args);
+            case "search_test_cycles":
+                return await handleSearchTestCycles(args);
+            case "manage_test_cycle":
+                return await handleManageTestCycle(args);
+            case "execute_tests":
+                return await handleExecuteTests(args);
+            case "manage_test_plan":
+                return await handleManageTestPlan(args);
+            case "get_report":
+                return await handleGetReport(args);
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const err = axios.isAxiosError(error) ? handleApiError(error) : (error instanceof Error ? error : new Error(String(error)));
+        const enrichedMessage = enrichErrorMessage(err.message);
+        return {
+            content: [{ type: "text", text: `Error: ${enrichedMessage}` }],
+            isError: true,
+        };
+    }
+});
+// Start
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`TestKase MCP Server v${VERSION} running on stdio (11 tools) → ${config.apiBaseUrl}`);
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map