@uarlouski/testrail-mcp-server 2.5.0 → 2.7.0

package/README.md

@@ -151,10 +151,12 @@ Once configured, turbo-charge your QA workflow by asking your AI assistant:
 | `TESTRAIL_API_KEY` | Your TestRail API key ([Guide](https://support.testrail.com/hc/en-us/articles/7077039051412-Accessing-the-TestRail-API)) | ✅ | |
 | `TESTRAIL_ENABLE_SHARED_STEPS` | Set to `true` to enable Shared Steps management tools | | `false` |
 | `TESTRAIL_ENABLE_CASE_HISTORY` | Set to `true` to enable Case History and revision tracking tools | | `false` |
+| `TESTRAIL_ENABLE_RAG_TOOLS` | Set to `true` to enable Knowledge Base / RAG export tools (`export_cases_for_rag`) | | `false` |
 | `TESTRAIL_ALLOW_WRITE_OPERATIONS` | Allow write operations (e.g. adding/updating test cases, test runs, sections) | | `true` |
 | `TESTRAIL_ALLOW_READ_OPERATIONS` | Allow read operations (e.g. retrieving projects, test cases, templates) | | `true` |
 | `TESTRAIL_ALLOW_DELETE_OPERATIONS` | Allow delete operations (e.g. deleting cases or shared steps). Enabled strictly via `true`. | | `false` |
 | `TESTRAIL_ENABLE_DEPRECATED_TOOLS` | Enable deprecated tools for backward compatibility. Set to `false` to reduce context token overhead. | | `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. | | - |
 
 ### ⚠️ Deprecation Lifecycle & Features Scheduled for Removal
 

package/dist/client/testrail.js

@@ -13,6 +13,7 @@ export class TestRailClient {
     statusesPromise = null;
     projectsPromise = null;
     templatesPromiseMap = new Map();
+    sectionsPromiseMap = new Map();
     constructor(baseUrl, email, apiKey) {
         this.baseUrl = baseUrl.replace(/\/$/, "");
         const auth = Buffer.from(`${email}:${apiKey}`).toString('base64');
@@ -60,7 +61,10 @@ export class TestRailClient {
         return this.paginateAll(url, 'cases');
     }
     async getSection(sectionId) {
-        return this.get(`${API_BASE_V2}/get_section/${sectionId}`);
+        if (!this.sectionsPromiseMap.has(sectionId.toString())) {
+            this.sectionsPromiseMap.set(sectionId.toString(), this.get(`${API_BASE_V2}/get_section/${sectionId}`));
+        }
+        return this.sectionsPromiseMap.get(sectionId.toString());
     }
     async getPriorities() {
         if (!this.prioritiesPromise) {

package/dist/index.js

@@ -12,30 +12,41 @@ const EnvSchema = z.object({
     TESTRAIL_API_KEY: z.string().min(1, 'API key is required'),
     TESTRAIL_ENABLE_SHARED_STEPS: z.string().optional().transform(val => val === 'true'),
     TESTRAIL_ENABLE_CASE_HISTORY: z.string().optional().transform(val => val === 'true'),
+    TESTRAIL_ENABLE_RAG_TOOLS: z.string().optional().transform(val => val === 'true'),
     TESTRAIL_ALLOW_WRITE_OPERATIONS: z.string().optional().transform(val => val === undefined ? true : val === 'true'),
     TESTRAIL_ALLOW_READ_OPERATIONS: z.string().optional().transform(val => val === undefined ? true : val === 'true'),
     TESTRAIL_ALLOW_DELETE_OPERATIONS: z.string().optional().transform(val => val === 'true'),
-    TESTRAIL_ENABLE_DEPRECATED_TOOLS: z.string().optional().transform(val => val === undefined ? true : 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) : [])
 });
 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_ALLOW_WRITE_OPERATIONS, TESTRAIL_ALLOW_READ_OPERATIONS, TESTRAIL_ALLOW_DELETE_OPERATIONS, TESTRAIL_ENABLE_DEPRECATED_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 } = parseResult.data;
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "2.5.0",
+    version: "2.7.0",
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
-const tools = getToolsToRegister({
-    enableSharedSteps: TESTRAIL_ENABLE_SHARED_STEPS,
-    enableCaseHistory: TESTRAIL_ENABLE_CASE_HISTORY,
-    allowWrite: TESTRAIL_ALLOW_WRITE_OPERATIONS,
-    allowRead: TESTRAIL_ALLOW_READ_OPERATIONS,
-    allowDelete: TESTRAIL_ALLOW_DELETE_OPERATIONS,
-    enableDeprecatedTools: TESTRAIL_ENABLE_DEPRECATED_TOOLS
-});
+let tools;
+try {
+    tools = getToolsToRegister({
+        enableSharedSteps: TESTRAIL_ENABLE_SHARED_STEPS,
+        enableCaseHistory: TESTRAIL_ENABLE_CASE_HISTORY,
+        enableRagTools: TESTRAIL_ENABLE_RAG_TOOLS,
+        allowWrite: TESTRAIL_ALLOW_WRITE_OPERATIONS,
+        allowRead: TESTRAIL_ALLOW_READ_OPERATIONS,
+        allowDelete: TESTRAIL_ALLOW_DELETE_OPERATIONS,
+        enableDeprecatedTools: TESTRAIL_ENABLE_DEPRECATED_TOOLS,
+        disabledTools: TESTRAIL_DISABLED_TOOLS
+    });
+}
+catch (error) {
+    console.error("Invalid TestRail environment configuration:", error.message);
+    process.exit(1);
+}
 for (const tool of tools) {
     server.registerTool(tool.name, {
         description: tool.description,

package/dist/tools/cases/export_cases_for_rag.js

@@ -0,0 +1,189 @@
+import { z } from "zod";
+import * as fs from "fs";
+import * as path from "path";
+import { normalizeEntityId, sanitizeValue } from "../../utils/sanitizer.js";
+import { processCustomFields } from "../../utils/mapper.js";
+import { getBaseDirectory } from "../../utils/fs.js";
+import { CaseFieldTypeId, getFieldType } from "./fields.js";
+const parameters = {
+    case_ids: z.array(z.union([z.string(), z.number()])).min(1).describe("List of test case IDs (e.g. ['C123', 456])"),
+    output_dir: z.string().optional().describe("Directory to save exported files. Defaults to an auto-generated directory in the current working directory."),
+};
+function formatStepsSeparated(steps) {
+    return steps.map((step, idx) => {
+        const stepNum = idx + 1;
+        const content = typeof step.content === "string" ? sanitizeValue(step.content).trim() : "";
+        const expected = typeof step.expected === "string" ? sanitizeValue(step.expected).trim() : "";
+        const additionalInfo = typeof step.additional_info === "string" ? sanitizeValue(step.additional_info).trim() : "";
+        let stepText = `${stepNum}. **Action**: ${content}`;
+        if (additionalInfo) {
+            stepText += `\n   - **Info**: ${additionalInfo}`;
+        }
+        if (expected) {
+            stepText += `\n   - **Expected**: ${expected}`;
+        }
+        return stepText;
+    }).join("\n\n");
+}
+function isMarkdownField(fieldDef, value) {
+    if (fieldDef) {
+        const typeInfo = getFieldType(fieldDef.type_id);
+        if (!typeInfo.isStructured) {
+            return true;
+        }
+        // If string type, check if content is multi-line
+        if (fieldDef.type_id === CaseFieldTypeId.String) {
+            return typeof value === "string" && value.includes("\n");
+        }
+        return false;
+    }
+    // Fallback if no field schema definition is found
+    return typeof value === "string" && value.includes("\n");
+}
+function sanitizeMetadataValue(val) {
+    if (Array.isArray(val)) {
+        return val.map(item => (item !== null && typeof item === "object") ? (item.title || item.name || item.label || JSON.stringify(item)) : item);
+    }
+    return val;
+}
+const IGNORED_METADATA_FIELDS = new Set([
+    "created_by",
+    "updated_by",
+    "display_order",
+    "is_deleted",
+    "review_status",
+    "reviewer",
+]);
+function buildFieldDefinitionMap(caseFields) {
+    const fieldDefMap = new Map();
+    for (const cf of caseFields) {
+        fieldDefMap.set(cf.system_name, cf);
+        if (cf.name) {
+            fieldDefMap.set(cf.name, cf);
+        }
+        const clean = cf.system_name.replace(/^custom_/, "");
+        fieldDefMap.set(clean, cf);
+        if (cf.label) {
+            fieldDefMap.set(cf.label, cf);
+            const snakeLabel = cf.label.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '');
+            fieldDefMap.set(snakeLabel, cf);
+        }
+    }
+    return fieldDefMap;
+}
+function categorizeCustomFields(customFields, fieldDefMap) {
+    const markdownFields = [];
+    const metadataFields = [];
+    const seenKeys = new Set();
+    for (const [key, val] of Object.entries(customFields)) {
+        const cleanKey = key.replace(/^custom_/, "");
+        if (seenKeys.has(cleanKey) || seenKeys.has(key) || IGNORED_METADATA_FIELDS.has(cleanKey) || IGNORED_METADATA_FIELDS.has(key)) {
+            continue;
+        }
+        if (val === null || val === undefined || val === "" || (Array.isArray(val) && val.length === 0)) {
+            continue;
+        }
+        seenKeys.add(cleanKey);
+        seenKeys.add(key);
+        const fieldDef = fieldDefMap.get(key) || fieldDefMap.get(cleanKey) || fieldDefMap.get(`custom_${cleanKey}`);
+        if (isMarkdownField(fieldDef, val)) {
+            const header = fieldDef?.label || cleanKey.replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase());
+            markdownFields.push({ header, value: val, fieldDef });
+        }
+        else {
+            metadataFields.push({ key: cleanKey, value: val, fieldDef });
+        }
+    }
+    return { markdownFields, metadataFields };
+}
+function buildMarkdownBody(testCase, sectionName, markdownFields) {
+    const mdLines = [];
+    mdLines.push(`# [C${testCase.id}] ${sanitizeValue(testCase.title)}`);
+    mdLines.push("");
+    mdLines.push(`**Section**: ${sectionName}`);
+    mdLines.push("");
+    for (const { header, value, fieldDef } of markdownFields) {
+        mdLines.push(`## ${header}`);
+        if (fieldDef?.type_id === CaseFieldTypeId.Steps || (Array.isArray(value) && value[0]?.content !== undefined)) {
+            mdLines.push(formatStepsSeparated(value));
+        }
+        else {
+            mdLines.push(typeof value === "object" ? JSON.stringify(value, null, 2) : sanitizeValue(String(value)).trim());
+        }
+        mdLines.push("");
+    }
+    return mdLines.join("\n").trim() + "\n";
+}
+function buildMetadataAttributes(testCase, sectionName, priority, metadataFields) {
+    const metadataAttributes = {
+        case_id: testCase.id,
+        title: testCase.title,
+        section: sectionName,
+        priority: priority,
+    };
+    if (testCase.refs) {
+        metadataAttributes.references = testCase.refs;
+    }
+    if (testCase.labels && testCase.labels.length > 0) {
+        metadataAttributes.labels = testCase.labels.map(l => l.title);
+    }
+    for (const { key, value, fieldDef } of metadataFields) {
+        if (fieldDef?.type_id === CaseFieldTypeId.MultiSelect) {
+            const listVal = Array.isArray(value) ? value : [value];
+            metadataAttributes[key] = sanitizeMetadataValue(listVal.map(item => String(item)));
+        }
+        else {
+            metadataAttributes[key] = sanitizeMetadataValue(value);
+        }
+    }
+    return metadataAttributes;
+}
+export const exportCasesForRagTool = {
+    name: "export_cases_for_rag",
+    mode: "read",
+    description: "Export test cases as formatted Markdown documents with companion JSON metadata sidecar files for Knowledge Base and RAG ingestion.",
+    parameters,
+    handler: async ({ case_ids, output_dir }, client) => {
+        const baseDir = getBaseDirectory();
+        const targetDir = output_dir
+            ? (path.isAbsolute(output_dir) ? output_dir : path.resolve(baseDir, output_dir))
+            : path.resolve(baseDir, `rag_export_${Date.now()}`);
+        await fs.promises.mkdir(targetDir, { recursive: true });
+        const [priorities, caseFields] = await Promise.all([
+            client.getPriorities().catch(() => []),
+            client.getCaseFields().catch(() => []),
+        ]);
+        const writtenFiles = [];
+        for (const rawId of case_ids) {
+            const id = normalizeEntityId(rawId);
+            const testCase = await client.getCase(id);
+            let sectionName = "Unknown";
+            if (testCase.section_id) {
+                const section = await client.getSection(Number(testCase.section_id));
+                if (section?.name) {
+                    sectionName = section.name;
+                }
+            }
+            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 fieldDefMap = buildFieldDefinitionMap(applicableFields);
+            const customFields = processCustomFields(testCase, caseFields);
+            const { markdownFields, metadataFields } = categorizeCustomFields(customFields, fieldDefMap);
+            const markdownContent = buildMarkdownBody(testCase, sectionName, markdownFields);
+            const metadataAttributes = buildMetadataAttributes(testCase, sectionName, priority, metadataFields);
+            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");
+            await fs.promises.writeFile(path.join(targetDir, metaFilename), JSON.stringify({ metadataAttributes }, null, 2), "utf-8");
+            writtenFiles.push(docFilename, metaFilename);
+        }
+        return {
+            success: true,
+            exported_count: case_ids.length,
+            output_dir: targetDir,
+            files: writtenFiles,
+            message: `Successfully exported ${case_ids.length} test case(s) for Knowledge Base ingestion.`,
+        };
+    },
+};

package/dist/tools/cases/fields.js

@@ -0,0 +1,47 @@
+export const CaseFieldTypeId = {
+    String: 1,
+    Integer: 2,
+    Text: 3,
+    URL: 4,
+    Checkbox: 5,
+    Dropdown: 6,
+    User: 7,
+    Date: 8,
+    Milestone: 9,
+    Steps: 10,
+    StepResults: 11,
+    MultiSelect: 12,
+    Scenarios: 13,
+    List: 14,
+};
+export const FIELD_TYPES = [
+    { typeId: CaseFieldTypeId.String, name: "String", isStructured: true },
+    { typeId: CaseFieldTypeId.Integer, name: "Integer", isStructured: true },
+    { typeId: CaseFieldTypeId.Text, name: "Text", isStructured: false },
+    { typeId: CaseFieldTypeId.URL, name: "URL", isStructured: true },
+    { typeId: CaseFieldTypeId.Checkbox, name: "Checkbox", description: "Boolean value, either true or false.", isStructured: true },
+    { typeId: CaseFieldTypeId.Dropdown, name: "Dropdown", isStructured: true },
+    { typeId: CaseFieldTypeId.User, name: "User", isStructured: true },
+    { typeId: CaseFieldTypeId.Date, name: "Date", isStructured: true },
+    { typeId: CaseFieldTypeId.Milestone, name: "Milestone", isStructured: true },
+    { typeId: CaseFieldTypeId.Steps, name: "Steps", isStructured: false },
+    { typeId: CaseFieldTypeId.StepResults, name: "Step Results", isStructured: false },
+    { typeId: CaseFieldTypeId.MultiSelect, name: "Multi-select", isStructured: true },
+    { typeId: CaseFieldTypeId.Scenarios, name: "Scenarios", isStructured: false },
+    { typeId: CaseFieldTypeId.List, name: "List", isStructured: true },
+];
+export function getFieldType(typeId) {
+    const found = FIELD_TYPES.find(t => t.typeId === typeId);
+    return found ?? { typeId, name: `Unknown (${typeId})`, isStructured: true };
+}
+export const SYSTEM_FIELDS = [
+    { system_name: "title", label: "Title", type: getFieldType(CaseFieldTypeId.String).name, is_required: true, project_scope: { scope: "global" } },
+    { system_name: "section_id", label: "Section", type: getFieldType(CaseFieldTypeId.Integer).name, is_required: true, project_scope: { scope: "global" } },
+    { system_name: "template_id", label: "Template", type: getFieldType(CaseFieldTypeId.Integer).name, is_required: false, project_scope: { scope: "global" } },
+    { system_name: "type_id", label: "Type", type: getFieldType(CaseFieldTypeId.Integer).name, is_required: false, project_scope: { scope: "global" } },
+    { system_name: "priority_id", label: "Priority", type: getFieldType(CaseFieldTypeId.Integer).name, is_required: false, project_scope: { scope: "global" } },
+    { system_name: "estimate", label: "Estimate", type: getFieldType(CaseFieldTypeId.String).name, is_required: false, project_scope: { scope: "global" } },
+    { system_name: "milestone_id", label: "Milestone", type: getFieldType(CaseFieldTypeId.Integer).name, is_required: false, project_scope: { scope: "global" } },
+    { 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." },
+];

package/dist/tools/cases/get_case_fields.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { CaseFieldTypeId, FIELD_TYPES, getFieldType, SYSTEM_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.
@@ -13,26 +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 const FIELD_TYPES = [
-    { typeId: 1, name: "String" },
-    { typeId: 2, name: "Integer" },
-    { typeId: 3, name: "Text" },
-    { typeId: 4, name: "URL" },
-    { typeId: 5, name: "Checkbox", description: "Boolean value, either true or false." },
-    { typeId: 6, name: "Dropdown" },
-    { typeId: 7, name: "User" },
-    { typeId: 8, name: "Date" },
-    { typeId: 9, name: "Milestone" },
-    { typeId: 10, name: "Steps" },
-    { typeId: 11, name: "Step Results" },
-    { typeId: 12, name: "Multi-select" },
-    { typeId: 13, name: "Scenarios" },
-    { typeId: 14, name: "List" },
-];
-function getFieldType(typeId) {
-    const found = FIELD_TYPES.find(t => t.typeId === typeId);
-    return found ?? { typeId, name: `Unknown (${typeId})` };
-}
+export { CaseFieldTypeId, FIELD_TYPES, getFieldType, SYSTEM_FIELDS };
 function isFieldRequired(field) {
     return field.configs.some(config => config.options?.is_required === true);
 }
@@ -51,7 +33,7 @@ export function mapToFieldSchema(field) {
     if (!field.include_all && field.template_ids.length > 0) {
         schema.template_ids = field.template_ids;
     }
-    if (field.type_id === 6 || field.type_id === 12) {
+    if (field.type_id === CaseFieldTypeId.Dropdown || field.type_id === CaseFieldTypeId.MultiSelect) {
         schema.options = Array.from(parseDropdownOptions(field).values());
     }
     const contexts = field.configs.map(c => c.context).filter(Boolean);
@@ -69,21 +51,11 @@ export function mapToFieldSchema(field) {
 }
 export function isFieldForProject(field, projectId) {
     const contexts = field.configs.map(c => c.context).filter(Boolean);
-    if (contexts.length === 0)
+    if (contexts.length === 0) {
         return true;
+    }
     return contexts.some(ctx => ctx.is_global || ctx.project_ids.includes(projectId));
 }
-export const SYSTEM_FIELDS = [
-    { system_name: "title", label: "Title", type: getFieldType(1).name, is_required: true, project_scope: { scope: "global" } },
-    { system_name: "section_id", label: "Section", type: getFieldType(2).name, is_required: true, project_scope: { scope: "global" } },
-    { system_name: "template_id", label: "Template", type: getFieldType(2).name, is_required: false, project_scope: { scope: "global" } },
-    { system_name: "type_id", label: "Type", type: getFieldType(2).name, is_required: false, project_scope: { scope: "global" } },
-    { system_name: "priority_id", label: "Priority", type: getFieldType(2).name, is_required: false, project_scope: { scope: "global" } },
-    { system_name: "estimate", label: "Estimate", type: getFieldType(1).name, is_required: false, project_scope: { scope: "global" } },
-    { system_name: "milestone_id", label: "Milestone", type: getFieldType(2).name, is_required: false, project_scope: { scope: "global" } },
-    { system_name: "refs", label: "References", type: getFieldType(1).name, is_required: false, project_scope: { scope: "global" } },
-    { system_name: "labels", label: "Labels", type: getFieldType(14).name, is_required: false, project_scope: { scope: "global" }, description: "Use get_labels tool to get available labels/tags." },
-];
 const description = `
 Get the field schema for test cases for a specific project.
 You should normally provide project_id to get fields applicable to your project.

package/dist/tools/cases/index.js

@@ -6,7 +6,8 @@ import { updateCasesTool } from "./update_cases.js";
 import { addCaseTool } from "./add_case.js";
 import { getCaseHistoryTool } from "./get_case_history.js";
 import { resolveCaseFieldTool } from "./resolve_case_field.js";
-export { getCaseHistoryTool, resolveCaseFieldTool };
+import { exportCasesForRagTool } from "./export_cases_for_rag.js";
+export { getCaseHistoryTool, resolveCaseFieldTool, exportCasesForRagTool };
 export const casesTools = [
     getCaseTool,
     getCasesTool,

package/dist/tools/cases/resolve_case_field.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { parseDropdownOptions } from "../../utils/mapper.js";
 import { isActive } from "../../utils/sanitizer.js";
-import { isFieldForProject } from "./get_case_fields.js";
+import { isFieldForProject, CaseFieldTypeId } from "./get_case_fields.js";
 const parameters = {
     project_id: z.number().describe("The ID of the project to resolve field values for"),
     field_name: z.string().describe("The system name of the Multi-select field (e.g. 'custom_case_feature_tags')"),
@@ -22,7 +22,7 @@ export const resolveCaseFieldTool = {
         if (!targetField) {
             throw new Error(`Field '${field_name}' not found in active case fields.`);
         }
-        if (targetField.type_id !== 12) {
+        if (targetField.type_id !== CaseFieldTypeId.MultiSelect) {
             throw new Error(`Field '${targetField.system_name}' is of type_id ${targetField.type_id}, but resolve_case_field only supports Multi-select fields (type_id: 12).`);
         }
         if (!isFieldForProject(targetField, project_id)) {

package/dist/tools/cases/types.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { LabelSchema } from "../commons/types.js";
+import { CaseFieldTypeId } from "./fields.js";
+export { CaseFieldTypeId };
 export const CaseFieldConfigSchema = z.object({
     context: z.object({
         is_global: z.boolean(),

package/dist/tools/registry.js

@@ -1,4 +1,4 @@
-import { casesTools, getCaseHistoryTool } from "./cases/index.js";
+import { casesTools, getCaseHistoryTool, exportCasesForRagTool } from "./cases/index.js";
 import { projectsTools } from "./projects/index.js";
 import { suitesTools } from "./suites/index.js";
 import { sectionsTools } from "./sections/index.js";
@@ -7,7 +7,27 @@ 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";
+export const ALL_TOOLS = [
+    ...projectsTools,
+    ...suitesTools,
+    ...casesTools,
+    getCaseHistoryTool,
+    exportCasesForRagTool,
+    ...sectionsTools,
+    ...runsTools,
+    ...resultsTools,
+    ...attachmentsTools,
+    ...commonsTools,
+    ...sharedStepsTools,
+];
+const ALL_TOOL_NAMES = new Set(ALL_TOOLS.map(t => t.name));
 export function getToolsToRegister(config) {
+    if (config.disabledTools && config.disabledTools.length > 0) {
+        const unknownTools = config.disabledTools.filter(name => !ALL_TOOL_NAMES.has(name));
+        if (unknownTools.length > 0) {
+            throw new Error(`Cannot disable non-existent tool(s): ${unknownTools.join(', ')}`);
+        }
+    }
     const tools = [
         ...projectsTools,
         ...suitesTools,
@@ -24,11 +44,17 @@ export function getToolsToRegister(config) {
     if (config.enableCaseHistory) {
         tools.push(getCaseHistoryTool);
     }
+    if (config.enableRagTools) {
+        tools.push(exportCasesForRagTool);
+    }
     const allowWrite = config.allowWrite !== false;
     const allowRead = config.allowRead !== false;
     const allowDelete = config.allowDelete === true;
     const enableDeprecatedTools = config.enableDeprecatedTools !== false;
+    const disabledSet = new Set(config.disabledTools ?? []);
     const filteredTools = tools.filter(tool => {
+        if (disabledSet.has(tool.name))
+            return false;
         if (tool.deprecated && !enableDeprecatedTools)
             return false;
         if (tool.mode === 'write')

package/dist/utils/fs.js

@@ -0,0 +1,36 @@
+import * as fs from "fs";
+import * as os from "os";
+/**
+ * Resolves a safe, writable base directory for exports and file operations.
+ *
+ * When the MCP server is spawned by host applications (IDE daemons, npx, Claude Desktop, Cursor, Gemini),
+ * `process.cwd()` or `process.env.PWD` often resolves to the root filesystem (`"/"`), where direct writes
+ * fail with ENOENT / permission errors (especially on macOS read-only APFS volumes).
+ *
+ * This function handles multi-environment fallbacks:
+ * 1. `process.env.INIT_CWD`: Set by package managers (npm/npx/pnpm) to the original caller's working directory.
+ * 2. `process.cwd()` / `process.env.PWD`: Used if pointing to a valid non-root directory.
+ * 3. `os.homedir()`: User home directory fallback if the working directory is root or invalid.
+ * 4. `os.tmpdir()`: Final safety fallback.
+ */
+export function getBaseDirectory() {
+    const candidates = [
+        process.env.INIT_CWD,
+        process.cwd(),
+        process.env.PWD,
+        os.homedir(),
+    ];
+    for (const candidate of candidates) {
+        if (candidate && candidate !== "/" && candidate.trim() !== "") {
+            try {
+                if (fs.existsSync(candidate)) {
+                    return candidate;
+                }
+            }
+            catch {
+                // Ignore and try next candidate
+            }
+        }
+    }
+    return os.tmpdir();
+}

package/dist/utils/mapper.js

@@ -1,3 +1,4 @@
+import { CaseFieldTypeId } from "../tools/cases/types.js";
 import { sanitizeValue } from "./sanitizer.js";
 /**
  * Processes custom fields from a test case, converting system names to human-readable labels
@@ -33,8 +34,24 @@ export function processCustomFields(testCase, caseFields) {
         let finalValue = value;
         if (dropdownOptionsMap.has(key)) {
             const options = dropdownOptionsMap.get(key);
-            const optionKey = String(value);
-            finalValue = options.get(optionKey) || value;
+            const field = applicableFields.find(f => f.system_name === key);
+            if (Array.isArray(value)) {
+                finalValue = value.map(v => options.get(String(v)) || v);
+            }
+            else if (field?.type_id === CaseFieldTypeId.MultiSelect) {
+                const resolved = options.get(String(value)) || value;
+                finalValue = [resolved];
+            }
+            else {
+                const optionKey = String(value);
+                finalValue = options.get(optionKey) || value;
+            }
+        }
+        else {
+            const field = applicableFields.find(f => f.system_name === key);
+            if (field?.type_id === CaseFieldTypeId.MultiSelect) {
+                finalValue = Array.isArray(value) ? value : [value];
+            }
         }
         result[outputKey] = sanitizeValue(finalValue);
     }

package/dist/utils/sanitizer.js

@@ -1,11 +1,100 @@
 /**
- * Recursively strips inline style attributes from HTML tags contained in string values
- * in an object or array. Useful for cleaning up TestRail markdown content before sending
- * to LLMs.
+ * Decodes standard and numeric HTML entities.
+ */
+function decodeHtmlEntities(str) {
+    return str
+        .replace(/ /gi, ' ')
+        .replace(/&/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;|&apos;/gi, "'")
+        .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, code) => String.fromCharCode(parseInt(code, 16)));
+}
+/**
+ * Converts TestRail HTML markup to clean, structured Markdown / plain text.
+ */
+export function htmlToMarkdown(html) {
+    if (!html || typeof html !== 'string') {
+        return html;
+    }
+    // Quick path if no HTML tags or entities
+    if (!html.includes('<') && !html.includes('&')) {
+        return html.trim();
+    }
+    let text = html;
+    // Normalize line breaks
+    text = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    // Process images / attachments (e.g. data-attachment-id, attachment get URL, or general image)
+    text = text.replace(/<span[^>]*class="[^"]*markdown-img-container[^"]*"[^>]*>([\s\S]*?)<\/span>/gi, '$1');
+    text = text.replace(/<img\b([^>]*)>/gi, (_, attrs) => {
+        const attachmentIdMatch = attrs.match(/data-attachment-id=["']([^"']+)["']/i)
+            || attrs.match(/id=["']attachment-([^"']+)["']/i)
+            || attrs.match(/src=["'][^"']*attachments\/get\/([a-zA-Z0-9-]+)[^"']*["']/i);
+        if (attachmentIdMatch) {
+            return `[Attachment: ${attachmentIdMatch[1]}]`;
+        }
+        const srcMatch = attrs.match(/src=["']([^"']+)["']/i);
+        const altMatch = attrs.match(/alt=["']([^"']*)["']/i);
+        if (srcMatch) {
+            const alt = altMatch ? altMatch[1] : 'Image';
+            return `![${alt}](${srcMatch[1]})`;
+        }
+        return '[Image]';
+    });
+    // Headings <h1> - <h6>
+    text = text.replace(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi, (_, level, content) => {
+        return `\n${'#'.repeat(Number(level))} ${content.trim()}\n\n`;
+    });
+    // Preformatted & code blocks
+    text = text.replace(/<pre[^>]*><code[^>]*>([\s\S]*?)<\/code><\/pre>/gi, (_, code) => `\n\`\`\`\n${code}\n\`\`\`\n`);
+    text = text.replace(/<pre[^>]*>([\s\S]*?)<\/pre>/gi, (_, code) => `\n\`\`\`\n${code}\n\`\`\`\n`);
+    text = text.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, '`$1`');
+    // Formatting: Bold, Italic, Strikethrough
+    text = text.replace(/<(strong|b)\b[^>]*>([\s\S]*?)<\/\1>/gi, '**$2**');
+    text = text.replace(/<(em|i)\b[^>]*>([\s\S]*?)<\/\1>/gi, '*$2*');
+    text = text.replace(/<(del|s|strike)\b[^>]*>([\s\S]*?)<\/\1>/gi, '~~$2~~');
+    // Links
+    text = text.replace(/<a\b[^>]*href=["']([^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi, '[$2]($1)');
+    // Paragraphs, breaks, dividers, divs (process before lists so li content is cleanly trimmed)
+    text = text.replace(/<hr\b[^>]*\/?>/gi, '\n---\n');
+    text = text.replace(/<br\b[^>]*\/?>/gi, '\n');
+    text = text.replace(/<p\b[^>]*>([\s\S]*?)<\/p>/gi, '\n$1\n');
+    text = text.replace(/<div\b[^>]*>([\s\S]*?)<\/div>/gi, '\n$1\n');
+    // Ordered & Unordered Lists
+    text = text.replace(/<ol\b[^>]*>([\s\S]*?)<\/ol>/gi, (_, listContent) => {
+        let index = 1;
+        const items = listContent.replace(/<li\b[^>]*>([\s\S]*?)<\/li>/gi, (__, itemContent) => {
+            const cleaned = itemContent.trim();
+            return `\n${index++}. ${cleaned}`;
+        });
+        return `\n${items}\n`;
+    });
+    text = text.replace(/<ul\b[^>]*>([\s\S]*?)<\/ul>/gi, (_, listContent) => {
+        const items = listContent.replace(/<li\b[^>]*>([\s\S]*?)<\/li>/gi, (__, itemContent) => {
+            const cleaned = itemContent.trim();
+            return `\n- ${cleaned}`;
+        });
+        return `\n${items}\n`;
+    });
+    // Strip remaining HTML tags
+    text = text.replace(/<[^>]+>/g, '');
+    // Decode HTML entities
+    text = decodeHtmlEntities(text);
+    // Clean up whitespace and newlines
+    const lines = text.split('\n').map(line => line.trimEnd());
+    text = lines.join('\n');
+    text = text.replace(/\n{3,}/g, '\n\n');
+    return text.trim();
+}
+/**
+ * Recursively cleans HTML from TestRail strings, converting HTML markup
+ * to clean Markdown/plaintext and decoding entities.
  */
 export function sanitizeValue(value) {
     if (typeof value === 'string') {
-        return value.replace(/\s*style\s*=\s*["'][^"']*["']/gi, '');
+        return htmlToMarkdown(value);
     }
     if (Array.isArray(value)) {
         return value.map(sanitizeValue);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "mcpName": "io.github.uarlouski/testrail-mcp-server",
   "description": "Model Context Protocol (MCP) server for TestRail integration, enabling LLMs to fetch test cases and metadata.",
   "main": "dist/index.js",