@testkase/mcp-server 2.2.0 → 2.3.0

package/build/index.js

@@ -4,12 +4,28 @@ 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;
 }
@@ -33,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;
@@ -48,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 ─────────────────────────────────────────────────────────
@@ -71,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) {
@@ -113,10 +141,119 @@ function safeJsonParse(raw, fieldName) {
     }
 }
 function validateId(id, fieldName) {
-    if (!/^[a-zA-Z0-9_\-]+$/.test(id)) {
+    const str = String(id);
+    if (!/^[a-zA-Z0-9_\-]+$/.test(str)) {
         throw new Error(`Invalid ${fieldName}: contains disallowed characters`);
     }
-    return id;
+    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);
@@ -136,7 +273,9 @@ const ERROR_HINTS = [
     { 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." },
+        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." },
 ];
@@ -192,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)
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -199,12 +345,12 @@ 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: [],
     },
@@ -213,6 +359,7 @@ const GET_PROJECT_STRUCTURE_TOOL = {
     name: "get_project_structure",
     description: "Get the structure of a project: folders, labels, team members, and field options (allowed values for priority, status, etc.). " +
         "IMPORTANT: Call this before create/update to discover allowed field values, which are project-specific.",
+    annotations: { readOnlyHint: true },
     inputSchema: {
         type: "object",
         properties: {
@@ -232,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" },
         },
@@ -252,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: {
@@ -262,27 +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: "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" +
+        "Create, update or delete test cases and their test steps.\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" +
+        "  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' }\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
@@ -292,14 +453,14 @@ const MANAGE_TESTCASE_TOOL = {
                 type: "string",
                 description: "[create] Priority. Values are project-specific — call get_project_structure(projectId, include='field_options') first to discover allowed values.",
             },
-            folder_id: { type: "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: [{"description":"...","test_data":"...","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: {
@@ -310,15 +471,15 @@ const MANAGE_TESTCASE_TOOL = {
                 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" },
+            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" },
+            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"]})',
@@ -326,7 +487,8 @@ const MANAGE_TESTCASE_TOOL = {
             // 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/delete params
             ids: {
@@ -335,9 +497,15 @@ const MANAGE_TESTCASE_TOOL = {
             },
             field: {
                 type: "string",
-                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.",
+                enum: TESTCASE_FIELDS.split(", "),
+                description: "[update] Field to update. For priority/status/automated/platform/environment, call get_project_structure(include='field_options') to get allowed values.",
             },
             value: { type: "string", description: "[update] New value. String for most fields. For labels/features/environment: comma-separated. For custom_fields: JSON object (e.g. {\"fieldName\": \"value\"})" },
+            // step params
+            testcaseId: { type: "string", description: "[add_steps/update_step/delete_steps/reorder_steps] Test case ID (e.g. TEST-123)" },
+            step_id: { type: "number", description: "[update_step] Step ID to change" },
+            description: { type: "string", description: "[update_step] Step description" },
+            step_ids: { type: "string", description: "[delete_steps/reorder_steps] Comma-separated step IDs" },
         },
         required: ["projectId", "action"],
     },
@@ -348,8 +516,10 @@ const MANAGE_FOLDER_TOOL = {
         "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)",
+        "  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: {
@@ -380,15 +550,16 @@ 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"],
     },
@@ -406,6 +577,7 @@ const MANAGE_TEST_CYCLE_TOOL = {
         "  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: {
@@ -434,7 +606,8 @@ const MANAGE_TEST_CYCLE_TOOL = {
             summary: { type: "string", description: "[create/update] Description" },
             status: {
                 type: "string",
-                description: "[create/update] Status: open, in_progress, completed",
+                enum: ["open", "in_progress", "completed"],
+                description: "[create/update] Status",
             },
             planned_start_date: {
                 type: "string",
@@ -474,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.",
+        "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: {
@@ -485,6 +659,12 @@ 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"],
     },
@@ -501,7 +681,9 @@ const MANAGE_TEST_PLAN_TOOL = {
         "  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",
+        "  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: {
@@ -529,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)",
@@ -559,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, " +
@@ -571,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: {
@@ -579,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: {
@@ -663,7 +848,6 @@ 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"),
         },
@@ -717,10 +901,17 @@ async function handleSearchTestcases(args) {
     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"),
@@ -767,158 +958,71 @@ async function handleManageTestcase(args) {
             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 = 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()).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 ? safeJsonParse(stepsRaw, "test_steps") : 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) {
-                // 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,
-                    });
-                }
-            }
+            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) {
-                const created2 = createResult?.data || createResult;
-                if (created2 && typeof created2 === "object") {
-                    created2.url = `${getFrontendBaseUrl()}/${projectId}/testcases/${tcId}`;
+                createResult.url = `${getFrontendBaseUrl()}/${projectId}/testcases/${tcId}`;
+                if (testSteps?.length) {
+                    const steps = await addSteps(projectId, tcId, testSteps);
+                    createResult.steps_created = steps.created;
+                    if (steps.errors.length) {
+                        createResult.step_errors = steps.errors;
+                        hints.push(`The test case ${tcId} WAS created; do not create it again. Add the missing steps with manage_testcase(action='add_steps', testcaseId='${tcId}').`);
+                    }
                 }
             }
-            return jsonResponseWithHints(createResult, [
-                "To update fields, use manage_testcase(action='update', ids='<id>', field='<name>', value='<value>')",
-            ]);
+            return jsonResponseWithHints(createResult, hints);
         }
         case "create_bulk": {
             const rawTestcases = p(args, "testcases", "test_cases", "items");
             if (!rawTestcases)
                 throw new Error("testcases is required for create_bulk action");
             const testcases = safeJsonParse(rawTestcases, "testcases");
-            // 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;
-                const rawFolderId = tc.folder_id || tc.folderId;
-                if (rawFolderId) {
-                    const numFolderId = Number(rawFolderId);
-                    normalized.folder_id = isNaN(numFolderId) ? rawFolderId : numFolderId;
+            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),
+                    });
                 }
-                if (tc.labels) {
-                    normalized.labels = typeof tc.labels === "string"
-                        ? tc.labels.split(",").map((l) => l.trim()).filter(Boolean)
-                        : tc.labels;
+                catch (error) {
+                    throw new Error(`testcases[${i}]: ${error.message}`);
                 }
-                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,
-                };
-            });
-            const cleanTestcases = withSteps.map((t) => t.testcase);
-            const bulkResult = await callApi("post", `projects/testcases/create-bulk-testcase/${projectId}`, { body: { testcases: cleanTestcases } });
+            }
+            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 {
-                            // 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 {
-                            // 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");
@@ -930,7 +1034,10 @@ 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 idsStr = Array.isArray(ids) ? ids.join(",") : String(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
@@ -964,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 idsStr = Array.isArray(ids) ? ids.join(",") : String(ids);
             const data = await callApi("delete", `projects/testcases/delete-testcase/${projectId}`, {
-                query: { ids: idsStr },
+                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
@@ -998,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);
         }
@@ -1022,9 +1178,12 @@ async function handleManageFolder(args) {
                 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);
         }
@@ -1048,11 +1207,15 @@ async function handleSearchTestCycles(args) {
     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"),
         },
@@ -1060,8 +1223,9 @@ async function handleSearchTestCycles(args) {
     const baseUrl = getFrontendBaseUrl();
     if (Array.isArray(data?.data)) {
         data.data.forEach((cycle) => {
-            if (cycle.id)
-                cycle.url = `${baseUrl}/${projectId}/testcycles/${cycle.id}`;
+            const id = cycle.test_cycle_id || cycle.id;
+            if (id)
+                cycle.url = `${baseUrl}/${projectId}/testcycles/${id}`;
         });
     }
     return jsonResponse(data);
@@ -1090,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);
         }
