@uarlouski/testrail-mcp-server 1.6.1 → 1.7.0

package/README.md

@@ -1,14 +1,15 @@
-<p align="center">
-  <h1 align="center">TestRail MCP Server</h1>
-  <p align="center">
-    A Model Context Protocol (MCP) server that connects AI assistants to TestRail test management — search, create, update, and execute test cases using natural language.
+<div align="center">
+  <h1>🚀 TestRail MCP Server</h1>
+  <p>
+    <strong>A high-performance Model Context Protocol (MCP) server connecting AI assistants (Claude, Cursor, Windsurf) directly to TestRail.</strong><br>
+    <em>Seamlessly search, create, update, and execute test cases using natural language.</em>
   </p>
-</p>
+</div>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@uarlouski/testrail-mcp-server"><img src="https://badge.fury.io/js/@uarlouski%2Ftestrail-mcp-server.svg" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/@uarlouski/testrail-mcp-server"><img src="https://img.shields.io/npm/dm/@uarlouski/testrail-mcp-server.svg" alt="npm downloads"></a>
-  <a href="https://github.com/uarlouski/testrail-mcp-server/actions/workflows/ci.yml"><img src="https://github.com/uarlouski/testrail-mcp-server/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/uarlouski/testrail-mcp-server/actions/workflows/ci.yml"><img src="https://github.com/uarlouski/testrail-mcp-server/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
   <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>
@@ -16,35 +17,35 @@
 
 ---
 
-## Why TestRail MCP Server?
+## 🌟 Why Choose TestRail MCP Server?
 
-Managing test cases manually is tedious. With the TestRail MCP Server, your AI assistant (Claude, Cursor, Windsurf, or any MCP-compliant client) talks directly to TestRail. Ask it to find test cases, create new ones, kick off test runs, or report results — all through natural conversation.
+Managing test cases manually is tedious and error-prone. With the **TestRail MCP Server**, your AI assistant (whether it’s **Claude, Cursor, Windsurf**, or any MCP-compliant client) interacts directly with your TestRail instance. Instruct it to find test cases, draft new ones, kick off test runs, and record test results—all through natural conversation.
 
-**No context switching. No copy-pasting. Just ask.**
+**No context switching. No tedious copy-pasting. Just ask your AI.**
 
-## ✨ Features
+## ✨ Key Features & Capabilities
 
-| Category | Capabilities |
-|----------|-------------|
-| **🔍 Discovery** | Browse projects, suites, and sections to map your test organization |
-| **📋 Case Management** | Fetch, create, update, and bulk-edit test cases with full custom field support |
-| **▶️ Test Execution** | Create runs, record results, attach files, and track test statuses |
-| **🧠 Context-Aware** | Exposes templates, field definitions, priorities, and case types so LLMs generate valid, well-structured test cases |
+| Capability | Description |
+|------------|-------------|
+| **🔍 Intelligent Discovery** | Browse projects, test suites, and sections to automatically map your QA organization. |
+| **📋 Full Case Management** | Fetch, create, update, and bulk-edit test cases with comprehensive custom field support. |
+| **▶️ Actionable Execution** | Create test runs, update results by `test_id` or `case_id`, attach files, and track statuses. |
+| **🧠 Context-Aware AI** | Dynamically exposes templates, fields, priorities, and statuses so LLMs generate valid, structured data. |
 
-## 🚀 Quick Start
+## 🚀 Quick Start Guide
 
-### 1. Get Your TestRail API Key
+### 1. Obtain Your TestRail API Key
 
-Navigate to **My Settings → API Keys** in your TestRail instance and generate a new key.
+Navigate to **My Settings → API Keys** in your TestRail platform and generate a new key for authentication.
 
 ### 2. Configure Your MCP Client
 
-Add the server to your MCP client configuration. Below are examples for popular clients.
+Add the server to your chosen MCP client configuration. Below are examples for popular AI IDEs and assistants:
 
 <details>
-<summary><strong>Claude Desktop</strong></summary>
+<summary><strong>🤖 Claude Desktop</strong></summary>
 
