@uarlouski/testrail-mcp-server 1.1.0 → 1.3.0

package/src/tools/get_case.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { processCustomFields } from "../utils/mapper.js";
 import { TestRailClient } from "../client/testrail.js";
-import { TestCaseResponse, ToolDefinition, withErrorHandling } from "../types/custom.js";
+import { TestCaseResponse, ToolDefinition } from "../types/custom.js";
 
 const parameters = {
     case_id: z.string().describe("The ID of the test case (e.g. '123' or 'C123')"),
@@ -9,9 +9,9 @@ const parameters = {
 
 export const getCaseTool: ToolDefinition<typeof parameters, TestRailClient> = {
     name: "get_case",
-    description: "Get a test case from TestRail by ID",
+    description: "Get detailed information about a test case including its custom fields",
     parameters,
-    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ case_id }, client) => {
+    handler: async ({ case_id }, client) => {
         const id = case_id.toUpperCase().startsWith("C") ? case_id.substring(1) : case_id;
         const testCase = await client.getCase(id);
 
@@ -39,13 +39,6 @@ export const getCaseTool: ToolDefinition<typeof parameters, TestRailClient> = {
             ...customFields
         };
 
-        return {
-            content: [
-                {
-                    type: "text" as const,
-                    text: JSON.stringify(response, null, 2),
-                },
-            ],
-        };
-    })
+        return response;
+    }
 };

package/src/tools/get_case_fields.ts

@@ -1,5 +1,5 @@
 import { TestRailClient } from "../client/testrail.js";
-import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+import { ToolDefinition } from "../types/custom.js";
 import { CaseField } from "../types/testrail.js";
 import { parseDropdownOptions } from "../utils/mapper.js";
 
@@ -76,7 +76,7 @@ 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) => {
+    handler: async (_args, client) => {
         const caseFields = await client.getCaseFields();
 
         const customFieldSchemas = caseFields.filter(field => field.is_active).map(mapToFieldSchema);
@@ -85,13 +85,6 @@ export const getCaseFieldsTool: ToolDefinition<typeof parameters, TestRailClient
             fields: [...SYSTEM_FIELDS, ...customFieldSchemas],
         };
 
-        return {
-            content: [
-                {
-                    type: "text" as const,
-                    text: JSON.stringify(response, null, 2),
-                },
-            ],
-        };
-    })
+        return response;
+    }
 };

package/src/tools/get_cases.ts

@@ -1,14 +1,14 @@
 import { z } from "zod";
 import { TestRailClient } from "../client/testrail.js";
-import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+import { ToolDefinition } 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\"]"),
+    project_id: z.string().describe("The ID of the project. Use get_projects to find available projects"),
+    section_id: z.string().optional().describe("Optional section ID to filter cases by section. Use get_sections to find available sections"),
+    filter: z.record(z.string(), z.string()).optional().describe("Optional API-side filters (more efficient for large datasets). Supported: priority_id, type_id, created_by, updated_by, milestone_id, refs, created_after, created_before, updated_after, updated_before. Use comma-separated values for IDs. 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 (filters after fetching all cases). Supports exact value matching. Example: {\"custom_automation_status\": 1, \"priority_id\": 2}"),
+    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\"]"),
 };
 
 interface CasesResponse {
@@ -19,7 +19,7 @@ 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) => {
+    handler: 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
@@ -55,13 +55,6 @@ export const getCasesTool: ToolDefinition<typeof parameters, TestRailClient> = {
             }),
         };
 
-        return {
-            content: [
-                {
-                    type: "text" as const,
-                    text: JSON.stringify(response, null, 2),
-                },
-            ],
-        };
-    })
+        return response;
+    }
 };

package/src/tools/get_projects.ts

@@ -1,40 +1,20 @@
 import { TestRailClient } from "../client/testrail.js";
-import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+import { ToolDefinition } from "../types/custom.js";
+import { ProjectSchema } from "../types/testrail.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.",
+    description: "Get all available projects in TestRail. Returns project IDs and names that can be used with get_sections, get_templates, get_cases, and add_run",
     parameters,
-    handler: withErrorHandling<typeof parameters, TestRailClient>(async (_args, client) => {
+    handler: async (_args, client) => {
         const projects = await client.getProjects();
 
-        const response: ProjectsResponse = {
+        return {
             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),
-                },
-            ],
+                .map(p => ProjectSchema.parse(p)),
         };
-    })
+    }
 };

