@uarlouski/testrail-mcp-server 1.8.0 → 1.10.0

package/README.md

@@ -1,8 +1,10 @@
 <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>
+    <strong>An open-source Model Context Protocol (MCP) server that connects Claude, Cursor, Windsurf, and other AI assistants directly to TestRail.</strong>
+  </p>
+  <p>
+    Manage TestRail projects, search and create test cases, kick off test runs, record results, and attach files — all through natural-language conversation with your AI assistant. Built for QA engineers and AI-assisted test automation.
   </p>
 </div>
 
@@ -13,8 +15,19 @@
   <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>
+  <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>
+</p>
+
+<p align="center">
+  <strong>Compatible with:</strong>
+  <img src="https://img.shields.io/badge/Claude%20Desktop-D97757?logo=anthropic&logoColor=white" alt="Claude Desktop">
+  <img src="https://img.shields.io/badge/Cursor-000000?logo=cursor&logoColor=white" alt="Cursor">
+  <img src="https://img.shields.io/badge/Windsurf-19A1BC?logo=codeium&logoColor=white" alt="Windsurf">
+  <img src="https://img.shields.io/badge/VS%20Code-007ACC?logo=visualstudiocode&logoColor=white" alt="VS Code">
 </p>
 
+<!-- TODO: insert demo.gif — short screencast of asking "create a test case" in Claude or Cursor and seeing the case appear in TestRail -->
+
 ---
 
 ## 🌟 Why Choose TestRail MCP Server?
@@ -40,10 +53,9 @@ Navigate to **My Settings → API Keys** in your TestRail platform and generate
 
 ### 2. Configure Your MCP Client
 
-Add the server to your chosen MCP client configuration. Below are examples for popular AI IDEs and assistants:
+Add the server to your chosen MCP client configuration. The Claude Desktop example is shown below; Cursor, Windsurf, and other clients use the same pattern (see the collapsible sections further down).
 
-<details>
-<summary><strong>🤖 Claude Desktop</strong></summary>
+#### 🤖 Claude Desktop
 
 Add this to your `claude_desktop_config.json`:
 
@@ -56,13 +68,13 @@ Add this to your `claude_desktop_config.json`:
       "env": {
         "TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
         "TESTRAIL_USERNAME": "your@email.com",
-        "TESTRAIL_API_KEY": "your-api-key"
+        "TESTRAIL_API_KEY": "your-api-key",
+        "TESTRAIL_ENABLE_SHARED_STEPS": "true"
       }
     }
   }
 }
 ```
-</details>
 
 <details>
 <summary><strong>⌨️ Cursor</strong></summary>
@@ -133,6 +145,7 @@ Once configured, turbo-charge your QA workflow by asking your AI assistant:
 | `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)) | ✅ |
+| `TESTRAIL_ENABLE_SHARED_STEPS` | Set to `true` to enable Shared Steps management tools | |
 
 ---
 
@@ -140,6 +153,9 @@ Once configured, turbo-charge your QA workflow by asking your AI assistant:
 
 The TestRail MCP Server provides heavily typed, descriptive tools designed specifically for LLM interaction:
 
+> **💡 Pro Tip: Handling Large Data Sets**
+> For list-based tools like `get_cases` and `get_sections`, you can supply the `output_file` parameter with an absolute file path. The server will bypass the LLM context window by writing the raw JSON directly to disk and returning a concise summary, allowing you to run external scripts against the export!
+
 ### 🔭 Discovery & Navigation
 | Tool | Functionality |
 |------|-------------|
@@ -151,7 +167,7 @@ The TestRail MCP Server provides heavily typed, descriptive tools designed speci
 |------|-------------|
 | `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. |
+| `add_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. |
 
