@uarlouski/testrail-mcp-server 2.0.0 → 2.2.0

package/dist/client/testrail.js

@@ -25,7 +25,9 @@ export class TestRailClient {
         return this.get(`${API_BASE_V2}/get_case/${caseId}`);
     }
     async getCasesRecursively(projectId, sectionId, filter, excludedSectionNames) {
-        const sections = await this.getSections(projectId);
+        // Extract suite_id from filter if present, for getSections call
+        const suiteId = filter?.suite_id ? parseInt(filter.suite_id) : undefined;
+        const sections = await this.getSections(projectId, suiteId);
         const sectionIds = this.getSubSectionIds(sections, sectionId, excludedSectionNames);
         sectionIds.push(sectionId);
         const promises = sectionIds.map(id => this.getCases(projectId, id, filter));
@@ -105,8 +107,11 @@ export class TestRailClient {
     async updateRun(runId, fields) {
         return this.post(`${API_BASE_V2}/update_run/${runId}`, fields);
     }
-    async getSections(projectId) {
-        const url = `${API_BASE_V2}/get_sections/${projectId}`;
+    async getSections(projectId, suiteId) {
+        let url = `${API_BASE_V2}/get_sections/${projectId}`;
+        if (suiteId) {
+            url += `&suite_id=${suiteId}`;
+        }
         return this.paginateAll(url, 'sections');
     }
     async addSection(projectId, data) {
@@ -152,8 +157,7 @@ export class TestRailClient {
     }
     async getProjects() {
         if (!this.projectsPromise) {
-            this.projectsPromise = this.get(`${API_BASE_V2}/get_projects`)
-                .then(response => response.projects);
+            this.projectsPromise = this.paginateAll(`${API_BASE_V2}/get_projects`, 'projects');
         }
         return this.projectsPromise;
     }
@@ -221,6 +225,12 @@ export class TestRailClient {
         let nextUrl = url;
         while (nextUrl) {
             const response = await this.get(nextUrl);
+            // Handle older TestRail versions (pre-7.x) that return flat arrays
+            // instead of paginated objects like { "suites": [...], "_links": {...} }
+            if (Array.isArray(response)) {
+                allItems.push(...response);
+                break;
+            }
             if (response[dataKey] && Array.isArray(response[dataKey])) {
                 allItems.push(...response[dataKey]);
             }

package/dist/index.js

@@ -23,7 +23,7 @@ if (!parseResult.success) {
 const { TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY, TESTRAIL_ENABLE_SHARED_STEPS, TESTRAIL_ALLOW_WRITE_OPERATIONS, TESTRAIL_ALLOW_READ_OPERATIONS, TESTRAIL_ALLOW_DELETE_OPERATIONS } = parseResult.data;
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "2.0.0",
+    version: "2.2.0",
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
 const tools = getToolsToRegister({

package/dist/tools/cases/get_case_fields.js

@@ -13,35 +13,41 @@ Example: {"priority_id": 2, "template_id": 1, "labels": [1, 2]}
 Call get_case_fields with project_id first if field names are not already known.
 Using an unknown field name (e.g. 'label_ids') will result in an error.
 `;
-const FIELD_TYPE_NAMES = {
-    1: "String",
-    2: "Integer",
-    3: "Text",
-    4: "URL",
-    5: "Checkbox",
-    6: "Dropdown",
-    7: "User",
-    8: "Date",
-    9: "Milestone",
-    10: "Steps",
-    11: "Step Results",
-    12: "Multi-select",
-    13: "Scenarios",
-    14: "List",
-};
-function getFieldTypeName(typeId) {
-    return FIELD_TYPE_NAMES[typeId] || `Unknown (${typeId})`;
+export const FIELD_TYPES = [
+    { typeId: 1, name: "String" },
+    { typeId: 2, name: "Integer" },
+    { typeId: 3, name: "Text" },
+    { typeId: 4, name: "URL" },
+    { typeId: 5, name: "Checkbox", description: "Boolean value, either true or false." },
+    { typeId: 6, name: "Dropdown" },
+    { typeId: 7, name: "User" },
+    { typeId: 8, name: "Date" },
+    { typeId: 9, name: "Milestone" },
+    { typeId: 10, name: "Steps" },
+    { typeId: 11, name: "Step Results" },
+    { typeId: 12, name: "Multi-select" },
+    { typeId: 13, name: "Scenarios" },
+    { typeId: 14, name: "List" },
+];
+function getFieldType(typeId) {
+    const found = FIELD_TYPES.find(t => t.typeId === typeId);
+    return found ?? { typeId, name: `Unknown (${typeId})` };
 }
 function isFieldRequired(field) {
     return field.configs.some(config => config.options?.is_required === true);
 }
 export function mapToFieldSchema(field) {
+    const fieldType = getFieldType(field.type_id);
+    const descriptions = [field.description, fieldType.description].filter(Boolean);
     const schema = {
         system_name: field.system_name,
         label: field.label,
-        type: getFieldTypeName(field.type_id),
+        type: fieldType.name,
         is_required: isFieldRequired(field),
     };
+    if (descriptions.length > 0) {
+        schema.description = descriptions.join(" ");
+    }
     if (!field.include_all && field.template_ids.length > 0) {
         schema.template_ids = field.template_ids;
     }
@@ -68,15 +74,15 @@ function isFieldForProject(field, projectId) {
     return contexts.some(ctx => ctx.is_global || ctx.project_ids.includes(projectId));
 }
 export const SYSTEM_FIELDS = [
-    { system_name: "title", label: "Title", type: "String", is_required: true, project_scope: { scope: "global" } },
-    { system_name: "section_id", label: "Section", type: "Integer", is_required: true, project_scope: { scope: "global" } },
-    { system_name: "template_id", label: "Template", type: "Integer", is_required: false, project_scope: { scope: "global" } },
-    { system_name: "type_id", label: "Type", type: "Integer", is_required: false, project_scope: { scope: "global" } },
-    { system_name: "priority_id", label: "Priority", type: "Integer", is_required: false, project_scope: { scope: "global" } },
-    { system_name: "estimate", label: "Estimate", type: "String", is_required: false, project_scope: { scope: "global" } },
-    { system_name: "milestone_id", label: "Milestone", type: "Integer", is_required: false, project_scope: { scope: "global" } },
-    { system_name: "refs", label: "References", type: "String", is_required: false, project_scope: { scope: "global" } },
-    { system_name: "labels", label: "Labels", type: "List", is_required: false, project_scope: { scope: "global" }, comment: "Use get_labels tool to get available labels/tags." },
+    { system_name: "title", label: "Title", type: getFieldType(1).name, is_required: true, project_scope: { scope: "global" } },
+    { system_name: "section_id", label: "Section", type: getFieldType(2).name, is_required: true, project_scope: { scope: "global" } },
+    { system_name: "template_id", label: "Template", type: getFieldType(2).name, is_required: false, project_scope: { scope: "global" } },
+    { system_name: "type_id", label: "Type", type: getFieldType(2).name, is_required: false, project_scope: { scope: "global" } },
+    { system_name: "priority_id", label: "Priority", type: getFieldType(2).name, is_required: false, project_scope: { scope: "global" } },
+    { system_name: "estimate", label: "Estimate", type: getFieldType(1).name, is_required: false, project_scope: { scope: "global" } },
+    { system_name: "milestone_id", label: "Milestone", type: getFieldType(2).name, is_required: false, project_scope: { scope: "global" } },
+    { system_name: "refs", label: "References", type: getFieldType(1).name, is_required: false, project_scope: { scope: "global" } },
+    { system_name: "labels", label: "Labels", type: getFieldType(14).name, is_required: false, project_scope: { scope: "global" }, description: "Use get_labels tool to get available labels/tags." },
 ];
 const description = `
 Get the field schema for test cases for a specific project.

package/dist/tools/cases/get_cases.js

@@ -1,8 +1,9 @@
 import { z } from "zod";
 import fs from "fs";
-import { validateCaseFields } from "../../utils/validator.js";
+import { validateCaseFields, validateSuiteId } from "../../utils/validator.js";
 const parameters = {
     project_id: z.number().describe("The ID of the project. Use get_projects to find available projects"),
+    suite_id: z.number().optional().describe("The ID of the test suite (required for multi-suite projects, i.e. suite_mode=3). Use get_suites to find available suites"),
     section: z.object({
         id: z.number(),
         recursive: z.boolean().optional().default(false).describe("If true, fetches cases from the section and all its child sections"),
@@ -18,7 +19,8 @@ export const getCasesTool = {
     mode: "read",
     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, output_file }, client) => {
+    handler: async ({ project_id, suite_id, section, filter, where, fields, output_file }, client) => {
+        await validateSuiteId(client, project_id, suite_id);
         const caseFields = await client.getCaseFields();
         if (fields) {
             validateCaseFields(fields, caseFields);
@@ -26,6 +28,10 @@ export const getCasesTool = {
         if (where) {
             validateCaseFields(Object.keys(where), caseFields);
         }
+        // Inject suite_id into filter for multi-suite projects
+        if (suite_id) {
+            filter = { ...filter, suite_id: suite_id.toString() };
+        }
         let cases;
         if (section?.recursive) {
             cases = await client.getCasesRecursively(project_id, section.id, filter, section.excludes);

package/dist/tools/sections/get_sections.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
 import fs from "fs";
 import { SectionSchema } from "./types.js";
+import { validateSuiteId } from "../../utils/validator.js";
 const parameters = {
     project_id: z.number().describe("The ID of the project. Use get_projects to find available projects"),
+    suite_id: z.number().optional().describe("The ID of the test suite (required for multi-suite projects, i.e. suite_mode=3). Use get_suites to find available suites"),
     output_file: z.string().optional().describe("Absolute file path to save the JSON response to. Use this for large datasets to avoid blowing up context limits."),
 };
 export const getSectionsTool = {
@@ -10,8 +12,9 @@ export const getSectionsTool = {
     mode: "read",
     description: "Get all sections for a project. Returns section IDs and names that can be used with add_case",
     parameters,
-    handler: async ({ project_id, output_file }, client) => {
-        const sections = await client.getSections(project_id);
+    handler: async ({ project_id, suite_id, output_file }, client) => {
+        await validateSuiteId(client, project_id, suite_id);
+        const sections = await client.getSections(project_id, suite_id);
         const response = {
             sections: sections.map(s => SectionSchema.parse(s)),
         };

package/dist/tools/sections/mutate_section.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { SectionSchema, CreateSectionSchema, UpdateSectionSchema } from "./types.js";
 import { handleMutate } from "../../utils/mutate_handler.js";
+import { validateSuiteId } from "../../utils/validator.js";
 const parameters = {
     payload: z.discriminatedUnion("action", [
         CreateSectionSchema,
@@ -15,6 +16,7 @@ export const mutateSectionTool = {
     handler: async (args, client) => {
         const { payload } = args;
         return handleMutate(payload, async (createPayload) => {
+            await validateSuiteId(client, createPayload.project_id, createPayload.suite_id);
             const { project_id, action, ...data } = createPayload;
             return client.addSection(project_id, data);
         }, async (updatePayload) => {

package/dist/tools/sections/types.js

@@ -13,6 +13,7 @@ export const BaseSectionFields = z.object({
 export const CreateSectionSchema = BaseSectionFields.extend({
     action: z.literal("create").describe("The operation to perform: create a new section"),
     project_id: z.number().describe("The ID of the project the section should be added to"),
+    suite_id: z.number().optional().describe("The ID of the test suite (required for multi-suite projects, i.e. suite_mode=2 or 3). Use get_suites to find available suites"),
     parent_id: z.number().optional().describe("The ID of the parent section (to build section hierarchies)"),
 });
 export const UpdateSectionSchema = BaseSectionFields.partial().extend({

package/dist/utils/validator.js

@@ -1,5 +1,20 @@
 import { SYSTEM_FIELDS, mapToFieldSchema } from "../tools/cases/get_case_fields.js";
 import { isActive } from "./sanitizer.js";
+const SUITE_MODE_SINGLE_WITH_BASELINES = 2;
+const SUITE_MODE_MULTI = 3;
+/**
+ * Validates that suite_id is provided when the project uses multiple test suites or baselines (suite_mode=2 or 3).
+ * Throws a descriptive Error if suite_id is required but missing.
+ */
+export async function validateSuiteId(client, projectId, suiteId) {
+    if (suiteId)
+        return;
+    const project = await client.getProject(projectId);
+    if (project.suite_mode === SUITE_MODE_MULTI || project.suite_mode === SUITE_MODE_SINGLE_WITH_BASELINES) {
+        throw new Error(`Project "${project.name}" (id: ${project.id}) uses multiple test suites/baselines (suite_mode=${project.suite_mode}). ` +
+            `The suite_id parameter is required. Use get_suites to find available suites for this project.`);
+    }
+}
 /**
  * Validates that the provided fields exist in the TestRail case schema.
  * Throws an Error if any field is invalid.

package/package.json

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