@uarlouski/testrail-mcp-server 1.11.0 → 2.0.0

package/README.md

@@ -139,14 +139,17 @@ Once configured, turbo-charge your QA workflow by asking your AI assistant:
 
 ---
 
-## ⚙️ Environment Variables
-
-| 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 | |
+## ⚙️ Environment Variables & Security Controls
+
+| 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` |
 
 ---
 
@@ -161,8 +164,11 @@ The TestRail MCP Server provides heavily typed, descriptive tools designed speci
 ### 🔭 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
@@ -177,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. |
@@ -191,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 |
@@ -200,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

@@ -102,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`)
@@ -159,6 +203,9 @@ 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);
     }

package/dist/index.js

@@ -3,81 +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 { 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";
-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.11.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,
-    getUsersTool,
-];
-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,16 +1,17 @@
 import { z } from "zod";
-import { parseDropdownOptions } from "../utils/mapper.js";
-import { isActive } from "../utils/sanitizer.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",
@@ -85,6 +86,7 @@ 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) => {

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/{get_users.js → commons/get_users.js}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { UserSchema } from "../types/testrail.js";
+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."),
@@ -21,6 +21,7 @@ async function getUsersFallbackAllProjects(client) {
 }
 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) => {

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,
+];

package/dist/tools/commons/types.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+export const LabelSchema = z.object({
+    id: z.number(),
+    title: z.string(),
+});
+export const PrioritySchema = z.object({
+    id: z.number(),
+    is_default: z.boolean(),
+    name: z.string(),
+});
+export const CaseTypeSchema = z.object({
+    id: z.number(),
+    is_default: z.boolean(),
+    name: z.string(),
+});
+export const TemplateSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    is_default: z.boolean(),
+});
+export const StatusSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    label: z.string(),
+});
+export const TestSchema = z.object({
+    id: z.number(),
+    case_id: z.number(),
+    status_id: z.number(),
+    title: z.string(),
+    run_id: z.number(),
+});
+export const TestsSchema = z.array(TestSchema);
+export const UserSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    email: z.string(),
+});
+export const ConfigurationSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    group_id: z.number(),
+});
+export const ConfigurationGroupSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    project_id: z.number(),
+    configs: z.array(ConfigurationSchema),
+});

package/dist/tools/projects/index.js

@@ -0,0 +1,4 @@
+import { queryProjectTool } from "./query_project.js";
+export const projectsTools = [
+    queryProjectTool,
+];

package/dist/tools/projects/query_project.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { ProjectSchema, GetOneProjectSchema, GetManyProjectsSchema } from "./types.js";
+import { handleQuery } from "../../utils/query_handler.js";
+const parameters = {
+    payload: z.discriminatedUnion("action", [
+        GetOneProjectSchema,
+        GetManyProjectsSchema,
+    ]).describe("The payload containing the action ('one' or 'many') and corresponding parameters"),
+};
+export const queryProjectTool = {
+    name: "query_project",
+    mode: "read",
+    description: "Retrieve a single project or all projects 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 project = await client.getProject(p.project_id);
+            return {
+                project: ProjectSchema.parse(project),
+            };
+        }, async (p) => {
+            const projects = await client.getProjects();
+            const filteredProjects = projects.filter(prj => !prj.is_completed);
+            return {
+                projects: filteredProjects.map(prj => ProjectSchema.parse(prj)),
+            };
+        });
+    }
+};

package/dist/tools/projects/types.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export const ProjectSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+    is_completed: z.boolean(),
+    suite_mode: z.number(),
+});
+export const GetOneProjectSchema = z.object({
+    action: z.literal("one").describe("Retrieve a single project by ID"),
+    project_id: z.number().int().describe("The ID of the project"),
+});
+export const GetManyProjectsSchema = z.object({
+    action: z.literal("many").describe("Retrieve all available projects"),
+});