@testkase/mcp-server 2.1.0 → 2.2.0

package/build/index.js

@@ -7,6 +7,12 @@ const config = {
     apiBaseUrl: process.env.TESTKASE_API_BASE_URL || "https://apiqa.testkase.com",
     patToken: process.env.TESTKASE_PAT_TOKEN,
 };
+// ─── Frontend URL helper ─────────────────────────────────────────────────────
+function getFrontendBaseUrl() {
+    const url = new URL(config.apiBaseUrl);
+    url.hostname = url.hostname.replace(/^api\.?/, "");
+    return url.origin;
+}
 // ─── Auth helpers (reused from v1) ───────────────────────────────────────────
 function validateAuth() {
     if (!config.patToken) {
@@ -76,7 +82,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 +102,88 @@ 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) {
+    if (!/^[a-zA-Z0-9_\-]+$/.test(id)) {
+        throw new Error(`Invalid ${fieldName}: contains disallowed characters`);
+    }
+    return id;
+}
+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 from TestKase account settings." },
+    { 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) {
@@ -115,8 +211,8 @@ const LIST_PROJECTS_TOOL = {
 };
 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.",
     inputSchema: {
         type: "object",
         properties: {
@@ -128,7 +224,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"],
@@ -168,8 +264,18 @@ const GET_TESTCASE_TOOL = {
 };
 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, bulk create, update, or delete test cases.\n\n" +
+        "ACTIONS:\n" +
+        "  create       - Create a single test case. Params: title (required), summary, priority, folder_id, labels, test_steps, precondition, status, automated, test_data, expected_result, platform, environment, features, owner_id, custom_fields\n" +
+        "  create_bulk  - Create multiple test cases. Params: testcases (JSON array)\n" +
+        "  update       - Update one field for test case(s). Params: ids, field, value (all required)\n" +
+        "  delete       - Delete test case(s). Params: ids (required)\n\n" +
+        "VALID UPDATE FIELDS: title, summary, precondition, priority, status, automated, test_data, expected_result, labels, features, platform, environment, custom_fields, owner_id, folder_id\n\n" +
+        "EXAMPLES:\n" +
+        "  Create:  { action: 'create', title: 'Verify login' }\n" +
+        "  Update:  { action: 'update', ids: 'TEST-1', field: 'priority', value: '<value from get_project_structure>' }\n" +
+        "  Delete:  { action: 'delete', ids: 'TEST-1,TEST-2' }",
     inputSchema: {
         type: "object",
         properties: {
@@ -184,7 +290,7 @@ 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" },
             labels: {
@@ -193,30 +299,57 @@ const MANAGE_TESTCASE_TOOL = {
             },
             test_steps: {
                 type: "string",
-                description: '[create] JSON array of test steps: [{"step":"...","expected_result":"..."}]',
+                description: '[create] JSON array of test steps: [{"description":"...","test_data":"...","expected_result":"..."}]',
+            },
+            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] Test data for the test case" },
+            expected_result: { type: "string", description: "[create] Expected result for the test case" },
+            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" },
+            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",
             },
-            // 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.)",
+                description: "[update] Field to update. Valid: title, summary, precondition, priority, status, automated, test_data, expected_result, labels, features, platform, environment, custom_fields, owner_id, folder_id. 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\"})" },
         },
         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 (null for root)\n" +
+        "  delete  - Delete a folder. Params: folderId (required)",
     inputSchema: {
         type: "object",
         properties: {
@@ -262,8 +395,17 @@ const SEARCH_TEST_CYCLES_TOOL = {
 };
 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",
     inputSchema: {
         type: "object",
         properties: {
@@ -292,7 +434,7 @@ const MANAGE_TEST_CYCLE_TOOL = {
             summary: { type: "string", description: "[create/update] Description" },
             status: {
                 type: "string",
-                description: "[create/update] Status: open, closed, in progress",
+                description: "[create/update] Status: open, in_progress, completed",
             },
             planned_start_date: {
                 type: "string",
@@ -332,7 +474,7 @@ 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.",
     inputSchema: {
         type: "object",
         properties: {
@@ -349,8 +491,17 @@ const EXECUTE_TESTS_TOOL = {
 };
 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",
     inputSchema: {
         type: "object",
         properties: {
@@ -517,15 +668,18 @@ async function handleListProjects(args) {
             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,14 +701,22 @@ 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 data = await callApi("get", `projects/testcases/get-testcase/${projectId}`, {
         query: {
             search: p(args, "search"),
@@ -565,6 +727,13 @@ async function handleSearchTestcases(args) {
             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 +744,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,6 +760,7 @@ 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": {
@@ -596,40 +771,94 @@ async function handleManageTestcase(args) {
             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");
+                testcaseData.priority = await coerceFieldValue(projectId, "priority", p(args, "priority"));
+            const rawFolderId = p(args, "folder_id", "folderId");
+            if (rawFolderId) {
+                const numFolderId = Number(rawFolderId);
+                testcaseData.folder_id = isNaN(numFolderId) ? rawFolderId : numFolderId;
+            }
             const labelsRaw = p(args, "labels");
             if (labelsRaw) {
                 testcaseData.labels =
                     typeof labelsRaw === "string"
-                        ? labelsRaw.split(",").map((l) => l.trim())
+                        ? labelsRaw.split(",").map((l) => l.trim()).filter(Boolean)
                         : labelsRaw;
             }
+            if (p(args, "precondition"))
+                testcaseData.precondition = p(args, "precondition");
+            if (p(args, "status"))
+                testcaseData.status = await coerceFieldValue(projectId, "status", p(args, "status"));
+            if (p(args, "automated"))
+                testcaseData.automated = await coerceFieldValue(projectId, "automated", p(args, "automated"));
+            if (p(args, "test_data"))
+                testcaseData.test_data = p(args, "test_data");
+            if (p(args, "expected_result"))
+                testcaseData.expected_result = p(args, "expected_result");
+            if (p(args, "platform"))
+                testcaseData.platform = await coerceFieldValue(projectId, "platform", p(args, "platform"));
+            const featuresRaw = p(args, "features");
+            if (featuresRaw) {
+                testcaseData.features = typeof featuresRaw === "string"
+                    ? featuresRaw.split(",").map((s) => s.trim())
+                    : featuresRaw;
+            }
+            const envRaw = p(args, "environment");
+            if (envRaw) {
+                testcaseData.environment = typeof envRaw === "string"
+                    ? envRaw.split(",").map((s) => s.trim())
+                    : envRaw;
+            }
+            const ownerId = p(args, "owner_id", "ownerId");
+            if (ownerId) {
+                const num = Number(ownerId);
+                testcaseData.owner_id = isNaN(num) ? ownerId : num;
+            }
+            const customFieldsRaw = p(args, "custom_fields", "customFields");
+            if (customFieldsRaw) {
+                const parsed = safeJsonParse(customFieldsRaw, "custom_fields");
+                for (const key of Object.keys(parsed)) {
+                    if (!Array.isArray(parsed[key])) {
+                        parsed[key] = [parsed[key]];
+                    }
+                }
+                testcaseData.custom_fields = parsed;
+            }
             // Parse test_steps
             const stepsRaw = p(args, "test_steps", "testSteps", "steps");
-            const testSteps = stepsRaw
-                ? typeof stepsRaw === "string"
-                    ? JSON.parse(stepsRaw)
-                    : stepsRaw
-                : null;
+            const testSteps = stepsRaw ? safeJsonParse(stepsRaw, "test_steps") : null;
             // Step 1: Create testcase
             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 },
-                });
+                // Backend endpoint accepts a single step per call, so loop through each step
+                for (const s of testSteps) {
+                    const step = {
+                        description: s.description || s.step,
+                        test_data: s.test_data,
+                        expected_result: s.expected_result,
+                    };
+                    await callApi("post", `projects/testcases/teststeps/${projectId}/${tcId}`, {
+                        body: step,
+                    });
+                }
             }
-            return jsonResponse(createResult);
+            if (tcId) {
+                const created2 = createResult?.data || createResult;
+                if (created2 && typeof created2 === "object") {
+                    created2.url = `${getFrontendBaseUrl()}/${projectId}/testcases/${tcId}`;
+                }
+            }
+            return jsonResponseWithHints(createResult, [
+                "To update fields, use manage_testcase(action='update', ids='<id>', field='<name>', value='<value>')",
+            ]);
         }
         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;
+            const testcases = safeJsonParse(rawTestcases, "testcases");
             // Separate test_steps for post-creation
             const withSteps = testcases.map((tc) => {
                 const normalized = { title: tc.title || tc.name };
@@ -637,8 +866,22 @@ async function handleManageTestcase(args) {
                     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;
+                const rawFolderId = tc.folder_id || tc.folderId;
+                if (rawFolderId) {
+                    const numFolderId = Number(rawFolderId);
+                    normalized.folder_id = isNaN(numFolderId) ? rawFolderId : numFolderId;
+                }
+                if (tc.labels) {
+                    normalized.labels = typeof tc.labels === "string"
+                        ? tc.labels.split(",").map((l) => l.trim()).filter(Boolean)
+                        : tc.labels;
+                }
+                if (tc.precondition)
+                    normalized.precondition = tc.precondition;
+                if (tc.status)
+                    normalized.status = tc.status;
+                if (tc.automated)
+                    normalized.automated = tc.automated;
                 return {
                     testcase: normalized,
                     test_steps: tc.test_steps || tc.testSteps || tc.steps,
@@ -656,9 +899,17 @@ async function handleManageTestcase(args) {
                     const tcId = r.testcaseId || r.id;
                     if (tcId) {
                         try {
-                            await callApi("post", `projects/testcases/teststeps/${projectId}/${tcId}`, {
-                                body: { steps },
-                            });
+                            // Backend endpoint accepts a single step per call, so loop through each step
+                            for (const s of steps) {
+                                const step = {
+                                    description: s.description || s.step,
+                                    test_data: s.test_data,
+                                    expected_result: s.expected_result,
+                                };
+                                await callApi("post", `projects/testcases/teststeps/${projectId}/${tcId}`, {
+                                    body: step,
+                                });
+                            }
                             stepsCreated++;
                         }
                         catch {
@@ -679,9 +930,33 @@ 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;
+            const idsStr = Array.isArray(ids) ? ids.join(",") : String(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,9 +964,9 @@ 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 idsStr = Array.isArray(ids) ? ids.join(",") : String(ids);
             const data = await callApi("delete", `projects/testcases/delete-testcase/${projectId}`, {
-                body: { ids: idList },
+                query: { ids: idsStr },
             });
             return jsonResponse(data);
         }
@@ -707,6 +982,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) {
@@ -733,6 +1009,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,6 +1020,7 @@ 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 data = await callApi("patch", `folders/${folderId}/move`, {
                 query: { projectId, section },
@@ -754,6 +1032,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,6 +1047,7 @@ async function handleSearchTestCycles(args) {
     const projectId = p(args, "projectId", "project_id");
     if (!projectId)
         throw new Error("projectId is required");
+    validateId(projectId, "projectId");
     const data = await callApi("get", `projects/test-cycles/get-test-cycles/${projectId}`, {
         query: {
             search: p(args, "search"),
@@ -777,6 +1057,13 @@ async function handleSearchTestCycles(args) {
             limit: p(args, "limit"),
         },
     });
+    const baseUrl = getFrontendBaseUrl();
+    if (Array.isArray(data?.data)) {
+        data.data.forEach((cycle) => {
+            if (cycle.id)
+                cycle.url = `${baseUrl}/${projectId}/testcycles/${cycle.id}`;
+        });
+    }
     return jsonResponse(data);
 }
 // 8. manage_test_cycle
@@ -787,6 +1074,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");
@@ -830,21 +1118,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 +1154,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 +1166,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 +1181,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,16 +1201,25 @@ 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");
     }
+    // Validate all results have required fields
+    for (const r of results) {
+        if (!r.testcase_id && !r.testcaseId) {
+            throw new Error("testcase_id is required in each result");
+        }
+        if (!r.execution_status && !r.executionStatus) {
+            throw new Error("execution_status is required in each result. Valid values: pass, fail, blocked, not_executed");
+        }
+    }
     // Single result → use PATCH update-execution endpoint
     if (results.length === 1) {
         const r = results[0];
         const testcaseId = r.testcase_id || r.testcaseId;
-        if (!testcaseId)
-            throw new Error("testcase_id is required in each result");
         const body = {
             execution_status: r.execution_status || r.executionStatus,
         };
@@ -945,6 +1250,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");
@@ -988,8 +1294,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 +1306,24 @@ async function handleManageTestPlan(args) {
                     limit: p(args, "limit"),
                 },
             });
+            const baseUrl = getFrontendBaseUrl();
+            if (Array.isArray(data?.data)) {
+                data.data.forEach((plan) => {
+                    if (plan.id)
+                        plan.url = `${baseUrl}/${projectId}/testplans/${plan.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 +1333,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 +1345,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 +1368,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 +1388,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];
@@ -1075,10 +1397,10 @@ async function handleGetReport(args) {
     }
     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, "test_cycle_ids", "testCycleIds", "testCycleId"))
+        query.testCycleId = p(args, "test_cycle_ids", "testCycleIds", "testCycleId");
+    if (p(args, "test_plan_ids", "testPlanIds", "testPlanId"))
+        query.testPlanId = p(args, "test_plan_ids", "testPlanIds", "testPlanId");
     if (p(args, "startDate", "start_date"))
         query.startDate = p(args, "startDate", "start_date");
     if (p(args, "endDate", "end_date"))
@@ -1087,7 +1409,7 @@ async function handleGetReport(args) {
         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 +1418,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: "2.2.0" }, { capabilities: { tools: {} } });
 // List all 11 tools
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
@@ -1145,9 +1467,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 +1479,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 v2.2.0 running on stdio (11 tools)");
 }
 main().catch((error) => {
     console.error("Fatal error in main():", error);