@uarlouski/testrail-mcp-server 1.1.0

package/src/tools/create_case.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { TestRailClient } from "../client/testrail.js";
+import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+
+const parameters = {
+    section_id: z.string().describe("The ID of the section where the case should be created"),
+    title: z.string().describe("The title of the test case (required)"),
+    fields: z.record(z.string(), z.any()).optional().describe("Optional object containing additional fields. Use get_case_fields to see available fields. Example: {\"priority_id\": 2, \"template_id\": 1, \"custom_automation_priority\": 1}"),
+};
+
+export const createCaseTool: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "create_case",
+    description: "Create a new test case in TestRail. IMPORTANT: Before creating a case, first call get_templates to discover available templates for the project, then use get_case_fields to see which fields are available for the chosen template. Requires section_id and title.",
+    parameters,
+    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ section_id, title, fields }, client) => {
+        const caseData = {
+            title,
+            ...fields,
+        };
+
+        const createdCase = await client.createCase(section_id, caseData);
+
+        return {
+            content: [
+                {
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        success: true,
+                        case_id: createdCase.id,
+                        message: `Test case C${createdCase.id} created successfully`,
+                    }, null, 2),
+                },
+            ],
+        };
+    })
+};

package/src/tools/get_case.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { processCustomFields } from "../utils/mapper.js";
+import { TestRailClient } from "../client/testrail.js";
+import { TestCaseResponse, ToolDefinition, withErrorHandling } from "../types/custom.js";
+
+const parameters = {
+    case_id: z.string().describe("The ID of the test case (e.g. '123' or 'C123')"),
+};
+
+export const getCaseTool: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "get_case",
+    description: "Get a test case from TestRail by ID",
+    parameters,
+    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ case_id }, client) => {
+        const id = case_id.toUpperCase().startsWith("C") ? case_id.substring(1) : case_id;
+        const testCase = await client.getCase(id);
+
+        const [section, caseTypes, priorities, caseFields] = await Promise.all([
+            client.getSection(testCase.section_id.toString()),
+            client.getCaseTypes(),
+            client.getPriorities(),
+            client.getCaseFields()
+        ]);
+
+        const caseType = caseTypes.find(t => t.id === testCase.type_id);
+        const priority = priorities.find(p => p.id === testCase.priority_id);
+
+        const customFields = processCustomFields(testCase, caseFields);
+
+        const response: TestCaseResponse = {
+            id: testCase.id,
+            title: testCase.title,
+            section: section.name,
+            type: caseType ? caseType.name : "Unknown",
+            priority: priority ? priority.name : "Unknown",
+            labels: testCase.labels || [],
+            references: testCase.refs,
+            updated_on: testCase.updated_on,
+            ...customFields
+        };
+
+        return {
+            content: [
+                {
+                    type: "text" as const,
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    })
+};

package/src/tools/get_case_fields.ts

@@ -0,0 +1,97 @@
+import { TestRailClient } from "../client/testrail.js";
+import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+import { CaseField } from "../types/testrail.js";
+import { parseDropdownOptions } from "../utils/mapper.js";
+
+const parameters = {};
+
+interface FieldSchema {
+    system_name: string;
+    label: string;
+    type: string;
+    is_required: boolean;
+    template_ids?: number[];
+    options?: string[];
+}
+
+interface CaseFieldsResponse {
+    fields: FieldSchema[];
+}
+
+const FIELD_TYPE_NAMES: Record<number, string> = {
+    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",
+};
+
+function getFieldTypeName(typeId: number): string {
+    return FIELD_TYPE_NAMES[typeId] || `Unknown (${typeId})`;
+}
+
+function isFieldRequired(field: CaseField): boolean {
+    return field.configs.some(config => config.options?.is_required === true);
+}
+
+function mapToFieldSchema(field: CaseField): FieldSchema {
+    const schema: FieldSchema = {
+        system_name: field.system_name,
+        label: field.label,
+        type: getFieldTypeName(field.type_id),
+        is_required: isFieldRequired(field),
+    };
+
+    if (!field.include_all && field.template_ids.length > 0) {
+        schema.template_ids = field.template_ids;
+    }
+
+    if (field.type_id === 6 || field.type_id === 12) {
+        schema.options = Array.from(parseDropdownOptions(field).values());
+    }
+
+    return schema;
+}
+
+const SYSTEM_FIELDS: FieldSchema[] = [
+    { 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 },
+    { system_name: "type_id", label: "Type", type: "Integer", is_required: false },
+    { system_name: "priority_id", label: "Priority", type: "Integer", is_required: false },
+    { system_name: "estimate", label: "Estimate", type: "String", is_required: false },
+    { system_name: "milestone_id", label: "Milestone", type: "Integer", is_required: false },
+    { system_name: "refs", label: "References", type: "String", is_required: false },
+];
+
+export const getCaseFieldsTool: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "get_case_fields",
+    description: "Get the field schema for test cases. Returns all available fields with their types, descriptions, and options (for dropdown fields). Use this to understand what fields can be set when creating or updating test cases.",
+    parameters,
+    handler: withErrorHandling<typeof parameters, TestRailClient>(async (_args, client) => {
+        const caseFields = await client.getCaseFields();
+
+        const customFieldSchemas = caseFields.filter(field => field.is_active).map(mapToFieldSchema);
+
+        const response: CaseFieldsResponse = {
+            fields: [...SYSTEM_FIELDS, ...customFieldSchemas],
+        };
+
+        return {
+            content: [
+                {
+                    type: "text" as const,
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    })
+};

package/src/tools/get_cases.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { TestRailClient } from "../client/testrail.js";
+import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+import { Case } from "../types/testrail.js";
+
+const parameters = {
+    project_id: z.string().describe("The ID of the project"),
+    section_id: z.string().optional().describe("Optional section ID to filter cases by section"),
+    filter: z.record(z.string(), z.string()).optional().describe("Optional API filter parameters. Supported filters: priority_id (comma-separated IDs), type_id (comma-separated IDs), created_by (comma-separated user IDs), updated_by, milestone_id, refs, created_after, created_before, updated_after, updated_before. Example: {\"priority_id\": \"1,2\", \"type_id\": \"3\"}"),
+    where: z.record(z.string(), z.any()).optional().describe("Optional client-side filter for any field including custom fields. Cases are filtered after fetching. Supports exact match for values. Example: {\"custom_automation_status\": 1, \"priority_id\": 2}"),
+    fields: z.array(z.string()).optional().describe("Optional list of additional fields to include in the response. Use get_case_fields to see available field names. Example: [\"priority_id\", \"type_id\", \"custom_automation_status\"]"),
+};
+
+interface CasesResponse {
+    cases: Record<string, any>[];
+}
+
+export const getCasesTool: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "get_cases",
+    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: withErrorHandling<typeof parameters, TestRailClient>(async ({ project_id, section_id, filter, where, fields }, client) => {
+        let cases: Case[] = 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 as Record<string, any>)[key];
+                    if (caseValue !== value) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+        }
+
+        const response: CasesResponse = {
+            cases: cases.map(c => {
+                const result: Record<string, any> = {
+                    id: c.id,
+                    title: c.title,
+                    suite_id: c.suite_id,
+                };
+
+                if (fields) {
+                    for (const field of fields) {
+                        if (field in c) {
+                            result[field] = c[field];
+                        }
+                    }
+                }
+
+                return result;
+            }),
+        };
+
+        return {
+            content: [
+                {
+                    type: "text" as const,
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    })
+};

package/src/tools/get_projects.ts

@@ -0,0 +1,40 @@
+import { TestRailClient } from "../client/testrail.js";
+import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+
+const parameters = {};
+
+interface ProjectSchema {
+    id: number;
+    name: string;
+}
+
+interface ProjectsResponse {
+    projects: ProjectSchema[];
+}
+
+export const getProjectsTool: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "get_projects",
+    description: "Get all available projects in TestRail. Returns project IDs and names. Use this to find the project_id needed for get_sections and get_templates.",
+    parameters,
+    handler: withErrorHandling<typeof parameters, TestRailClient>(async (_args, client) => {
+        const projects = await client.getProjects();
+
+        const response: ProjectsResponse = {
+            projects: projects
+                .filter(p => !p.is_completed)
+                .map(p => ({
+                    id: p.id,
+                    name: p.name,
+                })),
+        };
+
+        return {
+            content: [
+                {
+                    type: "text" as const,
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    })
+};

package/src/tools/get_sections.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { TestRailClient } from "../client/testrail.js";
+import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+
+const parameters = {
+    project_id: z.string().describe("The ID of the project"),
+};
+
+interface SectionSchema {
+    id: number;
+    name: string;
+}
+
+interface SectionsResponse {
+    sections: SectionSchema[];
+}
+
+export const getSectionsTool: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "get_sections",
+    description: "Get all sections for a project. Returns section IDs and names. Use this to find the section_id needed for create_case.",
+    parameters,
+    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ project_id }, client) => {
+        const sections = await client.getSections(project_id);
+
+        const response: SectionsResponse = {
+            sections: sections.map(s => ({
+                id: s.id,
+                name: s.name,
+            })),
+        };
+
+        return {
+            content: [
+                {
+                    type: "text" as const,
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    })
+};

package/src/tools/get_templates.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { TestRailClient } from "../client/testrail.js";
+import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+
+const parameters = {
+    project_id: z.string().describe("The ID of the project"),
+};
+
+interface TemplateSchema {
+    id: number;
+    name: string;
+}
+
+interface TemplatesResponse {
+    templates: TemplateSchema[];
+}
+
+export const getTemplatesTool: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "get_templates",
+    description: "Get available test case templates for a project. Returns template IDs and names. Use template IDs with get_case_fields to understand which fields apply to each template.",
+    parameters,
+    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ project_id }, client) => {
+        const templates = await client.getTemplates(project_id);
+
+        const response: TemplatesResponse = {
+            templates: templates.map(t => ({
+                id: t.id,
+                name: t.name,
+            })),
+        };
+
+        return {
+            content: [
+                {
+                    type: "text" as const,
+                    text: JSON.stringify(response, null, 2),
+                },
+            ],
+        };
+    })
+};

