@uarlouski/testrail-mcp-server 3.0.0 → 3.2.0

package/README.md

@@ -42,7 +42,7 @@
 
 The **TestRail MCP Server** is a free, open-source [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI assistants direct, structured access to a [TestRail](https://www.testrail.com/) instance through the TestRail API v2. Once configured, an assistant such as **Claude Desktop, Cursor, Windsurf, or GitHub Copilot in VS Code** can search test cases, draft new ones, start test runs, record results, and upload attachments on your behalf — without you leaving the chat window.
 
-It exposes **34 tools**, runs locally on **Node.js 18+** over the MCP stdio transport, and is licensed under **Apache 2.0**. There is nothing to host or deploy: your MCP client launches it on demand with `npx`.
+It exposes **35 tools**, runs locally on **Node.js 18+** over the MCP stdio transport, and is licensed under **Apache 2.0**. There is nothing to host or deploy: your MCP client launches it on demand with `npx`.
 
 **No context switching. No tedious copy-pasting. Just ask your AI.**
 
@@ -279,19 +279,19 @@ See the [CLI & CI/CD guide](https://uarlouski.github.io/testrail-mcp-server/guid
 | `TESTRAIL_ENABLE_DEPRECATED_TOOLS` | Preserved for backward compatibility with existing host configurations. | | `true` |
 | `TESTRAIL_DISABLED_TOOLS` | Comma-separated list of specific tool names to disable (e.g., `mutate_suite,delete_entity`). Fails if invalid tool names are specified. | | - |
 
-With only the three required credentials, **26 of the 34 tools** are registered. Ready-made read-only and least-privilege configurations are in the [Configuration guide](https://uarlouski.github.io/testrail-mcp-server/guide/configuration).
+With only the three required credentials, **27 of the 35 tools** are registered. Ready-made read-only and least-privilege configurations are in the [Configuration guide](https://uarlouski.github.io/testrail-mcp-server/guide/configuration).
 
 ---
 
 ## 🧰 Available Tools
 
-All 34 tools, grouped by area. Each declares a `read`, `write`, or `delete` mode, which the server surfaces to clients as MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`).
+All 35 tools, grouped by area. Each declares a `read`, `write`, or `delete` mode, which the server surfaces to clients as MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
 
 | Area | Tools | Reference |
 |------|-------|-----------|
 | **Discovery & Navigation** | `query_project`, `query_suite`, `mutate_suite`, `query_section`, `mutate_section`, `get_users` | [Docs](https://uarlouski.github.io/testrail-mcp-server/reference/discovery) |
 | **Test Case Management** | `get_case`, `get_cases`, `add_case`, `update_case`, `update_cases`, `get_case_fields`, `resolve_case_field`, `get_case_history`, `export_cases_for_rag` | [Docs](https://uarlouski.github.io/testrail-mcp-server/reference/cases) |
-| **Execution & Tracking** | `query_run`, `mutate_run`, `get_tests`, `get_results`, `add_results`, `add_results_for_cases` | [Docs](https://uarlouski.github.io/testrail-mcp-server/reference/execution) |
+| **Execution & Tracking** | `query_run`, `mutate_run`, `query_test`, `get_tests`, `get_results`, `add_results`, `add_results_for_cases` | [Docs](https://uarlouski.github.io/testrail-mcp-server/reference/execution) |
 | **Attachments & Media** | `add_attachment`, `query_attachment` | [Docs](https://uarlouski.github.io/testrail-mcp-server/reference/attachments) |
 | **Shared Steps** | `get_shared_step`, `get_shared_steps`, `get_shared_step_history`, `add_shared_step`, `update_shared_step` | [Docs](https://uarlouski.github.io/testrail-mcp-server/reference/shared-steps) |
 | **System Metadata** | `get_statuses`, `get_priorities`, `get_case_fields`, `get_templates`, `get_labels`, `get_configurations` | [Docs](https://uarlouski.github.io/testrail-mcp-server/reference/metadata) |
@@ -355,14 +355,13 @@ For a comprehensive guide, detailed configuration options, and a complete breakd
 
 - 🚀 **[Getting Started](https://uarlouski.github.io/testrail-mcp-server/guide/getting-started)**: Per-client setup for Claude, Cursor, Windsurf, and VS Code.
 - ⚙️ **[Configuration](https://uarlouski.github.io/testrail-mcp-server/guide/configuration)**: Every environment variable, permission, and feature flag.
-- 🧰 **[All Tools](https://uarlouski.github.io/testrail-mcp-server/reference/)**: All 34 tools with modes and feature flags in one table.
+- 🧰 **[All Tools](https://uarlouski.github.io/testrail-mcp-server/reference/)**: All 35 tools with modes and feature flags in one table.
 - 🔭 **[Discovery & Navigation](https://uarlouski.github.io/testrail-mcp-server/reference/discovery)**: Exploring projects, suites, and sections.
 - 📋 **[Test Case Management](https://uarlouski.github.io/testrail-mcp-server/reference/cases)**: Fetching, creating, and bulk-updating test cases.
 - ▶️ **[Execution & Tracking](https://uarlouski.github.io/testrail-mcp-server/reference/execution)**: Managing test runs and submitting test results.
 - 📎 **[Attachments](https://uarlouski.github.io/testrail-mcp-server/reference/attachments)**: Automatically zipping and uploading files or directories.
 - 🔗 **[Shared Steps](https://uarlouski.github.io/testrail-mcp-server/reference/shared-steps)**: Managing reusable step definitions.
 - 🖥️ **[CLI & CI/CD](https://uarlouski.github.io/testrail-mcp-server/guide/cli)**: Pipeline automation without an LLM.
-
 ---
 
 ## 🤝 Contributing

package/dist/cli.js

@@ -29,7 +29,17 @@ export function resolveClient(options, env) {
         console.error("or supply them via --url, --username, and --api-key options.");
         return null;
     }
-    return new TestRailClient(credResult.data.url, credResult.data.username, credResult.data.apiKey);
+    const timeoutEnv = env.TESTRAIL_REQUEST_TIMEOUT_MS;
+    let timeoutMs;
+    if (timeoutEnv) {
+        const parsed = parseInt(timeoutEnv, 10);
+        if (!isNaN(parsed) && parsed > 0) {
+            timeoutMs = parsed;
+        }
+    }
+    return new TestRailClient(credResult.data.url, credResult.data.username, credResult.data.apiKey, {
+        timeoutMs,
+    });
 }
 export function validateToolArgs(tool, flags) {
     const coercedArgs = coerceFlagsForTool(flags, tool.parameters);

package/dist/client/testrail.js

@@ -7,6 +7,7 @@ export class TestRailClient {
     baseUrl;
     headers;
     auth;
+    timeoutMs;
     prioritiesPromise = null;
     caseTypesPromise = null;
     caseFieldsPromise = null;
@@ -14,7 +15,7 @@ export class TestRailClient {
     projectsPromise = null;
     templatesPromiseMap = new Map();
     sectionsPromiseMap = new Map();
-    constructor(baseUrl, email, apiKey) {
+    constructor(baseUrl, email, apiKey, options) {
         this.baseUrl = baseUrl.replace(/\/$/, "");
         const auth = Buffer.from(`${email}:${apiKey}`).toString('base64');
         this.auth = `Basic ${auth}`;
@@ -22,6 +23,7 @@ export class TestRailClient {
             "Content-Type": "application/json",
             "Authorization": this.auth,
         };
+        this.timeoutMs = options?.timeoutMs ?? 30_000;
     }
     async getCase(caseId) {
         return this.get(`${API_BASE_V2}/get_case/${caseId}`);
@@ -173,6 +175,9 @@ export class TestRailClient {
         const url = `${API_BASE_V2}/get_labels/${projectId}`;
         return this.paginateAll(url, 'labels');
     }
+    async getTest(testId) {
+        return this.get(`${API_BASE_V2}/get_test/${testId}`);
+    }
     async getTests(runId, statusId) {
         let url = `${API_BASE_V2}/get_tests/${runId}`;
         if (statusId && statusId.length > 0) {
@@ -283,17 +288,19 @@ export class TestRailClient {
     }
     async _executeRequest(method, endpoint, headers, body, responseType = 'json') {
         const url = `${this.baseUrl}${endpoint}`;
-        const params = {
-            method,
-            headers,
-            body,
-        };
         const maxRetries = 3;
         const baseDelayMs = 1000;
         let attempt = 0;
         while (attempt <= maxRetries) {
             console.error(`[TestRailClient] Executing ${method} request to ${endpoint}${attempt > 0 ? ` (Attempt ${attempt + 1})` : ''}`);
             const startTime = Date.now();
+            const signal = AbortSignal.timeout(this.timeoutMs);
+            const params = {
+                method,
+                headers,
+                body,
+                signal,
+            };
             try {
                 const response = await fetch(url, params);
                 const duration = Date.now() - startTime;
@@ -329,10 +336,20 @@ export class TestRailClient {
                 return await response.text();
             }
             catch (error) {
-                const networkError = error instanceof Error && !error.message.startsWith('TestRail API Error');
+                const errName = error?.name;
+                const errMsg = typeof error?.message === 'string' ? error.message : '';
+                const isTimeout = signal.aborted ||
+                    errName === 'TimeoutError' ||
+                    signal.reason?.name === 'TimeoutError';
+                if (isTimeout) {
+                    const timeoutMessage = `TestRail request timed out after ${this.timeoutMs}ms: ${method} ${endpoint}`;
+                    console.error(`[TestRailClient] Request Failed: ${method} ${endpoint} - ${timeoutMessage}`);
+                    throw new Error(timeoutMessage);
+                }
+                const networkError = !errMsg.startsWith('TestRail API Error');
                 if (networkError && attempt < maxRetries) {
                     const delayMs = baseDelayMs * Math.pow(2, attempt);
-                    console.error(`[TestRailClient] Network error (${error.message}). Retrying in ${delayMs}ms...`);
+                    console.error(`[TestRailClient] Network error (${errMsg}). Retrying in ${delayMs}ms...`);
                     await this.delay(delayMs);
                     attempt++;
                     continue;

package/dist/index.js

@@ -27,19 +27,27 @@ const EnvSchema = z.object({
     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_ENABLE_DEPRECATED_TOOLS: z.string().optional().transform(val => val === undefined ? true : val === 'true'),
-    TESTRAIL_DISABLED_TOOLS: z.string().optional().transform(val => val ? val.split(',').map(s => s.trim()).filter(Boolean) : [])
+    TESTRAIL_DISABLED_TOOLS: z.string().optional().transform(val => val ? val.split(',').map(s => s.trim()).filter(Boolean) : []),
+    TESTRAIL_REQUEST_TIMEOUT_MS: z.string().optional().refine(val => {
+        if (!val)
+            return true;
+        const num = Number(val);
+        return Number.isInteger(num) && num > 0;
+    }, { message: 'Must be a positive integer' }).transform(val => val ? parseInt(val, 10) : undefined),
 });
 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_ENABLE_CASE_HISTORY, TESTRAIL_ENABLE_RAG_TOOLS, TESTRAIL_ALLOW_WRITE_OPERATIONS, TESTRAIL_ALLOW_READ_OPERATIONS, TESTRAIL_ALLOW_DELETE_OPERATIONS, TESTRAIL_ENABLE_DEPRECATED_TOOLS, TESTRAIL_DISABLED_TOOLS } = parseResult.data;
+const { TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY, TESTRAIL_ENABLE_SHARED_STEPS, TESTRAIL_ENABLE_CASE_HISTORY, TESTRAIL_ENABLE_RAG_TOOLS, TESTRAIL_ALLOW_WRITE_OPERATIONS, TESTRAIL_ALLOW_READ_OPERATIONS, TESTRAIL_ALLOW_DELETE_OPERATIONS, TESTRAIL_ENABLE_DEPRECATED_TOOLS, TESTRAIL_DISABLED_TOOLS, TESTRAIL_REQUEST_TIMEOUT_MS, } = parseResult.data;
 const server = new McpServer({
     name: "TestRail MCP Server",
     version: VERSION,
 });
-const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
+const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY, {
+    timeoutMs: TESTRAIL_REQUEST_TIMEOUT_MS,
+});
 let tools;
 try {
     tools = getToolsToRegister({

package/dist/tools/cases/add_case.js

@@ -17,7 +17,7 @@ export const addCaseTool = {
     parameters,
     handler: async ({ section_id, title, fields }, client) => {
         if (fields) {
-            validateCaseFields(fields, await client.getCaseFields());
+            validateCaseFields(fields, await client.getCaseFields(), { allowReadonly: false });
         }
         const caseData = {
             title,

package/dist/tools/cases/export_cases_for_rag.js

@@ -81,9 +81,6 @@ function categorizeCustomFields(testCase, applicableFieldDefs, ignoredFieldsSet)
         if (!systemName.startsWith("custom_")) {
             continue;
         }
-        if (rawValue === null || rawValue === undefined || rawValue === "" || (Array.isArray(rawValue) && rawValue.length === 0)) {
-            continue;
-        }
         const strippedName = systemName.replace(/^custom_/, "");
         if (ignoredFieldsSet.has(systemName) || ignoredFieldsSet.has(strippedName)) {
             continue;
@@ -92,6 +89,10 @@ function categorizeCustomFields(testCase, applicableFieldDefs, ignoredFieldsSet)
         if (!fieldDef) {
             continue;
         }
+        const isCheckbox = fieldDef.type_id === CaseFieldTypeId.Checkbox;
+        if (!isCheckbox && (rawValue === null || rawValue === undefined || rawValue === "" || (Array.isArray(rawValue) && rawValue.length === 0))) {
+            continue;
+        }
         const val = resolveCustomFieldValue(fieldDef, rawValue);
         if (isMarkdownField(fieldDef, val)) {
             const header = fieldDef.label || systemName.replace(/^custom_/, "");

package/dist/tools/cases/fields.js

@@ -45,3 +45,13 @@ export const SYSTEM_FIELDS = [
     { system_name: "refs", label: "References", type: getFieldType(CaseFieldTypeId.String).name, is_required: false, project_scope: { scope: "global" } },
     { system_name: "labels", label: "Labels", type: getFieldType(CaseFieldTypeId.List).name, is_required: false, project_scope: { scope: "global" }, description: "Use get_labels tool to get available labels/tags." },
 ];
+export const READONLY_CASE_FIELDS = [
+    "id",
+    "suite_id",
+    "created_on",
+    "updated_on",
+    "created_by",
+    "updated_by",
+    "estimate_forecast",
+    "is_deleted",
+];

package/dist/tools/cases/get_case_fields.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { CaseFieldTypeId, FIELD_TYPES, getFieldType, SYSTEM_FIELDS } from "./fields.js";
+import { CaseFieldTypeId, FIELD_TYPES, getFieldType, SYSTEM_FIELDS, READONLY_CASE_FIELDS } from "./fields.js";
 import { parseDropdownOptions } from "../../utils/mapper.js";
 import { isActive } from "../../utils/sanitizer.js";
 // Field remains optional for backward compatibility with previous implementation.
@@ -14,7 +14,7 @@ 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.
 `;
-export { CaseFieldTypeId, FIELD_TYPES, getFieldType, SYSTEM_FIELDS };
+export { CaseFieldTypeId, FIELD_TYPES, getFieldType, SYSTEM_FIELDS, READONLY_CASE_FIELDS };
 function isFieldRequired(field) {
     return field.configs.some(config => config.options?.is_required === true);
 }

package/dist/tools/cases/get_cases.js

@@ -11,7 +11,7 @@ const parameters = {
     }).optional().describe("Section filter configuration. Use query_section to find available sections"),
     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\"]"),
+    fields: z.array(z.string()).optional().describe("Additional fields to include in response beyond id, title, and suite_id (supports system fields such as updated_on, created_on, created_by, updated_by, as well as custom fields). Example: [\"updated_on\", \"priority_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 async function fetchFilteredCases(client, options) {

package/dist/tools/cases/types.js

@@ -34,10 +34,14 @@ export const CaseSchema = z.object({
     priority_id: z.number(),
     milestone_id: z.number().nullable(),
     refs: z.string().nullable(),
+    created_by: z.number().optional(),
     created_on: z.number(),
+    updated_by: z.number().optional(),
     updated_on: z.number(),
     estimate: z.string().nullable(),
+    estimate_forecast: z.string().nullable().optional(),
     suite_id: z.number(),
+    is_deleted: z.number().optional(),
     labels: z.array(LabelSchema),
 }).loose();
 export const CaseHistoryChangeSchema = z.object({

package/dist/tools/cases/update_case.js

@@ -17,7 +17,7 @@ export const updateCaseTool = {
     description: description.trim(),
     parameters,
     handler: async ({ case_id, fields }, client) => {
-        validateCaseFields(fields, await client.getCaseFields());
+        validateCaseFields(fields, await client.getCaseFields(), { allowReadonly: false });
         const id = normalizeEntityId(case_id);
         const updatedCase = await client.updateCase(id, fields);
         return {

package/dist/tools/cases/update_cases.js

@@ -16,7 +16,7 @@ export const updateCasesTool = {
     description: description.trim(),
     parameters,
     handler: async ({ case_ids, fields }, client) => {
-        validateCaseFields(fields, await client.getCaseFields());
+        validateCaseFields(fields, await client.getCaseFields(), { allowReadonly: false });
         const caseData = await client.getCase(case_ids[0]);
         const updatedCases = await client.updateCases(caseData.suite_id, case_ids, fields);
         return {

package/dist/tools/commons/index.js

@@ -4,7 +4,6 @@ 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,
@@ -13,6 +12,5 @@ export const commonsTools = [
     getPrioritiesTool,
     getStatusesTool,
     getTemplatesTool,
-    getTestsTool,
     getUsersTool,
 ];

package/dist/tools/commons/types.js

@@ -23,14 +23,7 @@ export const StatusSchema = z.object({
     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 { TestSchema, TestsSchema } from "../tests/types.js";
 export const UserSchema = z.object({
     id: z.number(),
     name: z.string(),

package/dist/tools/registry.js

@@ -7,6 +7,7 @@ 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";
+import { testsTools } from "./tests/index.js";
 export const ALL_TOOLS = [
     ...projectsTools,
     ...suitesTools,
@@ -15,6 +16,7 @@ export const ALL_TOOLS = [
     exportCasesForRagTool,
     ...sectionsTools,
     ...runsTools,
+    ...testsTools,
     ...resultsTools,
     ...attachmentsTools,
     ...commonsTools,
@@ -34,6 +36,7 @@ export function getToolsToRegister(config) {
         ...casesTools,
         ...sectionsTools,
         ...runsTools,
+        ...testsTools,
         ...resultsTools,
         ...attachmentsTools,
         ...commonsTools,
@@ -68,6 +71,7 @@ export function getToolsToRegister(config) {
             readOnlyHint: tool.mode === 'read',
             destructiveHint: tool.mode === 'delete',
             idempotentHint: tool.mode === 'read',
+            openWorldHint: false,
         };
         return {
             ...tool,

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

@@ -1,5 +1,4 @@
 import { z } from "zod";
-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"),
@@ -7,12 +6,19 @@ const parameters = {
 export const getTestsTool = {
     name: "get_tests",
     mode: "read",
-    description: "Get tests for a test run, optionally filtered by status",
+    deprecated: true,
+    description: "Get tests for a test run, optionally filtered by status (Deprecated: use query_test with action 'many' instead)",
     parameters,
     handler: async ({ run_id, status_id }, client) => {
         const tests = await client.getTests(run_id, status_id);
         return {
-            tests: tests.map(test => TestSchema.parse(test)),
+            tests: tests.map(test => ({
+                id: test.id,
+                case_id: test.case_id,
+                status_id: test.status_id,
+                title: test.title,
+                run_id: test.run_id,
+            })),
         };
     },
 };

package/dist/tools/tests/index.js

@@ -0,0 +1,7 @@
+import { queryTestTool } from "./query_test.js";
+import { getTestsTool } from "./get_tests.js";
+export const testsTools = [
+    queryTestTool,
+    getTestsTool,
+];
+export { queryTestTool, getTestsTool };

package/dist/tools/tests/query_test.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import fs from "fs";
+import { GetOneTestSchema, GetManyTestsSchema, TestSchema } from "./types.js";
+import { handleQuery } from "../../utils/query_handler.js";
+import { normalizeEntityId } from "../../utils/sanitizer.js";
+const parameters = {
+    payload: z.discriminatedUnion("action", [
+        GetOneTestSchema,
+        GetManyTestsSchema,
+    ]).describe("The payload containing the action ('one' or 'many') and corresponding parameters"),
+};
+export const queryTestTool = {
+    name: "query_test",
+    mode: "read",
+    description: "Retrieve a single test by ID or all tests for a 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 testId = normalizeEntityId(p.test_id);
+            const test = await client.getTest(testId);
+            return {
+                test: TestSchema.parse(test),
+            };
+        }, async (p) => {
+            const tests = await client.getTests(p.run_id, p.status_id);
+            const response = {
+                tests: tests.map(t => {
+                    const baseTest = {
+                        id: t.id,
+                        case_id: t.case_id,
+                        status_id: t.status_id,
+                        title: t.title,
+                        run_id: t.run_id,
+                    };
+                    if (p.fields && p.fields.length > 0) {
+                        for (const field of p.fields) {
+                            if (field in t) {
+                                baseTest[field] = t[field];
+                            }
+                        }
+                    }
+                    return baseTest;
+                }),
+            };
+            if (p.output_file) {
+                await fs.promises.writeFile(p.output_file, JSON.stringify(response), "utf-8");
+                return {
+                    success: true,
+                    message: `Successfully exported ${response.tests.length} tests to ${p.output_file}`,
+                    file: p.output_file,
+                };
+            }
+            return response;
+        });
+    }
+};

package/dist/tools/tests/types.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export const TestSchema = z.looseObject({
+    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 GetOneTestSchema = z.object({
+    action: z.literal("one").describe("Retrieve a single test by ID"),
+    test_id: z.union([z.number(), z.string()]).describe("The ID of the test (e.g. 123 or 'T123')"),
+});
+export const GetManyTestsSchema = z.object({
+    action: z.literal("many").describe("Retrieve tests for a test run"),
+    run_id: z.number().int().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"),
+    fields: z.array(z.string()).optional().describe("Additional fields to include in response beyond default fields (id, case_id, status_id, title, run_id). Example: ['assignedto_id', 'priority_id', 'refs']"),
+    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."),
+});

package/dist/utils/mapper.js

@@ -23,15 +23,23 @@ export function processCustomFields(testCase, caseFields) {
     for (const [key, value] of Object.entries(testCase)) {
         if (!key.startsWith("custom_"))
             continue;
-        if (value === null || value === undefined)
-            continue;
         if (!fieldNameMap.has(key)) {
+            if (value === null || value === undefined)
+                continue;
             console.error(`No field mapping found for: ${key}`);
             result[key] = value;
             continue;
         }
-        const outputKey = fieldNameMap.get(key);
         const field = applicableFields.find(f => f.system_name === key);
+        const isCheckbox = field.type_id === CaseFieldTypeId.Checkbox;
+        if (value === null || value === undefined) {
+            if (isCheckbox) {
+                const outputKey = fieldNameMap.get(key);
+                result[outputKey] = resolveCustomFieldValue(field, value);
+            }
+            continue;
+        }
+        const outputKey = fieldNameMap.get(key);
         const options = dropdownOptionsMap.get(key);
         result[outputKey] = resolveCustomFieldValue(field, value, options);
     }
@@ -41,9 +49,16 @@ export function processCustomFields(testCase, caseFields) {
  * Resolves a custom field value against its field definition:
  * - Maps dropdown option IDs to their display labels
  * - Normalizes multi-select values into arrays
+ * - Normalizes checkbox / boolean values (defaults null/undefined to false)
  * - Sanitizes HTML formatting in strings
  */
 export function resolveCustomFieldValue(field, value, optionsMap) {
+    if (field.type_id === CaseFieldTypeId.Checkbox) {
+        if (value === null || value === undefined) {
+            return false;
+        }
+        return value === true || value === 1 || value === "1" || value === "true";
+    }
     if (value === null || value === undefined) {
         return value;
     }

package/dist/utils/sanitizer.js

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

package/dist/utils/validator.js

@@ -1,4 +1,4 @@
-import { SYSTEM_FIELDS, mapToFieldSchema } from "../tools/cases/get_case_fields.js";
+import { SYSTEM_FIELDS, READONLY_CASE_FIELDS, mapToFieldSchema } from "../tools/cases/get_case_fields.js";
 import { isActive } from "./sanitizer.js";
 const SUITE_MODE_SINGLE_WITH_BASELINES = 2;
 const SUITE_MODE_MULTI = 3;
@@ -21,16 +21,20 @@ export async function validateSuiteId(client, projectId, suiteId) {
  *
  * @param fields A record of fields or array of field names to validate
  * @param caseFields Available custom case fields from TestRail
+ * @param options Validation options (e.g. allowReadonly)
  */
-export function validateCaseFields(fields, caseFields) {
+export function validateCaseFields(fields, caseFields, options = { allowReadonly: true }) {
     const fieldKeys = Array.isArray(fields) ? fields : Object.keys(fields);
     if (fieldKeys.length === 0) {
         return;
     }
     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');
+    if (options.allowReadonly !== false) {
+        for (const field of READONLY_CASE_FIELDS) {
+            validFieldNames.add(field);
+        }
+    }
     const invalidFields = [];
     for (const key of fieldKeys) {
         if (!validFieldNames.has(key)) {

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "3.0.0";
+export const VERSION = "3.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "mcpName": "io.github.uarlouski/testrail-mcp-server",
   "description": "Model Context Protocol (MCP) server for TestRail: let Claude, Cursor, and Windsurf manage test cases, runs, results, and attachments.",
   "main": "dist/index.js",
@@ -19,6 +19,8 @@
     "testrail",
     "testrail-api",
     "testrail-mcp",
+    "testrail-mcp-server",
+    "mcp-testrail",
     "testrail-integration",
     "test-management",
     "test-case-management",
@@ -37,10 +39,14 @@
     "ai-agents",
     "llm",
     "claude",
+    "claude-desktop",
+    "claude-code",
     "cursor",
     "windsurf",
     "vscode",
     "copilot",
+    "github-copilot",
+    "test-case-generation",
     "rag",
     "typescript",
     "cli"
@@ -53,7 +59,7 @@
   "bugs": {
     "url": "https://github.com/uarlouski/testrail-mcp-server/issues"
   },
-  "homepage": "https://github.com/uarlouski/testrail-mcp-server#readme",
+  "homepage": "https://uarlouski.github.io/testrail-mcp-server/",
   "license": "Apache-2.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",