@uarlouski/testrail-mcp-server 1.9.0 → 1.11.0

package/README.md

@@ -15,6 +15,7 @@
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-blue.svg" alt="TypeScript"></a>
   <a href="https://github.com/uarlouski/testrail-mcp-server"><img src="https://img.shields.io/github/stars/uarlouski/testrail-mcp-server.svg?style=social&label=Star" alt="GitHub stars"></a>
+  <a href="https://glama.ai/mcp/servers/uarlouski/testrail-mcp-server"><img src="https://glama.ai/mcp/servers/uarlouski/testrail-mcp-server/badges/score.svg" alt="Score Badge"></a>
 </p>
 
 <p align="center">
@@ -130,6 +131,7 @@ Any MCP-compliant client can utilize this server. The pattern is universal—poi
 Once configured, turbo-charge your QA workflow by asking your AI assistant:
 
 - *"List all projects in TestRail to find the latest active project."*
+- *"Show me all active users in the project to find the right assignee."*
 - *"Show me all test cases in section 5 of project 3."*
 - *"Create a comprehensive test case for 'Login Validation' with detailed steps."*
 - *"Start a new test run containing cases from section 5."*
@@ -152,11 +154,16 @@ Once configured, turbo-charge your QA workflow by asking your AI assistant:
 
 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 |
 |------|-------------|
 | `get_projects` | List all available active and completed projects in your instance. |
 | `get_sections` | Navigate the precise folder/section hierarchy of any test suite. |
+| `get_users` | Retrieve active users. Handles per-project filtering and automatic fallback polling for non-admin accounts. |
 
 ### 📋 Test Case Management
 | Tool | Functionality |

package/dist/client/testrail.js

@@ -1,3 +1,4 @@
+import { isActive } from "../utils/sanitizer.js";
 import * as fs from "fs";
 const API_INDEX = '/index.php?';
 const API_BASE_V2 = `${API_INDEX}/api/v2`;
