@uarlouski/testrail-mcp-server 1.3.0 → 1.3.1

package/dist/client/testrail.js

@@ -0,0 +1,167 @@
+import * as fs from "fs";
+const API_INDEX = '/index.php?';
+const API_BASE_V2 = `${API_INDEX}/api/v2`;
+export class TestRailClient {
+    baseUrl;
+    headers;
+    auth;
+    prioritiesPromise = null;
+    caseTypesPromise = null;
+    caseFieldsPromise = null;
+    statusesPromise = null;
+    projectsPromise = null;
+    templatesPromiseMap = new Map();
+    constructor(baseUrl, email, apiKey) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        const auth = Buffer.from(`${email}:${apiKey}`).toString('base64');
+        this.auth = `Basic ${auth}`;
+        this.headers = {
+            "Content-Type": "application/json",
+            "Authorization": this.auth,
+        };
+    }
+    async getCase(caseId) {
+        return this.get(`${API_BASE_V2}/get_case/${caseId}`);
+    }
+    async getCases(projectId, sectionId, filter) {
+        let url = `${API_BASE_V2}/get_cases/${projectId}`;
+        if (sectionId) {
+            url += `&section_id=${sectionId}`;
+        }
+        if (filter) {
+            for (const [key, value] of Object.entries(filter)) {
+                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;
+    }
+    async getSection(sectionId) {
+        return this.get(`${API_BASE_V2}/get_section/${sectionId}`);
+    }
+    async getPriorities() {
+        if (!this.prioritiesPromise) {
+            this.prioritiesPromise = this.get(`${API_BASE_V2}/get_priorities`);
+        }
+        return this.prioritiesPromise;
+    }
+    async getCaseTypes() {
+        if (!this.caseTypesPromise) {
+            this.caseTypesPromise = this.get(`${API_BASE_V2}/get_case_types`);
+        }
+        return this.caseTypesPromise;
+    }
+    async getCaseFields() {
+        if (!this.caseFieldsPromise) {
+            this.caseFieldsPromise = this.get(`${API_BASE_V2}/get_case_fields`);
+        }
+        return this.caseFieldsPromise;
+    }
+    async getStatuses() {
+        if (!this.statusesPromise) {
+            this.statusesPromise = this.get(`${API_BASE_V2}/get_statuses`);
+        }
+        return this.statusesPromise;
+    }
+    async getTemplates(projectId) {
+        if (!this.templatesPromiseMap.has(projectId)) {
+            this.templatesPromiseMap.set(projectId, this.get(`${API_BASE_V2}/get_templates/${projectId}`));
+        }
+        return this.templatesPromiseMap.get(projectId);
+    }
+    async updateCase(caseId, fields) {
+        return this.post(`${API_BASE_V2}/update_case/${caseId}`, fields);
+    }
+    async updateCases(suiteId, caseIds, fields) {
+        const response = await this.post(`${API_BASE_V2}/update_cases/${suiteId}`, {
+            case_ids: caseIds,
+            ...fields,
+        });
+        return response.updated_cases;
+    }
+    async createCase(sectionId, fields) {
+        return this.post(`${API_BASE_V2}/add_case/${sectionId}`, fields);
+    }
+    async addRun(projectId, fields) {
+        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;
+    }
+    async getProjects() {
+        if (!this.projectsPromise) {
+            this.projectsPromise = this.get(`${API_BASE_V2}/get_projects`)
+                .then(response => response.projects);
+        }
+        return this.projectsPromise;
+    }
+    async getTests(runId, statusId) {
+        let url = `${API_BASE_V2}/get_tests/${runId}`;
+        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;
+    }
+    async addResults(runId, results) {
+        return this.post(`${API_BASE_V2}/add_results/${runId}`, { results });
+    }
+    async addAttachmentToRun(runId, filePath, filename) {
+        const fileBuffer = await fs.promises.readFile(filePath);
+        const blob = new Blob([fileBuffer]);
+        const formData = new FormData();
+        formData.append('attachment', blob, filename);
+        const headers = {
+            'Authorization': this.auth,
+        };
+        return this._executeRequest('POST', `${API_BASE_V2}/add_attachment_to_run/${runId}`, headers, formData);
+    }
+    async get(endpoint) {
+        return this.executeRequest('GET', endpoint);
+    }
+    async post(endpoint, data) {
+        return this.executeRequest('POST', endpoint, data);
+    }
+    async executeRequest(method, endpoint, data) {
+        let jsonData = undefined;
+        if (data) {
+            jsonData = JSON.stringify(data);
+        }
+        return this._executeRequest(method, endpoint, this.headers, jsonData);
+    }
+    async _executeRequest(method, endpoint, headers, body) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const params = {
+            method,
+            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);
+        }
+        return await response.json();
+    }
+}

