@uarlouski/testrail-mcp-server 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [1.3.0] - 2026-02-18
+
+### Added
+
+- **Test run and result management tools**
+    - `add_run` - Create a new test run in TestRail
+    - `get_tests` - Get tests for a test run, optionally filtered by status
+    - `add_results` - Add one or more test results to a test run
+    - `get_statuses` - Get all available test statuses (e.g. Passed, Failed, Blocked)
+- Add `add_attachment_to_run` tool to attach files to test runs
+
 ## [1.2.0] - 2026-02-14
 
 ### Changed

package/README.md

@@ -1,7 +1,12 @@
 # TestRail MCP Server
 
-[![npm version](https://img.shields.io/npm/v/@uarlouski/testrail-mcp-server.svg)](https://www.npmjs.com/package/@uarlouski/testrail-mcp-server)
-[![License](https://img.shields.io/npm/l/@uarlouski/testrail-mcp-server.svg)](https://github.com/uarlouski/testrail-mcp-server/blob/main/LICENSE)
+[![npm version](https://badge.fury.io/js/@uarlouski%2Ftestrail-mcp-server.svg)](https://www.npmjs.com/package/@uarlouski/testrail-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/@uarlouski/testrail-mcp-server.svg)](https://www.npmjs.com/package/@uarlouski/testrail-mcp-server)
+[![CI](https://github.com/uarlouski/testrail-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/uarlouski/testrail-mcp-server/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-blue.svg)](https://www.typescriptlang.org/)
+[![GitHub stars](https://img.shields.io/github/stars/uarlouski/testrail-mcp-server.svg?style=social&label=Star)](https://github.com/uarlouski/testrail-mcp-server)
+
 
 A powerful **Model Context Protocol (MCP)** server for seamless integration between **Large Language Models (LLMs)** and **TestRail** test case management.
 
@@ -63,6 +68,11 @@ This MCP server exposes the following tools to the LLM:
 | `create_case` | **Authoring**: Create new test cases. *Tip: The model should check templates and fields first to ensure validity.* |
 | `update_case` | **Maintenance**: Modify existing test case fields, title, or steps. |
 | `update_cases` | **Bulk Edit**: Update multiple cases simultaneously for efficient refactoring. |
+| `add_run` | **Test Execution**: Create a new test run in TestRail. |
+| `get_tests` | **Test Execution**: Get tests for a test run, optionally filtered by status. |
+| `add_results` | **Test Execution**: Add one or more test results to a test run. |
+| `add_attachment_to_run` | **Test Execution**: Add an attachment (file or zipped folder) to a test run. |
+| `get_statuses` | **Metadata**: Get all available test statuses (e.g. Passed, Failed, Blocked). |
 | `get_case_fields` | **Metadata**: Retrieve definitions of custom fields to understand available inputs. |
 | `get_templates` | **Metadata**: List available case templates to ensure correct case creation structure. |
 | `get_priorities` | **Metadata**: List available priority levels. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Model Context Protocol (MCP) server for TestRail integration, enabling LLMs to fetch test cases and metadata.",
   "main": "index.js",
   "type": "module",
@@ -34,10 +34,12 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.3",
+    "archiver": "^7.0.1",
     "dotenv": "^17.2.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
+    "@types/archiver": "^7.0.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.0.9",
     "jest": "^30.2.0",

package/src/client/testrail.ts

@@ -1,28 +1,38 @@
-import { Case, Section, Priority, CaseType, CaseField, Template, Project } from "../types/testrail.js";
+import { Case, Section, Priority, CaseType, CaseField, Template, Project, Run, Status, Test, Result, Attachment } from "../types/testrail.js";
+
+import * as fs from "fs";
 
 interface PaginatedCasesResponse {
     cases: Case[];
     _links: { next: string | null };
 }
 
+interface PaginatedTestsResponse {
+    tests: Test[];
+    _links: { next: string | null };
+}
+
 const API_INDEX = '/index.php?';
 const API_BASE_V2 = `${API_INDEX}/api/v2`;
 
 export class TestRailClient {
     private baseUrl: string;
     private headers: HeadersInit;
+    private auth: string;
     private prioritiesPromise: Promise<Priority[]> | null = null;
     private caseTypesPromise: Promise<CaseType[]> | null = null;
     private caseFieldsPromise: Promise<CaseField[]> | null = null;
+    private statusesPromise: Promise<Status[]> | null = null;
     private projectsPromise: Promise<Project[]> | null = null;
     private templatesPromiseMap: Map<string, Promise<Template[]>> = new Map();
 
     constructor(baseUrl: string, email: string, apiKey: string) {
         this.baseUrl = baseUrl.replace(/\/$/, "");
         const auth = Buffer.from(`${email}:${apiKey}`).toString('base64');
+        this.auth = `Basic ${auth}`;
         this.headers = {
             "Content-Type": "application/json",
-            "Authorization": `Basic ${auth}`,
+            "Authorization": this.auth,
         };
     }
 
@@ -85,6 +95,13 @@ export class TestRailClient {
         return this.caseFieldsPromise;
     }
 
+    async getStatuses(): Promise<Status[]> {
+        if (!this.statusesPromise) {
+            this.statusesPromise = this.get<Status[]>(`${API_BASE_V2}/get_statuses`);
+        }
+        return this.statusesPromise;
+    }
+
     async getTemplates(projectId: string): Promise<Template[]> {
         if (!this.templatesPromiseMap.has(projectId)) {
             this.templatesPromiseMap.set(
@@ -99,11 +116,8 @@ export class TestRailClient {
         return this.post<Case>(`${API_BASE_V2}/update_case/${caseId}`, fields);
     }
 
-    async updateCases(caseIds: number[], fields: Record<string, any>): Promise<Case[]> {
-        // Assume the project is operating in single suite mode, get suite_id from the first case
-        const caseData = await this.getCase(String(caseIds[0]));
-
-        const response = await this.post<{ updated_cases: Case[] }>(`${API_BASE_V2}/update_cases/${caseData.suite_id}`, {
+    async updateCases(suiteId: number, caseIds: number[], fields: Record<string, any>): Promise<Case[]> {
+        const response = await this.post<{ updated_cases: Case[] }>(`${API_BASE_V2}/update_cases/${suiteId}`, {
             case_ids: caseIds,
             ...fields,
         });
@@ -115,6 +129,10 @@ export class TestRailClient {
         return this.post<Case>(`${API_BASE_V2}/add_case/${sectionId}`, fields);
     }
 
+    async addRun(projectId: string, fields: Record<string, any>): Promise<Run> {
+        return this.post<Run>(`${API_BASE_V2}/add_run/${projectId}`, fields);
+    }
+
     async getSections(projectId: string): Promise<Section[]> {
         const response = await this.get<{ sections: Section[] }>(`${API_BASE_V2}/get_sections/${projectId}`);
         return response.sections;
@@ -128,6 +146,48 @@ export class TestRailClient {
         return this.projectsPromise;
     }
 
+
+    async getTests(runId: number, statusId?: number[]): Promise<Test[]> {
+        let url = `${API_BASE_V2}/get_tests/${runId}`;
+
+        if (statusId && statusId.length > 0) {
+            url += `&status_id=${statusId.join(',')}`;
+        }
+
+        const allTests: Test[] = [];
+        let nextUrl: string | null = url;
+
+        while (nextUrl) {
+            const response: PaginatedTestsResponse = await this.get<PaginatedTestsResponse>(nextUrl);
+            allTests.push(...response.tests);
+
+            nextUrl = response._links?.next;
+            if (nextUrl) {
+                nextUrl = `${API_INDEX}${nextUrl}`;
+            }
+        }
+
+        return allTests;
+    }
+
+
+    async addResults(runId: number, results: Array<Record<string, any>>): Promise<Result[]> {
+        return this.post<Result[]>(`${API_BASE_V2}/add_results/${runId}`, { results });
+    }
+
+    async addAttachmentToRun(runId: number, filePath: string, filename: string): Promise<Attachment> {
+        const fileBuffer = await fs.promises.readFile(filePath);
+        const blob = new Blob([fileBuffer]);
+        const formData = new FormData();
+        formData.append('attachment', blob, filename);
+
+        const headers: HeadersInit = {
+            'Authorization': this.auth,
+        };
+
+        return this._executeRequest<Attachment>('POST', `${API_BASE_V2}/add_attachment_to_run/${runId}`, headers, formData);
+    }
+
     private async get<T>(endpoint: string): Promise<T> {
         return this.executeRequest<T>('GET', endpoint);
     }
@@ -137,16 +197,22 @@ export class TestRailClient {
     }
 
     private async executeRequest<T>(method: 'GET' | 'POST', endpoint: string, data?: Record<string, any>): Promise<T> {
+        let jsonData = undefined;
+        if (data) {
+            jsonData = JSON.stringify(data);
+        }
+
+        return this._executeRequest<T>(method, endpoint, this.headers, jsonData);
+    }
+
+    private async _executeRequest<T>(method: 'GET' | 'POST', endpoint: string, headers: HeadersInit, body?: any): Promise<T> {
         const url = `${this.baseUrl}${endpoint}`;
         const params: RequestInit = {
             method,
-            headers: this.headers,
+            headers,
+            body,
         };
 
-        if (data) {
-            params.body = JSON.stringify(data);
-        }
-
         const response = await fetch(url, params);
 
         if (!response.ok) {

package/src/index.ts

@@ -11,6 +11,11 @@ import { updateCasesTool } from "./tools/update_cases.js";
 import { createCaseTool } from "./tools/create_case.js";
 import { getSectionsTool } from "./tools/get_sections.js";
 import { getProjectsTool } from "./tools/get_projects.js";
+import { addRunTool } from "./tools/add_run.js";
+import { getStatusesTool } from "./tools/get_statuses.js";
+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;
@@ -24,7 +29,7 @@ if (!TESTRAIL_INSTANCE_URL || !TESTRAIL_USERNAME || !TESTRAIL_API_KEY) {
 
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "1.2.0",
+    version: "1.3.0",
 });
 
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
@@ -39,6 +44,11 @@ const tools = [
     updateCaseTool,
     updateCasesTool,
     createCaseTool,
+    addRunTool,
+    getStatusesTool,
+    getTestsTool,
+    addResultsTool,
+    addAttachmentToRunTool,
 ]
 
 for (const tool of tools) {
@@ -57,7 +67,7 @@ for (const tool of tools) {
                     content: [
                         {
                             type: "text" as const,
-                            text: JSON.stringify(sanitized, null, 2),
+                            text: JSON.stringify(sanitized),
                         },
                     ],
                 } as any;

package/src/tools/add_attachment_to_run.ts

@@ -0,0 +1,62 @@
+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> = {
+    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) => {
+        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 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) => {
+                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 {
+            if (isTemporary && fs.existsSync(uploadPath)) {
+                fs.unlinkSync(uploadPath);
+            }
+        }
+    },
+};

package/src/tools/add_results.ts

@@ -0,0 +1,28 @@
+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({
+        test_id: z.number().describe("The ID of the test. Use get_tests with a run_id to retrieve available test IDs"),
+        status_id: z.number().describe("The ID of the test status (e.g. Passed, Failed). Use get_statuses to retrieve available status IDs"),
+        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> = {
+    name: "add_results",
+    description: "Add one or more test results to a test run",
+    parameters,
+    handler: async ({ run_id, results }, client: TestRailClient) => {
+        const response = await client.addResults(run_id, results);
+        return {
+            success: true,
+            added_count: response.length,
+            results: response.map(r => ResultSchema.parse(r)),
+        };
+    },
+};

package/src/tools/add_run.ts

@@ -0,0 +1,24 @@
+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> = {
+    name: "add_run",
+    description: "Create a new test run in TestRail",
+    parameters,
+    handler: async ({ project_id, ...fields }, client: TestRailClient) => {
+        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

@@ -3,14 +3,14 @@ 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"),
-    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}"),
+    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> = {
     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.",
+    description: "Create a new test case in TestRail",
     parameters,
     handler: async ({ section_id, title, fields }, client) => {
         const caseData = {

package/src/tools/get_case.ts

@@ -9,7 +9,7 @@ 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: async ({ case_id }, client) => {
         const id = case_id.toUpperCase().startsWith("C") ? case_id.substring(1) : case_id;

package/src/tools/get_cases.ts

@@ -4,11 +4,11 @@ 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 {

package/src/tools/get_projects.ts

@@ -6,17 +6,15 @@ const parameters = {};
 
 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: async (_args, client) => {
         const projects = await client.getProjects();
 
-        const response = {
+        return {
             projects: projects
                 .filter(p => !p.is_completed)
                 .map(p => ProjectSchema.parse(p)),
         };
-
-        return response;
     }
 };

package/src/tools/get_sections.ts

@@ -4,20 +4,18 @@ 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"),
 };
 
 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: async ({ project_id }, client) => {
         const sections = await client.getSections(project_id);
 
-        const response = {
+        return {
             sections: sections.map(s => SectionSchema.parse(s)),
         };
-
-        return response;
     }
 };

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

@@ -4,20 +4,18 @@ 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"),
 };
 
 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: async ({ project_id }, client) => {
         const templates = await client.getTemplates(project_id);
 
-        const response = {
+        return {
             templates: templates.map(t => TemplateSchema.parse(t)),
         };
-
-        return response;
     }
 };

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

@@ -9,7 +9,7 @@ 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: async ({ case_id, fields }, client) => {
         const id = case_id.toUpperCase().startsWith("C") ? case_id.substring(1) : case_id;

package/src/tools/update_cases.ts

@@ -9,10 +9,11 @@ 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: async ({ case_ids, fields }, client) => {
-        const updatedCases = await client.updateCases(case_ids, fields);
+        const caseData = await client.getCase(String(case_ids[0]));
+        const updatedCases = await client.updateCases(caseData.suite_id, case_ids, fields);
 
         return {
             success: true,

package/src/types/testrail.ts

@@ -85,3 +85,56 @@ export const ProjectSchema = z.object({
 });
 
 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>

package/test/client/testrail.test.ts

@@ -1,5 +1,6 @@
 import { jest, describe, test, expect, beforeEach, afterEach } from '@jest/globals';
 import { TestRailClient } from '../../src/client/testrail.js';
+import * as fs from 'fs';
 
 describe('TestRailClient', () => {
     let client: TestRailClient;
@@ -315,26 +316,16 @@ describe('TestRailClient', () => {
         );
     });
 
-    test('updateCases gets suite_id from first case and updates all', async () => {
-        const mockCase = { id: 1, suite_id: 10 };
+    test('updateCases uses passed suiteId', async () => {
         const mockUpdated = [{ id: 1, title: 'Updated' }, { id: 2, title: 'Updated' }];
 
-        fetchMock
-            .mockResolvedValueOnce({
-                ok: true,
-                json: async () => mockCase
-            })
-            .mockResolvedValueOnce({
-                ok: true,
-                json: async () => ({ updated_cases: mockUpdated })
-            });
+        fetchMock.mockResolvedValue({
+            ok: true,
+            json: async () => ({ updated_cases: mockUpdated })
+        });
 
-        const result = await client.updateCases([1, 2], { title: 'Updated' });
+        const result = await client.updateCases(10, [1, 2], { title: 'Updated' });
         expect(result).toEqual(mockUpdated);
-        expect(fetchMock).toHaveBeenCalledWith(
-            'https://testrail.io/index.php?/api/v2/get_case/1',
-            expect.any(Object)
-        );
         expect(fetchMock).toHaveBeenCalledWith(
             'https://testrail.io/index.php?/api/v2/update_cases/10',
             expect.objectContaining({
@@ -420,11 +411,135 @@ describe('TestRailClient', () => {
         );
     });
 
-    test('handleError formats error when network fails', async () => {
-        fetchMock.mockRejectedValue(new Error('Network Error'));
+    test('addRun posts fields directly', async () => {
+        const mockRun = { id: 1, name: 'New Run' };
 
-        await expect(client.getCase('1')).rejects.toThrow(
-            'Network Error'
+        fetchMock.mockResolvedValue({
+            ok: true,
+            json: async () => mockRun
+        });
+
+        const result = await client.addRun('1', { name: 'New Run', suite_id: 20 });
+
+        expect(result).toEqual(mockRun);
+        expect(fetchMock).toHaveBeenCalledWith(
+            'https://testrail.io/index.php?/api/v2/add_run/1',
+            expect.objectContaining({
+                method: 'POST',
+                body: JSON.stringify({ name: 'New Run', suite_id: 20 })
+            })
+        );
+    });
+
+    test('getTests handles pagination', async () => {
+        fetchMock
+            .mockImplementationOnce(() => Promise.resolve({
+                ok: true,
+                json: () => Promise.resolve({
+                    tests: [{ id: 1, case_id: 1, status_id: 1, title: 'Test 1', run_id: 1 }],
+                    _links: { next: '/api/v2/get_tests/1&offset=1' }
+                }),
+            } as Response))
+            .mockImplementationOnce(() => Promise.resolve({
+                ok: true,
+                json: () => Promise.resolve({
+                    tests: [{ id: 2, case_id: 2, status_id: 1, title: 'Test 2', run_id: 1 }],
+                    _links: { next: null }
+                }),
+            } as Response));
+
+        const tests = await client.getTests(1);
+        expect(tests).toHaveLength(2);
+        expect(tests[0].id).toBe(1);
+        expect(tests[1].id).toBe(2);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    test('getTests with status_id adds filter', async () => {
+        fetchMock.mockResolvedValue({
+            ok: true,
+            json: async () => ({
+                tests: [],
+                _links: { next: null }
+            })
+        } as Response);
+
+        await client.getTests(1, [1, 5]);
+
+        expect(fetchMock).toHaveBeenCalledWith(
+            expect.stringContaining('/get_tests/1&status_id=1,5'),
+            expect.any(Object)
+        );
+    });
+
+    test('getStatuses caches result', async () => {
+        const mockStatuses = [{ id: 1, name: 'passed', label: 'Passed' }];
+        fetchMock.mockResolvedValue({
+            ok: true,
+            json: async () => mockStatuses
+        });
+
+        await client.getStatuses();
+        await client.getStatuses();
+
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    test('addResults posts results array', async () => {
+        const mockResults = [
+            { id: 1, test_id: 100, status_id: 1, comment: 'Passed', defects: null },
+            { id: 2, test_id: 101, status_id: 5, comment: 'Failed', defects: 'BUG-123' }
+        ];
+
+        fetchMock.mockResolvedValue({
+            ok: true,
+            json: async () => mockResults
+        });
+
+        const results = await client.addResults(50, [
+            { test_id: 100, status_id: 1, comment: 'Passed' },
+            { test_id: 101, status_id: 5, comment: 'Failed', defects: 'BUG-123' }
+        ]);
+
+        expect(results).toEqual(mockResults);
+        expect(fetchMock).toHaveBeenCalledWith(
+            'https://testrail.io/index.php?/api/v2/add_results/50',
+            expect.objectContaining({
+                method: 'POST',
+                body: JSON.stringify({
+                    results: [
+                        { test_id: 100, status_id: 1, comment: 'Passed' },
+                        { test_id: 101, status_id: 5, comment: 'Failed', defects: 'BUG-123' }
+                    ]
+                })
+            })
+        );
+    });
+
+    test('addAttachmentToRun uploads file using FormData', async () => {
+        const mockAttachment = { attachment_id: 443 };
+        const mockFileBuffer = Buffer.from('file content');
+
+        jest.spyOn(fs.promises, 'readFile').mockResolvedValue(mockFileBuffer);
+
+        fetchMock.mockResolvedValue({
+            ok: true,
+            json: async () => mockAttachment
+        });
+
+        const result = await client.addAttachmentToRun(100, '/path/to/file.txt', 'file.txt');
+
+        expect(result).toEqual(mockAttachment);
+        expect(fs.promises.readFile).toHaveBeenCalledWith('/path/to/file.txt');
+        expect(fetchMock).toHaveBeenCalledWith(
+            'https://testrail.io/index.php?/api/v2/add_attachment_to_run/100',
+            expect.objectContaining({
+                method: 'POST',
+                headers: expect.objectContaining({
+                    'Authorization': expect.stringContaining('Basic')
+                }),
+                body: expect.any(FormData)
+            })
         );
     });
 });

package/test/tools/add_results.test.ts

@@ -0,0 +1,94 @@
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { addResultsTool } from '../../src/tools/add_results.js';
+import { TestRailClient } from '../../src/client/testrail.js';
+import { Result } from '../../src/types/testrail.js';
+
+describe('add_results tool', () => {
+    let mockClient: jest.Mocked<TestRailClient>;
+    let addResultsMock: jest.Mock<(runId: number, results: Array<Record<string, any>>) => Promise<Result[]>>;
+
+    const mockResults: Result[] = [
+        {
+            id: 1,
+            test_id: 100,
+            status_id: 1,
+            comment: 'Test passed',
+            defects: null
+        },
+        {
+            id: 2,
+            test_id: 101,
+            status_id: 5,
+            comment: 'Test failed',
+            defects: 'BUG-123'
+        }
+    ];
+
+    beforeEach(() => {
+        addResultsMock = jest.fn<(runId: number, results: Array<Record<string, any>>) => Promise<Result[]>>().mockResolvedValue(mockResults);
+
+        mockClient = {
+            addResults: addResultsMock
+        } as unknown as jest.Mocked<TestRailClient>;
+    });
+
+    test('exports correct tool definition', () => {
+        expect(addResultsTool.name).toBe('add_results');
+        expect(addResultsTool.description).toBeDefined();
+        expect(addResultsTool.parameters).toBeDefined();
+    });
+
+    test('handler calls addResults with correct arguments', async () => {
+        const args = {
+            run_id: 50,
+            results: [
+                {
+                    test_id: 100,
+                    status_id: 1,
+                    comment: 'Test passed'
+                },
+                {
+                    test_id: 101,
+                    status_id: 5,
+                    comment: 'Test failed',
+                    defects: 'BUG-123'
+                }
+            ]
+        };
+
+        const result = await addResultsTool.handler(args, mockClient);
+
+        expect(result).toBeDefined();
+        expect(mockClient.addResults).toHaveBeenCalledWith(50, args.results);
+
+        expect(result.success).toBe(true);
+        expect(result.added_count).toBe(2);
+        expect(result.results).toHaveLength(2);
+    });
+
+    test('handler works with single result', async () => {
+        const singleResult = [mockResults[0]];
+        addResultsMock.mockResolvedValue(singleResult);
+
+        const args = {
+            run_id: 50,
+            results: [
+                {
+                    test_id: 100,
+                    status_id: 1,
+                    comment: 'Test passed'
+                }
+            ]
+        };
+
+        const result = await addResultsTool.handler(args, mockClient);
+
+        expect(result.success).toBe(true);
+        expect(result.added_count).toBe(1);
+    });
+
+    test('handler returns error on failure', async () => {
+        addResultsMock.mockRejectedValue(new Error('API Error'));
+        await expect(addResultsTool.handler({ run_id: 50, results: [] }, mockClient)).rejects.toThrow('API Error');
+    });
+});

package/test/tools/add_run.test.ts

@@ -0,0 +1,83 @@
+import { jest } from '@jest/globals';
+import { addRunTool } from '../../src/tools/add_run.js';
+import { TestRailClient } from '../../src/client/testrail.js';
+
+describe('add_run tool', () => {
+    let client: TestRailClient;
+    let addRunMock: any;
+
+    beforeEach(() => {
+        addRunMock = jest.fn();
+        client = {
+            addRun: addRunMock,
+            getCase: jest.fn(),
+        } as any as TestRailClient;
+    });
+
+    test('should wrap client result including only required fields and forcing include_all to false', async () => {
+        const run = {
+            id: 1,
+            name: 'Test Run',
+            description: null,
+            suite_id: 10,
+            project_id: 1,
+            is_completed: false,
+            passed_count: 0,
+            blocked_count: 0,
+            untested_count: 5,
+            retest_count: 0,
+            failed_count: 0,
+            url: 'https://testrail.io/runs/view/1'
+        };
+        addRunMock.mockResolvedValue(run);
+
+        const mockCase = { suite_id: 10 };
+        (client.getCase as jest.Mock<any>).mockResolvedValue(mockCase);
+
+        const result = await addRunTool.handler({ project_id: '1', name: 'Test Run', case_ids: [1] }, client);
+
+        expect(client.getCase).toHaveBeenCalledWith('1');
+        expect(addRunMock).toHaveBeenCalledWith('1', { name: 'Test Run', case_ids: [1], suite_id: 10, include_all: false });
+        expect(result).toEqual(run);
+    });
+
+    test('should wrap client result handling optional fields', async () => {
+        const run = {
+            id: 1,
+            name: 'Test Run',
+            description: 'Description',
+            suite_id: 10,
+            project_id: 1,
+            is_completed: false,
+            passed_count: 0,
+            blocked_count: 0,
+            untested_count: 3,
+            retest_count: 0,
+            failed_count: 0,
+            url: 'https://testrail.io/runs/view/1'
+        };
+        addRunMock.mockResolvedValue(run);
+
+        const mockCase = { suite_id: 10 };
+        (client.getCase as jest.Mock<any>).mockResolvedValue(mockCase);
+
+        const args = {
+            project_id: '1',
+            name: 'Test Run',
+            description: 'Description',
+            case_ids: [1, 2, 3]
+        };
+
+        const result = await addRunTool.handler(args, client);
+
+        expect(client.getCase).toHaveBeenCalledWith('1');
+        expect(addRunMock).toHaveBeenCalledWith('1', {
+            name: 'Test Run',
+            description: 'Description',
+            case_ids: [1, 2, 3],
+            suite_id: 10,
+            include_all: false
+        });
+        expect(result).toEqual(run);
+    });
+});

package/test/tools/get_case.test.ts

@@ -39,7 +39,7 @@ describe('get_case tool', () => {
 
     test('exports correct tool definition', () => {
         expect(getCaseTool.name).toBe('get_case');
-        expect(getCaseTool.description).toBe('Get a test case from TestRail by ID');
+        expect(getCaseTool.description).toBe('Get detailed information about a test case including its custom fields');
         expect(getCaseTool.parameters).toBeDefined();
     });
 

package/test/tools/get_statuses.test.ts

@@ -0,0 +1,56 @@
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { getStatusesTool } from '../../src/tools/get_statuses.js';
+import { TestRailClient } from '../../src/client/testrail.js';
+import { Status } from '../../src/types/testrail.js';
+
+describe('get_statuses tool', () => {
+    let mockClient: jest.Mocked<TestRailClient>;
+    let getStatusesMock: jest.Mock<() => Promise<Status[]>>;
+
+    const mockStatuses: Status[] = [
+        { id: 1, name: 'passed', label: 'Passed' },
+        { id: 2, name: 'blocked', label: 'Blocked' },
+        { id: 3, name: 'untested', label: 'Untested' },
+        { id: 4, name: 'retest', label: 'Retest' },
+        { id: 5, name: 'failed', label: 'Failed' },
+    ];
+
+    beforeEach(() => {
+        getStatusesMock = jest.fn<() => Promise<Status[]>>().mockResolvedValue(mockStatuses);
+
+        mockClient = {
+            getStatuses: getStatusesMock
+        } as unknown as jest.Mocked<TestRailClient>;
+    });
+
+    test('exports correct tool definition', () => {
+        expect(getStatusesTool.name).toBe('get_statuses');
+        expect(getStatusesTool.description).toContain('statuses');
+        expect(getStatusesTool.parameters).toBeDefined();
+    });
+
+    test('handler fetches and returns statuses', async () => {
+        const result = await getStatusesTool.handler({}, mockClient);
+
+        expect(result).toBeDefined();
+        expect(result.statuses).toBeDefined();
+        expect(result.statuses).toHaveLength(5);
+        expect(mockClient.getStatuses).toHaveBeenCalled();
+    });
+
+    test('returns correct status structure', async () => {
+        const result = await getStatusesTool.handler({}, mockClient);
+
+        expect(result.statuses[0]).toEqual({
+            id: 1,
+            name: 'passed',
+            label: 'Passed'
+        });
+    });
+
+    test('handler returns error on failure', async () => {
+        getStatusesMock.mockRejectedValue(new Error('API Error'));
+
+        await expect(getStatusesTool.handler({}, mockClient)).rejects.toThrow('API Error');
+    });
+});

package/test/tools/get_tests.test.ts

@@ -0,0 +1,47 @@
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { getTestsTool } from '../../src/tools/get_tests.js';
+import { TestRailClient } from '../../src/client/testrail.js';
+import { Test } from '../../src/types/testrail.js';
+
+describe('get_tests tool', () => {
+    let mockClient: jest.Mocked<TestRailClient>;
+    let getTestsMock: jest.Mock<(runId: number, statusId?: number[]) => Promise<Test[]>>;
+
+    const mockTests: Test[] = [
+        { id: 1, case_id: 101, status_id: 1, title: 'Test 1', run_id: 1 },
+        { id: 2, case_id: 102, status_id: 2, title: 'Test 2', run_id: 1 },
+    ];
+
+    beforeEach(() => {
+        getTestsMock = jest.fn<(runId: number, statusId?: number[]) => Promise<Test[]>>().mockResolvedValue(mockTests);
+
+        mockClient = {
+            getTests: getTestsMock
+        } as unknown as jest.Mocked<TestRailClient>;
+    });
+
+    test('exports correct tool definition', () => {
+        expect(getTestsTool.name).toBe('get_tests');
+        expect(getTestsTool.description).toBeDefined();
+        expect(getTestsTool.parameters).toBeDefined();
+    });
+
+    test('handler fetches and returns tests', async () => {
+        const result = await getTestsTool.handler({ run_id: 1 }, mockClient);
+
+        expect(result).toBeDefined();
+        expect(result.tests).toBeDefined();
+        expect(result.tests).toHaveLength(2);
+        expect(mockClient.getTests).toHaveBeenCalledWith(1, undefined);
+    });
+
+    test('handler passes status_id filter', async () => {
+        const result = await getTestsTool.handler({ run_id: 1, status_id: [1, 5] }, mockClient);
+        expect(mockClient.getTests).toHaveBeenCalledWith(1, [1, 5]);
+    });
+
+    test('handler returns error on failure', async () => {
+        getTestsMock.mockRejectedValue(new Error('API Error'));
+        await expect(getTestsTool.handler({ run_id: 1 }, mockClient)).rejects.toThrow('API Error');
+    });
+});

package/test/tools/update_cases.test.ts

@@ -33,8 +33,12 @@ describe('update_cases tool', () => {
             .mockResolvedValue(mockUpdatedCases);
 
         mockClient = {
-            updateCases: updateCasesMock
+            updateCases: updateCasesMock,
+            getCase: jest.fn(),
         } as unknown as jest.Mocked<TestRailClient>;
+
+        // Default mock for getCase to avoid failures in unrelated tests
+        (mockClient.getCase as jest.Mock<any>).mockResolvedValue({ suite_id: 1 });
     });
 
     test('exports correct tool definition', () => {
@@ -56,6 +60,30 @@ describe('update_cases tool', () => {
         expect(result.updated_count).toBe(3);
         expect(result.case_ids).toEqual([1, 2, 3]);
         expect(result.message).toContain('3 test cases');
-        expect(mockClient.updateCases).toHaveBeenCalledWith([1, 2, 3], { priority_id: 3 });
+    });
+
+    test('passes case_ids and fields correctly', async () => {
+        const fields = { priority_id: 2, type_id: 1 };
+        const mockCase = { suite_id: 5 } as Case;
+        (mockClient.getCase as jest.Mock<any>).mockResolvedValue(mockCase);
+
+        await updateCasesTool.handler(
+            { case_ids: [10, 20, 30], fields },
+            mockClient
+        );
+
+        expect(mockClient.getCase).toHaveBeenCalledWith('10');
+        expect(mockClient.updateCases).toHaveBeenCalledWith(5, [10, 20, 30], fields);
+    });
+
+    test('handler throws error on failure', async () => {
+        updateCasesMock.mockRejectedValue(new Error('API Error'));
+
+        await expect(
+            updateCasesTool.handler(
+                { case_ids: [1, 2], fields: { priority_id: 2 } },
+                mockClient
+            )
+        ).rejects.toThrow('API Error');
     });
 });