@@ -161,6 +162,13 @@ export class TestRailClient {
     async deleteSharedStep(sharedStepId) {
         return this._executeRequest('POST', `${API_BASE_V2}/delete_shared_step/${sharedStepId}`, this.headers, JSON.stringify({}), false);
     }
+    async getUsers(projectId) {
+        const url = projectId
+            ? `${API_BASE_V2}/get_users/${projectId}`
+            : `${API_BASE_V2}/get_users`;
+        const allUsers = await this.paginateAll(url, 'users');
+        return allUsers.filter(isActive);
+    }
     async paginateAll(url, dataKey) {
         const allItems = [];
         let nextUrl = url;

package/dist/index.js

@@ -20,6 +20,7 @@ import { addResultsTool } from "./tools/add_results.js";
 import { addAttachmentToRunTool } from "./tools/add_attachment_to_run.js";
 import { addResultsForCasesTool } from "./tools/add_results_for_cases.js";
 import { getLabelsTool } from "./tools/get_labels.js";
+import { getUsersTool } from "./tools/get_users.js";
 import { getSharedStepsTool } from "./tools/shared_steps/get_shared_steps.js";
 import { getSharedStepTool } from "./tools/shared_steps/get_shared_step.js";
 import { getSharedStepHistoryTool } from "./tools/shared_steps/get_shared_step_history.js";
@@ -42,7 +43,7 @@ if (!parseResult.success) {
 const { TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY, TESTRAIL_ENABLE_SHARED_STEPS } = parseResult.data;
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "1.9.0",
+    version: "1.11.0",
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
 const tools = [
@@ -63,6 +64,7 @@ const tools = [
     addResultsForCasesTool,
     addAttachmentToRunTool,
     getLabelsTool,
+    getUsersTool,
 ];
 if (TESTRAIL_ENABLE_SHARED_STEPS) {
     tools.push(getSharedStepsTool);

package/dist/tools/get_case_fields.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { parseDropdownOptions } from "../utils/mapper.js";
+import { isActive } from "../utils/sanitizer.js";
 // Field remains optional for backward compatibility with previous implementation.
 // However, it is recommended to always provide project_id to get fields applicable to the project.
 const parameters = {
@@ -88,7 +89,7 @@ export const getCaseFieldsTool = {
     parameters,
     handler: async ({ project_id }, client) => {
         const caseFields = await client.getCaseFields();
-        const activeFields = caseFields.filter(field => field.is_active);
+        const activeFields = caseFields.filter(isActive);
         const filtered = project_id !== undefined
             ? activeFields.filter(field => isFieldForProject(field, project_id))
             : activeFields;

package/dist/tools/get_cases.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import fs from "fs";
 import { validateCaseFields } from "../utils/validator.js";
 const parameters = {
     project_id: z.number().describe("The ID of the project. Use get_projects to find available projects"),
@@ -10,12 +11,13 @@ const parameters = {
     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\"]"),
+    output_file: z.string().optional().describe("Absolute file path to save the JSON response to. Use this for large datasets to avoid blowing up context limits."),
 };
 export const getCasesTool = {
     name: "get_cases",
     description: "Get all test cases for a project. Filter by section, API params (priority, type), or any field including custom fields via 'where'. Returns case IDs, titles, and any additional requested fields.",
     parameters,
-    handler: async ({ project_id, section, filter, where, fields }, client) => {
+    handler: async ({ project_id, section, filter, where, fields, output_file }, client) => {
         const caseFields = await client.getCaseFields();
         if (fields) {
             validateCaseFields(fields, caseFields);
@@ -59,6 +61,14 @@ export const getCasesTool = {
                 return result;
             }),
         };
+        if (output_file) {
+            await fs.promises.writeFile(output_file, JSON.stringify(response), "utf-8");
+            return {
+                success: true,
+                message: `Successfully exported ${response.cases.length} cases to ${output_file}`,
+                file: output_file
+            };
+        }
         return response;
     }
 };

package/dist/tools/get_sections.js

@@ -1,16 +1,27 @@
 import { z } from "zod";
+import fs from "fs";
 import { SectionSchema } from "../types/testrail.js";
 const parameters = {
     project_id: z.number().describe("The ID of the project. Use get_projects to find available projects"),
+    output_file: z.string().optional().describe("Absolute file path to save the JSON response to. Use this for large datasets to avoid blowing up context limits."),
 };
 export const getSectionsTool = {
     name: "get_sections",
     description: "Get all sections for a project. Returns section IDs and names that can be used with add_case",
     parameters,
-    handler: async ({ project_id }, client) => {
+    handler: async ({ project_id, output_file }, client) => {
         const sections = await client.getSections(project_id);
-        return {
+        const response = {
             sections: sections.map(s => SectionSchema.parse(s)),
         };
+        if (output_file) {
+            await fs.promises.writeFile(output_file, JSON.stringify(response), "utf-8");
+            return {
+                success: true,
+                message: `Successfully exported ${response.sections.length} sections to ${output_file}`,
+                file: output_file
+            };
+        }
+        return response;
     }
 };

package/dist/tools/get_users.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { UserSchema } from "../types/testrail.js";
+const parameters = {
+    project_id: z.number().optional().describe("Optional ID of the project to retrieve users for. If omitted, attempts to fetch all users globally."),
+    fallback_all_projects: z.boolean().optional().default(true).describe("If true and global user retrieval is forbidden (non-admin), automatically falls back to fetching users across all active projects."),
+};
+async function getUsersFallbackAllProjects(client) {
+    const projects = await client.getProjects();
+    const activeProjects = projects.filter(p => !p.is_completed);
+    const userPromises = activeProjects.map(project => client.getUsers(project.id).catch(err => {
+        console.error(`[get_users] Failed to fetch users for project ${project.id} (${project.name}): ${err.message}`);
+        return [];
+    }));
+    const results = await Promise.all(userPromises);
+    const allUsers = results.flat();
+    const uniqueUsersMap = new Map();
+    for (const user of allUsers) {
+        uniqueUsersMap.set(user.id, user);
+    }
+    return Array.from(uniqueUsersMap.values());
+}
+export const getUsersTool = {
+    name: "get_users",
+    description: "Get active users from TestRail. Resolves active users globally or per-project. If global fetch is forbidden (for non-admin accounts), falls back to merging users across all active projects so users referenced as reviewers or assignees can be resolved.",
+    parameters,
+    handler: async ({ project_id, fallback_all_projects }, client) => {
+        let users;
+        try {
+            users = await client.getUsers(project_id);
+        }
+        catch (err) {
+            const isPermissionError = err.message?.includes("Access Denied");
+            if (!project_id && fallback_all_projects !== false && isPermissionError) {
+                console.error("[get_users] Global fetch failed (Access Denied). Falling back to multi-project polling...");
+                users = await getUsersFallbackAllProjects(client);
+            }
+            else {
+                throw err;
+            }
+        }
+        return {
+            users: users.map(user => UserSchema.parse(user))
+        };
+    }
+};

package/dist/types/testrail.js

@@ -123,3 +123,8 @@ export const SharedStepHistorySchema = z.object({
     timestamp: z.number().optional(),
     custom_steps_separated: z.array(SharedStepContentSchema).optional(),
 });
+export const UserSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    email: z.string(),
+});

package/dist/utils/sanitizer.js

@@ -44,3 +44,14 @@ export function removeNullish(value) {
     }
     return value;
 }
+/**
+ * Checks if an entity is active by checking its active flag.
+ * Supports passing either the direct primitive value or the parent object containing `.is_active`.
+ */
+export function isActive(value) {
+    if (value == null) {
+        return false;
+    }
+    const activeFlag = (typeof value === 'object') ? value.is_active : value;
+    return activeFlag === 1 || activeFlag === true || activeFlag === '1' || activeFlag === 'true';
+}

package/dist/utils/validator.js

@@ -1,4 +1,5 @@
 import { SYSTEM_FIELDS, mapToFieldSchema } from "../tools/get_case_fields.js";
+import { isActive } from "./sanitizer.js";
 /**
  * Validates that the provided fields exist in the TestRail case schema.
  * Throws an Error if any field is invalid.
@@ -11,7 +12,7 @@ export function validateCaseFields(fields, caseFields) {
     if (fieldKeys.length === 0) {
         return;
     }
-    const customFieldSchemas = caseFields.filter(field => field.is_active).map(mapToFieldSchema);
+    const customFieldSchemas = caseFields.filter(isActive).map(mapToFieldSchema);
     const validFieldNames = new Set([...SYSTEM_FIELDS, ...customFieldSchemas].map(f => f.system_name));
     validFieldNames.add('id');
     validFieldNames.add('suite_id');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "1.9.0",
+  "version": "1.11.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",
@@ -11,13 +11,6 @@
     "dist"
   ],
   "type": "module",
-  "scripts": {
-    "build": "rimraf dist && tsc",
-    "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"
-  },
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -40,10 +33,10 @@
   "homepage": "https://github.com/uarlouski/testrail-mcp-server#readme",
   "license": "Apache-2.0",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "archiver": "^7.0.1",
-    "dotenv": "^17.3.1",
-    "zod": "^4.3.6"
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/archiver": "^7.0.0",
@@ -53,6 +46,21 @@
     "rimraf": "^6.1.3",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "@jest/globals": "^29.7.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.1.2",
+      "onFail": "error"
+    }
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "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"
   }
 }