-Edit your `claude_desktop_config.json`:
+Add this to your `claude_desktop_config.json`:
 
 ```json
 {
@@ -61,13 +62,12 @@ Edit your `claude_desktop_config.json`:
   }
 }
 ```
-
 </details>
 
 <details>
-<summary><strong>Cursor</strong></summary>
+<summary><strong>⌨️ Cursor</strong></summary>
 
-Open **Settings → MCP** and add a new server:
+Open **Settings → Features → MCP** and add a new configuration:
 
 ```json
 {
@@ -84,13 +84,12 @@ Open **Settings → MCP** and add a new server:
   }
 }
 ```
-
 </details>
 
 <details>
-<summary><strong>Windsurf</strong></summary>
+<summary><strong>🌊 Windsurf</strong></summary>
 
-Add to your Windsurf MCP configuration:
+Update your Windsurf MCP configuration file:
 
 ```json
 {
@@ -107,111 +106,91 @@ Add to your Windsurf MCP configuration:
   }
 }
 ```
-
 </details>
 
 <details>
-<summary><strong>Other MCP Clients</strong></summary>
-
-Any MCP-compliant client can use this server. The configuration pattern is the same — point it at the `npx` command with the required environment variables.
+<summary><strong>🌐 Other MCP Clients</strong></summary>
 
+Any MCP-compliant client can utilize this server. The pattern is universal—point your client at the `npx` command with the required environment variables.
 </details>
 
-### 3. Start Using It
+### 3. See It in Action
 
-Once configured, ask your AI assistant things like:
+Once configured, turbo-charge your QA workflow by asking your AI assistant:
 
-- *"List all projects in TestRail"*
-- *"Show me the test cases in suite 1 of project 3"*
-- *"Create a test case for login validation with steps"*
-- *"Start a new test run with cases from section 5"*
-- *"Mark test 42 as passed with a comment"*
+- *"List all projects in TestRail to find the latest active project."*
+- *"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'."*
 
-## ⚙️ Configuration
+---
 
