@uarlouski/testrail-mcp-server 2.2.0 → 2.3.0

package/README.md

@@ -150,6 +150,17 @@ Once configured, turbo-charge your QA workflow by asking your AI assistant:
 | `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!
 
 ---
 
@@ -189,7 +200,12 @@ The TestRail MCP Server provides heavily typed, descriptive tools designed speci
 | `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. |
+
+### 📎 Attachments & Media
+| Tool | Functionality |
+|------|-------------|
+| `add_attachment` | Add an attachment (screenshot, log, file, or auto-zipped directory) to a test case or test run (`entity_type: "case" \| "run"`). |
+| `query_attachment` | Download an attachment to a local file (`action: "one"`) or retrieve attachment metadata for a test case or test run (`action: "many"`, supporting `output_file` export). |
 
 ### 🔗 Shared Steps (Optional)
 | Tool | Functionality |
@@ -203,7 +219,7 @@ The TestRail MCP Server provides heavily typed, descriptive tools designed speci
 ### 🗑️ 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. |
+| `delete_entity` | Deletes a specified TestRail entity (supports `"case"`, `"shared_step"`, or `"attachment"`) by its ID. Requires `TESTRAIL_ALLOW_DELETE_OPERATIONS` to be set to `true` in your environment. |
 
 ### 🧠 System Metadata
 | Tool | Functionality |

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 {
@@ -178,7 +179,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 +187,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 +212,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 +274,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 +312,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

@@ -13,24 +13,26 @@ const EnvSchema = z.object({
     TESTRAIL_ENABLE_SHARED_STEPS: 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_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.3.0",
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
 const tools = getToolsToRegister({
     enableSharedSteps: TESTRAIL_ENABLE_SHARED_STEPS,
     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/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

@@ -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,6 +15,7 @@ export function getToolsToRegister(config) {
         ...sectionsTools,
         ...runsTools,
         ...resultsTools,
+        ...attachmentsTools,
         ...commonsTools,
     ];
     if (config.enableSharedSteps) {
@@ -22,7 +24,10 @@ export function getToolsToRegister(config) {
     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,58 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import archiver from "archiver";
+/**
+ * Normalizes an entity ID (case ID or run ID).
+ * Handles string IDs with 'C' prefixes (e.g. 'C123' -> 123) and numeric IDs.
+ */
+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;
+}
+/**
+ * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "2.2.0",
+  "version": "2.3.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",