@uarlouski/testrail-mcp-server 1.4.0 → 1.6.0

package/dist/client/testrail.js

@@ -50,17 +50,7 @@ export class TestRailClient {
                 url += `&${key}=${encodeURIComponent(value)}`;
             }
         }
-        const allCases = [];
-        let nextUrl = url;
-        while (nextUrl) {
-            const response = await this.get(nextUrl);
-            allCases.push(...response.cases);
-            nextUrl = response._links?.next;
-            if (nextUrl) {
-                nextUrl = `${API_INDEX}${nextUrl}`;
-            }
-        }
-        return allCases;
+        return this.paginateAll(url, 'cases');
     }
     async getSection(sectionId) {
         return this.get(`${API_BASE_V2}/get_section/${sectionId}`);
@@ -112,8 +102,8 @@ export class TestRailClient {
         return this.post(`${API_BASE_V2}/add_run/${projectId}`, fields);
     }
     async getSections(projectId) {
-        const response = await this.get(`${API_BASE_V2}/get_sections/${projectId}`);
-        return response.sections;
+        const url = `${API_BASE_V2}/get_sections/${projectId}`;
+        return this.paginateAll(url, 'sections');
     }
     async getProjects() {
         if (!this.projectsPromise) {
@@ -127,17 +117,7 @@ export class TestRailClient {
         if (statusId && statusId.length > 0) {
             url += `&status_id=${statusId.join(',')}`;
         }
-        const allTests = [];
-        let nextUrl = url;
-        while (nextUrl) {
-            const response = await this.get(nextUrl);
-            allTests.push(...response.tests);
-            nextUrl = response._links?.next;
-            if (nextUrl) {
-                nextUrl = `${API_INDEX}${nextUrl}`;
-            }
-        }
-        return allTests;
+        return this.paginateAll(url, 'tests');
     }
     async addResults(runId, results) {
         return this.post(`${API_BASE_V2}/add_results/${runId}`, { results });
@@ -152,6 +132,21 @@ export class TestRailClient {
         };
         return this._executeRequest('POST', `${API_BASE_V2}/add_attachment_to_run/${runId}`, headers, formData);
     }
+    async paginateAll(url, dataKey) {
+        const allItems = [];
+        let nextUrl = url;
+        while (nextUrl) {
+            const response = await this.get(nextUrl);
+            if (response[dataKey] && Array.isArray(response[dataKey])) {
+                allItems.push(...response[dataKey]);
+            }
+            nextUrl = response._links?.next || null;
+            if (nextUrl) {
+                nextUrl = `${API_INDEX}${nextUrl}`;
+            }
+        }
+        return allItems;
+    }
     async get(endpoint) {
         return this.executeRequest('GET', endpoint);
     }
@@ -172,13 +167,57 @@ export class TestRailClient {
             headers,
             body,
         };
-        const response = await fetch(url, params);
-        if (!response.ok) {
-            let errorMessage = `TestRail: ${response.status} ${response.statusText}`;
-            const errorText = await response.text();
-            errorMessage += ` - ${errorText}`;
-            throw new Error(errorMessage);
+        const maxRetries = 3;
+        const baseDelayMs = 1000;
+        let attempt = 0;
+        while (attempt <= maxRetries) {
+            console.error(`[TestRailClient] Executing ${method} request to ${endpoint}${attempt > 0 ? ` (Attempt ${attempt + 1})` : ''}`);
+            const startTime = Date.now();
+            try {
+                const response = await fetch(url, params);
+                const duration = Date.now() - startTime;
+                console.error(`[TestRailClient] Received ${response.status} ${response.statusText} from ${method} ${endpoint} in ${duration}ms`);
+                if (!response.ok) {
+                    if ([429, 500, 502, 503, 504].includes(response.status) && attempt < maxRetries) {
+                        let delayMs = baseDelayMs * Math.pow(2, attempt);
+                        const retryAfter = response.headers.get('Retry-After');
+                        if (retryAfter) {
+                            const retryAfterSeconds = parseInt(retryAfter);
+                            if (!isNaN(retryAfterSeconds)) {
+                                delayMs = retryAfterSeconds * 1000;
+                            }
+                        }
+                        console.error(`[TestRailClient] Rate limited or server error (${response.status}). Retrying in ${delayMs}ms...`);
+                        await this.delay(delayMs);
+                        attempt++;
+                        continue;
+                    }
+                    let errorMessage = `TestRail API Error: ${response.status} ${response.statusText}`;
+                    const errorText = await response.text();
+                    errorMessage += ` - ${errorText}`;
+                    console.error(`[TestRailClient] Error Details: ${errorMessage}`);
+                    throw new Error(errorMessage);
+                }
+                return await response.json();
+            }
+            catch (error) {
+                const networkError = error instanceof Error && !error.message.startsWith('TestRail API Error');
+                if (networkError && attempt < maxRetries) {
+                    const delayMs = baseDelayMs * Math.pow(2, attempt);
+                    console.error(`[TestRailClient] Network error (${error.message}). Retrying in ${delayMs}ms...`);
+                    await this.delay(delayMs);
+                    attempt++;
+                    continue;
+                }
+                if (networkError) {
+                    console.error(`[TestRailClient] Request Failed: ${method} ${endpoint} - ${error.message}`);
+                }
+                throw error;
+            }
         }
-        return await response.json();
+        throw new Error(`[TestRailClient] Max retries (${maxRetries}) exceeded for ${method} ${endpoint}`);
+    }
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
     }
 }

package/dist/index.js

@@ -18,16 +18,21 @@ import { getTestsTool } from "./tools/get_tests.js";
 import { addResultsTool } from "./tools/add_results.js";
 import { addAttachmentToRunTool } from "./tools/add_attachment_to_run.js";
 import { removeNullish } from "./utils/sanitizer.js";
-const TESTRAIL_INSTANCE_URL = process.env.TESTRAIL_INSTANCE_URL;
-const TESTRAIL_USERNAME = process.env.TESTRAIL_USERNAME;
-const TESTRAIL_API_KEY = process.env.TESTRAIL_API_KEY;
-if (!TESTRAIL_INSTANCE_URL || !TESTRAIL_USERNAME || !TESTRAIL_API_KEY) {
-    console.error("Error: TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, and TESTRAIL_API_KEY environment variables are required.");
+import z from "zod";
+const EnvSchema = z.object({
+    TESTRAIL_INSTANCE_URL: z.url('Must be a valid TestRail URL'),
+    TESTRAIL_USERNAME: z.email('Must be a valid email address'),
+    TESTRAIL_API_KEY: z.string().min(1, 'API key is required')
+});
+const parseResult = EnvSchema.safeParse(process.env);
+if (!parseResult.success) {
+    console.error("Invalid TestRail environment configuration:", JSON.stringify(z.treeifyError(parseResult.error), null, 2));
     process.exit(1);
 }
+const { TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY } = parseResult.data;
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "1.4.0",
+    version: "1.6.0",
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
 const tools = [

package/dist/tools/add_run.js

@@ -4,7 +4,7 @@ const parameters = {
     project_id: z.number().describe("The ID of the project. Use get_projects to find available projects"),
     name: z.string().optional().describe("The name of the test run"),
     description: z.string().optional().describe("The description of the test run"),
-    case_ids: z.array(z.number()).describe("Array of case IDs to include in the run. After creating the run, use get_tests with the returned run_id to retrieve test IDs for result submission")
+    case_ids: z.array(z.number()).min(1).describe("Array of case IDs to include in the run. After creating the run, use get_tests with the returned run_id to retrieve test IDs for result submission")
 };
 export const addRunTool = {
     name: "add_run",

package/dist/tools/create_case.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { validateCaseFields } from "../utils/validator.js";
 const parameters = {
     section_id: z.number().describe("The ID of the section where the case should be created. Use get_sections to find available sections"),
     title: z.string().describe("The title of the test case"),
@@ -9,6 +10,9 @@ export const createCaseTool = {
     description: "Create a new test case in TestRail",
     parameters,
     handler: async ({ section_id, title, fields }, client) => {
+        if (fields) {
+            validateCaseFields(fields, await client.getCaseFields());
+        }
         const caseData = {
             title,
             ...fields,

package/dist/tools/get_case_fields.js

@@ -21,7 +21,7 @@ function getFieldTypeName(typeId) {
 function isFieldRequired(field) {
     return field.configs.some(config => config.options?.is_required === true);
 }
-function mapToFieldSchema(field) {
+export function mapToFieldSchema(field) {
     const schema = {
         system_name: field.system_name,
         label: field.label,
@@ -36,7 +36,7 @@ function mapToFieldSchema(field) {
     }
     return schema;
 }
-const SYSTEM_FIELDS = [
+export const SYSTEM_FIELDS = [
     { system_name: "title", label: "Title", type: "String", is_required: true },
     { system_name: "section_id", label: "Section", type: "Integer", is_required: true },
     { system_name: "template_id", label: "Template", type: "Integer", is_required: false },

package/dist/tools/get_cases.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { validateCaseFields } from "../utils/validator.js";
 const parameters = {
     project_id: z.number().describe("The ID of the project. Use get_projects to find available projects"),
     section: z.object({
@@ -15,6 +16,13 @@ export const getCasesTool = {
     description: "Get all test cases for a project. Filter by section, API params (priority, type), or any field including custom fields via 'where'. Returns case IDs, titles, and any additional requested fields.",
     parameters,
     handler: async ({ project_id, section, filter, where, fields }, client) => {
+        const caseFields = await client.getCaseFields();
+        if (fields) {
+            validateCaseFields(fields, caseFields);
+        }
+        if (where) {
+            validateCaseFields(Object.keys(where), caseFields);
+        }
         let cases;
         if (section?.recursive) {
             cases = await client.getCasesRecursively(project_id, section.id, filter, section.excludes);

package/dist/tools/update_case.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { validateCaseFields } from "../utils/validator.js";
 const parameters = {
     case_id: z.string().describe("The ID of the test case to update (e.g. '123' or 'C123')"),
     fields: z.record(z.string(), z.any()).describe("Object containing fields to update. Use get_case_fields to see available fields. Example: {\"title\": \"New title\", \"priority_id\": 2, \"custom_automation_priority\": 1}"),
@@ -8,6 +9,7 @@ export const updateCaseTool = {
     description: "Update a test case in TestRail. Supports partial updates - only specify the fields you want to change",
     parameters,
     handler: async ({ case_id, fields }, client) => {
+        validateCaseFields(fields, await client.getCaseFields());
         const idString = case_id.toUpperCase().startsWith("C") ? case_id.substring(1) : case_id;
         const id = Number(idString);
         const updatedCase = await client.updateCase(id, fields);

package/dist/tools/update_cases.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
+import { validateCaseFields } from "../utils/validator.js";
 const parameters = {
-    case_ids: z.array(z.number()).describe("Array of case IDs to update (e.g. [123, 456, 789])"),
+    case_ids: z.array(z.number()).min(1).describe("Array of case IDs to update (e.g. [123, 456, 789])"),
     fields: z.record(z.string(), z.any()).describe("Object containing fields to update for ALL specified cases. Use get_case_fields to see available fields. Example: {\"priority_id\": 2, \"type_id\": 1}"),
 };
 export const updateCasesTool = {
@@ -8,6 +9,7 @@ export const updateCasesTool = {
     description: "Bulk update multiple test cases with the same field values. More efficient than calling update_case multiple times",
     parameters,
     handler: async ({ case_ids, fields }, client) => {
+        validateCaseFields(fields, await client.getCaseFields());
         const caseData = await client.getCase(case_ids[0]);
         const updatedCases = await client.updateCases(caseData.suite_id, case_ids, fields);
         return {

package/dist/utils/sanitizer.js

@@ -1,5 +1,5 @@
 /**
- * Recursively ыtrips inline style attributes from HTML tags contained in string values
+ * Recursively strips inline style attributes from HTML tags contained in string values
  * in an object or array. Useful for cleaning up TestRail markdown content before sending
  * to LLMs.
  */

package/dist/utils/validator.js

@@ -0,0 +1,29 @@
+import { SYSTEM_FIELDS, mapToFieldSchema } from "../tools/get_case_fields.js";
+/**
+ * Validates that the provided fields exist in the TestRail case schema.
+ * Throws an Error if any field is invalid.
+ *
+ * @param fields A record of fields or array of field names to validate
+ * @param caseFields Available custom case fields from TestRail
+ */
+export function validateCaseFields(fields, caseFields) {
+    const fieldKeys = Array.isArray(fields) ? fields : Object.keys(fields);
+    if (fieldKeys.length === 0) {
+        return;
+    }
+    const customFieldSchemas = caseFields.filter(field => field.is_active).map(mapToFieldSchema);
+    const validFieldNames = new Set([...SYSTEM_FIELDS, ...customFieldSchemas].map(f => f.system_name));
+    validFieldNames.add('id');
+    validFieldNames.add('suite_id');
+    const invalidFields = [];
+    for (const key of fieldKeys) {
+        if (!validFieldNames.has(key)) {
+            invalidFields.push(key);
+        }
+    }
+    if (invalidFields.length > 0) {
+        const validKeysList = Array.from(validFieldNames).sort().join(', ');
+        const invalidFieldsList = invalidFields.map(f => `'${f}'`).join(', ');
+        throw new Error(`Invalid fields provided: ${invalidFieldsList}. Available fields are: ${validKeysList}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Model Context Protocol (MCP) server for TestRail integration, enabling LLMs to fetch test cases and metadata.",
   "main": "dist/index.js",
   "bin": {