package/{src/index.ts → dist/index.js}

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import "dotenv/config";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -17,23 +18,18 @@ 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.");
     process.exit(1);
 }
-
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "1.3.0",
+    version: "1.3.1",
 });
-
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
-
 const tools = [
     getProjectsTool,
     getCaseTool,
@@ -49,37 +45,31 @@ const tools = [
     getTestsTool,
     addResultsTool,
     addAttachmentToRunTool,
-]
-
+];
 for (const tool of tools) {
-    server.registerTool(
-        tool.name,
-        {
-            description: tool.description,
-            inputSchema: tool.parameters,
-        },
-        async (args: any) => {
-            try {
-                const output: Record<string, any> = await tool.handler(args, client);
-                const sanitized = removeNullish(output);
-
-                return {
-                    content: [
-                        {
-                            type: "text" as const,
-                            text: JSON.stringify(sanitized),
-                        },
-                    ],
-                } as any;
-            } catch (error: any) {
-                return {
-                    content: [{ type: "text", text: `Error: ${error.message}` }],
-                    isError: true,
-                };
-            }
+    server.registerTool(tool.name, {
+        description: tool.description,
+        inputSchema: tool.parameters,
+    }, async (args) => {
+        try {
+            const output = await tool.handler(args, client);
+            const sanitized = removeNullish(output);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(sanitized),
+                    },
+                ],
+            };
         }
-    );
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${error.message}` }],
+                isError: true,
+            };
+        }
+    });
 }
-
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/{src/tools/add_attachment_to_run.ts → dist/tools/add_attachment_to_run.js}

@@ -1,59 +1,49 @@
-import { TestRailClient } from "../client/testrail.js";
 import { z } from "zod";
 import { AttachmentSchema } from "../types/testrail.js";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import archiver from "archiver";
-import { ToolDefinition } from "../types/custom.js";
-
 const parameters = {
     run_id: z.string().describe("The ID of the test run to attach the file to"),
     file_path: z.string().describe("The path to the file or directory to attach. Directories will be automatically zipped."),
-}
-
-export const addAttachmentToRunTool: ToolDefinition<typeof parameters, TestRailClient> = {
+};
+export const addAttachmentToRunTool = {
     name: "add_attachment_to_run",
     description: "Add an attachment to a test run in TestRail. If the file_path points to a directory, it will be automatically zipped before uploading. Maximum upload size is 256MB.",
     parameters,
-    handler: async ({ run_id, file_path }, client: TestRailClient) => {
+    handler: async ({ run_id, file_path }, client) => {
         if (!fs.existsSync(file_path)) {
             throw new Error(`File or directory not found: ${file_path}`);
         }
-
         const stats = fs.statSync(file_path);
-        let uploadPath: string = file_path;
-        let filename: string = path.basename(file_path);
+        let uploadPath = file_path;
+        let filename = path.basename(file_path);
         let isTemporary = false;
-
         if (stats.isDirectory()) {
             const basename = path.basename(file_path);
             const tempDir = os.tmpdir();
             const zipPath = path.join(tempDir, `${basename}-${Date.now()}.zip`);
-
-            await new Promise<void>((resolve, reject) => {
+            await new Promise((resolve, reject) => {
                 const output = fs.createWriteStream(zipPath);
                 const archive = archiver('zip', {
                     zlib: { level: 9 }
                 });
-
                 output.on('close', () => resolve());
                 archive.on('error', (err) => reject(err));
-
                 archive.pipe(output);
                 archive.directory(file_path, basename);
                 archive.finalize();
             });
-
             uploadPath = zipPath;
             filename = `${basename}.zip`;
             isTemporary = true;
         }
-
         try {
             const result = await client.addAttachmentToRun(Number(run_id), uploadPath, filename);
             return AttachmentSchema.parse(result);
-        } finally {
+        }
+        finally {
             if (isTemporary && fs.existsSync(uploadPath)) {
                 fs.unlinkSync(uploadPath);
             }

package/{src/tools/add_results.ts → dist/tools/add_results.js}

@@ -1,8 +1,5 @@
-import { TestRailClient } from "../client/testrail.js";
 import { z } from "zod";
 import { ResultSchema } from "../types/testrail.js";
-import { ToolDefinition } from "../types/custom.js";
-
 const parameters = {
     run_id: z.number().describe("The ID of the test run"),
     results: z.array(z.object({
@@ -11,13 +8,12 @@ const parameters = {
         comment: z.string().optional().describe("Optional comment/description for the result"),
         defects: z.string().optional().describe("Optional comma-separated list of defect IDs"),
     })).describe("Array of results to add. Each result must have test_id and status_id"),
-}
-
-export const addResultsTool: ToolDefinition<typeof parameters, TestRailClient> = {
+};
+export const addResultsTool = {
     name: "add_results",
     description: "Add one or more test results to a test run",
     parameters,
-    handler: async ({ run_id, results }, client: TestRailClient) => {
+    handler: async ({ run_id, results }, client) => {
         const response = await client.addResults(run_id, results);
         return {
             success: true,

package/{src/tools/add_run.ts → dist/tools/add_run.js}

@@ -1,24 +1,19 @@
-import { TestRailClient } from "../client/testrail.js";
 import { z } from "zod";
 import { RunSchema } from "../types/testrail.js";
-import { ToolDefinition } from "../types/custom.js";
-
 const parameters = {
     project_id: z.string().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")
-}
-
-export const addRunTool: ToolDefinition<typeof parameters, TestRailClient> = {
+};
+export const addRunTool = {
     name: "add_run",
     description: "Create a new test run in TestRail",
     parameters,
-    handler: async ({ project_id, ...fields }, client: TestRailClient) => {
+    handler: async ({ project_id, ...fields }, client) => {
         const caseData = await client.getCase(String(fields.case_ids[0]));
         const params = { suite_id: caseData.suite_id, include_all: false, ...fields };
         const run = await client.addRun(project_id, params);
-
         return RunSchema.parse(run);
     },
 };

package/{src/tools/create_case.ts → dist/tools/create_case.js}

@@ -1,14 +1,10 @@
 import { z } from "zod";
-import { TestRailClient } from "../client/testrail.js";
-import { ToolDefinition } from "../types/custom.js";
-
 const parameters = {
     section_id: z.string().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"),
     fields: z.record(z.string(), z.any()).optional().describe("Optional fields for the test case. First use get_templates to discover available templates, then get_case_fields to see available fields for your template. Example: {\"priority_id\": 2, \"template_id\": 1, \"custom_automation_priority\": 1}"),
 };
-
-export const createCaseTool: ToolDefinition<typeof parameters, TestRailClient> = {
+export const createCaseTool = {
     name: "create_case",
     description: "Create a new test case in TestRail",
     parameters,
@@ -17,9 +13,7 @@ export const createCaseTool: ToolDefinition<typeof parameters, TestRailClient> =
             title,
             ...fields,
         };
-
         const createdCase = await client.createCase(section_id, caseData);
-
         return {
             success: true,
             case_id: createdCase.id,

package/{src/tools/get_case.ts → dist/tools/get_case.js}

@@ -1,33 +1,25 @@
 import { z } from "zod";
 import { processCustomFields } from "../utils/mapper.js";
-import { TestRailClient } from "../client/testrail.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')"),
 };
-
-export const getCaseTool: ToolDefinition<typeof parameters, TestRailClient> = {
+export const getCaseTool = {
     name: "get_case",
     description: "Get detailed information about a test case including its custom fields",
     parameters,
     handler: 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 = {
+        const response = {
             id: testCase.id,
             title: testCase.title,
             section: section.name,
@@ -38,7 +30,6 @@ export const getCaseTool: ToolDefinition<typeof parameters, TestRailClient> = {
             updated_on: testCase.updated_on,
             ...customFields
         };
-
         return response;
     }
 };

package/{src/tools/get_case_fields.ts → dist/tools/get_case_fields.js}

@@ -1,24 +1,6 @@
-import { TestRailClient } from "../client/testrail.js";
-import { ToolDefinition } 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> = {
+const FIELD_TYPE_NAMES = {
     1: "String",
     2: "Integer",
     3: "Text",
@@ -33,35 +15,28 @@ const FIELD_TYPE_NAMES: Record<number, string> = {
     12: "Multi-select",
     13: "Scenarios",
 };
-
-function getFieldTypeName(typeId: number): string {
+function getFieldTypeName(typeId) {
     return FIELD_TYPE_NAMES[typeId] || `Unknown (${typeId})`;
 }
-
-function isFieldRequired(field: CaseField): boolean {
+function isFieldRequired(field) {
     return field.configs.some(config => config.options?.is_required === true);
 }
-
-function mapToFieldSchema(field: CaseField): FieldSchema {
-    const schema: FieldSchema = {
+function mapToFieldSchema(field) {
+    const schema = {
         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[] = [
+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 },
@@ -71,20 +46,16 @@ const SYSTEM_FIELDS: FieldSchema[] = [
     { 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> = {
+export const getCaseFieldsTool = {
     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: async (_args, client) => {
         const caseFields = await client.getCaseFields();
-
         const customFieldSchemas = caseFields.filter(field => field.is_active).map(mapToFieldSchema);
-
-        const response: CaseFieldsResponse = {
+        const response = {
             fields: [...SYSTEM_FIELDS, ...customFieldSchemas],
         };
-
         return response;
     }
 };

package/{src/tools/get_cases.ts → dist/tools/get_cases.js}

@@ -1,8 +1,4 @@
 import { z } from "zod";
-import { TestRailClient } from "../client/testrail.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. 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"),
@@ -10,23 +6,17 @@ const parameters = {
     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 {
-    cases: Record<string, any>[];
-}
-
-export const getCasesTool: ToolDefinition<typeof parameters, TestRailClient> = {
+export const getCasesTool = {
     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: async ({ project_id, section_id, filter, where, fields }, client) => {
-        let cases: Case[] = await client.getCases(project_id, section_id, filter);
-
+        let 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 as Record<string, any>)[key];
+                    const caseValue = c[key];
                     if (caseValue !== value) {
                         return false;
                     }
@@ -34,15 +24,13 @@ export const getCasesTool: ToolDefinition<typeof parameters, TestRailClient> = {
                 return true;
             });
         }
-
-        const response: CasesResponse = {
+        const response = {
             cases: cases.map(c => {
-                const result: Record<string, any> = {
+                const result = {
                     id: c.id,
                     title: c.title,
                     suite_id: c.suite_id,
                 };
-
                 if (fields) {
                     for (const field of fields) {
                         if (field in c) {
@@ -50,11 +38,9 @@ export const getCasesTool: ToolDefinition<typeof parameters, TestRailClient> = {
                         }
                     }
                 }
-
                 return result;
             }),
         };
-
         return response;
     }
 };

package/{src/tools/get_projects.ts → dist/tools/get_projects.js}

@@ -1,16 +1,11 @@
-import { TestRailClient } from "../client/testrail.js";
-import { ToolDefinition } from "../types/custom.js";
 import { ProjectSchema } from "../types/testrail.js";
-
 const parameters = {};
-
-export const getProjectsTool: ToolDefinition<typeof parameters, TestRailClient> = {
+export const getProjectsTool = {
     name: "get_projects",
     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: async (_args, client) => {
         const projects = await client.getProjects();
-
         return {
             projects: projects
                 .filter(p => !p.is_completed)

package/{src/tools/get_sections.ts → dist/tools/get_sections.js}

@@ -1,19 +1,14 @@
 import { z } from "zod";
-import { TestRailClient } from "../client/testrail.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. Use get_projects to find available projects"),
 };
-
-export const getSectionsTool: ToolDefinition<typeof parameters, TestRailClient> = {
+export const getSectionsTool = {
     name: "get_sections",
     description: "Get all sections for a project. Returns section IDs and names that can be used with create_case",
     parameters,
     handler: async ({ project_id }, client) => {
         const sections = await client.getSections(project_id);
-
         return {
             sections: sections.map(s => SectionSchema.parse(s)),
         };

package/{src/tools/get_statuses.ts → dist/tools/get_statuses.js}

@@ -1,15 +1,10 @@
-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> = {
+export const getStatusesTool = {
     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) => {
+    handler: async (args, client) => {
         const statuses = await client.getStatuses();
         return {
             statuses: statuses.map(s => StatusSchema.parse(s)),