@testkase/mcp-server 2.1.0 → 2.3.0

package/build/index.js

@@ -4,9 +4,31 @@ 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://apiqa.testkase.com",
+    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.3.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) {
@@ -27,11 +49,13 @@ function getApiHeaders() {
 // ─── 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() });
+        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;
@@ -42,7 +66,10 @@ async function getOrganizationId() {
     catch (error) {
         if (error instanceof Error && error.message.includes("Could not determine"))
             throw error;
-        throw new Error("Failed to fetch organization. Check your PAT token.");
+        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 ─────────────────────────────────────────────────────────
@@ -65,9 +92,16 @@ async function callApi(method, path, options = {}) {
         method,
         url,
         headers: getApiHeaders(),
+        timeout: REQUEST_TIMEOUT_MS,
         ...(options.body !== undefined && { data: options.body }),
     });
-    return response.data;
+    // 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) {
@@ -76,7 +110,15 @@ function handleApiError(error) {
         let msg = `API request failed: ${e.message}`;
         if (e.response) {
             msg += `\nStatus: ${e.response.status}`;
-            msg += `\nResponse: ${JSON.stringify(e.response.data)}`;
+            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);
     }
@@ -88,6 +130,199 @@ function jsonResponse(data) {
         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) {
@@ -96,6 +331,13 @@ function p(args, ...names) {
     }
     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)
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -103,20 +345,21 @@ 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: {
-            search: { type: "string", description: "Search by project name or ID" },
             page: { type: "number", description: "Page number (default: 1)" },
-            limit: { type: "number", description: "Items per page (default: 20)" },
+            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, and/or team members. " +
-        "Useful to discover folder IDs, label names, and member IDs before creating or updating items.",
+    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: {
@@ -128,7 +371,7 @@ const GET_PROJECT_STRUCTURE_TOOL = {
             },
             include: {
                 type: "string",
-                description: "Comma-separated list of what to include: folders,labels,members (default: all)",
+                description: "Comma-separated list of what to include: folders,labels,members,field_options (default: all)",
             },
         },
         required: ["projectId"],
@@ -136,18 +379,24 @@ const GET_PROJECT_STRUCTURE_TOOL = {
 };
 const SEARCH_TESTCASES_TOOL = {
     name: "search_testcases",
-    description: "Search and list test cases in a project. Supports text search, filters, sorting, and pagination.",
+    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 (title or summary)" },
+            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 string of filters. Example: {"status":["active"],"priority":["high","critical"]}',
+                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)" },
+            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" },
         },
@@ -156,7 +405,8 @@ const SEARCH_TESTCASES_TOOL = {
 };
 const GET_TESTCASE_TOOL = {
     name: "get_testcase",
-    description: "Get full details of a single test case including test steps and attachments.",
+    description: "Get full details of a single test case including test steps (with step ids) and attachments.",
+    annotations: { readOnlyHint: true },
     inputSchema: {
         type: "object",
         properties: {
@@ -166,17 +416,34 @@ const GET_TESTCASE_TOOL = {
         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: "Create, bulk create, update, or delete test cases. " +
-        "Set 'action' to: create, create_bulk, update, or delete.",
+    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"],
+                enum: ["create", "create_bulk", "update", "delete", "add_steps", "update_step", "delete_steps", "reorder_steps"],
                 description: "Action to perform",
             },
             // create params
@@ -184,39 +451,75 @@ const MANAGE_TESTCASE_TOOL = {
             summary: { type: "string", description: "[create] Description/summary" },
             priority: {
                 type: "string",
-                description: "[create] Priority: low, medium, high, or critical",
+                description: "[create] Priority. Values are project-specific — call get_project_structure(projectId, include='field_options') first to discover allowed values.",
             },
-            folder_id: { type: "string", description: "[create] Folder ID to place the test case in" },
+            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] JSON array of test steps: [{"step":"...","expected_result":"..."}]',
+                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 with title, summary, priority, folder_id, test_steps",
+                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 params
+            // update/delete params
             ids: {
                 type: "string",
-                description: "[update/delete] Comma-separated test case IDs",
+                description: "[update/delete] Test case IDs, comma-separated (e.g. 'TEST-1' or 'TEST-1,TEST-2')",
             },
             field: {
                 type: "string",
-                description: "[update] Field name to update (title, summary, priority, status, etc.)",
+                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 for the field" },
+            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).",
+    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: {
@@ -247,23 +550,34 @@ const MANAGE_FOLDER_TOOL = {
 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", description: "Filter by status (open, closed, etc.)" },
+            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)" },
+            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. " +
-        "Set 'action' to: create, update, delete, get_details, get_testcases, link_testcases, unlink_testcases, assign_testcases.",
+    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: {
@@ -292,7 +606,8 @@ const MANAGE_TEST_CYCLE_TOOL = {
             summary: { type: "string", description: "[create/update] Description" },
             status: {
                 type: "string",
-                description: "[create/update] Status: open, closed, in progress",
+                enum: ["open", "in_progress", "completed"],
+                description: "[create/update] Status",
             },
             planned_start_date: {
                 type: "string",
@@ -332,7 +647,8 @@ 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, in_progress.",
+        "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: {
@@ -343,14 +659,31 @@ const EXECUTE_TESTS_TOOL = {
                 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. " +
-        "Set 'action' to: create, update, delete, list, get_details, link_cycles, unlink_cycles, get_cycles, get_testcases.",
+    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: {
@@ -378,7 +711,7 @@ const MANAGE_TEST_PLAN_TOOL = {
             // create/update fields
             title: { type: "string", description: "[create/update] Plan title" },
             summary: { type: "string", description: "[create/update] Description" },
-            status: { type: "string", description: "[create/update] Status" },
+            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)",
@@ -408,7 +741,8 @@ const MANAGE_TEST_PLAN_TOOL = {
 };
 const GET_REPORT_TOOL = {
     name: "get_report",
-    description: "Get reports and analytics for a project. Covers execution, coverage, trends, team, defects, and AI insights. " +
+    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, " +
@@ -420,6 +754,7 @@ const GET_REPORT_TOOL = {
         "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: {
@@ -428,14 +763,15 @@ const GET_REPORT_TOOL = {
                 type: "string",
                 description: "Report type (see description for full list)",
             },
-            test_cycle_ids: {
+            test_cycle_id: {
                 type: "string",
-                description: "Comma-separated test cycle IDs to filter by",
+                description: "Only this test cycle (one ID, e.g. TCYCLE-3)",
             },
-            test_plan_ids: {
+            test_plan_id: {
                 type: "string",
-                description: "Comma-separated test plan IDs to filter by",
+                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: {
@@ -512,20 +848,22 @@ const REPORT_TYPE_MAP = {
 async function handleListProjects(args) {
     const data = await callApi("get", "projects/user/my-projects", {
         query: {
-            search: p(args, "search"),
             page: p(args, "page"),
             limit: p(args, "limit"),
         },
     });
-    return jsonResponse(data);
+    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";
+    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 = {};
@@ -547,24 +885,46 @@ async function handleGetProjectStructure(args) {
             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 jsonResponse(result);
+    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: p(args, "filters"),
+            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
@@ -575,7 +935,12 @@ async function handleGetTestcase(args) {
         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
@@ -586,88 +951,78 @@ async function handleManageTestcase(args) {
         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");
-            const testcaseData = { title };
-            if (p(args, "summary", "description"))
-                testcaseData.summary = p(args, "summary", "description");
-            if (p(args, "priority"))
-                testcaseData.priority = p(args, "priority");
-            if (p(args, "folder_id", "folderId"))
-                testcaseData.folder_id = p(args, "folder_id", "folderId");
-            const labelsRaw = p(args, "labels");
-            if (labelsRaw) {
-                testcaseData.labels =
-                    typeof labelsRaw === "string"
-                        ? labelsRaw.split(",").map((l) => l.trim())
-                        : labelsRaw;
-            }
-            // Parse test_steps
-            const stepsRaw = p(args, "test_steps", "testSteps", "steps");
-            const testSteps = stepsRaw
-                ? typeof stepsRaw === "string"
-                    ? JSON.parse(stepsRaw)
-                    : stepsRaw
-                : null;
-            // Step 1: Create testcase
+            // 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 });
-            // Step 2: Add test steps if provided
-            const created = createResult?.data || createResult;
-            const tcId = created?.id || created?.testcaseId;
-            if (testSteps && Array.isArray(testSteps) && testSteps.length > 0 && tcId) {
-                await callApi("post", `projects/testcases/teststeps/${projectId}/${tcId}`, {
-                    body: { steps: testSteps },
-                });
+            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 jsonResponse(createResult);
+            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 = typeof rawTestcases === "string" ? JSON.parse(rawTestcases) : rawTestcases;
-            // Separate test_steps for post-creation
-            const withSteps = testcases.map((tc) => {
-                const normalized = { title: tc.title || tc.name };
-                if (tc.summary || tc.description)
-                    normalized.summary = tc.summary || tc.description;
-                if (tc.priority)
-                    normalized.priority = tc.priority;
-                if (tc.folder_id || tc.folderId)
-                    normalized.folder_id = tc.folder_id || tc.folderId;
-                return {
-                    testcase: normalized,
-                    test_steps: tc.test_steps || tc.testSteps || tc.steps,
-                };
-            });
-            const cleanTestcases = withSteps.map((t) => t.testcase);
-            const bulkResult = await callApi("post", `projects/testcases/create-bulk-testcase/${projectId}`, { body: { testcases: cleanTestcases } });
+            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;
-            for (let i = 0; i < results.length; i++) {
-                const r = results[i];
-                const steps = withSteps[i]?.test_steps;
-                if (r.status === "success" && steps?.length) {
-                    const tcId = r.testcaseId || r.id;
-                    if (tcId) {
-                        try {
-                            await callApi("post", `projects/testcases/teststeps/${projectId}/${tcId}`, {
-                                body: { steps },
-                            });
-                            stepsCreated++;
-                        }
-                        catch {
-                            // Non-fatal: steps failed but testcase was created
-                        }
-                    }
-                }
+            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;
             }
-            return jsonResponse({ ...bulkResult, steps_created_for: stepsCreated });
+            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");
@@ -679,9 +1034,36 @@ async function handleManageTestcase(args) {
                 throw new Error("field is required for update action");
             if (value === undefined)
                 throw new Error("value is required for update action");
-            const idList = typeof ids === "string" ? ids.split(",").map((s) => s.trim()) : ids;
+            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: idList, field, value },
+                body: { ids: idsStr, [field]: parsedValue },
             });
             return jsonResponse(data);
         }
@@ -689,14 +1071,63 @@ async function handleManageTestcase(args) {
             const ids = p(args, "ids", "testcase_ids", "testcaseIds");
             if (!ids)
                 throw new Error("ids is required for delete action");
-            const idList = typeof ids === "string" ? ids.split(",").map((s) => s.trim()) : ids;
             const data = await callApi("delete", `projects/testcases/delete-testcase/${projectId}`, {
-                body: { ids: idList },
+                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`);
+            throw new Error(`Unknown action: ${action}. Use: create, create_bulk, update, delete, add_steps, update_step, delete_steps, reorder_steps`);
     }
 }
 // 6. manage_folder
@@ -707,6 +1138,7 @@ async function handleManageFolder(args) {
         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) {
@@ -722,7 +1154,7 @@ async function handleManageFolder(args) {
             };
             const parentId = p(args, "parentId", "parent_id");
             if (parentId)
-                body.parentId = parentId;
+                body.parentId = Number(parentId);
             const data = await callApi("post", "folders/create-folders", { body, skipOrgId: true });
             return jsonResponse(data);
         }
@@ -733,6 +1165,7 @@ async function handleManageFolder(args) {
                 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 },
@@ -743,10 +1176,14 @@ async function handleManageFolder(args) {
             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: { parentId: parentId ?? null },
+                body: { newParentId },
             });
             return jsonResponse(data);
         }
@@ -754,6 +1191,7 @@ async function handleManageFolder(args) {
             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 },
             });
@@ -768,15 +1206,28 @@ 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"),
-            folderId: p(args, "folderId", "folder_id"),
-            status: p(args, "status"),
+            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
@@ -787,6 +1238,7 @@ async function handleManageTestCycle(args) {
         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");
@@ -802,7 +1254,7 @@ async function handleManageTestCycle(args) {
             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 = 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);
         }
@@ -822,7 +1274,7 @@ async function handleManageTestCycle(args) {
             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 = 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);
         }
@@ -830,21 +1282,26 @@ async function handleManageTestCycle(args) {
             const ids = p(args, "ids", "cycleId", "cycle_id");
             if (!ids)
                 throw new Error("ids (or cycleId) is required for delete action");
-            const idList = typeof ids === "string" ? ids.split(",").map((s) => s.trim()) : ids;
-            const data = await callApi("delete", `projects/test-cycles/delete-test-cycle/${projectId}`, { body: { ids: idList } });
+            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"),
@@ -861,8 +1318,9 @@ async function handleManageTestCycle(args) {
                 throw new Error("cycleId is required for link_testcases action");
             if (!tcIds)
                 throw new Error("testcase_ids is required for link_testcases action");
-            const idList = typeof tcIds === "string" ? tcIds.split(",").map((s) => s.trim()) : tcIds;
-            const data = await callApi("post", `projects/test-cycles/testcases/link/${projectId}/${cycleId}`, { body: { testcase_ids: idList } });
+            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": {
@@ -872,8 +1330,9 @@ async function handleManageTestCycle(args) {
                 throw new Error("cycleId is required for unlink_testcases action");
             if (!tcIds)
                 throw new Error("testcase_ids is required for unlink_testcases action");
-            const idList = typeof tcIds === "string" ? tcIds.split(",").map((s) => s.trim()) : tcIds;
-            const data = await callApi("delete", `projects/test-cycles/testcases/unlink/${projectId}/${cycleId}`, { body: { testcase_ids: idList } });
+            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": {
@@ -886,8 +1345,9 @@ async function handleManageTestCycle(args) {
                 throw new Error("testcase_ids is required for assign_testcases action");
             if (!assigneeId)
                 throw new Error("assignee_id is required for assign_testcases action");
-            const idList = typeof tcIds === "string" ? tcIds.split(",").map((s) => s.trim()) : tcIds;
-            const data = await callApi("patch", `projects/test-cycles/testcases/assign/${projectId}/${cycleId}`, { body: { testcase_ids: idList, assignee_id: assigneeId } });
+            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:
@@ -905,37 +1365,60 @@ async function handleExecuteTests(args) {
         throw new Error("cycleId is required");
     if (!resultsRaw)
         throw new Error("results is required");
-    const results = typeof resultsRaw === "string" ? JSON.parse(resultsRaw) : resultsRaw;
+    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");
     }
-    // Single result → use PATCH update-execution endpoint
-    if (results.length === 1) {
-        const r = results[0];
+    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("testcase_id is required in each result");
-        const body = {
-            execution_status: r.execution_status || r.executionStatus,
+            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,
         };
-        if (r.actual_result || r.actualResult)
-            body.actual_result = r.actual_result || r.actualResult;
+        const actual = r.actual_result || r.actualResult;
+        if (actual)
+            out.actual_result = actual;
         if (r.environment)
-            body.environment = r.environment;
-        const data = await callApi("patch", `projects/test-cycles/testcases/update-execution/${projectId}/${cycleId}/${testcaseId}`, { body });
-        return jsonResponse(data);
+            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."]
+            : []);
     }
-    // Multiple results → use POST execute-bulk endpoint
-    const bulkResults = results.map((r) => ({
-        testcase_id: r.testcase_id || r.testcaseId,
-        execution_status: r.execution_status || r.executionStatus,
-        ...(r.actual_result || r.actualResult
-            ? { actual_result: r.actual_result || r.actualResult }
-            : {}),
-        ...(r.environment ? { environment: r.environment } : {}),
-    }));
-    const data = await callApi("post", `projects/test-cycles/execute-bulk/${projectId}/${cycleId}`, { body: { results: bulkResults } });
-    return jsonResponse(data);
+    // 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) {
@@ -945,6 +1428,7 @@ async function handleManageTestPlan(args) {
         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");
@@ -960,7 +1444,7 @@ async function handleManageTestPlan(args) {
             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 = 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);
         }
@@ -980,7 +1464,7 @@ async function handleManageTestPlan(args) {
             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 = 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);
         }
@@ -988,8 +1472,8 @@ async function handleManageTestPlan(args) {
             const ids = p(args, "ids", "planId", "plan_id");
             if (!ids)
                 throw new Error("ids (or planId) is required for delete action");
-            const idList = typeof ids === "string" ? ids.split(",").map((s) => s.trim()) : ids;
-            const data = await callApi("delete", `projects/test-plans/delete-test-plan/${projectId}`, { body: { ids: idList } });
+            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": {
@@ -1000,13 +1484,25 @@ async function handleManageTestPlan(args) {
                     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": {
@@ -1016,8 +1512,9 @@ async function handleManageTestPlan(args) {
                 throw new Error("planId is required for link_cycles action");
             if (!cycleIds)
                 throw new Error("cycle_ids is required for link_cycles action");
-            const idList = typeof cycleIds === "string" ? cycleIds.split(",").map((s) => s.trim()) : cycleIds;
-            const data = await callApi("post", `projects/test-plans/testcycles/link/${projectId}/${planId}`, { body: { test_cycle_ids: idList } });
+            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": {
@@ -1027,14 +1524,16 @@ async function handleManageTestPlan(args) {
                 throw new Error("planId is required for unlink_cycles action");
             if (!cycleIds)
                 throw new Error("cycle_ids is required for unlink_cycles action");
-            const idList = typeof cycleIds === "string" ? cycleIds.split(",").map((s) => s.trim()) : cycleIds;
-            const data = await callApi("delete", `projects/test-plans/testcycles/unlink/${projectId}/${planId}`, { body: { test_cycle_ids: idList } });
+            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"),
@@ -1048,6 +1547,7 @@ async function handleManageTestPlan(args) {
             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"),
@@ -1067,6 +1567,7 @@ async function handleGetReport(args) {
     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];
@@ -1074,20 +1575,31 @@ async function handleGetReport(args) {
         throw new Error(`Unknown report_type: ${reportType}. Valid types: ${Object.keys(REPORT_TYPE_MAP).join(", ")}`);
     }
     const query = {};
-    // Common filters
-    if (p(args, "test_cycle_ids", "testCycleIds"))
-        query.test_cycle_ids = p(args, "test_cycle_ids", "testCycleIds");
-    if (p(args, "test_plan_ids", "testPlanIds"))
-        query.test_plan_ids = p(args, "test_plan_ids", "testPlanIds");
-    if (p(args, "startDate", "start_date"))
-        query.startDate = p(args, "startDate", "start_date");
-    if (p(args, "endDate", "end_date"))
-        query.endDate = p(args, "endDate", "end_date");
+    // 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.cycle_ids = p(args, "cycle_ids", "cycleIds");
+        query.cycleIds = p(args, "cycle_ids", "cycleIds");
     const data = await callApi("get", `projects/reports/${endpointPath}/${projectId}`, {
         query,
     });
@@ -1096,7 +1608,7 @@ async function handleGetReport(args) {
 // ═══════════════════════════════════════════════════════════════════════════════
 // SERVER SETUP
 // ═══════════════════════════════════════════════════════════════════════════════
-const server = new Server({ name: "testkase-mcp-server", version: "2.1.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "testkase-mcp-server", version: VERSION }, { capabilities: { tools: {} } });
 // List all 11 tools
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
@@ -1145,9 +1657,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
     }
     catch (error) {
-        const err = error instanceof Error ? error : handleApiError(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: ${err.message}` }],
+            content: [{ type: "text", text: `Error: ${enrichedMessage}` }],
             isError: true,
         };
     }
@@ -1156,7 +1669,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("TestKase MCP Server v2.1.0 running on stdio (11 tools)");
+    console.error(`TestKase MCP Server v${VERSION} running on stdio (11 tools) → ${config.apiBaseUrl}`);
 }
 main().catch((error) => {
     console.error("Fatal error in main():", error);