package/src/tools/get_sections.ts

@@ -1,41 +1,21 @@
 import { z } from "zod";
 import { TestRailClient } from "../client/testrail.js";
-import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+import { ToolDefinition } from "../types/custom.js";
+import { SectionSchema } from "../types/testrail.js";
 
 const parameters = {
-    project_id: z.string().describe("The ID of the project"),
+    project_id: z.string().describe("The ID of the project. Use get_projects to find available projects"),
 };
 
-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.",
+    description: "Get all sections for a project. Returns section IDs and names that can be used with create_case",
     parameters,
-    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ project_id }, client) => {
+    handler: 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),
-                },
-            ],
+            sections: sections.map(s => SectionSchema.parse(s)),
         };
-    })
+    }
 };

package/src/tools/get_statuses.ts

@@ -0,0 +1,18 @@
+import { TestRailClient } from "../client/testrail.js";
+import { z } from "zod";
+import { StatusSchema } from "../types/testrail.js";
+import { ToolDefinition } from "../types/custom.js";
+
+const parameters = {};
+
+export const getStatusesTool: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "get_statuses",
+    description: "Get all available test statuses (e.g. Passed, Failed, Blocked). Returns status IDs and names that can be used with add_result and get_tests",
+    parameters,
+    handler: async (args: any, client: TestRailClient) => {
+        const statuses = await client.getStatuses();
+        return {
+            statuses: statuses.map(s => StatusSchema.parse(s)),
+        };
+    },
+};

package/src/tools/get_templates.ts

@@ -1,41 +1,21 @@
 import { z } from "zod";
 import { TestRailClient } from "../client/testrail.js";
-import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+import { ToolDefinition } from "../types/custom.js";
+import { TemplateSchema } from "../types/testrail.js";
 
 const parameters = {
-    project_id: z.string().describe("The ID of the project"),
+    project_id: z.string().describe("The ID of the project. Use get_projects to find available projects"),
 };
 
-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.",
+    description: "Get available test case templates for a project. Template IDs determine which fields are available when creating or updating test cases",
     parameters,
-    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ project_id }, client) => {
+    handler: 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),
-                },
-            ],
+            templates: templates.map(t => TemplateSchema.parse(t)),
         };
-    })
+    }
 };

package/src/tools/get_tests.ts

@@ -0,0 +1,22 @@
+import { TestRailClient } from "../client/testrail.js";
+import { z } from "zod";
+import { Test, TestSchema } from "../types/testrail.js";
+import { ToolDefinition } from "../types/custom.js";
+
+const parameters = {
+    run_id: z.number().describe("The ID of the test run"),
+    status_id: z.array(z.number()).optional().describe("Optional array of status IDs to filter by. Use get_statuses to retrieve available status IDs"),
+}
+
+export const getTestsTool: ToolDefinition<typeof parameters, TestRailClient> = {
+    name: "get_tests",
+    description: "Get tests for a test run, optionally filtered by status",
+    parameters,
+    handler: async ({ run_id, status_id }, client: TestRailClient) => {
+        const tests: Test[] = await client.getTests(run_id, status_id);
+
+        return {
+            tests: tests.map(test => TestSchema.parse(test)),
+        };
+    },
+};

package/src/tools/update_case.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { TestRailClient } from "../client/testrail.js";
-import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+import { ToolDefinition } from "../types/custom.js";
 
 const parameters = {
     case_id: z.string().describe("The ID of the test case to update (e.g. '123' or 'C123')"),
@@ -9,24 +9,17 @@ const parameters = {
 
 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.",
+    description: "Update a test case in TestRail. Supports partial updates - only specify the fields you want to change",
     parameters,
-    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ case_id, fields }, client) => {
+    handler: 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),
-                },
-            ],
+            success: true,
+            case_id: updatedCase.id,
+            message: `Test case C${updatedCase.id} updated successfully`,
         };
-    })
+    }
 };