package/src/tools/update_case.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { TestRailClient } from "../client/testrail.js";
+import { ToolDefinition, withErrorHandling } from "../types/custom.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}"),
+};
+
+export const updateCaseTool: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "update_case",
+    description: "Update a test case in TestRail. Supports partial updates - only specify the fields you want to change. Use get_case_fields to see available fields and their types.",
+    parameters,
+    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ case_id, fields }, client) => {
+        const id = case_id.toUpperCase().startsWith("C") ? case_id.substring(1) : case_id;
+
+        const updatedCase = await client.updateCase(id, fields);
+
+        return {
+            content: [
+                {
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        success: true,
+                        case_id: updatedCase.id,
+                        message: `Test case C${updatedCase.id} updated successfully`,
+                    }, null, 2),
+                },
+            ],
+        };
+    })
+};

package/src/tools/update_cases.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { TestRailClient } from "../client/testrail.js";
+import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+
+const parameters = {
+    case_ids: z.array(z.number()).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: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "update_cases",
+    description: "Bulk update multiple test cases with the same field values. More efficient than calling update_case multiple times. All cases will receive the same field values.",
+    parameters,
+    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ case_ids, fields }, client) => {
+        const updatedCases = await client.updateCases(case_ids, fields);
+
+        return {
+            content: [
+                {
+                    type: "text" as const,
+                    text: JSON.stringify({
+                        success: true,
+                        updated_count: updatedCases.length,
+                        case_ids: updatedCases.map(c => c.id),
+                        message: `Successfully updated ${updatedCases.length} test cases`,
+                    }, null, 2),
+                },
+            ],
+        };
+    })
+};