@@ -1110,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);
         }
@@ -1207,40 +1371,54 @@ async function handleExecuteTests(args) {
     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");
-        }
+    const mode = p(args, "mode") || "manual";
+    if (mode !== "manual" && mode !== "automation") {
+        throw new Error("mode must be 'manual' or 'automation'");
     }
-    // Single result → use PATCH update-execution endpoint
-    if (results.length === 1) {
-        const r = results[0];
+    // Validate all results before recording any
+    const normalized = results.map((r, i) => {
         const testcaseId = r.testcase_id || r.testcaseId;
-        const body = {
-            execution_status: r.execution_status || r.executionStatus,
+        const status = r.execution_status || r.executionStatus;
+        if (!testcaseId)
+            throw new Error(`results[${i}]: testcase_id is required`);
+        if (!status) {
+            throw new Error(`results[${i}]: execution_status is required. Valid values: pass, fail, blocked, not_executed`);
+        }
+        const out = {
+            testcase_id: validateId(testcaseId, "testcase_id"),
+            execution_status: status,
         };
-        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) {
@@ -1266,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);
         }
@@ -1286,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);
         }
@@ -1309,8 +1487,9 @@ async function handleManageTestPlan(args) {
             const baseUrl = getFrontendBaseUrl();
             if (Array.isArray(data?.data)) {
                 data.data.forEach((plan) => {
-                    if (plan.id)
-                        plan.url = `${baseUrl}/${projectId}/testplans/${plan.id}`;
+                    const id = plan.test_plan_id || plan.id;
+                    if (id)
+                        plan.url = `${baseUrl}/${projectId}/testplans/${id}`;
                 });
             }
             return jsonResponse(data);
@@ -1396,15 +1575,26 @@ 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", "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"))
-        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
@@ -1418,7 +1608,7 @@ async function handleGetReport(args) {
 // ═══════════════════════════════════════════════════════════════════════════════
 // SERVER SETUP
 // ═══════════════════════════════════════════════════════════════════════════════
-const server = new Server({ name: "testkase-mcp-server", version: "2.2.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "testkase-mcp-server", version: VERSION }, { capabilities: { tools: {} } });
 // List all 11 tools
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
@@ -1479,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.2.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);