@@ -164,12 +180,22 @@ The TestRail MCP Server provides heavily typed, descriptive tools designed speci
 | `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. |
 
+### 🔗 Shared Steps (Optional)
+| Tool | Functionality |
+|------|-------------|
+| `get_shared_steps` | List shared test steps for a project with optional reference filtering. |
+| `get_shared_step` | Retrieve precise details of a specific shared test step set. |
+| `get_shared_step_history` | View the complete audit trail and version history of a shared step set. |
+| `add_shared_step` | Create a new reusable set of shared test steps. |
+| `update_shared_step` | Modify an existing shared step set (changes propagate to all linked test cases). |
+| `delete_shared_step` | Securely delete a shared step entity. |
+
 ### 🧠 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_case_fields` | Discover custom field definitions, formats, and UI dropdown options. Supports filtering by `project_id`. |
 | `get_templates` | Identify available case templates to mandate correct AI structuring. |
 
 ---
@@ -185,12 +211,3 @@ This project is securely licensed under the [Apache License 2.0](LICENSE).
 <p align="center">
   <b>TestRail MCP Server</b> · Engineered with the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>
 </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

@@ -95,7 +95,7 @@ export class TestRailClient {
         });
         return response.updated_cases;
     }
-    async createCase(sectionId, fields) {
+    async addCase(sectionId, fields) {
         return this.post(`${API_BASE_V2}/add_case/${sectionId}`, fields);
     }
     async addRun(projectId, fields) {
@@ -139,6 +139,28 @@ export class TestRailClient {
         };
         return this._executeRequest('POST', `${API_BASE_V2}/add_attachment_to_run/${runId}`, headers, formData);
     }
+    async getSharedSteps(projectId, options) {
+        let url = `${API_BASE_V2}/get_shared_steps/${projectId}`;
+        if (options?.refs) {
+            url += `&refs=${options.refs}`;
+        }
+        return this.paginateAll(url, 'shared_steps');
+    }
+    async getSharedStep(sharedStepId) {
+        return this.get(`${API_BASE_V2}/get_shared_step/${sharedStepId}`);
+    }
+    async getSharedStepHistory(sharedStepId) {
+        return this.get(`${API_BASE_V2}/get_shared_step_history/${sharedStepId}`);
+    }
+    async addSharedStep(projectId, data) {
+        return this.post(`${API_BASE_V2}/add_shared_step/${projectId}`, data);
+    }
+    async updateSharedStep(sharedStepId, data) {
+        return this.post(`${API_BASE_V2}/update_shared_step/${sharedStepId}`, data);
+    }
+    async deleteSharedStep(sharedStepId) {
+        return this._executeRequest('POST', `${API_BASE_V2}/delete_shared_step/${sharedStepId}`, this.headers, JSON.stringify({}), false);
+    }
     async paginateAll(url, dataKey) {
         const allItems = [];
         let nextUrl = url;
@@ -167,7 +189,7 @@ export class TestRailClient {
         }
         return this._executeRequest(method, endpoint, this.headers, jsonData);
     }
-    async _executeRequest(method, endpoint, headers, body) {
+    async _executeRequest(method, endpoint, headers, body, parseBody = true) {
         const url = `${this.baseUrl}${endpoint}`;
         const params = {
             method,
@@ -205,7 +227,10 @@ export class TestRailClient {
                     console.error(`[TestRailClient] Error Details: ${errorMessage}`);
                     throw new Error(errorMessage);
                 }
-                return await response.json();
+                if (parseBody) {
+                    return await response.json();
+                }
+                return await response.text();
             }
             catch (error) {
                 const networkError = error instanceof Error && !error.message.startsWith('TestRail API Error');

package/dist/index.js

@@ -9,7 +9,7 @@ import { getCaseFieldsTool } from "./tools/get_case_fields.js";
 import { getTemplatesTool } from "./tools/get_templates.js";
 import { updateCaseTool } from "./tools/update_case.js";
 import { updateCasesTool } from "./tools/update_cases.js";
-import { createCaseTool } from "./tools/create_case.js";
+import { addCaseTool } from "./tools/add_case.js";
 import { getSectionsTool } from "./tools/get_sections.js";
 import { getProjectsTool } from "./tools/get_projects.js";
 import { addRunTool } from "./tools/add_run.js";
@@ -20,22 +20,29 @@ 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 { getLabelsTool } from "./tools/get_labels.js";
+import { getSharedStepsTool } from "./tools/shared_steps/get_shared_steps.js";
+import { getSharedStepTool } from "./tools/shared_steps/get_shared_step.js";
+import { getSharedStepHistoryTool } from "./tools/shared_steps/get_shared_step_history.js";
+import { addSharedStepTool } from "./tools/shared_steps/add_shared_step.js";
+import { updateSharedStepTool } from "./tools/shared_steps/update_shared_step.js";
+import { deleteSharedStepTool } from "./tools/shared_steps/delete_shared_step.js";
 import { removeNullish } from "./utils/sanitizer.js";
 import z from "zod";
 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'),
-    TESTRAIL_API_KEY: z.string().min(1, 'API key is required')
+    TESTRAIL_API_KEY: z.string().min(1, 'API key is required'),
+    TESTRAIL_ENABLE_SHARED_STEPS: z.string().optional().transform(val => val === 'true')
 });
 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 } = parseResult.data;
+const { TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY, TESTRAIL_ENABLE_SHARED_STEPS } = parseResult.data;
 const server = new McpServer({
     name: "TestRail MCP Server",
-    version: "1.8.0",
+    version: "1.10.0",
 });
 const client = new TestRailClient(TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME, TESTRAIL_API_KEY);
 const tools = [
@@ -47,7 +54,7 @@ const tools = [
     getSectionsTool,
     updateCaseTool,
     updateCasesTool,
-    createCaseTool,
+    addCaseTool,
     addRunTool,
     getStatusesTool,
     getPrioritiesTool,
@@ -57,6 +64,14 @@ const tools = [
     addAttachmentToRunTool,
     getLabelsTool,
 ];
+if (TESTRAIL_ENABLE_SHARED_STEPS) {
+    tools.push(getSharedStepsTool);
+    tools.push(getSharedStepTool);
+    tools.push(getSharedStepHistoryTool);
+    tools.push(addSharedStepTool);
+    tools.push(updateSharedStepTool);
+    tools.push(deleteSharedStepTool);
+}
 for (const tool of tools) {
     server.registerTool(tool.name, {
         description: tool.description,

package/dist/tools/{create_case.js → add_case.js}

@@ -1,13 +1,18 @@
 import { z } from "zod";
 import { validateCaseFields } from "../utils/validator.js";
+import { CASE_FIELDS_PARAM_DESCRIPTION } from "./get_case_fields.js";
 const parameters = {
     section_id: z.number().describe("The ID of the section where the case should be created. Use get_sections to find available sections"),
     title: z.string().describe("The title of the test case"),
-    fields: z.record(z.string(), z.any()).optional().describe("Optional fields for the test case. First use get_templates to discover available templates, then get_case_fields to see available fields for your template. Example: {\"priority_id\": 2, \"template_id\": 1, \"custom_automation_priority\": 1}"),
+    fields: z.record(z.string(), z.any()).optional().describe(CASE_FIELDS_PARAM_DESCRIPTION),
 };
-export const createCaseTool = {
-    name: "create_case",
-    description: "Create a new test case in TestRail",
+const description = `
+Create a new test case in TestRail.
+The create operation requires knowing valid field names that are returned by get_case_fields tool.
+`;
+export const addCaseTool = {
+    name: "add_case",
+    description: description.trim(),
     parameters,
     handler: async ({ section_id, title, fields }, client) => {
         if (fields) {
@@ -17,7 +22,7 @@ export const createCaseTool = {
             title,
             ...fields,
         };
-        const createdCase = await client.createCase(section_id, caseData);
+        const createdCase = await client.addCase(section_id, caseData);
         return {
             success: true,
             case_id: createdCase.id,

package/dist/tools/get_case_fields.js

@@ -1,5 +1,16 @@
+import { z } from "zod";
 import { parseDropdownOptions } from "../utils/mapper.js";
-const parameters = {};
+// Field remains optional for backward compatibility with previous implementation.
+// However, it is recommended to always provide project_id to get fields applicable to the project.
+const parameters = {
+    project_id: z.number().optional().describe("The project ID to get fields for. This is the primary way to use this tool, as it returns only the fields relevant to your current project. If omitted, returns all fields across all projects."),
+};
+export const CASE_FIELDS_PARAM_DESCRIPTION = `
+Must use system_name values from get_case_fields.
+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.
+Example: {"priority_id": 2, "template_id": 1, "labels": [1, 2]}
+`;
 const FIELD_TYPE_NAMES = {
     1: "String",
     2: "Integer",
@@ -35,29 +46,57 @@ export function mapToFieldSchema(field) {
     if (field.type_id === 6 || field.type_id === 12) {
         schema.options = Array.from(parseDropdownOptions(field).values());
     }
+    const contexts = field.configs.map(c => c.context).filter(Boolean);
+    if (contexts.length > 0) {
+        const isGlobal = contexts.some(ctx => ctx.is_global);
+        if (isGlobal) {
+            schema.project_scope = { scope: "global" };
+        }
+        else {
+            const projectIds = [...new Set(contexts.flatMap(ctx => ctx.project_ids))];
+            schema.project_scope = { scope: "projects", project_ids: projectIds };
+        }
+    }
     return schema;
 }
+function isFieldForProject(field, projectId) {
+    const contexts = field.configs.map(c => c.context).filter(Boolean);
+    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: "String", is_required: true },
-    { system_name: "section_id", label: "Section", type: "Integer", is_required: true },
-    { system_name: "template_id", label: "Template", type: "Integer", is_required: false },
-    { system_name: "type_id", label: "Type", type: "Integer", is_required: false },
-    { system_name: "priority_id", label: "Priority", type: "Integer", is_required: false },
-    { system_name: "estimate", label: "Estimate", type: "String", is_required: false },
-    { system_name: "milestone_id", label: "Milestone", type: "Integer", is_required: false },
-    { system_name: "refs", label: "References", type: "String", is_required: false },
-    { system_name: "labels", label: "Labels", type: "List", is_required: false, comment: "Use get_labels tool to get available labels/tags." },
+    { system_name: "title", label: "Title", type: "String", is_required: true, project_scope: { scope: "global" } },
+    { system_name: "section_id", label: "Section", type: "Integer", is_required: true, project_scope: { scope: "global" } },
+    { system_name: "template_id", label: "Template", type: "Integer", is_required: false, project_scope: { scope: "global" } },
+    { system_name: "type_id", label: "Type", type: "Integer", is_required: false, project_scope: { scope: "global" } },
+    { system_name: "priority_id", label: "Priority", type: "Integer", is_required: false, project_scope: { scope: "global" } },
+    { system_name: "estimate", label: "Estimate", type: "String", is_required: false, project_scope: { scope: "global" } },
+    { system_name: "milestone_id", label: "Milestone", type: "Integer", is_required: false, project_scope: { scope: "global" } },
+    { system_name: "refs", label: "References", type: "String", is_required: false, project_scope: { scope: "global" } },
+    { system_name: "labels", label: "Labels", type: "List", is_required: false, project_scope: { scope: "global" }, comment: "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.
+If you truly need all fields across all projects, you may omit project_id, but this is rarely what you want.
+Returns available fields with their types and options (for dropdown fields).
+`;
 export const getCaseFieldsTool = {
     name: "get_case_fields",
-    description: "Get the field schema for test cases. Returns all available fields with their types, descriptions, and options (for dropdown fields). Use this to understand what fields can be set when creating or updating test cases.",
+    description: description.trim(),
     parameters,
-    handler: async (_args, client) => {
+    handler: async ({ project_id }, client) => {
         const caseFields = await client.getCaseFields();
-        const customFieldSchemas = caseFields.filter(field => field.is_active).map(mapToFieldSchema);
-        const response = {
-            fields: [...SYSTEM_FIELDS, ...customFieldSchemas],
-        };
-        return response;
+        const activeFields = caseFields.filter(field => field.is_active);
+        const filtered = project_id !== undefined
+            ? activeFields.filter(field => isFieldForProject(field, project_id))
+            : activeFields;
+        const customFieldSchemas = filtered.map(mapToFieldSchema);
+        const allFields = [...SYSTEM_FIELDS, ...customFieldSchemas];
+        const fields = project_id !== undefined
+            ? allFields.map(({ project_scope: _, ...rest }) => rest)
+            : allFields;
+        return { fields };
     }
 };

package/dist/tools/get_cases.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import fs from "fs";
 import { validateCaseFields } from "../utils/validator.js";
 const parameters = {
     project_id: z.number().describe("The ID of the project. Use get_projects to find available projects"),
@@ -10,12 +11,13 @@ const parameters = {
     filter: z.record(z.string(), z.string()).optional().describe("Optional API-side filters (more efficient for large datasets). Supported: priority_id, type_id, created_by, updated_by, milestone_id, refs, created_after, created_before, updated_after, updated_before. Use comma-separated values for IDs. Example: {\"priority_id\": \"1,2\", \"type_id\": \"3\"}"),
     where: z.record(z.string(), z.any()).optional().describe("Optional client-side filter for any field including custom fields (filters after fetching all cases). Supports exact value matching. Example: {\"custom_automation_status\": 1, \"priority_id\": 2}"),
     fields: z.array(z.string()).optional().describe("Additional fields to include in response beyond id, title, and suite_id. Use get_case_fields to see available fields. Example: [\"priority_id\", \"type_id\", \"custom_automation_status\"]"),
+    output_file: z.string().optional().describe("Absolute file path to save the JSON response to. Use this for large datasets to avoid blowing up context limits."),
 };
 export const getCasesTool = {
     name: "get_cases",
     description: "Get all test cases for a project. Filter by section, API params (priority, type), or any field including custom fields via 'where'. Returns case IDs, titles, and any additional requested fields.",
     parameters,
-    handler: async ({ project_id, section, filter, where, fields }, client) => {
+    handler: async ({ project_id, section, filter, where, fields, output_file }, client) => {
         const caseFields = await client.getCaseFields();
         if (fields) {
             validateCaseFields(fields, caseFields);
@@ -59,6 +61,14 @@ export const getCasesTool = {
                 return result;
             }),
         };
+        if (output_file) {
+            await fs.promises.writeFile(output_file, JSON.stringify(response), "utf-8");
+            return {
+                success: true,
+                message: `Successfully exported ${response.cases.length} cases to ${output_file}`,
+                file: output_file
+            };
+        }
         return response;
     }
 };

package/dist/tools/get_sections.js

@@ -1,16 +1,27 @@
 import { z } from "zod";
+import fs from "fs";
 import { SectionSchema } from "../types/testrail.js";
 const parameters = {
     project_id: z.number().describe("The ID of the project. Use get_projects to find available projects"),
+    output_file: z.string().optional().describe("Absolute file path to save the JSON response to. Use this for large datasets to avoid blowing up context limits."),
 };
 export const getSectionsTool = {
     name: "get_sections",
-    description: "Get all sections for a project. Returns section IDs and names that can be used with create_case",
+    description: "Get all sections for a project. Returns section IDs and names that can be used with add_case",
     parameters,
-    handler: async ({ project_id }, client) => {
+    handler: async ({ project_id, output_file }, client) => {
         const sections = await client.getSections(project_id);
-        return {
+        const response = {
             sections: sections.map(s => SectionSchema.parse(s)),
         };
+        if (output_file) {
+            await fs.promises.writeFile(output_file, JSON.stringify(response), "utf-8");
+            return {
+                success: true,
+                message: `Successfully exported ${response.sections.length} sections to ${output_file}`,
+                file: output_file
+            };
+        }
+        return response;
     }
 };

package/dist/tools/shared_steps/add_shared_step.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { SharedStepSchema } from "../../types/testrail.js";
+const parameters = {
+    project_id: z.number().describe("The ID of the project where the shared step will be created"),
+    title: z.string().describe("The title of the shared test step"),
+    custom_steps_separated: z.array(z.object({
+        content: z.string().describe("The step instruction"),
+        expected: z.string().optional().describe("The expected result of the step"),
+    })).optional().describe("The steps of the shared test step"),
+};
+export const addSharedStepTool = {
+    name: "add_shared_step",
+    description: "Creates a new set of shared test steps.",
+    parameters,
+    handler: async (args, client) => {
+        const { project_id, ...data } = args;
+        const sharedStep = await client.addSharedStep(project_id, data);
+        return { shared_step: SharedStepSchema.parse(sharedStep) };
+    }
+};

package/dist/tools/shared_steps/delete_shared_step.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+const parameters = {
+    shared_step_id: z.number().describe("The ID of the shared test step to delete"),
+};
+const description = `
+Deletes an existing shared step entity.
+By default, this removes the shared step entity but keeps the steps in the test cases that used them.
+`;
+export const deleteSharedStepTool = {
+    name: "delete_shared_step",
+    description: description.trim(),
+    parameters,
+    handler: async (args, client) => {
+        const { shared_step_id } = args;
+        await client.deleteSharedStep(shared_step_id);
+        return { message: `Shared step ${shared_step_id} deleted successfully.` };
+    }
+};

package/dist/tools/shared_steps/get_shared_step.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { SharedStepSchema } from "../../types/testrail.js";
+const parameters = {
+    shared_step_id: z.number().describe("The ID of the shared test step"),
+};
+export const getSharedStepTool = {
+    name: "get_shared_step",
+    description: "Returns the details of a specific shared test step.",
+    parameters,
+    handler: async (args, client) => {
+        const { shared_step_id } = args;
+        const sharedStep = await client.getSharedStep(shared_step_id);
+        return { shared_step: SharedStepSchema.parse(sharedStep) };
+    }
+};

package/dist/tools/shared_steps/get_shared_step_history.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { SharedStepHistorySchema } from "../../types/testrail.js";
+const parameters = {
+    shared_step_id: z.number().describe("The ID of the shared test step"),
+};
+export const getSharedStepHistoryTool = {
+    name: "get_shared_step_history",
+    description: "Returns the change history of a set of shared test steps.",
+    parameters,
+    handler: async (args, client) => {
+        const { shared_step_id } = args;
+        const history = await client.getSharedStepHistory(shared_step_id);
+        return { history: history.map(h => SharedStepHistorySchema.parse(h)) };
+    }
+};

package/dist/tools/shared_steps/get_shared_steps.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { SharedStepSchema } from "../../types/testrail.js";
+const parameters = {
+    project_id: z.number().describe("The ID of the project"),
+    refs: z.string().optional().describe("Filter by a single Reference ID"),
+};
+export const getSharedStepsTool = {
+    name: "get_shared_steps",
+    description: "Returns a list of shared test steps for a specified project.",
+    parameters,
+    handler: async (args, client) => {
+        const { project_id, refs } = args;
+        const sharedSteps = await client.getSharedSteps(project_id, { refs });
+        return { shared_steps: sharedSteps.map(s => SharedStepSchema.parse(s)) };
+    }
+};

package/dist/tools/shared_steps/update_shared_step.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { SharedStepSchema } from "../../types/testrail.js";
+const parameters = {
+    shared_step_id: z.number().describe("The ID of the shared test step to update"),
+    title: z.string().optional().describe("The updated title of the shared test step"),
+    custom_steps_separated: z.array(z.object({
+        content: z.string().describe("The step instruction"),
+        expected: z.string().optional().describe("The expected result of the step"),
+    })).optional().describe("The updated steps (replaces all existing steps)"),
+};
+const description = `
+Updates an existing set of shared test steps.
+Updates are propagated automatically to all test cases using these steps.
+`;
+export const updateSharedStepTool = {
+    name: "update_shared_step",
+    description: description.trim(),
+    parameters,
+    handler: async (args, client) => {
+        const { shared_step_id, ...data } = args;
+        const sharedStep = await client.updateSharedStep(shared_step_id, data);
+        return { shared_step: SharedStepSchema.parse(sharedStep) };
+    }
+};

package/dist/tools/update_case.js

@@ -1,12 +1,18 @@
 import { z } from "zod";
 import { validateCaseFields } from "../utils/validator.js";
+import { CASE_FIELDS_PARAM_DESCRIPTION } from "./get_case_fields.js";
 const parameters = {
     case_id: z.string().describe("The ID of the test case to update (e.g. '123' or 'C123')"),
-    fields: z.record(z.string(), z.any()).describe("Object containing fields to update. Use get_case_fields to see available fields. Example: {\"title\": \"New title\", \"priority_id\": 2, \"custom_automation_priority\": 1}"),
+    fields: z.record(z.string(), z.any()).describe(CASE_FIELDS_PARAM_DESCRIPTION),
 };
+const description = `
+Update a test case in TestRail.
+The update operation requires knowing valid field names that are returned by get_case_fields tool.
+Supports partial updates — only specify the fields you want to change.
+`;
 export const updateCaseTool = {
     name: "update_case",
-    description: "Update a test case in TestRail. Supports partial updates - only specify the fields you want to change",
+    description: description.trim(),
     parameters,
     handler: async ({ case_id, fields }, client) => {
         validateCaseFields(fields, await client.getCaseFields());

package/dist/tools/update_cases.js

@@ -1,12 +1,18 @@
 import { z } from "zod";
 import { validateCaseFields } from "../utils/validator.js";
+import { CASE_FIELDS_PARAM_DESCRIPTION } from "./get_case_fields.js";
 const parameters = {
     case_ids: z.array(z.number()).min(1).describe("Array of case IDs to update (e.g. [123, 456, 789])"),
-    fields: z.record(z.string(), z.any()).describe("Object containing fields to update for ALL specified cases. Use get_case_fields to see available fields. Example: {\"priority_id\": 2, \"type_id\": 1}"),
+    fields: z.record(z.string(), z.any()).describe(CASE_FIELDS_PARAM_DESCRIPTION),
 };
+const description = `
+Bulk update multiple test cases with the same field values.
+The update operation requires knowing valid field names that are returned by get_case_fields tool.
+More efficient than calling update_case multiple times.
+`;
 export const updateCasesTool = {
     name: "update_cases",
-    description: "Bulk update multiple test cases with the same field values. More efficient than calling update_case multiple times",
+    description: description.trim(),
     parameters,
     handler: async ({ case_ids, fields }, client) => {
         validateCaseFields(fields, await client.getCaseFields());

package/dist/types/testrail.js

@@ -1,5 +1,9 @@
 import { z } from "zod";
 export const CaseFieldConfigSchema = z.object({
+    context: z.object({
+        is_global: z.boolean(),
+        project_ids: z.array(z.number()),
+    }).optional(),
     options: z.object({
         default_value: z.string().optional(),
         is_required: z.boolean().optional(),
@@ -102,3 +106,20 @@ export const ResultSchema = z.object({
 export const AttachmentSchema = z.object({
     attachment_id: z.number(),
 });
+export const SharedStepContentSchema = z.object({
+    content: z.string(),
+    expected: z.string().nullable().optional(),
+});
+export const SharedStepSchema = z.object({
+    id: z.number(),
+    title: z.string(),
+    project_id: z.number().optional(),
+    custom_steps_separated: z.array(SharedStepContentSchema).optional(),
+    case_ids: z.array(z.number()).optional(),
+});
+export const SharedStepHistorySchema = z.object({
+    id: z.number(),
+    title: z.string(),
+    timestamp: z.number().optional(),
+    custom_steps_separated: z.array(SharedStepContentSchema).optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uarlouski/testrail-mcp-server",
-  "version": "1.8.0",
+  "version": "1.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",
@@ -11,13 +11,6 @@
     "dist"
   ],
   "type": "module",
-  "scripts": {
-    "build": "rimraf dist && tsc",
-    "start": "node dist/index.js",
-    "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"
-  },
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -40,10 +33,10 @@
   "homepage": "https://github.com/uarlouski/testrail-mcp-server#readme",
   "license": "Apache-2.0",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "archiver": "^7.0.1",
-    "dotenv": "^17.3.1",
-    "zod": "^4.3.6"
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/archiver": "^7.0.0",
@@ -53,6 +46,21 @@
     "rimraf": "^6.1.3",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "@jest/globals": "^29.7.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.1.2",
+      "onFail": "error"
+    }
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc",
+    "start": "node dist/index.js",
+    "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"
   }
 }