package/src/types/custom.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+
+export interface TestCaseResponse {
+    id: number;
+    title: string;
+    section: string;
+    type: string;
+    priority: string;
+    labels: string[];
+    references: string | null;
+    [key: string]: any;
+}
+
+export interface ToolDefinition<T extends z.ZodRawShape, Context = any> {
+    name: string;
+    description: string;
+    parameters: T;
+    handler: (args: z.infer<z.ZodObject<T>>, context: Context) => Promise<any>;
+}
+
+export function withErrorHandling<T extends z.ZodRawShape, Context = any>(
+    handler: (args: z.infer<z.ZodObject<T>>, context: Context) => Promise<any>
+): (args: z.infer<z.ZodObject<T>>, context: Context) => Promise<any> {
+    return async (args, context) => {
+        try {
+            return await handler(args, context);
+        } catch (error: any) {
+            return {
+                content: [{ type: "text", text: `Error: ${error.message}` }],
+                isError: true,
+            };
+        }
+    };
+}

package/src/types/testrail.ts

@@ -0,0 +1,87 @@
+export interface Case {
+    id: number;
+    title: string;
+    section_id: number;
+    template_id: number;
+    type_id: number;
+    priority_id: number;
+    milestone_id: number | null;
+    refs: string | null;
+    created_by: number;
+    created_on: number;
+    updated_by: number;
+    updated_on: number;
+    estimate: string | null;
+    estimate_forecast: string | null;
+    suite_id: number;
+    display_order: number;
+    is_deleted: number;
+    labels: any[];
+    [key: string]: any;
+}
+
+export interface Section {
+    id: number;
+    name: string;
+    description: string | null;
+    parent_id: number | null;
+    depth: number;
+    display_order: number;
+    suite_id: number;
+}
+
+export interface Priority {
+    id: number;
+    is_default: boolean;
+    name: string;
+    priority: number;
+    short_name: string;
+}
+
+export interface CaseType {
+    id: number;
+    is_default: boolean;
+    name: string;
+}
+
+export interface CaseField {
+    id: number;
+    name: string;
+    system_name: string;
+    label: string;
+    type_id: number;
+    template_ids: number[];
+    is_active: boolean;
+    display_order: number;
+    description: string | null;
+    include_all: boolean;
+    configs: CaseFieldConfig[];
+}
+
+export interface CaseFieldConfig {
+    context: {
+        is_global: boolean;
+        project_ids: number[] | null;
+    };
+    options: {
+        default_value?: string;
+        format?: string;
+        is_required?: boolean;
+        rows?: string;
+        items?: string;
+    };
+}
+
+export interface Template {
+    id: number;
+    name: string;
+    is_default: boolean;
+}
+
+export interface Project {
+    id: number;
+    name: string;
+    announcement: string | null;
+    is_completed: boolean;
+    suite_mode: number;
+}

