@uarlouski/testrail-mcp-server 2.8.0 → 2.10.0

package/README.md

@@ -16,6 +16,7 @@
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-blue.svg" alt="TypeScript"></a>
   <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>
 </p>
 
 <p align="center">
@@ -138,7 +139,62 @@ Once configured, turbo-charge your QA workflow by asking your AI assistant:
 - *"Show me all test cases in section 5 of project 3."*
 - *"Create a comprehensive test case for 'Login Validation' with detailed steps."*
 - *"Start a new test run containing cases from section 5."*
-- *"Mark test case ID 1042 as passed with the comment 'Tested successfully on staging'."*
+---
+
+## 🖥️ Command Line Interface (CLI) & CI/CD Automation
+
+In addition to interacting via AI assistants, you can invoke any TestRail tool directly from shell scripts, terminal environments, and automated CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins) using **`testrail-cli`** or **`npx`** — with zero LLM overhead.
+
+- **Deterministic Execution**: Returns standard Unix exit codes (`0` on success, `1` on error).
+- **Pipeline-Native Output**: Emits clean JSON to `stdout` for piping into tools like `jq`, while diagnostics and errors go to `stderr`.
+- **Zero Duplication**: Reuses the exact same API client, retry logic, and validation schemas as the MCP server.
+
+### Invocation Methods
+
+```bash
+# Method 1: Direct npx subcommand (Recommended)
+npx @uarlouski/testrail-mcp-server cli <command> [flags]
+
+# Method 2: Global or local binary
+testrail-cli <command> [flags]
+
+# Method 3: Via package runner
+npx -p @uarlouski/testrail-mcp-server testrail-cli <command> [flags]
+```
+
+### Examples
+
+#### Query Projects (`query_project`)
+```bash
+# List all active projects
+npx @uarlouski/testrail-mcp-server cli query_project --action many
+
+# Query a single project by ID
+npx @uarlouski/testrail-mcp-server cli query_project --action one --project_id 1
+```
+
+#### Export Cases for Knowledge Base / RAG (`export_cases_for_rag`)
+```bash
+# Export all cases for a project into Markdown & metadata sidecars
+npx @uarlouski/testrail-mcp-server cli export_cases_for_rag \
+  --project_id 1 \
+  --output_dir ./rag_exports
+
+# Export specific cases by ID (comma-separated list)
+npx @uarlouski/testrail-mcp-server cli export_cases_for_rag \
+  --case_ids C101,C102,103 \
+  --output_dir ./rag_exports
+```
+
+#### Command Discovery & Flag Documentation
+```bash
+# List all available commands
+npx @uarlouski/testrail-mcp-server cli --help
+
+# Show parameter options for a specific tool
+npx @uarlouski/testrail-mcp-server cli query_project --help
+npx @uarlouski/testrail-mcp-server cli export_cases_for_rag --help
+```
 
 ---
 
