@uarlouski/testrail-mcp-server 2.2.0 → 2.4.0

package/README.md

@@ -36,6 +36,9 @@ Managing test cases manually is tedious and error-prone. With the **TestRail MCP
 
 **No context switching. No tedious copy-pasting. Just ask your AI.**
 
+> [!NOTE]
+> **Compatibility Baseline**: The primary baseline version this MCP server is tested and validated against is **TestRail 10.6.2** (API v2). Older TestRail instances (including pre-7.x pagination) are also supported via built-in backward compatibility.
+
 ## ✨ Key Features & Capabilities
 
 | Capability | Description |
@@ -147,72 +150,37 @@ Once configured, turbo-charge your QA workflow by asking your AI assistant:
 | `TESTRAIL_USERNAME` | Your TestRail user email address | ✅ | |
 | `TESTRAIL_API_KEY` | Your TestRail API key ([Guide](https://support.testrail.com/hc/en-us/articles/7077039051412-Accessing-the-TestRail-API)) | ✅ | |
 | `TESTRAIL_ENABLE_SHARED_STEPS` | Set to `true` to enable Shared Steps management tools | | `false` |
+| `TESTRAIL_ENABLE_CASE_HISTORY` | Set to `true` to enable Case History and revision tracking tools | | `false` |
 | `TESTRAIL_ALLOW_WRITE_OPERATIONS` | Allow write operations (e.g. adding/updating test cases, test runs, sections) | | `true` |
 | `TESTRAIL_ALLOW_READ_OPERATIONS` | Allow read operations (e.g. retrieving projects, test cases, templates) | | `true` |
 | `TESTRAIL_ALLOW_DELETE_OPERATIONS` | Allow delete operations (e.g. deleting cases or shared steps). Enabled strictly via `true`. | | `false` |
+| `TESTRAIL_ENABLE_DEPRECATED_TOOLS` | Enable deprecated tools for backward compatibility. Set to `false` to reduce context token overhead. | | `true` |
+
+### ⚠️ Deprecation Lifecycle & Features Scheduled for Removal
+
+To ensure smooth transitions, deprecated tools remain available by default (`TESTRAIL_ENABLE_DEPRECATED_TOOLS=true`) and will be removed in future major releases:
+
+| Deprecated Tool | Replacement | Status |
+|-----------------|-------------|--------|
+| `add_attachment_to_run` | `add_attachment` (`entity_type: "case" \| "run"`) | Deprecated in `2.3.0`, scheduled for removal in `3.0.0` |
+
+> **💡 Token Tip**: If you are not using legacy tools, set `TESTRAIL_ENABLE_DEPRECATED_TOOLS=false` in your environment to eliminate deprecated tool definitions from the LLM prompt and save tokens!
 
 ---
 
-## 🛠️ Complete Tool Reference
-
-The TestRail MCP Server provides heavily typed, descriptive tools designed specifically for LLM interaction:
-
-> **💡 Pro Tip: Handling Large Data Sets & Permissions**
-> - **Large Data Sets**: For list-based tools like `get_cases` and `get_sections`, you can supply the `output_file` parameter with an absolute file path. The server will bypass the LLM context window by writing the raw JSON directly to disk and returning a concise summary, allowing you to run external scripts against the export!
-> - **Intelligent User Fallback**: When fetching users using `get_users` without admin rights, TestRail denies access globally. The server dynamically catches this permission restriction and falls back to polling all active projects in parallel, retrieving and deduplicating active users so assignees and reviewers can always be mapped.
-
-### 🔭 Discovery & Navigation
-| Tool | Functionality |
-|------|-------------|
-| `query_project` | Retrieve a single project (`action: "one"`) or all active projects (`action: "many"`). |
-| `query_suite` | Retrieve a single test suite (`action: "one"`) or all test suites for a project (`action: "many"`). |
-| `get_sections` | Navigate the precise folder/section hierarchy of any test suite. |
-| `mutate_suite` | Create a new test suite or update an existing one in TestRail. |
-| `mutate_section` | Create a new section or update an existing section in TestRail. |
-| `get_users` | Retrieve active users. Handles per-project filtering and automatic fallback polling for non-admin accounts. |
-
-### 📋 Test Case Management
-| Tool | Functionality |
-|------|-------------|
-| `get_cases` | Query test cases with advanced filtering (priority, template, type, etc.) and pagination. |
-| `get_case` | Fetch complete, structured details of a specific test case, including custom steps and fields. |
-| `add_case` | Seamlessly create a new test case equipped with robust custom field validation. |
-| `update_case` | Modify an existing test case's steps, metadata, or titles. |
-| `update_cases` | Execute bulk-updates on multiple test cases simultaneously to save time. |
-
-### ▶️ Test Execution & Tracking
-| Tool | Functionality |
-|------|-------------|
-| `query_run` | Retrieve a single test run (`action: "one"`) or all test runs for a project (`action: "many"`, supporting filters). |
-| `mutate_run` | Create a new test run or update an existing one in TestRail. |
-| `get_tests` | Retrieve individual tests for a specific test run, with optional status filtering. |
-| `get_results` | Retrieve paginated results for a specific test ID. |
-| `add_results` | Submit test results to a test run using the specific `test_id`. |
-| `add_results_for_cases` | Submits results to a run mapping directly to `case_id`s, streamlining automation workflows. |
-| `add_attachment_to_run` | Attach logs, files, or zipped artifacts directly to an ongoing test run. |
-
-### 🔗 Shared Steps (Optional)
-| Tool | Functionality |
-|------|-------------|
-| `get_shared_steps` | List shared test steps for a project with optional reference filtering. |
-| `get_shared_step` | Retrieve precise details of a specific shared test step set. |
-| `get_shared_step_history` | View the complete audit trail and version history of a shared step set. |
-| `add_shared_step` | Create a new reusable set of shared test steps. |
-| `update_shared_step` | Modify an existing shared step set (changes propagate to all linked test cases). |
-
-### 🗑️ Deletion
-| Tool | Functionality |
-|------|-------------|
-| `delete_entity` | Deletes a specified TestRail entity (supports `"case"` or `"shared_step"`) by its ID. Requires `TESTRAIL_ALLOW_DELETE_OPERATIONS` to be set to `true` in your environment. |
-
-### 🧠 System Metadata
-| Tool | Functionality |
-|------|-------------|
-| `get_statuses` | Systematically list all configured test statuses (Passed, Failed, Blocked, Retest, etc.). |
-| `get_priorities` | Retrieve priority levels configured within your instance structure. |
-| `get_case_fields` | Discover custom field definitions, formats, and UI dropdown options. Supports filtering by `project_id`. |
-| `get_templates` | Identify available case templates to mandate correct AI structuring. |
-| `get_configurations` | Retrieve all configuration groups and configurations for a project. |
+## 📚 Documentation & Complete Tool Reference
+
+For a comprehensive guide, detailed configuration options, and a complete breakdown of all available tools, please visit our official documentation site:
+
+**👉 [TestRail MCP Server Documentation](https://uarlouski.github.io/testrail-mcp-server/)**
+
+The documentation includes detailed explanations for:
+- 🔭 **Discovery & Navigation**: Exploring projects, suites, and sections.
+- 📋 **Test Case Management**: Fetching, creating, and bulk-updating test cases.
+- ▶️ **Execution & Tracking**: Managing test runs and submitting test results.
+- 📎 **Attachments**: Automatically zipping and uploading files or directories.
+- 🔗 **Shared Steps**: Managing reusable step definitions.
+
 
 ---
 

package/dist/client/testrail.js

@@ -1,5 +1,6 @@
 import { isActive } from "../utils/sanitizer.js";
 import * as fs from "fs";
+import * as path from "path";
 const API_INDEX = '/index.php?';
 const API_BASE_V2 = `${API_INDEX}/api/v2`;
 export class TestRailClient {
@@ -24,6 +25,9 @@ export class TestRailClient {
     async getCase(caseId) {
         return this.get(`${API_BASE_V2}/get_case/${caseId}`);
     }
+    async getCaseHistory(caseId) {
+        return this.paginateAll(`${API_BASE_V2}/get_history_for_case/${caseId}`, 'history');
+    }
     async getCasesRecursively(projectId, sectionId, filter, excludedSectionNames) {
         // Extract suite_id from filter if present, for getSections call
         const suiteId = filter?.suite_id ? parseInt(filter.suite_id) : undefined;
@@ -178,7 +182,7 @@ export class TestRailClient {
     async addResultsForCases(runId, results) {
         return this.post(`${API_BASE_V2}/add_results_for_cases/${runId}`, { results });
     }
-    async addAttachmentToRun(runId, filePath, filename) {
+    async addAttachment(entityType, entityId, filePath, filename) {
         const fileBuffer = await fs.promises.readFile(filePath);
         const blob = new Blob([fileBuffer]);
         const formData = new FormData();
@@ -186,7 +190,11 @@ export class TestRailClient {
         const headers = {
             'Authorization': this.auth,
         };
-        return this._executeRequest('POST', `${API_BASE_V2}/add_attachment_to_run/${runId}`, headers, formData);
+        return this._executeRequest('POST', `${API_BASE_V2}/add_attachment_to_${entityType}/${entityId}`, headers, formData);
+    }
+    async getAttachments(entityType, entityId) {
+        const url = `${API_BASE_V2}/get_attachments_for_${entityType}/${entityId}`;
+        return this.paginateAll(url, 'attachments');
     }
     async getSharedSteps(projectId, options) {
         let url = `${API_BASE_V2}/get_shared_steps/${projectId}`;
@@ -207,11 +215,26 @@ export class TestRailClient {
     async updateSharedStep(sharedStepId, data) {
         return this.post(`${API_BASE_V2}/update_shared_step/${sharedStepId}`, data);
     }
+    async getAttachment(attachmentId, outputFilePath) {
+        const dir = path.dirname(outputFilePath);
+        if (dir && !fs.existsSync(dir)) {
+            await fs.promises.mkdir(dir, { recursive: true });
+        }
+        const buffer = await this._executeRequest('GET', `${API_BASE_V2}/get_attachment/${attachmentId}`, this.headers, undefined, 'buffer');
+        await fs.promises.writeFile(outputFilePath, buffer);
+        return {
+            file: outputFilePath,
+            size: buffer.byteLength,
+        };
+    }
     async deleteCase(caseId) {
-        return this._executeRequest('POST', `${API_BASE_V2}/delete_case/${caseId}`, this.headers, JSON.stringify({}), false);
+        return this._executeRequest('POST', `${API_BASE_V2}/delete_case/${caseId}`, this.headers, JSON.stringify({}), 'text');
     }
     async deleteSharedStep(sharedStepId) {
-        return this._executeRequest('POST', `${API_BASE_V2}/delete_shared_step/${sharedStepId}`, this.headers, JSON.stringify({}), false);
+        return this._executeRequest('POST', `${API_BASE_V2}/delete_shared_step/${sharedStepId}`, this.headers, JSON.stringify({}), 'text');
+    }
+    async deleteAttachment(attachmentId) {
+        return this._executeRequest('POST', `${API_BASE_V2}/delete_attachment/${attachmentId}`, this.headers, JSON.stringify({}), 'text');
     }
     async getUsers(projectId) {
         const url = projectId
@@ -254,7 +277,7 @@ export class TestRailClient {
         }
         return this._executeRequest(method, endpoint, this.headers, jsonData);
     }
-    async _executeRequest(method, endpoint, headers, body, parseBody = true) {
+    async _executeRequest(method, endpoint, headers, body, responseType = 'json') {
         const url = `${this.baseUrl}${endpoint}`;
         const params = {
             method,
@@ -292,9 +315,13 @@ export class TestRailClient {
                     console.error(`[TestRailClient] Error Details: ${errorMessage}`);
                     throw new Error(errorMessage);
                 }
-                if (parseBody) {
+                if (responseType === 'json') {
                     return await response.json();
                 }
+                else if (responseType === 'buffer') {
+                    const arrayBuffer = await response.arrayBuffer();
+                    return Buffer.from(arrayBuffer);
+                }
                 return await response.text();
             }
             catch (error) {

package/dist/index.js

@@ -11,26 +11,30 @@ const EnvSchema = z.object({
     TESTRAIL_USERNAME: z.email('Must be a valid email address'),
     TESTRAIL_API_KEY: z.string().min(1, 'API key is required'),
     TESTRAIL_ENABLE_SHARED_STEPS: z.string().optional().transform(val => val === 'true'),
+    TESTRAIL_ENABLE_CASE_HISTORY: z.string().optional().transform(val => val === 'true'),
     TESTRAIL_ALLOW_WRITE_OPERATIONS: z.string().optional().transform(val => val === undefined ? true : val === 'true'),
     TESTRAIL_ALLOW_READ_OPERATIONS: z.string().optional().transform(val => val === undefined ? true : val === 'true'),
-    TESTRAIL_ALLOW_DELETE_OPERATIONS: z.string().optional().transform(val => val === 'true')
+    TESTRAIL_ALLOW_DELETE_OPERATIONS: z.string().optional().transform(val => val === 'true'),
+    TESTRAIL_ENABLE_DEPRECATED_TOOLS: z.string().optional().transform(val => val === undefined ? true : val === 'true')
 });
 const parseResult = EnvSchema.safeParse(process.env);
 if (!parseResult.success) {
     console.error("Invalid TestRail environment configuration:", JSON.stringify(z.treeifyError(parseResult.error), null, 2));
     process.exit(1);
 }
-const { TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY, TESTRAIL_ENABLE_SHARED_STEPS, TESTRAIL_ALLOW_WRITE_OPERATIONS, TESTRAIL_ALLOW_READ_OPERATIONS, TESTRAIL_ALLOW_DELETE_OPERATIONS } = parseResult.data;
+const { TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY, TESTRAIL_ENABLE_SHARED_STEPS, TESTRAIL_ENABLE_CASE_HISTORY, TESTRAIL_ALLOW_WRITE_OPERATIONS, TESTRAIL_ALLOW_READ_OPERATIONS, TESTRAIL_ALLOW_DELETE_OPERATIONS, TESTRAIL_ENABLE_DEPRECATED_TOOLS } = parseResult.data;
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "2.2.0",
+    version: "2.4.0",
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
 const tools = getToolsToRegister({
     enableSharedSteps: TESTRAIL_ENABLE_SHARED_STEPS,
+    enableCaseHistory: TESTRAIL_ENABLE_CASE_HISTORY,
     allowWrite: TESTRAIL_ALLOW_WRITE_OPERATIONS,
     allowRead: TESTRAIL_ALLOW_READ_OPERATIONS,
-    allowDelete: TESTRAIL_ALLOW_DELETE_OPERATIONS
+    allowDelete: TESTRAIL_ALLOW_DELETE_OPERATIONS,
+    enableDeprecatedTools: TESTRAIL_ENABLE_DEPRECATED_TOOLS
 });
 for (const tool of tools) {
     server.registerTool(tool.name, {

package/dist/tools/attachments/add_attachment.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { AttachmentSchema } from "./types.js";
+import { normalizeEntityId, prepareUploadFile } from "../../utils/attachment_helper.js";
+const parameters = {
+    entity_type: z.enum(["case", "run"]).describe("The type of entity to attach the file to ('case' or 'run')"),
+    entity_id: z.union([z.number(), z.string()]).describe("The ID of the entity to attach the file to (e.g. 123 or 'C123' for cases, or numeric run ID)"),
+    file_path: z.string().describe("The path to the file or directory to attach. Directories will be automatically zipped."),
+};
+const description = `
+Add an attachment to a test case or test run in TestRail.
+If the file_path points to a directory, it will be automatically zipped before uploading.
+Maximum upload size is 256MB.
+`;
+export const addAttachmentTool = {
+    name: "add_attachment",
+    mode: "write",
+    description: description.trim(),
+    parameters,
+    handler: async ({ entity_type, entity_id, file_path }, client) => {
+        const normalizedId = normalizeEntityId(entity_id);
+        return prepareUploadFile(file_path, async (uploadPath, filename) => {
+            const result = await client.addAttachment(entity_type, normalizedId, uploadPath, filename);
+            return AttachmentSchema.parse(result);
+        });
+    },
+};

package/dist/tools/attachments/index.js

@@ -0,0 +1,6 @@
+import { addAttachmentTool } from "./add_attachment.js";
+import { queryAttachmentTool } from "./query_attachment.js";
+export const attachmentsTools = [
+    addAttachmentTool,
+    queryAttachmentTool,
+];

package/dist/tools/attachments/query_attachment.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import * as fs from "fs";
+import { AttachmentItemSchema, GetOneAttachmentSchema, GetManyAttachmentsSchema } from "./types.js";
+import { normalizeEntityId } from "../../utils/attachment_helper.js";
+import { handleQuery } from "../../utils/query_handler.js";
+const parameters = {
+    payload: z.discriminatedUnion("action", [
+        GetOneAttachmentSchema,
+        GetManyAttachmentsSchema,
+    ]).describe("The payload containing the action ('one' or 'many') and corresponding parameters"),
+};
+export const queryAttachmentTool = {
+    name: "query_attachment",
+    mode: "read",
+    description: "Download a single attachment or list all attachments for a test case or test run in TestRail. Set payload.action to 'one' or 'many' to specify the operation.",
+    parameters,
+    handler: async (args, client) => {
+        return handleQuery(args.payload, async (p) => {
+            const downloadResult = await client.getAttachment(p.attachment_id, p.output_file);
+            return {
+                success: true,
+                message: `Successfully downloaded attachment ${p.attachment_id} (${downloadResult.size} bytes) to ${downloadResult.file}`,
+                file: downloadResult.file,
+                size: downloadResult.size,
+            };
+        }, async (p) => {
+            const normalizedId = normalizeEntityId(p.entity_id);
+            const attachments = await client.getAttachments(p.entity_type, normalizedId);
+            const parsedAttachments = attachments.map(item => AttachmentItemSchema.parse(item));
+            const response = {
+                attachments: parsedAttachments,
+            };
+            if (p.output_file) {
+                await fs.promises.writeFile(p.output_file, JSON.stringify(response), "utf-8");
+                return {
+                    success: true,
+                    message: `Successfully exported ${response.attachments.length} attachments to ${p.output_file}`,
+                    file: p.output_file,
+                };
+            }
+            return response;
+        });
+    },
+};

package/dist/tools/attachments/types.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export const AttachmentSchema = z.object({
+    attachment_id: z.union([z.number(), z.string()]),
+});
+export const AttachmentItemSchema = z.object({
+    id: z.union([z.number(), z.string()]),
+    filename: z.string().optional(),
+    size: z.number().optional(),
+    file_type: z.string().optional(),
+    is_image: z.union([z.boolean(), z.number()]).optional(),
+});
+export const AddAttachmentSchema = z.object({
+    entity_type: z.enum(["case", "run"]).describe("The type of entity to attach the file to ('case' or 'run')"),
+    entity_id: z.union([z.number(), z.string()]).describe("The ID of the entity to attach the file to (e.g. 123 or 'C123' for cases, or numeric run ID)"),
+    file_path: z.string().describe("The path to the file or directory to attach. Directories will be automatically zipped."),
+});
+export const GetOneAttachmentSchema = z.object({
+    action: z.literal("one").describe("Download a single attachment by ID and save to local filesystem"),
+    attachment_id: z.union([z.number(), z.string()]).describe("The ID of the attachment to download (numeric ID or UUID)"),
+    output_file: z.string().describe("Absolute local file path where the downloaded attachment will be saved"),
+});
+export const GetManyAttachmentsSchema = z.object({
+    action: z.literal("many").describe("Retrieve attachment metadata for a test case or test run"),
+    entity_type: z.enum(["case", "run"]).describe("The type of entity to get attachments for ('case' or 'run')"),
+    entity_id: z.union([z.number(), z.string()]).describe("The ID of the entity (e.g. 123 or 'C123' for cases, or numeric run ID)"),
+    output_file: z.string().optional().describe("Optional absolute file path to export large metadata JSON responses"),
+});

package/dist/tools/cases/get_case.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { processCustomFields } from "../../utils/mapper.js";
+import { normalizeEntityId } from "../../utils/sanitizer.js";
 import { LabelSchema } from "../commons/types.js";
 const parameters = {
     case_id: z.string().describe("The ID of the test case (e.g. '123' or 'C123')"),
@@ -10,8 +11,7 @@ export const getCaseTool = {
     description: "Get detailed information about a test case including its custom fields",
     parameters,
     handler: async ({ case_id }, client) => {
-        const idString = case_id.toUpperCase().startsWith("C") ? case_id.substring(1) : case_id;
-        const id = Number(idString);
+        const id = normalizeEntityId(case_id);
         const testCase = await client.getCase(id);
         const [section, caseTypes, priorities, caseFields] = await Promise.all([
             client.getSection(Number(testCase.section_id)),

package/dist/tools/cases/get_case_history.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import fs from "fs";
+import path from "path";
+import { normalizeEntityId } from "../../utils/sanitizer.js";
+import { CaseHistoryEntrySchema } from "./types.js";
+const parameters = {
+    case_id: z.string().describe("The ID of the test case (e.g. '123' or 'C123')"),
+    limit: z.number().min(1).optional().describe("Maximum number of revisions to return (e.g. 5 for the last 5 revisions)"),
+    after_revision: z.number().optional().describe("Filter to only include revisions strictly newer than this revision ID (id > after_revision)"),
+    after_timestamp: z.number().optional().describe("Filter to only include revisions created after this unix timestamp (created_on > after_timestamp)"),
+    order: z.enum(["desc", "asc"]).optional().default("desc").describe("Sort order for the returned history entries ('desc' for newest-to-oldest, 'asc' for oldest-to-newest). Default is 'desc'"),
+    output_file: z.string().optional().describe("Absolute file path to save the JSON response to. Useful for large history change logs to avoid context limits."),
+};
+export const getCaseHistoryTool = {
+    name: "get_case_history",
+    mode: "read",
+    description: "Returns the revision and change history of a test case. Useful for tracking case updates, checking changes since a specific revision or timestamp, or getting the last N revisions.",
+    parameters,
+    handler: async ({ case_id, limit, after_revision, after_timestamp, order = "desc", output_file }, client) => {
+        const id = normalizeEntityId(case_id);
+        const allHistory = await client.getCaseHistory(id);
+        let latestRevision = null;
+        if (allHistory.length > 0) {
+            const sortedByRevisionDesc = [...allHistory].sort((a, b) => b.id - a.id);
+            latestRevision = sortedByRevisionDesc[0].id;
+        }
+        let filtered = [...allHistory];
+        if (after_revision !== undefined) {
+            filtered = filtered.filter(entry => entry.id > after_revision);
+        }
+        if (after_timestamp !== undefined) {
+            filtered = filtered.filter(entry => (entry.created_on ?? 0) > after_timestamp);
+        }
+        filtered.sort((a, b) => {
+            if (order === "asc") {
+                return a.id - b.id;
+            }
+            return b.id - a.id;
+        });
+        if (limit !== undefined) {
+            filtered = filtered.slice(0, limit);
+        }
+        const parsedHistory = filtered.map(h => CaseHistoryEntrySchema.parse(h));
+        const response = {
+            case_id: id,
+            latest_revision: latestRevision,
+            has_changes: parsedHistory.length > 0,
+            history: parsedHistory,
+        };
+        if (output_file) {
+            const dir = path.dirname(output_file);
+            if (dir && !fs.existsSync(dir)) {
+                await fs.promises.mkdir(dir, { recursive: true });
+            }
+            await fs.promises.writeFile(output_file, JSON.stringify(response, null, 2), "utf-8");
+            return {
+                success: true,
+                message: `Successfully exported ${response.history.length} history records to ${output_file}`,
+                file: output_file,
+                latest_revision: latestRevision,
+                has_changes: response.has_changes,
+            };
+        }
+        return response;
+    },
+};

package/dist/tools/cases/index.js

@@ -4,6 +4,8 @@ import { getCaseFieldsTool } from "./get_case_fields.js";
 import { updateCaseTool } from "./update_case.js";
 import { updateCasesTool } from "./update_cases.js";
 import { addCaseTool } from "./add_case.js";
+import { getCaseHistoryTool } from "./get_case_history.js";
+export { getCaseHistoryTool };
 export const casesTools = [
     getCaseTool,
     getCasesTool,

package/dist/tools/cases/types.js

@@ -38,3 +38,19 @@ export const CaseSchema = z.object({
     suite_id: z.number(),
     labels: z.array(LabelSchema),
 }).loose();
+export const CaseHistoryChangeSchema = z.object({
+    field: z.string(),
+    old_value: z.any().nullable().optional(),
+    new_value: z.any().nullable().optional(),
+});
+export const CaseHistoryEntrySchema = z.object({
+    id: z.number(),
+    created_on: z.number().optional(),
+    changes: z.array(CaseHistoryChangeSchema).optional().default([]),
+});
+export const CaseHistoryResponseSchema = z.object({
+    case_id: z.number(),
+    latest_revision: z.number().nullable(),
+    has_changes: z.boolean(),
+    history: z.array(CaseHistoryEntrySchema),
+});

package/dist/tools/cases/update_case.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { validateCaseFields } from "../../utils/validator.js";
+import { normalizeEntityId } from "../../utils/sanitizer.js";
 import { CASE_FIELDS_PARAM_DESCRIPTION } from "./get_case_fields.js";
 const parameters = {
     case_id: z.string().describe("The ID of the test case to update (e.g. '123' or 'C123')"),
@@ -17,8 +18,7 @@ export const updateCaseTool = {
     parameters,
     handler: async ({ case_id, fields }, client) => {
         validateCaseFields(fields, await client.getCaseFields());
-        const idString = case_id.toUpperCase().startsWith("C") ? case_id.substring(1) : case_id;
-        const id = Number(idString);
+        const id = normalizeEntityId(case_id);
         const updatedCase = await client.updateCase(id, fields);
         return {
             success: true,

package/dist/tools/commons/delete_entity.js

@@ -1,22 +1,28 @@
 import { z } from "zod";
 const parameters = {
-    entity_type: z.enum(["case", "shared_step"]).describe("The type of the entity to delete"),
+    entity_type: z.enum(["case", "shared_step", "attachment"]).describe("The type of the entity to delete"),
     entity_id: z.number().describe("The ID of the entity to delete"),
 };
 export const deleteEntityTool = {
     name: "delete_entity",
     mode: "delete",
-    description: "Deletes a specified TestRail entity (case or shared_step) by its ID.",
+    description: "Deletes a specified TestRail entity (case, shared_step, or attachment) by its ID.",
     parameters,
     handler: async (args, client) => {
         const { entity_type, entity_id } = args;
         switch (entity_type) {
-            case "case":
+            case "case": {
                 await client.deleteCase(entity_id);
                 return { message: `Case ${entity_id} deleted successfully.` };
-            case "shared_step":
+            }
+            case "shared_step": {
                 await client.deleteSharedStep(entity_id);
                 return { message: `Shared step ${entity_id} deleted successfully.` };
+            }
+            case "attachment": {
+                await client.deleteAttachment(entity_id);
+                return { message: `Attachment ${entity_id} deleted successfully.` };
+            }
             default:
                 throw new Error(`Unsupported entity type: ${entity_type}`);
         }

package/dist/tools/registry.js

@@ -1,4 +1,4 @@
-import { casesTools } from "./cases/index.js";
+import { casesTools, getCaseHistoryTool } from "./cases/index.js";
 import { projectsTools } from "./projects/index.js";
 import { suitesTools } from "./suites/index.js";
 import { sectionsTools } from "./sections/index.js";
@@ -6,6 +6,7 @@ import { runsTools } from "./runs/index.js";
 import { sharedStepsTools } from "./shared_steps/index.js";
 import { resultsTools } from "./results/index.js";
 import { commonsTools } from "./commons/index.js";
+import { attachmentsTools } from "./attachments/index.js";
 export function getToolsToRegister(config) {
     const tools = [
         ...projectsTools,
@@ -14,15 +15,22 @@ export function getToolsToRegister(config) {
         ...sectionsTools,
         ...runsTools,
         ...resultsTools,
+        ...attachmentsTools,
         ...commonsTools,
     ];
     if (config.enableSharedSteps) {
         tools.push(...sharedStepsTools);
     }
+    if (config.enableCaseHistory) {
+        tools.push(getCaseHistoryTool);
+    }
     const allowWrite = config.allowWrite !== false;
     const allowRead = config.allowRead !== false;
     const allowDelete = config.allowDelete === true;
+    const enableDeprecatedTools = config.enableDeprecatedTools !== false;
     const filteredTools = tools.filter(tool => {
+        if (tool.deprecated && !enableDeprecatedTools)
+            return false;
         if (tool.mode === 'write')
             return allowWrite;
         if (tool.mode === 'read')

package/dist/tools/runs/add_attachment_to_run.js

@@ -1,53 +1,23 @@
 import { z } from "zod";
-import { AttachmentSchema } from "./types.js";
-import * as fs from "fs";
-import * as path from "path";
-import * as os from "os";
-import archiver from "archiver";
+import { AttachmentSchema } from "../attachments/types.js";
+import { prepareUploadFile } from "../../utils/attachment_helper.js";
 const parameters = {
     run_id: z.number().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."),
 };
+/**
+ * @deprecated Use `add_attachment` tool from the attachments domain instead.
+ */
 export const addAttachmentToRunTool = {
     name: "add_attachment_to_run",
     mode: "write",
-    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.",
+    deprecated: true,
+    description: "Add an attachment to a test run in TestRail. (Deprecated: Prefer add_attachment tool). Maximum upload size is 256MB.",
     parameters,
     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 = 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((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(run_id, uploadPath, filename);
+        return prepareUploadFile(file_path, async (uploadPath, filename) => {
+            const result = await client.addAttachment('run', run_id, uploadPath, filename);
             return AttachmentSchema.parse(result);
-        }
-        finally {
-            if (isTemporary && fs.existsSync(uploadPath)) {
-                fs.unlinkSync(uploadPath);
-            }
-        }
+        });
     },
 };

package/dist/tools/runs/index.js

@@ -1,6 +1,6 @@
+import { addAttachmentToRunTool } from "./add_attachment_to_run.js";
 import { mutateRunTool } from "./mutate_run.js";
 import { queryRunTool } from "./query_run.js";
-import { addAttachmentToRunTool } from "./add_attachment_to_run.js";
 export const runsTools = [
     mutateRunTool,
     queryRunTool,

package/dist/utils/attachment_helper.js

@@ -0,0 +1,46 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import archiver from "archiver";
+export { normalizeEntityId } from "./sanitizer.js";
+/**
+ * Prepares a file or directory for upload.
+ * If the path points to a directory, it will automatically be zipped to a temporary archive.
+ * Ensures temporary zip files are cleaned up in a finally block.
+ */
+export async function prepareUploadFile(filePath, uploadCallback) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File or directory not found: ${filePath}`);
+    }
+    const stats = fs.statSync(filePath);
+    let uploadPath = filePath;
+    let filename = path.basename(filePath);
+    let isTemporary = false;
+    if (stats.isDirectory()) {
+        const basename = path.basename(filePath);
+        const tempDir = os.tmpdir();
+        const zipPath = path.join(tempDir, `${basename}-${Date.now()}.zip`);
+        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(filePath, basename);
+            archive.finalize();
+        });
+        uploadPath = zipPath;
+        filename = `${basename}.zip`;
+        isTemporary = true;
+    }
+    try {
+        return await uploadCallback(uploadPath, filename);
+    }
+    finally {
+        if (isTemporary && fs.existsSync(uploadPath)) {
+            fs.unlinkSync(uploadPath);
+        }
+    }
+}

package/dist/utils/sanitizer.js

@@ -55,3 +55,16 @@ export function isActive(value) {
     const activeFlag = (typeof value === 'object') ? value.is_active : value;
     return activeFlag === 1 || activeFlag === true || activeFlag === '1' || activeFlag === 'true';
 }
+/**
+ * Normalizes an entity ID (e.g. case ID, run ID, attachment ID).
+ * Handles string IDs with 'C' prefixes (e.g. 'C123' -> 123), numeric IDs, and trims whitespace.
+ */
+export function normalizeEntityId(id) {
+    const idString = typeof id === "string" ? id.trim() : String(id);
+    const cleaned = idString.toUpperCase().startsWith("C") ? idString.substring(1) : idString;
+    const parsed = Number(cleaned);
+    if (isNaN(parsed)) {
+        throw new Error(`Invalid entity ID: ${id}`);
+    }
+    return parsed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "mcpName": "io.github.uarlouski/testrail-mcp-server",
   "description": "Model Context Protocol (MCP) server for TestRail integration, enabling LLMs to fetch test cases and metadata.",
   "main": "dist/index.js",
@@ -14,13 +14,21 @@
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "mcp-server",
     "testrail",
     "server",
     "typescript",
     "llm",
     "ai",
+    "ai-agents",
     "testing",
-    "automation"
+    "automation",
+    "qa-automation",
+    "qa-tools",
+    "test-management",
+    "claude",
+    "cursor",
+    "windsurf"
   ],
   "author": "Uladzislau Arlouski",
   "repository": {
@@ -39,6 +47,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@jest/globals": "^29.7.0",
     "@types/archiver": "^7.0.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.5.0",
@@ -47,7 +56,8 @@
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3",
-    "@jest/globals": "^29.7.0"
+    "vitepress": "^1.6.4",
+    "vue": "^3.5.41"
   },
   "devEngines": {
     "packageManager": {
@@ -61,6 +71,9 @@
     "start": "node dist/index.js",
     "dev": "ts-node src/index.ts",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   }
 }