package/src/utils/mapper.ts

@@ -0,0 +1,90 @@
+import { Case, CaseField } from "../types/testrail.js";
+import { sanitizeValue } from "./sanitizer.js";
+
+/**
+ * Processes custom fields from a test case, converting system names to human-readable labels
+ * and mapping dropdown values to their display text.
+ */
+export function processCustomFields(
+    testCase: Case,
+    caseFields: CaseField[]
+): Record<string, any> {
+    if (!testCase) {
+        throw new Error("Test case is undefined or null");
+    }
+
+    const templateId = testCase.template_id;
+    const result: Record<string, any> = {};
+
+    const applicableFields = caseFields.filter(field =>
+        field.include_all || field.template_ids.includes(templateId)
+    );
+
+    const fieldNameMap = new Map<string, string>();
+    const dropdownOptionsMap = new Map<string, Map<string, string>>();
+
+    for (const field of applicableFields) {
+        fieldNameMap.set(field.system_name, toSnakeCase(field.label));
+
+        const optionsMap = parseDropdownOptions(field);
+        if (optionsMap.size > 0) {
+            dropdownOptionsMap.set(field.system_name, optionsMap);
+        }
+    }
+
+    for (const [key, value] of Object.entries(testCase)) {
+        if (!key.startsWith("custom_")) continue;
+        if (value === null || value === undefined) continue;
+
+        if (!fieldNameMap.has(key)) {
+            console.error(`No field mapping found for: ${key}`);
+            result[key] = value;
+            continue;
+        }
+
+        const outputKey = fieldNameMap.get(key)!;
+        let finalValue = value;
+
+        if (dropdownOptionsMap.has(key)) {
+            const options = dropdownOptionsMap.get(key)!;
+            const optionKey = String(value);
+            finalValue = options.get(optionKey) || value;
+        }
+
+        result[outputKey] = sanitizeValue(finalValue);
+    }
+
+    return result;
+}
+
+/**
+ * Parse dropdown options from field configs.
+ * Format: "1, First\n2, Second\n3, Third"
+ */
+export function parseDropdownOptions(field: CaseField): Map<string, string> {
+    const options = new Map<string, string>();
+
+    for (const config of field.configs) {
+        const items = config.options?.items;
+        if (!items) continue;
+
+        const lines = items.split('\n');
+        for (const line of lines) {
+            const commaIndex = line.indexOf(',');
+            if (commaIndex > 0) {
+                const id = line.substring(0, commaIndex).trim();
+                const label = line.substring(commaIndex + 1).trim();
+                options.set(id, label);
+            }
+        }
+    }
+
+    return options;
+}
+
+function toSnakeCase(str: string): string {
+    return str
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_|_$/g, '');
+}

package/src/utils/sanitizer.ts

@@ -0,0 +1,21 @@
+/**
+ * Recursively ыtrips 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.
+ */
+export function sanitizeValue(value: any): any {
+    if (typeof value === 'string') {
+        return value.replace(/\s*style\s*=\s*["'][^"']*["']/gi, '');
+    }
+    if (Array.isArray(value)) {
+        return value.map(sanitizeValue);
+    }
+    if (value !== null && typeof value === 'object') {
+        const result: Record<string, any> = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = sanitizeValue(val);
+        }
+        return result;
+    }
+    return value;
+}