@uarlouski/testrail-mcp-server 3.2.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">

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) => {
@@ -105,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}`);
@@ -123,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;
@@ -195,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/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(),
 });

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);

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

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.2.0";
+export const VERSION = "3.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "3.2.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",
@@ -62,7 +62,7 @@
   "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"