@uarlouski/testrail-mcp-server 2.7.0 → 2.8.0

package/README.md

@@ -151,7 +151,7 @@ Once configured, turbo-charge your QA workflow by asking your AI assistant:
 | `TESTRAIL_API_KEY` | Your TestRail API key ([Guide](https://support.testrail.com/hc/en-us/articles/7077039051412-Accessing-the-TestRail-API)) | ✅ | |
 | `TESTRAIL_ENABLE_SHARED_STEPS` | Set to `true` to enable Shared Steps management tools | | `false` |
 | `TESTRAIL_ENABLE_CASE_HISTORY` | Set to `true` to enable Case History and revision tracking tools | | `false` |
-| `TESTRAIL_ENABLE_RAG_TOOLS` | Set to `true` to enable Knowledge Base / RAG export tools (`export_cases_for_rag`) | | `false` |
+| `TESTRAIL_ENABLE_RAG_TOOLS` | Set to `true` to enable experimental Knowledge Base / RAG export tools (`export_cases_for_rag`). Subject to breaking API changes. | | `false` |
 | `TESTRAIL_ALLOW_WRITE_OPERATIONS` | Allow write operations (e.g. adding/updating test cases, test runs, sections) | | `true` |
 | `TESTRAIL_ALLOW_READ_OPERATIONS` | Allow read operations (e.g. retrieving projects, test cases, templates) | | `true` |
 | `TESTRAIL_ALLOW_DELETE_OPERATIONS` | Allow delete operations (e.g. deleting cases or shared steps). Enabled strictly via `true`. | | `false` |

package/dist/index.js

@@ -27,7 +27,7 @@ if (!parseResult.success) {
 const { TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY, TESTRAIL_ENABLE_SHARED_STEPS, TESTRAIL_ENABLE_CASE_HISTORY, TESTRAIL_ENABLE_RAG_TOOLS, TESTRAIL_ALLOW_WRITE_OPERATIONS, TESTRAIL_ALLOW_READ_OPERATIONS, TESTRAIL_ALLOW_DELETE_OPERATIONS, TESTRAIL_ENABLE_DEPRECATED_TOOLS, TESTRAIL_DISABLED_TOOLS } = parseResult.data;
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "2.7.0",
+    version: "2.8.0",
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
 let tools;

package/dist/tools/cases/export_cases_for_rag.js

@@ -2,12 +2,18 @@ import { z } from "zod";
 import * as fs from "fs";
 import * as path from "path";
 import { normalizeEntityId, sanitizeValue } from "../../utils/sanitizer.js";
-import { processCustomFields } from "../../utils/mapper.js";
+import { resolveCustomFieldValue } from "../../utils/mapper.js";
 import { getBaseDirectory } from "../../utils/fs.js";
 import { CaseFieldTypeId, getFieldType } from "./fields.js";
+import { fetchFilteredCases } from "./get_cases.js";
 const parameters = {
-    case_ids: z.array(z.union([z.string(), z.number()])).min(1).describe("List of test case IDs (e.g. ['C123', 456])"),
+    case_ids: z.array(z.union([z.string(), z.number()])).optional().describe("List of test case IDs (e.g. ['C123', 456]). Provide either case_ids OR project_id."),
+    project_id: z.number().optional().describe("The ID of the project to export cases from. Required if case_ids is not provided."),
+    suite_id: z.number().optional().describe("The ID of the test suite (required for multi-suite projects, i.e. suite_mode=2 or 3)."),
+    filter: z.record(z.string(), z.string()).optional().describe("Optional API-side filters (e.g. priority_id, type_id, milestone_id, refs, created_after, etc.)."),
+    where: z.record(z.string(), z.any()).optional().describe("Optional client-side filter for any field including custom fields (filters after fetching cases). Supports exact value matching. Example: {\"custom_automation_status\": 1}"),
     output_dir: z.string().optional().describe("Directory to save exported files. Defaults to an auto-generated directory in the current working directory."),
+    ignored_fields: z.array(z.string()).optional().describe("Optional list of custom field names or system names to ignore/exclude from export (e.g. ['custom_review_status', 'review_status']). Supports both full system_name and stripped field names. Core metadata attributes (case_id, title, section, priority, references, labels) cannot be ignored."),
 };
 function formatStepsSeparated(steps) {
     return steps.map((step, idx) => {
@@ -41,8 +47,16 @@ function isMarkdownField(fieldDef, value) {
     return typeof value === "string" && value.includes("\n");
 }
 function sanitizeMetadataValue(val) {
+    if (typeof val === "boolean") {
+        return String(val);
+    }
     if (Array.isArray(val)) {
-        return val.map(item => (item !== null && typeof item === "object") ? (item.title || item.name || item.label || JSON.stringify(item)) : item);
+        return val.map(item => {
+            if (item !== null && typeof item === "object") {
+                return item.title || item.name || item.label || JSON.stringify(item);
+            }
+            return String(item);
+        });
     }
     return val;
 }
@@ -51,47 +65,41 @@ const IGNORED_METADATA_FIELDS = new Set([
     "updated_by",
     "display_order",
     "is_deleted",
-    "review_status",
-    "reviewer",
 ]);
 function buildFieldDefinitionMap(caseFields) {
     const fieldDefMap = new Map();
     for (const cf of caseFields) {
         fieldDefMap.set(cf.system_name, cf);
-        if (cf.name) {
-            fieldDefMap.set(cf.name, cf);
-        }
-        const clean = cf.system_name.replace(/^custom_/, "");
-        fieldDefMap.set(clean, cf);
-        if (cf.label) {
-            fieldDefMap.set(cf.label, cf);
-            const snakeLabel = cf.label.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '');
-            fieldDefMap.set(snakeLabel, cf);
-        }
     }
     return fieldDefMap;
 }
-function categorizeCustomFields(customFields, fieldDefMap) {
+function categorizeCustomFields(testCase, applicableFieldDefs, ignoredFieldsSet) {
     const markdownFields = [];
     const metadataFields = [];
-    const seenKeys = new Set();
-    for (const [key, val] of Object.entries(customFields)) {
-        const cleanKey = key.replace(/^custom_/, "");
-        if (seenKeys.has(cleanKey) || seenKeys.has(key) || IGNORED_METADATA_FIELDS.has(cleanKey) || IGNORED_METADATA_FIELDS.has(key)) {
+    const fieldDefMap = buildFieldDefinitionMap(applicableFieldDefs);
+    for (const [systemName, rawValue] of Object.entries(testCase)) {
+        if (!systemName.startsWith("custom_")) {
+            continue;
+        }
+        if (rawValue === null || rawValue === undefined || rawValue === "" || (Array.isArray(rawValue) && rawValue.length === 0)) {
             continue;
         }
-        if (val === null || val === undefined || val === "" || (Array.isArray(val) && val.length === 0)) {
+        const strippedName = systemName.replace(/^custom_/, "");
+        if (ignoredFieldsSet.has(systemName) || ignoredFieldsSet.has(strippedName)) {
             continue;
         }
-        seenKeys.add(cleanKey);
-        seenKeys.add(key);
-        const fieldDef = fieldDefMap.get(key) || fieldDefMap.get(cleanKey) || fieldDefMap.get(`custom_${cleanKey}`);
+        const fieldDef = fieldDefMap.get(systemName);
+        if (!fieldDef) {
+            continue;
+        }
+        const val = resolveCustomFieldValue(fieldDef, rawValue);
         if (isMarkdownField(fieldDef, val)) {
-            const header = fieldDef?.label || cleanKey.replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase());
+            const header = fieldDef.label || systemName.replace(/^custom_/, "");
             markdownFields.push({ header, value: val, fieldDef });
         }
         else {
-            metadataFields.push({ key: cleanKey, value: val, fieldDef });
+            const metaKey = fieldDef.name || systemName.replace(/^custom_/, "");
+            metadataFields.push({ key: metaKey, value: val, fieldDef });
         }
     }
     return { markdownFields, metadataFields };
@@ -141,25 +149,55 @@ function buildMetadataAttributes(testCase, sectionName, priority, metadataFields
 export const exportCasesForRagTool = {
     name: "export_cases_for_rag",
     mode: "read",
-    description: "Export test cases as formatted Markdown documents with companion JSON metadata sidecar files for Knowledge Base and RAG ingestion.",
+    description: "Export test cases as formatted Markdown documents with companion JSON metadata sidecar files for Knowledge Base and RAG ingestion. Provide either 'case_ids' to export specific cases, or 'project_id' (with optional 'suite_id', 'filter', 'where') to query and export cases from TestRail. If exporting more than 25 cases, batch them into chunks of ~25 and execute in parallel with a shared output_dir to prevent tool call timeouts.",
     parameters,
-    handler: async ({ case_ids, output_dir }, client) => {
+    handler: async ({ case_ids, project_id, suite_id, filter, where, output_dir, ignored_fields }, client) => {
+        if ((!case_ids || case_ids.length === 0) && project_id === undefined) {
+            throw new Error("Either 'case_ids' or 'project_id' must be provided.");
+        }
+        const [priorities, caseFields] = await Promise.all([
+            client.getPriorities().catch(() => []),
+            client.getCaseFields().catch(() => []),
+        ]);
+        let testCases = [];
+        if (case_ids && case_ids.length > 0) {
+            for (const rawId of case_ids) {
+                const id = normalizeEntityId(rawId);
+                const testCase = await client.getCase(id);
+                testCases.push(testCase);
+            }
+        }
+        else if (project_id !== undefined) {
+            testCases = await fetchFilteredCases(client, {
+                project_id,
+                suite_id,
+                filter,
+                where,
+                caseFields,
+            });
+        }
         const baseDir = getBaseDirectory();
         const targetDir = output_dir
             ? (path.isAbsolute(output_dir) ? output_dir : path.resolve(baseDir, output_dir))
             : path.resolve(baseDir, `rag_export_${Date.now()}`);
         await fs.promises.mkdir(targetDir, { recursive: true });
-        const [priorities, caseFields] = await Promise.all([
-            client.getPriorities().catch(() => []),
-            client.getCaseFields().catch(() => []),
-        ]);
+        const ignoredFieldsSet = new Set(IGNORED_METADATA_FIELDS);
+        if (ignored_fields) {
+            for (const field of ignored_fields) {
+                ignoredFieldsSet.add(field);
+                if (field.startsWith("custom_")) {
+                    ignoredFieldsSet.add(field.replace(/^custom_/, ""));
+                }
+                else {
+                    ignoredFieldsSet.add(`custom_${field}`);
+                }
+            }
+        }
         const writtenFiles = [];
-        for (const rawId of case_ids) {
-            const id = normalizeEntityId(rawId);
-            const testCase = await client.getCase(id);
+        for (const testCase of testCases) {
             let sectionName = "Unknown";
             if (testCase.section_id) {
-                const section = await client.getSection(Number(testCase.section_id));
+                const section = await client.getSection(Number(testCase.section_id)).catch(() => null);
                 if (section?.name) {
                     sectionName = section.name;
                 }
@@ -167,9 +205,7 @@ export const exportCasesForRagTool = {
             const priority = priorities.find(p => p.id === testCase.priority_id)?.name || "Unknown";
             const templateId = testCase.template_id;
             const applicableFields = caseFields.filter(field => field.include_all || (templateId !== null && templateId !== undefined && field.template_ids.includes(templateId)));
-            const fieldDefMap = buildFieldDefinitionMap(applicableFields);
-            const customFields = processCustomFields(testCase, caseFields);
-            const { markdownFields, metadataFields } = categorizeCustomFields(customFields, fieldDefMap);
+            const { markdownFields, metadataFields } = categorizeCustomFields(testCase, applicableFields, ignoredFieldsSet);
             const markdownContent = buildMarkdownBody(testCase, sectionName, markdownFields);
             const metadataAttributes = buildMetadataAttributes(testCase, sectionName, priority, metadataFields);
             const docFilename = `C${testCase.id}.md`;
@@ -180,10 +216,10 @@ export const exportCasesForRagTool = {
         }
         return {
             success: true,
-            exported_count: case_ids.length,
+            exported_count: testCases.length,
             output_dir: targetDir,
             files: writtenFiles,
-            message: `Successfully exported ${case_ids.length} test case(s) for Knowledge Base ingestion.`,
+            message: `Successfully exported ${testCases.length} test case(s) for Knowledge Base ingestion.`,
         };
     },
 };

package/dist/tools/cases/get_cases.js

@@ -14,43 +14,57 @@ const parameters = {
     fields: z.array(z.string()).optional().describe("Additional fields to include in response beyond id, title, and suite_id. Use get_case_fields to see available fields. Example: [\"priority_id\", \"type_id\", \"custom_automation_status\"]"),
     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 async function fetchFilteredCases(client, options) {
+    const { project_id, suite_id, section, where } = options;
+    let filter = options.filter;
+    await validateSuiteId(client, project_id, suite_id);
+    const caseFields = options.caseFields ?? (await client.getCaseFields());
+    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);
+    }
+    else {
+        cases = await client.getCases(project_id, section?.id, filter);
+    }
+    // Client-side filtering for custom fields and other unsupported API filters
+    if (where) {
+        cases = cases.filter(c => {
+            for (const [key, value] of Object.entries(where)) {
+                const caseValue = c[key];
+                if (caseValue !== value) {
+                    return false;
+                }
+            }
+            return true;
+        });
+    }
+    return cases;
+}
 export const getCasesTool = {
     name: "get_cases",
     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, 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);
         }
-        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);
-        }
-        else {
-            cases = await client.getCases(project_id, section?.id, filter);
-        }
-        // Client-side filtering for custom fields and other unsupported API filters
-        if (where) {
-            cases = cases.filter(c => {
-                for (const [key, value] of Object.entries(where)) {
-                    const caseValue = c[key];
-                    if (caseValue !== value) {
-                        return false;
-                    }
-                }
-                return true;
-            });
-        }
+        const cases = await fetchFilteredCases(client, {
+            project_id,
+            suite_id,
+            section,
+            filter,
+            where,
+            caseFields,
+        });
         const response = {
             cases: cases.map(c => {
                 const result = {

package/dist/tools/sections/get_sections.js

@@ -7,10 +7,14 @@ const parameters = {
     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."),
 };
+/**
+ * @deprecated Use `query_section` with payload.action = 'many' instead.
+ */
 export const getSectionsTool = {
     name: "get_sections",
     mode: "read",
-    description: "Get all sections for a project. Returns section IDs and names that can be used with add_case",
+    deprecated: true,
+    description: "Get all sections for a project. (Deprecated: Prefer query_section tool). Returns section IDs and names that can be used with add_case",
     parameters,
     handler: async ({ project_id, suite_id, output_file }, client) => {
         await validateSuiteId(client, project_id, suite_id);

package/dist/tools/sections/index.js

@@ -1,6 +1,9 @@
 import { getSectionsTool } from "./get_sections.js";
+import { querySectionTool } from "./query_section.js";
 import { mutateSectionTool } from "./mutate_section.js";
 export const sectionsTools = [
+    querySectionTool,
     getSectionsTool,
     mutateSectionTool,
 ];
+export { getSectionsTool, querySectionTool, mutateSectionTool };

package/dist/tools/sections/query_section.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import fs from "fs";
+import { SectionSchema, GetOneSectionSchema, GetManySectionsSchema } from "./types.js";
+import { handleQuery } from "../../utils/query_handler.js";
+import { validateSuiteId } from "../../utils/validator.js";
+const parameters = {
+    payload: z.discriminatedUnion("action", [
+        GetOneSectionSchema,
+        GetManySectionsSchema,
+    ]).describe("The payload containing the action ('one' or 'many') and corresponding parameters"),
+};
+export function buildSectionTree(parent, allSections) {
+    const children = allSections.filter(s => s.parent_id === parent.id);
+    return {
+        ...SectionSchema.parse(parent),
+        children: children.map(child => buildSectionTree(child, allSections)),
+    };
+}
+export const querySectionTool = {
+    name: "query_section",
+    mode: "read",
+    description: "Retrieve a single section or all sections for a project in TestRail. Set payload.action to 'one' or 'many' to specify the operation.",
+    parameters,
+    handler: async (args, client) => {
+        return handleQuery(args.payload, async (p) => {
+            if (p.include_child) {
+                if (!p.project_id) {
+                    throw new Error("project_id is required when include_child is true to resolve child sections");
+                }
+                await validateSuiteId(client, p.project_id, p.suite_id);
+                const allSections = await client.getSections(p.project_id, p.suite_id);
+                let targetSection = allSections.find(s => s.id === p.section_id);
+                if (!targetSection) {
+                    targetSection = await client.getSection(p.section_id);
+                }
+                return {
+                    section: buildSectionTree(targetSection, allSections),
+                };
+            }
+            const section = await client.getSection(p.section_id);
+            return {
+                section: SectionSchema.parse(section),
+            };
+        }, async (p) => {
+            await validateSuiteId(client, p.project_id, p.suite_id);
+            let sections = await client.getSections(p.project_id, p.suite_id);
+            if (p.name_pattern) {
+                try {
+                    const regex = new RegExp(p.name_pattern, "i");
+                    sections = sections.filter(s => regex.test(s.name));
+                }
+                catch (err) {
+                    throw new Error(`Invalid regex pattern provided for name_pattern: '${p.name_pattern}'`);
+                }
+            }
+            const response = {
+                sections: sections.map(s => SectionSchema.parse(s)),
+            };
+            if (p.output_file) {
+                await fs.promises.writeFile(p.output_file, JSON.stringify(response), "utf-8");
+                return {
+                    success: true,
+                    message: `Successfully exported ${response.sections.length} sections to ${p.output_file}`,
+                    file: p.output_file,
+                };
+            }
+            return response;
+        });
+    }
+};

package/dist/tools/sections/types.js

@@ -20,3 +20,17 @@ export const UpdateSectionSchema = BaseSectionFields.partial().extend({
     action: z.literal("update").describe("The operation to perform: update an existing section"),
     section_id: z.number().describe("The ID of the section to update"),
 });
+export const GetOneSectionSchema = z.object({
+    action: z.literal("one").describe("Retrieve a single section by ID"),
+    section_id: z.number().int().describe("The ID of the section"),
+    project_id: z.number().int().optional().describe("The ID of the project (required when include_child is true to fetch child sections)"),
+    suite_id: z.number().int().optional().describe("The ID of the test suite (for multi-suite projects). Use query_suite to find available suites"),
+    include_child: z.boolean().optional().default(false).describe("Whether to include child/descendant sections in the response as a nested tree. Defaults to false"),
+});
+export const GetManySectionsSchema = z.object({
+    action: z.literal("many").describe("Retrieve all sections for a project"),
+    project_id: z.number().int().describe("The ID of the project. Use query_project to find available projects"),
+    suite_id: z.number().int().optional().describe("The ID of the test suite (required for multi-suite projects, i.e. suite_mode=2 or 3). Use query_suite to find available suites"),
+    name_pattern: z.string().optional().describe("Optional regex pattern to filter sections by name (e.g. 'auth.*' or 'login|signup'). Case-insensitive."),
+    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."),
+});

package/dist/utils/mapper.js

@@ -31,31 +31,41 @@ export function processCustomFields(testCase, caseFields) {
             continue;
         }
         const outputKey = fieldNameMap.get(key);
-        let finalValue = value;
-        if (dropdownOptionsMap.has(key)) {
-            const options = dropdownOptionsMap.get(key);
-            const field = applicableFields.find(f => f.system_name === key);
-            if (Array.isArray(value)) {
-                finalValue = value.map(v => options.get(String(v)) || v);
-            }
-            else if (field?.type_id === CaseFieldTypeId.MultiSelect) {
-                const resolved = options.get(String(value)) || value;
-                finalValue = [resolved];
-            }
-            else {
-                const optionKey = String(value);
-                finalValue = options.get(optionKey) || value;
-            }
+        const field = applicableFields.find(f => f.system_name === key);
+        const options = dropdownOptionsMap.get(key);
+        result[outputKey] = resolveCustomFieldValue(field, value, options);
+    }
+    return result;
+}
+/**
+ * Resolves a custom field value against its field definition:
+ * - Maps dropdown option IDs to their display labels
+ * - Normalizes multi-select values into arrays
+ * - Sanitizes HTML formatting in strings
+ */
+export function resolveCustomFieldValue(field, value, optionsMap) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const options = optionsMap ?? parseDropdownOptions(field);
+    let finalValue = value;
+    if (options.size > 0) {
+        if (Array.isArray(value)) {
+            finalValue = value.map(v => options.get(String(v)) || v);
+        }
+        else if (field.type_id === CaseFieldTypeId.MultiSelect) {
+            const resolved = options.get(String(value)) || value;
+            finalValue = [resolved];
         }
         else {
-            const field = applicableFields.find(f => f.system_name === key);
-            if (field?.type_id === CaseFieldTypeId.MultiSelect) {
-                finalValue = Array.isArray(value) ? value : [value];
-            }
+            const optionKey = String(value);
+            finalValue = options.get(optionKey) || value;
         }
-        result[outputKey] = sanitizeValue(finalValue);
     }
-    return result;
+    else if (field.type_id === CaseFieldTypeId.MultiSelect) {
+        finalValue = Array.isArray(value) ? value : [value];
+    }
+    return sanitizeValue(finalValue);
 }
 /**
  * Parse dropdown options from field configs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "2.7.0",
+  "version": "2.8.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",