@uarlouski/testrail-mcp-server 3.1.0 → 3.3.0

package/README.md

@@ -17,6 +17,7 @@
   <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>
   <a href="https://m8ven.ai/mcp/uarlouski/testrail-mcp-server"><img src="https://m8ven.ai/badge/mcp/uarlouski/testrail-mcp-server" alt="M8ven Score"></a>
+  <a href="https://smithery.ai/servers/uarlouski/testrail-mcp-server"><img src="https://smithery.ai/badge/uarlouski/testrail-mcp-server" alt="Smithery badge"></a>
 </p>
 
 <p align="center">
@@ -42,7 +43,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 +280,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 +356,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/export_cases_for_rag.js

@@ -6,6 +6,8 @@ import { resolveCustomFieldValue } from "../../utils/mapper.js";
 import { getBaseDirectory } from "../../utils/fs.js";
 import { CaseFieldTypeId, getFieldType } from "./fields.js";
 import { fetchFilteredCases } from "./get_cases.js";
+import { createSectionLookup, formatSectionPath, resolveSectionPath } from "../../utils/section_path.js";
+import { computeContentHash } from "../../utils/content_hash.js";
 const parameters = {
     case_ids: z.array(z.union([z.string(), z.number()])).optional().describe("List of test case IDs (e.g. ['C123', 456]). Provide either case_ids OR project_id."),
     project_id: z.number().optional().describe("The ID of the project to export cases from. Required if case_ids is not provided."),
@@ -13,7 +15,7 @@ const parameters = {
     filter: z.record(z.string(), z.string()).optional().describe("Optional API-side filters (e.g. priority_id, type_id, milestone_id, refs, created_after, etc.)."),
     where: z.record(z.string(), z.any()).optional().describe("Optional client-side filter for any field including custom fields (filters after fetching cases). Supports exact value matching. Example: {\"custom_automation_status\": 1}"),
     output_dir: z.string().optional().describe("Directory to save exported files. Defaults to an auto-generated directory in the current working directory."),
-    ignored_fields: z.array(z.string()).optional().describe("Optional list of custom field names or system names to ignore/exclude from export (e.g. ['custom_review_status', 'review_status']). Supports both full system_name and stripped field names. Core metadata attributes (case_id, updated_on, title, section, priority, references, labels) cannot be ignored."),
+    ignored_fields: z.array(z.string()).optional().describe("Optional list of custom field names or system names to ignore/exclude from export (e.g. ['custom_review_status', 'review_status']). Supports both full system_name and stripped field names. Core metadata attributes (case_id, updated_on, title, section, section_path, priority, references, labels, content_hash) cannot be ignored."),
 };
 function formatStepsSeparated(steps) {
     return steps.map((step, idx) => {
@@ -81,9 +83,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 +91,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_/, "");
@@ -104,11 +107,11 @@ function categorizeCustomFields(testCase, applicableFieldDefs, ignoredFieldsSet)
     }
     return { markdownFields, metadataFields };
 }
-function buildMarkdownBody(testCase, sectionName, markdownFields) {
+function buildMarkdownBody(testCase, sectionPath, markdownFields) {
     const mdLines = [];
     mdLines.push(`# [C${testCase.id}] ${sanitizeValue(testCase.title)}`);
     mdLines.push("");
-    mdLines.push(`**Section**: ${sectionName}`);
+    mdLines.push(`**Section**: ${sectionPath.length > 0 ? formatSectionPath(sectionPath) : "Unknown"}`);
     mdLines.push("");
     for (const { header, value, fieldDef } of markdownFields) {
         mdLines.push(`## ${header}`);
@@ -122,27 +125,44 @@ function buildMarkdownBody(testCase, sectionName, markdownFields) {
     }
     return mdLines.join("\n").trim() + "\n";
 }
-function buildMetadataAttributes(testCase, sectionName, priority, metadataFields) {
+function buildMetadataAttributes(testCase, sectionPath, priority, metadataFields) {
     const metadataAttributes = {
         case_id: testCase.id,
         updated_on: testCase.updated_on,
         title: testCase.title,
-        section: sectionName,
+        section: sectionPath.length > 0 ? sectionPath[sectionPath.length - 1] : "Unknown",
         priority: priority,
     };
+    if (sectionPath.length > 0) {
+        metadataAttributes.section_path = sectionPath;
+    }
     if (testCase.refs) {
         metadataAttributes.references = testCase.refs;
     }
     if (testCase.labels && testCase.labels.length > 0) {
         metadataAttributes.labels = testCase.labels.map(l => l.title);
     }
+    const CORE_METADATA_KEYS = new Set([
+        "case_id",
+        "updated_on",
+        "title",
+        "section",
+        "section_path",
+        "priority",
+        "references",
+        "labels",
+        "content_hash",
+    ]);
     for (const { key, value, fieldDef } of metadataFields) {
+        const targetKey = CORE_METADATA_KEYS.has(key)
+            ? (fieldDef?.system_name || `custom_${key}`)
+            : key;
         if (fieldDef?.type_id === CaseFieldTypeId.MultiSelect) {
             const listVal = Array.isArray(value) ? value : [value];
-            metadataAttributes[key] = sanitizeMetadataValue(listVal.map(item => String(item)));
+            metadataAttributes[targetKey] = sanitizeMetadataValue(listVal.map(item => String(item)));
         }
         else {
-            metadataAttributes[key] = sanitizeMetadataValue(value);
+            metadataAttributes[targetKey] = sanitizeMetadataValue(value);
         }
     }
     return metadataAttributes;
@@ -194,21 +214,23 @@ export const exportCasesForRagTool = {
                 }
             }
         }
+        let preloadedSections = [];
+        if (testCases.length > 0) {
+            preloadedSections = await client.getSections(project_id, suite_id).catch(() => []);
+        }
+        const sectionLookup = createSectionLookup(client, preloadedSections);
         const writtenFiles = [];
         for (const testCase of testCases) {
-            let sectionName = "Unknown";
-            if (testCase.section_id) {
-                const section = await client.getSection(Number(testCase.section_id)).catch(() => null);
-                if (section?.name) {
-                    sectionName = section.name;
-                }
-            }
+            const sectionPath = testCase.section_id
+                ? await resolveSectionPath(Number(testCase.section_id), sectionLookup)
+                : [];
             const priority = priorities.find(p => p.id === testCase.priority_id)?.name || "Unknown";
             const templateId = testCase.template_id;
             const applicableFields = caseFields.filter(field => field.include_all || (templateId !== null && templateId !== undefined && field.template_ids.includes(templateId)));
             const { markdownFields, metadataFields } = categorizeCustomFields(testCase, applicableFields, ignoredFieldsSet);
-            const markdownContent = buildMarkdownBody(testCase, sectionName, markdownFields);
-            const metadataAttributes = buildMetadataAttributes(testCase, sectionName, priority, metadataFields);
+            const markdownContent = buildMarkdownBody(testCase, sectionPath, markdownFields);
+            const metadataAttributes = buildMetadataAttributes(testCase, sectionPath, priority, metadataFields);
+            metadataAttributes.content_hash = computeContentHash(markdownContent, metadataAttributes);
             const docFilename = `C${testCase.id}.md`;
             const metaFilename = `C${testCase.id}.md.metadata.json`;
             await fs.promises.writeFile(path.join(targetDir, docFilename), markdownContent, "utf-8");

package/dist/tools/cases/fields.js

@@ -55,3 +55,13 @@ export const READONLY_CASE_FIELDS = [
     "estimate_forecast",
     "is_deleted",
 ];
+/**
+ * Standard case property names that must not be overwritten by custom fields.
+ * If a custom field's converted label collides with one of these names (e.g. "labels", "title"),
+ * the custom field retains its `system_name` (e.g. `custom_labels`, `custom_title`) to prevent collisions.
+ */
+export const RESERVED_CASE_FIELDS = new Set([
+    ...SYSTEM_FIELDS.map(f => f.label.toLowerCase()),
+    ...SYSTEM_FIELDS.map(f => f.system_name),
+    ...READONLY_CASE_FIELDS,
+]);

package/dist/tools/cases/get_case.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { processCustomFields } from "../../utils/mapper.js";
 import { normalizeEntityId } from "../../utils/sanitizer.js";
-import { LabelSchema } from "../commons/types.js";
+import { CaseLabelSchema } from "../commons/types.js";
 const parameters = {
     case_id: z.string().describe("The ID of the test case (e.g. '123' or 'C123')"),
 };
@@ -23,15 +23,15 @@ export const getCaseTool = {
         const priority = priorities.find(p => p.id === testCase.priority_id);
         const customFields = processCustomFields(testCase, caseFields);
         const response = {
+            ...customFields,
             id: testCase.id,
             title: testCase.title,
             section: section.name,
             type: caseType ? caseType.name : "Unknown",
             priority: priority ? priority.name : "Unknown",
-            labels: (testCase.labels || []).map((label) => LabelSchema.parse(label)),
+            labels: (testCase.labels || []).map((label) => CaseLabelSchema.parse(label)),
             references: testCase.refs,
             updated_on: testCase.updated_on,
-            ...customFields
         };
         return response;
     }

package/dist/tools/cases/types.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { LabelSchema } from "../commons/types.js";
+import { CaseLabelSchema } from "../commons/types.js";
 import { CaseFieldTypeId } from "./fields.js";
 export { CaseFieldTypeId };
 export const CaseFieldConfigSchema = z.object({
@@ -42,7 +42,7 @@ export const CaseSchema = z.object({
     estimate_forecast: z.string().nullable().optional(),
     suite_id: z.number(),
     is_deleted: z.number().optional(),
-    labels: z.array(LabelSchema),
+    labels: z.array(CaseLabelSchema),
 }).loose();
 export const CaseHistoryChangeSchema = z.object({
     field: z.string(),

package/dist/tools/commons/get_labels.js

@@ -6,7 +6,7 @@ const parameters = {
 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.",
+    description: "Get all available test case labels (sometimes called tags) for a project. Returns label IDs and names that can be used when creating or updating test cases.",
     parameters,
     handler: async ({ project_id }, client) => {
         const labels = await client.getLabels(project_id);

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

@@ -1,5 +1,11 @@
 import { z } from "zod";
+/** Label as returned by the `get_labels` endpoint (uses `name`). */
 export const LabelSchema = z.object({
+    id: z.number(),
+    name: z.string(),
+});
+/** Label as embedded in a case payload (`get_case`, `get_cases`); uses `title`. */
+export const CaseLabelSchema = z.object({
     id: z.number(),
     title: z.string(),
 });
@@ -23,14 +29,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/content_hash.js

@@ -0,0 +1,47 @@
+import * as crypto from "crypto";
+export const DEFAULT_VOLATILE_KEYS = new Set([
+    "content_hash",
+    "export_time",
+    "exported_at",
+    "output_path",
+    "output_dir",
+]);
+/**
+ * Serializes a value to canonical JSON with sorted object keys,
+ * normalized \n line endings, and volatile keys omitted.
+ */
+export function canonicalizeJson(val, volatileKeys = DEFAULT_VOLATILE_KEYS) {
+    if (val === undefined) {
+        return "null";
+    }
+    if (val === null || typeof val !== "object") {
+        if (typeof val === "string") {
+            return JSON.stringify(val.replace(/\r\n/g, "\n"));
+        }
+        return JSON.stringify(val);
+    }
+    if (Array.isArray(val)) {
+        return "[" + val.map(item => canonicalizeJson(item, volatileKeys)).join(",") + "]";
+    }
+    const sortedKeys = Object.keys(val)
+        .filter(key => !volatileKeys.has(key) && val[key] !== undefined)
+        .sort();
+    const entries = sortedKeys.map(key => {
+        return JSON.stringify(key) + ":" + canonicalizeJson(val[key], volatileKeys);
+    });
+    return "{" + entries.join(",") + "}";
+}
+/**
+ * Computes a deterministic SHA-256 content hash of the exported Markdown body
+ * and its companion metadataAttributes (excluding content_hash and volatile keys).
+ *
+ * Formula: sha256( markdown body + "\n" + canonical JSON of metadataAttributes, excluding content_hash )
+ * Format: "sha256:<hex>"
+ */
+export function computeContentHash(markdownBody, metadataAttributes, volatileKeys = DEFAULT_VOLATILE_KEYS) {
+    const normalizedMarkdown = markdownBody.replace(/\r\n/g, "\n");
+    const canonicalJson = canonicalizeJson(metadataAttributes, volatileKeys);
+    const hashInput = `${normalizedMarkdown}\n${canonicalJson}`;
+    const digest = crypto.createHash("sha256").update(hashInput, "utf-8").digest("hex");
+    return `sha256:${digest}`;
+}

package/dist/utils/mapper.js

@@ -1,5 +1,7 @@
 import { CaseFieldTypeId } from "../tools/cases/types.js";
+import { RESERVED_CASE_FIELDS } from "../tools/cases/fields.js";
 import { sanitizeValue } from "./sanitizer.js";
+export { RESERVED_CASE_FIELDS };
 /**
  * Processes custom fields from a test case, converting system names to human-readable labels
  * and mapping dropdown values to their display text.
@@ -14,7 +16,9 @@ export function processCustomFields(testCase, caseFields) {
     const fieldNameMap = new Map();
     const dropdownOptionsMap = new Map();
     for (const field of applicableFields) {
-        fieldNameMap.set(field.system_name, toSnakeCase(field.label));
+        const snakeLabel = toSnakeCase(field.label);
+        const outputKey = RESERVED_CASE_FIELDS.has(snakeLabel) ? field.system_name : snakeLabel;
+        fieldNameMap.set(field.system_name, outputKey);
         const optionsMap = parseDropdownOptions(field);
         if (optionsMap.size > 0) {
             dropdownOptionsMap.set(field.system_name, optionsMap);
@@ -23,15 +27,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 +53,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

@@ -12,6 +12,31 @@ function decodeHtmlEntities(str) {
         .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)))
         .replace(/&#x([0-9a-fA-F]+);/g, (_, code) => String.fromCharCode(parseInt(code, 16)));
 }
+const KNOWN_HTML_TAGS = new Set([
+    'a', 'abbr', 'address', 'area', 'article', 'aside', 'audio',
+    'b', 'base', 'bdi', 'bdo', 'blockquote', 'body', 'br', 'button',
+    'canvas', 'caption', 'cite', 'code', 'col', 'colgroup',
+    'data', 'datalist', 'dd', 'del', 'details', 'dfn', 'dialog', 'div', 'dl', 'dt',
+    'em', 'embed',
+    'fieldset', 'figcaption', 'figure', 'footer', 'form',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'head', 'header', 'hgroup', 'hr', 'html',
+    'i', 'iframe', 'img', 'input', 'ins',
+    'kbd',
+    'label', 'legend', 'li', 'link',
+    'main', 'map', 'mark', 'menu', 'meta', 'meter',
+    'nav', 'noscript',
+    'object', 'ol', 'optgroup', 'option', 'output',
+    'p', 'picture', 'pre', 'progress',
+    'q',
+    'rp', 'rt', 'ruby',
+    's', 'samp', 'script', 'search', 'section', 'select', 'slot', 'small', 'source', 'span', 'strong', 'style', 'sub',
+    'summary', 'sup', 'svg',
+    'table', 'tbody', 'td', 'template', 'textarea', 'tfoot', 'th', 'thead', 'time', 'title', 'tr', 'track',
+    'u', 'ul',
+    'var', 'video',
+    'wbr',
+    'font', 'center', 'strike', 'tt', 'big', 'marquee', 'nobr', 'o:p'
+]);
 /**
  * Converts TestRail HTML markup to clean, structured Markdown / plain text.
  */
@@ -78,8 +103,20 @@ export function htmlToMarkdown(html) {
         });
         return `\n${items}\n`;
     });
-    // Strip remaining HTML tags
-    text = text.replace(/<[^>]+>/g, '');
+    // Strip scripts and styles along with their content
+    text = text.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '');
+    text = text.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '');
+    // Strip HTML comments, CDATA, and DOCTYPE declarations
+    text = text.replace(/<!--[\s\S]*?-->/g, '');
+    text = text.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/gi, '$1');
+    text = text.replace(/<!DOCTYPE[^>]*>/gi, '');
+    // Strip remaining known HTML tags while preserving comparison signs and non-HTML angle brackets
+    text = text.replace(/<\/?([a-zA-Z][a-zA-Z0-9:-]*)(?:\s+[a-zA-Z_:@][-a-zA-Z0-9_:.]*(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'>]+))?)*\s*\/?>/gi, (match, tagName) => {
+        if (KNOWN_HTML_TAGS.has(tagName.toLowerCase())) {
+            return '';
+        }
+        return match;
+    });
     // Decode HTML entities
     text = decodeHtmlEntities(text);
     // Clean up whitespace and newlines
@@ -145,12 +182,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/section_path.js

@@ -0,0 +1,60 @@
+export const SECTION_PATH_SEPARATOR = " > ";
+export const MAX_SECTION_DEPTH = 50;
+/**
+ * Creates a memoized section lookup. Sections passed in `preloaded` (e.g. from a single
+ * `getSections` call) are served from memory; anything missing is fetched lazily via
+ * `client.getSection`. Failed lookups resolve to `null`.
+ */
+export function createSectionLookup(client, preloaded = []) {
+    const cache = new Map();
+    for (const section of preloaded) {
+        cache.set(section.id, section);
+    }
+    return async (sectionId) => {
+        const cached = cache.get(sectionId);
+        if (cached) {
+            return cached;
+        }
+        const section = await client.getSection(sectionId).catch(() => null);
+        if (section) {
+            cache.set(sectionId, section);
+        }
+        return section ?? null;
+    };
+}
+/**
+ * Resolves the section hierarchy from root to leaf by walking `parent_id`.
+ *
+ * - Returns `[]` if the leaf section itself cannot be resolved (or has no name).
+ * - Falls back to `[leafName]` if any ancestor cannot be resolved, a cycle is detected,
+ *   or the hierarchy exceeds `MAX_SECTION_DEPTH`.
+ */
+export async function resolveSectionPath(sectionId, lookup) {
+    const leaf = await lookup(sectionId);
+    if (!leaf?.name) {
+        return [];
+    }
+    const names = [leaf.name];
+    const visited = new Set([sectionId]);
+    let parentId = leaf.parent_id;
+    while (parentId !== null && parentId !== undefined) {
+        if (visited.has(parentId) || names.length >= MAX_SECTION_DEPTH) {
+            return [leaf.name];
+        }
+        visited.add(parentId);
+        const parent = await lookup(parentId);
+        if (!parent?.name) {
+            return [leaf.name];
+        }
+        names.unshift(parent.name);
+        parentId = parent.parent_id;
+    }
+    return names;
+}
+/**
+ * Formats a section path for Markdown output. Literal `>` characters inside section names
+ * are escaped as `\>` so they cannot be confused with the path separator.
+ */
+export function formatSectionPath(names) {
+    return names.map(name => name.replace(/>/g, "\\>")).join(SECTION_PATH_SEPARATOR);
+}

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "3.1.0";
+export const VERSION = "3.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "3.1.0",
+  "version": "3.3.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,10 +59,10 @@
   "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",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "archiver": "^7.0.1",
     "dotenv": "^17.4.2",
     "zod": "^4.6.5"