package/src/tools/update_cases.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { TestRailClient } from "../client/testrail.js";
-import { ToolDefinition, withErrorHandling } from "../types/custom.js";
+import { ToolDefinition } from "../types/custom.js";
 
 const parameters = {
     case_ids: z.array(z.number()).describe("Array of case IDs to update (e.g. [123, 456, 789])"),
@@ -9,23 +9,17 @@ const parameters = {
 
 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.",
+    description: "Bulk update multiple test cases with the same field values. More efficient than calling update_case multiple times",
     parameters,
-    handler: withErrorHandling<typeof parameters, TestRailClient>(async ({ case_ids, fields }, client) => {
-        const updatedCases = await client.updateCases(case_ids, fields);
+    handler: async ({ case_ids, fields }, client) => {
+        const caseData = await client.getCase(String(case_ids[0]));
+        const updatedCases = await client.updateCases(caseData.suite_id, 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),
-                },
-            ],
+            success: true,
+            updated_count: updatedCases.length,
+            case_ids: updatedCases.map(c => c.id),
+            message: `Successfully updated ${updatedCases.length} test cases`,
         };
-    })
+    }
 };

package/src/types/custom.ts

@@ -15,20 +15,5 @@ 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,
-            };
-        }
-    };
+    handler: (args: z.infer<z.ZodObject<T>>, context: Context) => Promise<Record<string, any>>;
 }

package/src/types/testrail.ts

@@ -1,87 +1,140 @@
-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;
-}
+import { z } from "zod";
+
+export const CaseFieldConfigSchema = z.object({
+    options: z.object({
+        default_value: z.string().optional(),
+        is_required: z.boolean().optional(),
+        items: z.string().optional(),
+    }),
+});
+
+export type CaseFieldConfig = z.infer<typeof CaseFieldConfigSchema>;
+
+export const CaseFieldSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    system_name: z.string(),
+    label: z.string(),
+    type_id: z.number(),
+    template_ids: z.array(z.number()),
+    is_active: z.boolean(),
+    description: z.string().nullable(),
+    include_all: z.boolean(),
+    configs: z.array(CaseFieldConfigSchema),
+});
+
+export type CaseField = z.infer<typeof CaseFieldSchema>;
+
+export const CaseSchema = z.object({
+    id: z.number(),
+    title: z.string(),
+    section_id: z.number(),
+    template_id: z.number(),
+    type_id: z.number(),
+    priority_id: z.number(),
+    milestone_id: z.number().nullable(),
+    refs: z.string().nullable(),
+    created_on: z.number(),
+    updated_on: z.number(),
+    estimate: z.string().nullable(),
+    suite_id: z.number(),
+    labels: z.array(z.any()),
+}).loose();
+
+export type Case = z.infer<typeof CaseSchema>;
+
+export const SectionSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    description: z.string().nullish(),
+    parent_id: z.number().nullish(),
+    suite_id: z.number(),
+});
+
+export type Section = z.infer<typeof SectionSchema>;
+
+export const PrioritySchema = z.object({
+    id: z.number(),
+    is_default: z.boolean(),
+    name: z.string(),
+});
+
+export type Priority = z.infer<typeof PrioritySchema>;
+
+export const CaseTypeSchema = z.object({
+    id: z.number(),
+    is_default: z.boolean(),
+    name: z.string(),
+});
+
+export type CaseType = z.infer<typeof CaseTypeSchema>;
+
+export const TemplateSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    is_default: z.boolean(),
+});
+
+export type Template = z.infer<typeof TemplateSchema>;
+
+export const ProjectSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    is_completed: z.boolean(),
+    suite_mode: z.number(),
+});
+
+export type Project = z.infer<typeof ProjectSchema>;
+
+export const RunSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    description: z.string().nullable(),
+    suite_id: z.number().nullable(),
+    project_id: z.number(),
+    is_completed: z.boolean(),
+    passed_count: z.number(),
+    blocked_count: z.number(),
+    untested_count: z.number(),
+    retest_count: z.number(),
+    failed_count: z.number(),
+    url: z.string(),
+});
+
+export type Run = z.infer<typeof RunSchema>;
+
+export const StatusSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    label: z.string(),
+});
+
+export type Status = z.infer<typeof StatusSchema>;
+
+export const TestSchema = z.object({
+    id: z.number(),
+    case_id: z.number(),
+    status_id: z.number(),
+    title: z.string(),
+    run_id: z.number(),
+})
+
+export const TestsSchema = z.array(TestSchema)
+
+export type Test = z.infer<typeof TestSchema>
+
+export const ResultSchema = z.object({
+    id: z.number(),
+    test_id: z.number(),
+    status_id: z.number(),
+    comment: z.string().nullable(),
+    defects: z.string().nullable(),
+});
+
+export type Result = z.infer<typeof ResultSchema>
+
+export const AttachmentSchema = z.object({
+    attachment_id: z.number(),
+});
+
+export type Attachment = z.infer<typeof AttachmentSchema>