-| Environment Variable | Description | Required |
-|---------------------|-------------|:--------:|
-| `TESTRAIL_INSTANCE_URL` | Your TestRail instance URL (e.g., `https://example.testrail.io`) | ✅ |
-| `TESTRAIL_USERNAME` | Your TestRail email address | ✅ |
-| `TESTRAIL_API_KEY` | Your TestRail API key ([how to get one](https://support.testrail.com/hc/en-us/articles/7077039051412-Accessing-the-TestRail-API)) | ✅ |
+## ⚙️ Environment Variables
 
-## 🛠️ Available Tools
+| Variable | Description | Required |
+|----------|-------------|:--------:|
+| `TESTRAIL_INSTANCE_URL` | Your TestRail instance URL (e.g., `https://example.testrail.io`) | ✅ |
+| `TESTRAIL_USERNAME` | Your TestRail user email address | ✅ |
+| `TESTRAIL_API_KEY` | Your TestRail API key ([Guide](https://support.testrail.com/hc/en-us/articles/7077039051412-Accessing-the-TestRail-API)) | ✅ |
 
-### Discovery
+---
 
-| Tool | Description |
-|------|-------------|
-| `get_projects` | List all available projects in your TestRail instance |
-| `get_sections` | Navigate the folder/section hierarchy of a test suite |
+## 🛠️ Complete Tool Reference
 
-### Test Case Management
+The TestRail MCP Server provides heavily typed, descriptive tools designed specifically for LLM interaction:
 
-| Tool | Description |
+### 🔭 Discovery & Navigation
+| Tool | Functionality |
 |------|-------------|
-| `get_cases` | Query test cases with filtering by priority, template, type, and more — supports pagination and recursive section fetching |
-| `get_case` | Fetch complete details of a specific test case including steps and custom fields |
-| `create_case` | Create a new test case with full custom field support |
-| `update_case` | Modify an existing test case's fields, title, or steps |
-| `update_cases` | Bulk-update multiple test cases simultaneously |
-
-### Test Execution
+| `get_projects` | List all available active and completed projects in your instance. |
+| `get_sections` | Navigate the precise folder/section hierarchy of any test suite. |
 
-| Tool | Description |
+### 📋 Test Case Management
+| Tool | Functionality |
 |------|-------------|
-| `add_run` | Create a new test run in TestRail |
-| `get_tests` | Get tests for a run, optionally filtered by status |
-| `add_results` | Submit one or more test results to a run |
-| `add_attachment_to_run` | Attach a file or zipped folder to a test run |
-
-### Metadata
-
-| Tool | Description |
+| `get_cases` | Query test cases with advanced filtering (priority, template, type, etc.) and pagination. |
+| `get_case` | Fetch complete, structured details of a specific test case, including custom steps and fields. |
+| `create_case` | Seamlessly create a new test case equipped with robust custom field validation. |
+| `update_case` | Modify an existing test case's steps, metadata, or titles. |
+| `update_cases` | Execute bulk-updates on multiple test cases simultaneously to save time. |
+
+### ▶️ Test Execution & Tracking
+| Tool | Functionality |
 |------|-------------|
-| `get_statuses` | List all available test statuses (Passed, Failed, Blocked, etc.) |
-| `get_case_fields` | Retrieve custom field definitions and dropdown options |
-| `get_templates` | List available case templates for correct case structure |
-
-## 🏗️ Development
-
-### Prerequisites
-
-- [Node.js](https://nodejs.org/) 18+
-- npm
-
-### Setup
-
-```bash
-git clone https://github.com/uarlouski/testrail-mcp-server.git
-cd testrail-mcp-server
-npm install
-```
-
-### Build
-
-```bash
-npm run build
-```
-
-### Run Tests
+| `add_run` | Generate a new, focused test run directly in TestRail. |
+| `get_tests` | Retrieve individual tests for a specific test run, with optional status filtering. |
+| `add_results` | Submit test results to a test run using the specific `test_id`. |
+| `add_results_for_cases` | Submits results to a run mapping directly to `case_id`s, streamlining automation workflows. |
+| `add_attachment_to_run` | Attach logs, files, or zipped artifacts directly to an ongoing test run. |
+
+### 🧠 System Metadata
+| Tool | Functionality |
+|------|-------------|
+| `get_statuses` | Systematically list all configured test statuses (Passed, Failed, Blocked, Retest, etc.). |
+| `get_priorities` | Retrieve priority levels configured within your instance structure. |
+| `get_case_fields` | Discover custom field definitions, formats, and UI dropdown options. |
+| `get_templates` | Identify available case templates to mandate correct AI structuring. |
 
-```bash
-npm test
-```
+---
 
 ## 🤝 Contributing
-
-Contributions are welcome! Please feel free to open an [issue](https://github.com/uarlouski/testrail-mcp-server/issues) or submit a pull request.
+Open-source contributions are actively welcomed! Please feel free to open an [issue](https://github.com/uarlouski/testrail-mcp-server/issues) for feature requests or submit a pull request for improvements.
 
 ## 📜 License
-
-This project is licensed under the [Apache License 2.0](LICENSE).
+This project is securely licensed under the [Apache License 2.0](LICENSE).
 
 ---
 
 <p align="center">
-  <b>TestRail MCP Server</b> · Built with the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>
+  <b>TestRail MCP Server</b> · Engineered with the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>
 </p>
 
-<p align="center">
-  <sub>Keywords: TestRail MCP Server, Model Context Protocol, TestRail API integration, AI test management, LLM testing tools, Claude TestRail, Cursor TestRail, Windsurf TestRail, test case automation, QA AI assistant, MCP server for testing, TestRail plugin, test run management, AI-powered QA</sub>
-</p>
+<!-- SEO Keywords -->
+<div align="center">
+  <p>
+    <small>
+      <b>Keywords:</b> TestRail MCP Server, Model Context Protocol, TestRail API Integration, AI Test Management, LLM Testing Tools, Claude TestRail Plugin, Cursor TestRail, Windsurf QA Tool, Test Case Automation, QA AI Assistant, MCP Server Developer Tools, Prompt Engineering TestRail, Test Run Tracking, QA Productivity Automation.
+    </small>
+  </p>
+</div>

package/dist/client/testrail.js

@@ -122,6 +122,9 @@ export class TestRailClient {
     async addResults(runId, results) {
         return this.post(`${API_BASE_V2}/add_results/${runId}`, { results });
     }
+    async addResultsForCases(runId, results) {
+        return this.post(`${API_BASE_V2}/add_results_for_cases/${runId}`, { results });
+    }
     async addAttachmentToRun(runId, filePath, filename) {
         const fileBuffer = await fs.promises.readFile(filePath);
         const blob = new Blob([fileBuffer]);

package/dist/index.js

@@ -14,9 +14,11 @@ import { getSectionsTool } from "./tools/get_sections.js";
 import { getProjectsTool } from "./tools/get_projects.js";
 import { addRunTool } from "./tools/add_run.js";
 import { getStatusesTool } from "./tools/get_statuses.js";
+import { getPrioritiesTool } from "./tools/get_priorities.js";
 import { getTestsTool } from "./tools/get_tests.js";
 import { addResultsTool } from "./tools/add_results.js";
 import { addAttachmentToRunTool } from "./tools/add_attachment_to_run.js";
+import { addResultsForCasesTool } from "./tools/add_results_for_cases.js";
 import { removeNullish } from "./utils/sanitizer.js";
 import z from "zod";
 const EnvSchema = z.object({
@@ -32,7 +34,7 @@ if (!parseResult.success) {
 const { TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY } = parseResult.data;
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "1.6.1",
+    version: "1.7.0",
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
 const tools = [
@@ -47,8 +49,10 @@ const tools = [
     createCaseTool,
     addRunTool,
     getStatusesTool,
+    getPrioritiesTool,
     getTestsTool,
     addResultsTool,
+    addResultsForCasesTool,
     addAttachmentToRunTool,
 ];
 for (const tool of tools) {

package/dist/tools/add_results_for_cases.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { ResultSchema } from "../types/testrail.js";
+const parameters = {
+    run_id: z.number().describe("The ID of the test run"),
+    results: z.array(z.object({
+        case_id: z.number().describe("The ID of the test case. Use get_cases with a project_id to retrieve available case IDs"),
+        status_id: z.number().describe("The ID of the test status (e.g. Passed, Failed). Use get_statuses to retrieve available status IDs"),
+        comment: z.string().optional().describe("Optional comment/description for the result"),
+        defects: z.string().optional().describe("Optional comma-separated list of defect IDs"),
+    })).describe("Array of results to add. Each result must have case_id and status_id"),
+};
+export const addResultsForCasesTool = {
+    name: "add_results_for_cases",
+    description: "Add one or more test results to a test run using case IDs instead of test IDs",
+    parameters,
+    handler: async ({ run_id, results }, client) => {
+        const response = await client.addResultsForCases(run_id, results);
+        return {
+            success: true,
+            added_count: response.length,
+            results: response.map(r => ResultSchema.parse(r)),
+        };
+    },
+};

package/dist/tools/get_priorities.js

@@ -0,0 +1,13 @@
+import { PrioritySchema } from "../types/testrail.js";
+const parameters = {};
+export const getPrioritiesTool = {
+    name: "get_priorities",
+    description: "Get all available test case priorities (e.g. Critical, High, Medium, Low). Returns priority IDs and names that can be used when creating or updating test cases.",
+    parameters,
+    handler: async (_args, client) => {
+        const priorities = await client.getPriorities();
+        return {
+            priorities: priorities.map(p => PrioritySchema.parse(p)),
+        };
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "1.6.1",
+  "version": "1.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",
@@ -40,17 +40,17 @@
   "homepage": "https://github.com/uarlouski/testrail-mcp-server#readme",
   "license": "Apache-2.0",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "archiver": "^7.0.1",
-    "dotenv": "^17.2.3",
-    "zod": "^4.3.5"
+    "dotenv": "^17.3.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/archiver": "^7.0.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.0.9",
-    "jest": "^30.2.0",
-    "rimraf": "^6.1.2",
+    "@types/node": "^25.5.0",
+    "jest": "^30.3.0",
+    "rimraf": "^6.1.3",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"