@@ -164,7 +220,8 @@ To ensure smooth transitions, deprecated tools remain available by default (`TES
 
 | Deprecated Tool | Replacement | Status |
 |-----------------|-------------|--------|
-| `add_attachment_to_run` | `add_attachment` (`entity_type: "case" \| "run"`) | Deprecated in `2.3.0`, scheduled for removal in `3.0.0` |
+| `add_attachment_to_run` | `add_attachment` (`entity_type: "case" \| "run" \| "result"`) | Deprecated in `2.3.0`, scheduled for removal in `3.0.0` |
+| `get_sections` | `query_section` (`action: "many"`) | Deprecated in `2.8.0`, scheduled for removal in `3.0.0` |
 
 > **💡 Token Tip**: If you are not using legacy tools, set `TESTRAIL_ENABLE_DEPRECATED_TOOLS=false` in your environment to eliminate deprecated tool definitions from the LLM prompt and save tokens!
 

package/dist/adapters/cli_parser.js

@@ -0,0 +1,187 @@
+/**
+ * Parses raw command-line arguments into a command name, tool flags, and global connection options.
+ */
+export function parseArgs(argv) {
+    let command;
+    const flags = {};
+    const globalOptions = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help") {
+            globalOptions.help = true;
+            flags.help = true;
+        }
+        else if (arg === "-v" || arg === "--version") {
+            globalOptions.version = true;
+            flags.version = true;
+        }
+        else if (!arg.startsWith("-")) {
+            if (!command) {
+                command = arg;
+            }
+        }
+        else {
+            let [rawKey, val] = arg.replace(/^--?/, "").split("=");
+            let isNegative = false;
+            if (rawKey.startsWith("no-")) {
+                rawKey = rawKey.slice(3);
+                isNegative = true;
+            }
+            const key = rawKey.replace(/-/g, "_");
+            if (val === undefined) {
+                if (isNegative) {
+                    val = "false";
+                }
+                else if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+                    val = argv[++i];
+                }
+                else {
+                    val = "true";
+                }
+            }
+            if (key === "url") {
+                globalOptions.url = val;
+            }
+            else if (key === "username") {
+                globalOptions.username = val;
+            }
+            else if (key === "api_key" || key === "apikey") {
+                globalOptions.apiKey = val;
+            }
+            else {
+                flags[key] = val === "true" ? true : val === "false" ? false : val;
+            }
+        }
+    }
+    return { command, flags, globalOptions };
+}
+/**
+ * Coerces primitive CLI strings to numbers, booleans, JSON objects, or arrays.
+ */
+export function coerceValue(raw) {
+    if (raw === undefined || raw === null || typeof raw === "boolean") {
+        return raw;
+    }
+    if (typeof raw === "string") {
+        const trimmed = raw.trim();
+        if (trimmed === "true") {
+            return true;
+        }
+        if (trimmed === "false") {
+            return false;
+        }
+        // JSON objects or arrays
+        if ((trimmed.startsWith("{") && trimmed.endsWith("}")) || (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+            try {
+                return JSON.parse(trimmed);
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        // Comma-separated array list
+        if (trimmed.includes(",")) {
+            return trimmed.split(",").map(item => coerceValue(item.trim()));
+        }
+        // Numeric string
+        if (!isNaN(Number(trimmed)) && trimmed !== "") {
+            return Number(trimmed);
+        }
+        return raw;
+    }
+    if (Array.isArray(raw)) {
+        return raw.map(item => coerceValue(item));
+    }
+    return raw;
+}
+/**
+ * Coerces flat CLI flags and auto-wraps into `{ payload: ... }` for discriminated union tools.
+ */
+export function coerceFlagsForTool(rawFlags, parameters) {
+    const cleanFlags = {};
+    for (const [key, val] of Object.entries(rawFlags)) {
+        if (key === "help" || key === "version" || key === "_") {
+            continue;
+        }
+        cleanFlags[key] = coerceValue(val);
+    }
+    // Auto-wrap into payload if the tool expects a payload container (e.g. query_project)
+    if (parameters.payload && !cleanFlags.payload) {
+        return { payload: cleanFlags };
+    }
+    return cleanFlags;
+}
+/**
+ * Formats general CLI help documentation.
+ */
+export function formatGeneralHelp(tools) {
+    const maxLen = Math.max(...tools.map(t => t.name.length), 20);
+    const cmdList = tools
+        .map(t => `  ${t.name.padEnd(maxLen + 2, " ")}${t.description.split("\n")[0]}`)
+        .join("\n");
+    return [
+        "TestRail CLI - Execute TestRail actions directly in terminal & CI/CD",
+        "",
+        "Usage: testrail-cli <command> [options]",
+        "",
+        "Commands:",
+        cmdList,
+        "",
+        "Global Options:",
+        "  --url <url>           TestRail instance URL (overrides TESTRAIL_INSTANCE_URL)",
+        "  --username <email>    TestRail username (overrides TESTRAIL_USERNAME)",
+        "  --api-key <key>       TestRail API key (overrides TESTRAIL_API_KEY)",
+        "  -h, --help            Show help documentation",
+        "  -v, --version         Show CLI version",
+        "",
+        "Run 'testrail-cli <command> --help' for command-specific flags."
+    ].join("\n");
+}
+/**
+ * Formats tool-specific help documentation.
+ */
+export function formatToolHelp(tool) {
+    const shapes = [];
+    const params = tool.parameters;
+    if (params.payload) {
+        const payloadDef = params.payload.def;
+        if (Array.isArray(payloadDef?.options)) {
+            for (const opt of payloadDef.options) {
+                shapes.push(opt.shape);
+            }
+        }
+    }
+    else {
+        shapes.push(params);
+    }
+    const seen = new Set();
+    const options = [];
+    for (const shape of shapes) {
+        for (const [name, fieldSchema] of Object.entries(shape)) {
+            if (seen.has(name)) {
+                continue;
+            }
+            seen.add(name);
+            const def = fieldSchema?.def;
+            const isOptional = def?.type === "optional";
+            const innerDef = isOptional ? def?.innerType?.def : def;
+            const type = innerDef?.type || "string";
+            const desc = fieldSchema?.description || "";
+            const req = isOptional ? "(Optional)" : "(Required)";
+            options.push(`  --${name} <${type}>  ${desc} ${req}`.trimEnd());
+        }
+    }
+    return [
+        `Command: ${tool.name}`,
+        `Description: ${tool.description}`,
+        "",
+        "Options:",
+        ...options,
+        "",
+        "Global Options:",
+        "  --url <url>           TestRail instance URL",
+        "  --username <email>    TestRail username",
+        "  --api-key <key>       TestRail API key",
+        "  -h, --help            Show help for this command"
+    ].join("\n");
+}

package/dist/cli.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { z } from "zod";
+import { TestRailClient } from "./client/testrail.js";
+import { ALL_TOOLS } from "./tools/registry.js";
+import { removeNullish } from "./utils/sanitizer.js";
+import { parseArgs, coerceFlagsForTool, formatGeneralHelp, formatToolHelp } from "./adapters/cli_parser.js";
+import { VERSION } from "./version.js";
+const CredentialSchema = z.object({
+    url: z.url("Must be a valid TestRail URL (e.g. https://example.testrail.io)"),
+    username: z.email("Must be a valid email address"),
+    apiKey: z.string().min(1, "API key is required"),
+});
+export function resolveClient(options, env) {
+    const instanceUrl = options.url || env.TESTRAIL_INSTANCE_URL;
+    const username = options.username || env.TESTRAIL_USERNAME;
+    const apiKey = options.apiKey || env.TESTRAIL_API_KEY;
+    const credResult = CredentialSchema.safeParse({
+        url: instanceUrl,
+        username,
+        apiKey,
+    });
+    if (!credResult.success) {
+        console.error("Error: Missing or invalid TestRail credentials.");
+        for (const issue of credResult.error.issues) {
+            console.error(`  - ${issue.path.join(".")}: ${issue.message}`);
+        }
+        console.error("\nPlease set TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, and TESTRAIL_API_KEY environment variables,");
+        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);
+}
+export function validateToolArgs(tool, flags) {
+    const coercedArgs = coerceFlagsForTool(flags, tool.parameters);
+    const ToolSchema = z.object(tool.parameters);
+    const validationResult = ToolSchema.safeParse(coercedArgs);
+    if (!validationResult.success) {
+        console.error(`Validation error for command "${tool.name}":`);
+        for (const issue of validationResult.error.issues) {
+            console.error(`  - ${issue.path.join(".")}: ${issue.message}`);
+        }
+        console.error(`\nRun 'testrail-cli ${tool.name} --help' for flag specifications.`);
+        return null;
+    }
+    return validationResult.data;
+}
+export async function executeTool(tool, client, args) {
+    try {
+        const output = await tool.handler(args, client);
+        const sanitized = removeNullish(output);
+        console.log(JSON.stringify(sanitized, null, 2));
+        return 0;
+    }
+    catch (error) {
+        console.error(`Error executing "${tool.name}": ${error.message || error}`);
+        return 1;
+    }
+}
+export async function runCli(argv, env = process.env, clientOverride) {
+    const { command, flags, globalOptions } = parseArgs(argv);
+    if (globalOptions.version) {
+        console.log(`testrail-cli v${VERSION}`);
+        return 0;
+    }
+    if (!command) {
+        if (globalOptions.help) {
+            console.log(formatGeneralHelp(ALL_TOOLS));
+            return 0;
+        }
+        console.error("Error: No command specified.\n");
+        console.error(formatGeneralHelp(ALL_TOOLS));
+        return 1;
+    }
+    const tool = ALL_TOOLS.find(t => t.name === command);
+    if (!tool) {
+        console.error(`Error: Unknown command "${command}".\n`);
+        console.error("Run 'testrail-cli --help' to view available commands.");
+        return 1;
+    }
+    if (globalOptions.help) {
+        console.log(formatToolHelp(tool));
+        return 0;
+    }
+    const client = clientOverride || resolveClient(globalOptions, env);
+    if (!client) {
+        return 1;
+    }
+    const toolArgs = validateToolArgs(tool, flags);
+    if (!toolArgs) {
+        return 1;
+    }
+    return executeTool(tool, client, toolArgs);
+}
+// Direct execution from CLI
+const isDirectExecution = process.argv[1] && (process.argv[1].endsWith("/cli.js") ||
+    process.argv[1].endsWith("/cli.ts") ||
+    process.argv[1].endsWith("/testrail-cli"));
+if (isDirectExecution) {
+    runCli(process.argv.slice(2)).then(code => {
+        if (code !== 0) {
+            process.exit(code);
+        }
+    }).catch(err => {
+        console.error("Unexpected error:", err);
+        process.exit(1);
+    });
+}

package/dist/index.js

@@ -5,7 +5,17 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { TestRailClient } from "./client/testrail.js";
 import { getToolsToRegister } from "./tools/registry.js";
 import { removeNullish } from "./utils/sanitizer.js";
+import { VERSION } from "./version.js";
 import z from "zod";
+// Allow delegating to CLI directly when invoked via 'cli' subcommand (e.g. npx @uarlouski/testrail-mcp-server cli ...)
+const isDirectExecution = process.argv[1] && (process.argv[1].endsWith("/index.js") ||
+    process.argv[1].endsWith("/index.ts") ||
+    process.argv[1].endsWith("/testrail-mcp-server"));
+if (isDirectExecution && process.argv[2] === "cli") {
+    const { runCli } = await import("./cli.js");
+    const code = await runCli(process.argv.slice(3));
+    process.exit(code);
+}
 const EnvSchema = z.object({
     TESTRAIL_INSTANCE_URL: z.url('Must be a valid TestRail URL'),
     TESTRAIL_USERNAME: z.email('Must be a valid email address'),
@@ -27,7 +37,7 @@ if (!parseResult.success) {
 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.8.0",
+    version: VERSION,
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
 let tools;

package/dist/tools/attachments/add_attachment.js

@@ -2,12 +2,12 @@ import { z } from "zod";
 import { AttachmentSchema } from "./types.js";
 import { normalizeEntityId, prepareUploadFile } from "../../utils/attachment_helper.js";
 const parameters = {
-    entity_type: z.enum(["case", "run"]).describe("The type of entity to attach the file to ('case' or 'run')"),
-    entity_id: z.union([z.number(), z.string()]).describe("The ID of the entity to attach the file to (e.g. 123 or 'C123' for cases, or numeric run ID)"),
+    entity_type: z.enum(["case", "run", "result"]).describe("The type of entity to attach the file to ('case', 'run', or 'result')"),
+    entity_id: z.union([z.number(), z.string()]).describe("The ID of the entity to attach the file to (e.g. 123 or 'C123' for cases, or numeric run / result ID)"),
     file_path: z.string().describe("The path to the file or directory to attach. Directories will be automatically zipped."),
 };
 const description = `
-Add an attachment to a test case or test run in TestRail.
+Add an attachment to a test case, test run, or test result in TestRail.
 If the file_path points to a directory, it will be automatically zipped before uploading.
 Maximum upload size is 256MB.
 `;

package/dist/tools/attachments/types.js

@@ -10,8 +10,8 @@ export const AttachmentItemSchema = z.object({
     is_image: z.union([z.boolean(), z.number()]).optional(),
 });
 export const AddAttachmentSchema = z.object({
-    entity_type: z.enum(["case", "run"]).describe("The type of entity to attach the file to ('case' or 'run')"),
-    entity_id: z.union([z.number(), z.string()]).describe("The ID of the entity to attach the file to (e.g. 123 or 'C123' for cases, or numeric run ID)"),
+    entity_type: z.enum(["case", "run", "result"]).describe("The type of entity to attach the file to ('case', 'run', or 'result')"),
+    entity_id: z.union([z.number(), z.string()]).describe("The ID of the entity to attach the file to (e.g. 123 or 'C123' for cases, or numeric run / result ID)"),
     file_path: z.string().describe("The path to the file or directory to attach. Directories will be automatically zipped."),
 });
 export const GetOneAttachmentSchema = z.object({

package/dist/tools/cases/export_cases_for_rag.js

@@ -13,7 +13,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, 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, priority, references, labels) cannot be ignored."),
 };
 function formatStepsSeparated(steps) {
     return steps.map((step, idx) => {
@@ -125,6 +125,7 @@ function buildMarkdownBody(testCase, sectionName, markdownFields) {
 function buildMetadataAttributes(testCase, sectionName, priority, metadataFields) {
     const metadataAttributes = {
         case_id: testCase.id,
+        updated_on: testCase.updated_on,
         title: testCase.title,
         section: sectionName,
         priority: priority,

package/dist/tools/results/types.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 export const ResultSchema = z.object({
     id: z.number(),
     test_id: z.number(),
-    status_id: z.number(),
+    status_id: z.number().nullable(),
     comment: z.string().nullable(),
     defects: z.string().nullable(),
 });

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = "2.10.0";

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "2.8.0",
+  "version": "2.10.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",
   "bin": {
-    "testrail-mcp-server": "./dist/index.js"
+    "testrail-mcp-server": "./dist/index.js",
+    "testrail-cli": "./dist/cli.js"
   },
   "files": [
     "dist"
@@ -41,10 +42,10 @@
   "homepage": "https://github.com/uarlouski/testrail-mcp-server#readme",
   "license": "Apache-2.0",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "archiver": "^7.0.1",
     "dotenv": "^17.4.2",
-    "zod": "^4.4.3"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -55,9 +56,7 @@
     "rimraf": "^6.1.3",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3",
-    "vitepress": "^1.6.4",
-    "vue": "^3.5.41"
+    "typescript": "^5.9.3"
   },
   "devEngines": {
     "packageManager": {
@@ -67,13 +66,16 @@
     }
   },
   "scripts": {
-    "build": "rimraf dist && tsc",
+    "version:sync": "node scripts/sync-version.mjs",
+    "prebuild": "pnpm version:sync",
+    "build": "rimraf dist && tsc && node -e \"if (process.platform !== 'win32') { ['dist/index.js', 'dist/cli.js'].forEach(f => require('fs').chmodSync(f, 0o755)); }\"",
     "start": "node dist/index.js",
+    "cli": "ts-node src/cli.ts",
     "dev": "ts-node src/index.ts",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
     "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
+    "docs:dev": "pnpm --prefix docs dev",
+    "docs:build": "pnpm --prefix docs build",
+    "docs:preview": "pnpm --prefix docs preview"
   }
 }