@uarlouski/testrail-mcp-server 1.10.0 → 2.0.0

package/README.md

@@ -131,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."*
@@ -138,14 +139,17 @@ Once configured, turbo-charge your QA workflow by asking your AI assistant:
 
 ---
 
-## ⚙️ Environment Variables
+## ⚙️ Environment Variables & Security Controls
 
-| Variable | Description | Required |
-|----------|-------------|:--------:|
-| `TESTRAIL_INSTANCE_URL` | Your TestRail instance URL (e.g., `https://example.testrail.io`) | ✅ |
-| `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 | |
+| Variable | Description | Required | Default |
+|----------|-------------|:--------:|:-------:|
+| `TESTRAIL_INSTANCE_URL` | Your TestRail instance URL (e.g., `https://example.testrail.io`) | ✅ | |
+| `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_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` |
 
 ---
 
@@ -153,14 +157,19 @@ 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**
-> 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!
+> **💡 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. |
+| `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 |
@@ -174,8 +183,10 @@ The TestRail MCP Server provides heavily typed, descriptive tools designed speci
 ### ▶️ Test Execution & Tracking
 | Tool | Functionality |
 |------|-------------|
-| `add_run` | Generate a new, focused test run directly in TestRail. |
+| `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. |
@@ -188,7 +199,11 @@ The TestRail MCP Server provides heavily typed, descriptive tools designed speci
 | `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). |
-| `delete_shared_step` | Securely delete a shared step entity. |
+
+### 🗑️ 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 |
@@ -197,6 +212,7 @@ The TestRail MCP Server provides heavily typed, descriptive tools designed speci
 | `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. |
 
 ---
 

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`;
@@ -101,10 +102,54 @@ export class TestRailClient {
     async addRun(projectId, fields) {
         return this.post(`${API_BASE_V2}/add_run/${projectId}`, fields);
     }
+    async updateRun(runId, fields) {
+        return this.post(`${API_BASE_V2}/update_run/${runId}`, fields);
+    }
     async getSections(projectId) {
         const url = `${API_BASE_V2}/get_sections/${projectId}`;
         return this.paginateAll(url, 'sections');
     }
+    async addSection(projectId, data) {
+        return this.post(`${API_BASE_V2}/add_section/${projectId}`, data);
+    }
+    async updateSection(sectionId, data) {
+        return this.post(`${API_BASE_V2}/update_section/${sectionId}`, data);
+    }
+    async addSuite(projectId, data) {
+        return this.post(`${API_BASE_V2}/add_suite/${projectId}`, data);
+    }
+    async updateSuite(suiteId, data) {
+        return this.post(`${API_BASE_V2}/update_suite/${suiteId}`, data);
+    }
+    async getSuite(suiteId) {
+        return this.get(`${API_BASE_V2}/get_suite/${suiteId}`);
+    }
+    async getSuites(projectId) {
+        const url = `${API_BASE_V2}/get_suites/${projectId}`;
+        return this.paginateAll(url, 'suites');
+    }
+    async getRun(runId) {
+        return this.get(`${API_BASE_V2}/get_run/${runId}`);
+    }
+    async getRuns(projectId, filter) {
+        let url = `${API_BASE_V2}/get_runs/${projectId}`;
+        if (filter) {
+            for (const [key, value] of Object.entries(filter)) {
+                url += `&${key}=${encodeURIComponent(value)}`;
+            }
+        }
+        return this.paginateAll(url, 'runs');
+    }
+    async getResults(testId) {
+        const url = `${API_BASE_V2}/get_results/${testId}`;
+        return this.paginateAll(url, 'results');
+    }
+    async getConfigs(projectId) {
+        return this.get(`${API_BASE_V2}/get_configs/${projectId}`);
+    }
+    async getProject(projectId) {
+        return this.get(`${API_BASE_V2}/get_project/${projectId}`);
+    }
     async getProjects() {
         if (!this.projectsPromise) {
             this.projectsPromise = this.get(`${API_BASE_V2}/get_projects`)
@@ -158,9 +203,19 @@ export class TestRailClient {
     async updateSharedStep(sharedStepId, data) {
         return this.post(`${API_BASE_V2}/update_shared_step/${sharedStepId}`, data);
     }
+    async deleteCase(caseId) {
+        return this._executeRequest('POST', `${API_BASE_V2}/delete_case/${caseId}`, this.headers, JSON.stringify({}), false);
+    }
     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

@@ -3,79 +3,40 @@ import "dotenv/config";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { TestRailClient } from "./client/testrail.js";
-import { getCaseTool } from "./tools/get_case.js";
-import { getCasesTool } from "./tools/get_cases.js";
-import { getCaseFieldsTool } from "./tools/get_case_fields.js";
-import { getTemplatesTool } from "./tools/get_templates.js";
-import { updateCaseTool } from "./tools/update_case.js";
-import { updateCasesTool } from "./tools/update_cases.js";
-import { addCaseTool } from "./tools/add_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 { getPrioritiesTool } from "./tools/get_priorities.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 { addResultsForCasesTool } from "./tools/add_results_for_cases.js";
-import { getLabelsTool } from "./tools/get_labels.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";
-import { addSharedStepTool } from "./tools/shared_steps/add_shared_step.js";
-import { updateSharedStepTool } from "./tools/shared_steps/update_shared_step.js";
-import { deleteSharedStepTool } from "./tools/shared_steps/delete_shared_step.js";
+import { getToolsToRegister } from "./tools/registry.js";
 import { removeNullish } from "./utils/sanitizer.js";
 import z from "zod";
 const EnvSchema = z.object({
     TESTRAIL_INSTANCE_URL: z.url('Must be a valid TestRail URL'),
     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_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')
 });
 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 } = 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 } = parseResult.data;
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "1.10.0",
+    version: "2.0.0",
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
-const tools = [
-    getProjectsTool,
-    getCaseTool,
-    getCasesTool,
-    getCaseFieldsTool,
-    getTemplatesTool,
-    getSectionsTool,
-    updateCaseTool,
-    updateCasesTool,
-    addCaseTool,
-    addRunTool,
-    getStatusesTool,
-    getPrioritiesTool,
-    getTestsTool,
-    addResultsTool,
-    addResultsForCasesTool,
-    addAttachmentToRunTool,
-    getLabelsTool,
-];
-if (TESTRAIL_ENABLE_SHARED_STEPS) {
-    tools.push(getSharedStepsTool);
-    tools.push(getSharedStepTool);
-    tools.push(getSharedStepHistoryTool);
-    tools.push(addSharedStepTool);
-    tools.push(updateSharedStepTool);
-    tools.push(deleteSharedStepTool);
-}
+const tools = getToolsToRegister({
+    enableSharedSteps: TESTRAIL_ENABLE_SHARED_STEPS,
+    allowWrite: TESTRAIL_ALLOW_WRITE_OPERATIONS,
+    allowRead: TESTRAIL_ALLOW_READ_OPERATIONS,
+    allowDelete: TESTRAIL_ALLOW_DELETE_OPERATIONS
+});
 for (const tool of tools) {
     server.registerTool(tool.name, {
         description: tool.description,
         inputSchema: tool.parameters,
+        annotations: tool.annotations,
     }, async (args) => {
         try {
             const output = await tool.handler(args, client);

package/dist/tools/{add_case.js → cases/add_case.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { validateCaseFields } from "../utils/validator.js";
+import { validateCaseFields } from "../../utils/validator.js";
 import { CASE_FIELDS_PARAM_DESCRIPTION } from "./get_case_fields.js";
 const parameters = {
     section_id: z.number().describe("The ID of the section where the case should be created. Use get_sections to find available sections"),
@@ -12,6 +12,7 @@ The create operation requires knowing valid field names that are returned by get
 `;
 export const addCaseTool = {
     name: "add_case",
+    mode: "write",
     description: description.trim(),
     parameters,
     handler: async ({ section_id, title, fields }, client) => {

package/dist/tools/{get_case.js → cases/get_case.js}

@@ -1,11 +1,12 @@
 import { z } from "zod";
-import { processCustomFields } from "../utils/mapper.js";
-import { LabelSchema } from "../types/testrail.js";
+import { processCustomFields } from "../../utils/mapper.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')"),
 };
 export const getCaseTool = {
     name: "get_case",
+    mode: "read",
     description: "Get detailed information about a test case including its custom fields",
     parameters,
     handler: async ({ case_id }, client) => {

package/dist/tools/{get_case_fields.js → cases/get_case_fields.js}

@@ -1,15 +1,17 @@
 import { z } from "zod";
-import { parseDropdownOptions } from "../utils/mapper.js";
+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 = {
     project_id: z.number().optional().describe("The project ID to get fields for. This is the primary way to use this tool, as it returns only the fields relevant to your current project. If omitted, returns all fields across all projects."),
 };
 export const CASE_FIELDS_PARAM_DESCRIPTION = `
+A flat key-value map of case fields. The server merges all entries directly into the root of the TestRail API request body — there is no nested "fields" key in the API call.
 Must use system_name values from get_case_fields.
+Example: {"priority_id": 2, "template_id": 1, "labels": [1, 2]}
 Call get_case_fields with project_id first if field names are not already known.
 Using an unknown field name (e.g. 'label_ids') will result in an error.
-Example: {"priority_id": 2, "template_id": 1, "labels": [1, 2]}
 `;
 const FIELD_TYPE_NAMES = {
     1: "String",
@@ -84,11 +86,12 @@ Returns available fields with their types and options (for dropdown fields).
 `;
 export const getCaseFieldsTool = {
     name: "get_case_fields",
+    mode: "read",
     description: description.trim(),
     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 → cases/get_cases.js}

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import fs from "fs";
-import { validateCaseFields } from "../utils/validator.js";
+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"),
     section: z.object({
@@ -15,6 +15,7 @@ const parameters = {
 };
 export const getCasesTool = {
     name: "get_cases",
+    mode: "read",
     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, output_file }, client) => {

package/dist/tools/cases/index.js

@@ -0,0 +1,14 @@
+import { getCaseTool } from "./get_case.js";
+import { getCasesTool } from "./get_cases.js";
+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";
+export const casesTools = [
+    getCaseTool,
+    getCasesTool,
+    getCaseFieldsTool,
+    updateCaseTool,
+    updateCasesTool,
+    addCaseTool,
+];

package/dist/tools/cases/types.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { LabelSchema } from "../commons/types.js";
+export const CaseFieldConfigSchema = z.object({
+    context: z.object({
+        is_global: z.boolean(),
+        project_ids: z.array(z.number()),
+    }).optional(),
+    options: z.object({
+        default_value: z.string().optional(),
+        is_required: z.boolean().optional(),
+        items: z.string().optional(),
+    }),
+});
+export const CaseFieldSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    system_name: z.string(),
+    label: z.string(),
+    type_id: z.number(),
+    template_ids: z.array(z.number()),
+    is_active: z.boolean(),
+    description: z.string().nullable(),
+    include_all: z.boolean(),
+    configs: z.array(CaseFieldConfigSchema),
+});
+export const CaseSchema = z.object({
+    id: z.number(),
+    title: z.string(),
+    section_id: z.number(),
+    template_id: z.number(),
+    type_id: z.number(),
+    priority_id: z.number(),
+    milestone_id: z.number().nullable(),
+    refs: z.string().nullable(),
+    created_on: z.number(),
+    updated_on: z.number(),
+    estimate: z.string().nullable(),
+    suite_id: z.number(),
+    labels: z.array(LabelSchema),
+}).loose();

package/dist/tools/{update_case.js → cases/update_case.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { validateCaseFields } from "../utils/validator.js";
+import { validateCaseFields } from "../../utils/validator.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')"),
@@ -12,6 +12,7 @@ Supports partial updates — only specify the fields you want to change.
 `;
 export const updateCaseTool = {
     name: "update_case",
+    mode: "write",
     description: description.trim(),
     parameters,
     handler: async ({ case_id, fields }, client) => {

package/dist/tools/{update_cases.js → cases/update_cases.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { validateCaseFields } from "../utils/validator.js";
+import { validateCaseFields } from "../../utils/validator.js";
 import { CASE_FIELDS_PARAM_DESCRIPTION } from "./get_case_fields.js";
 const parameters = {
     case_ids: z.array(z.number()).min(1).describe("Array of case IDs to update (e.g. [123, 456, 789])"),
@@ -12,6 +12,7 @@ More efficient than calling update_case multiple times.
 `;
 export const updateCasesTool = {
     name: "update_cases",
+    mode: "write",
     description: description.trim(),
     parameters,
     handler: async ({ case_ids, fields }, client) => {

package/dist/tools/commons/delete_entity.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+const parameters = {
+    entity_type: z.enum(["case", "shared_step"]).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.",
+    parameters,
+    handler: async (args, client) => {
+        const { entity_type, entity_id } = args;
+        switch (entity_type) {
+            case "case":
+                await client.deleteCase(entity_id);
+                return { message: `Case ${entity_id} deleted successfully.` };
+            case "shared_step":
+                await client.deleteSharedStep(entity_id);
+                return { message: `Shared step ${entity_id} deleted successfully.` };
+            default:
+                throw new Error(`Unsupported entity type: ${entity_type}`);
+        }
+    }
+};

package/dist/tools/commons/get_configurations.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { ConfigurationGroupSchema } from "./types.js";
+const parameters = {
+    project_id: z.number().int().describe("The ID of the project"),
+};
+export const getConfigurationsTool = {
+    name: "get_configurations",
+    mode: "read",
+    description: "Get all configuration groups and configurations for a project in TestRail.",
+    parameters,
+    handler: async (args, client) => {
+        const configs = await client.getConfigs(args.project_id);
+        return {
+            configurations: configs.map(c => ConfigurationGroupSchema.parse(c)),
+        };
+    }
+};

package/dist/tools/{get_labels.js → commons/get_labels.js}

@@ -1,10 +1,11 @@
 import { z } from "zod";
-import { LabelSchema } from "../types/testrail.js";
+import { LabelSchema } from "./types.js";
 const parameters = {
     project_id: z.number().describe("The ID of the project to retrieve labels for"),
 };
 export const getLabelsTool = {
     name: "get_labels",
+    mode: "read",
     description: "Get all available test case labels (sometimes called tags) for a project. Returns label IDs and titles that can be used when creating or updating test cases.",
     parameters,
     handler: async ({ project_id }, client) => {

package/dist/tools/{get_priorities.js → commons/get_priorities.js}

@@ -1,7 +1,8 @@
-import { PrioritySchema } from "../types/testrail.js";
+import { PrioritySchema } from "./types.js";
 const parameters = {};
 export const getPrioritiesTool = {
     name: "get_priorities",
+    mode: "read",
     description: "Get all available test case priorities (e.g. Critical, High, Medium, Low). Returns priority IDs and names that can be used when creating or updating test cases.",
     parameters,
     handler: async (_args, client) => {

package/dist/tools/{get_statuses.js → commons/get_statuses.js}

@@ -1,7 +1,8 @@
-import { StatusSchema } from "../types/testrail.js";
+import { StatusSchema } from "./types.js";
 const parameters = {};
 export const getStatusesTool = {
     name: "get_statuses",
+    mode: "read",
     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, client) => {

package/dist/tools/{get_templates.js → commons/get_templates.js}

@@ -1,10 +1,11 @@
 import { z } from "zod";
-import { TemplateSchema } from "../types/testrail.js";
+import { TemplateSchema } from "./types.js";
 const parameters = {
     project_id: z.number().describe("The ID of the project. Use get_projects to find available projects"),
 };
 export const getTemplatesTool = {
     name: "get_templates",
+    mode: "read",
     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) => {

package/dist/tools/{get_tests.js → commons/get_tests.js}

@@ -1,11 +1,12 @@
 import { z } from "zod";
-import { TestSchema } from "../types/testrail.js";
+import { TestSchema } from "./types.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 = {
     name: "get_tests",
+    mode: "read",
     description: "Get tests for a test run, optionally filtered by status",
     parameters,
     handler: async ({ run_id, status_id }, client) => {

package/dist/tools/commons/get_users.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { UserSchema } from "./types.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",
+    mode: "read",
+    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/tools/commons/index.js

@@ -0,0 +1,18 @@
+import { deleteEntityTool } from "./delete_entity.js";
+import { getConfigurationsTool } from "./get_configurations.js";
+import { getLabelsTool } from "./get_labels.js";
+import { getPrioritiesTool } from "./get_priorities.js";
+import { getStatusesTool } from "./get_statuses.js";
+import { getTemplatesTool } from "./get_templates.js";
+import { getTestsTool } from "./get_tests.js";
+import { getUsersTool } from "./get_users.js";
+export const commonsTools = [
+    deleteEntityTool,
+    getConfigurationsTool,
+    getLabelsTool,
+    getPrioritiesTool,
+    getStatusesTool,
+    getTemplatesTool,
+    getTestsTool,
+    getUsersTool,
+];