TestRail MCP Server

Instructions

Implementation Reference

• src/server.ts:64-121 (handler)

  Inline handler function for the 'add_case' MCP tool. Validates inputs via Zod schema, constructs CaseCreatePayload, calls addCase service, formats success/error responses.

  server.registerTool(
    'add_case',
    {
      title: 'Add TestRail Case',
      description: 'Create a new TestRail test case in a specific section. IMPORTANT: Before creating a case, gather required information using get_projects, get_suites, get_sections, and get_case_fields tools to ensure proper section_id, type_id, and custom field values. Or ask the user to provide the information if not provided.',
      inputSchema: {
        title: z.string().min(1).describe('Test case title - should be descriptive and unique within the section'),
        section_id: z.number().int().positive().describe('Section ID where the case will be created. REQUIRED: Use get_sections tool first to find valid section IDs for your project/suite. Different projects have different section structures.'),
        type_id: z.number().int().positive().optional().describe('Test case type ID (e.g., 1=Acceptance, 2=Accessibility, 3=Automated, 4=Compatibility, 5=Destructive, 6=Functional, 7=Other, 8=Performance, 9=Regression, 10=Security, 11=Smoke & Sanity, 12=Usability). RECOMMENDED: Use get_cases tool to see what type_id values are used in existing cases in your target section.'),
        priority_id: z.number().int().positive().optional().describe('Priority ID (1=Low, 2=Medium, 3=High, 4=Critical). RECOMMENDED: Use get_cases tool to see what priority_id values are used in existing cases.'),
        refs: z.string().nullable().optional().describe('References (e.g., requirement IDs, JIRA tickets, user story numbers). Can be comma-separated for multiple references.'),
        custom: z.record(z.string(), z.unknown()).optional().describe('Custom fields (key-value pairs). REQUIRED: Use get_case_fields tool first to discover available custom fields and their valid values. Common fields include: custom_automation_type (1=None, 2=Playwright, 3=ChatGPT, 4=Non-Automated, 5=Partial), custom_environment (1=UAT Only, 2=UAT/Prod, 3=Demo UAT, 4=Live UAT), custom_preconds (preconditions text), custom_steps (test steps text), custom_expected (expected results text). Some custom fields are required by the project configuration.'),
      },
    },
    async ({ title, section_id, type_id, priority_id, refs, custom }) => {
      logger.debug(`Add case tool called with section_id: ${section_id}, title: ${title}`);
      try {
        const payload: CaseCreatePayload = {
          title,
          section_id,
          type_id,
          priority_id,
          refs,
          custom,
        };
        
        const result = await addCase(payload);
        logger.debug(`Add case tool completed successfully. Case ID: ${result.id}`);
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (err) {
        logger.error({ err }, `Add case tool failed for section_id: ${section_id}`);
        const e = err as { type?: string; status?: number; message?: string };
        let message = 'Unexpected error';
        if (e?.type === 'auth') message = 'Authentication failed: check TESTRAIL_USER/API_KEY';
        else if (e?.type === 'not_found') message = `Section ${section_id} not found. Use get_sections tool to find valid section IDs for your project.`;
        else if (e?.type === 'validation_error') message = `Validation error: ${e.message}. Check custom field values using get_case_fields tool and ensure required fields are provided.`;
        else if (e?.type === 'permission_denied') message = `Permission denied for section ${section_id}. Try a different project or section using get_projects and get_sections tools.`;
        else if (e?.type === 'rate_limited') message = 'Rate limited by TestRail; try again later';
        else if (e?.type === 'server') message = 'TestRail server error';
        else if (e?.type === 'network') message = 'Network error contacting TestRail';
        else if (e?.message) message = e.message;
  
        return {
          content: [
            { type: 'text', text: message },
          ],
          isError: true,
        };
      }
    },
  );

• src/server.ts:69-76 (schema)

  Zod input schema for 'add_case' tool defining required/optional parameters with descriptions and validation rules.

  inputSchema: {
    title: z.string().min(1).describe('Test case title - should be descriptive and unique within the section'),
    section_id: z.number().int().positive().describe('Section ID where the case will be created. REQUIRED: Use get_sections tool first to find valid section IDs for your project/suite. Different projects have different section structures.'),
    type_id: z.number().int().positive().optional().describe('Test case type ID (e.g., 1=Acceptance, 2=Accessibility, 3=Automated, 4=Compatibility, 5=Destructive, 6=Functional, 7=Other, 8=Performance, 9=Regression, 10=Security, 11=Smoke & Sanity, 12=Usability). RECOMMENDED: Use get_cases tool to see what type_id values are used in existing cases in your target section.'),
    priority_id: z.number().int().positive().optional().describe('Priority ID (1=Low, 2=Medium, 3=High, 4=Critical). RECOMMENDED: Use get_cases tool to see what priority_id values are used in existing cases.'),
    refs: z.string().nullable().optional().describe('References (e.g., requirement IDs, JIRA tickets, user story numbers). Can be comma-separated for multiple references.'),
    custom: z.record(z.string(), z.unknown()).optional().describe('Custom fields (key-value pairs). REQUIRED: Use get_case_fields tool first to discover available custom fields and their valid values. Common fields include: custom_automation_type (1=None, 2=Playwright, 3=ChatGPT, 4=Non-Automated, 5=Partial), custom_environment (1=UAT Only, 2=UAT/Prod, 3=Demo UAT, 4=Live UAT), custom_preconds (preconditions text), custom_steps (test steps text), custom_expected (expected results text). Some custom fields are required by the project configuration.'),
  },

• src/services/testrailService.ts:328-378 (helper)

  Service layer function addCase that transforms high-level payload to TestRailCaseCreateDto (adds custom_ prefix), calls TestRail client, normalizes response to CaseSummary.

  export async function addCase(payload: CaseCreatePayload): Promise<CaseSummary> {
    // Transform the payload to match TestRail API format
    const createPayload: TestRailCaseCreateDto = {
      title: payload.title,
      section_id: payload.section_id,
      type_id: payload.type_id,
      priority_id: payload.priority_id,
      refs: payload.refs,
    };
  
    // Add custom fields with proper naming convention
    if (payload.custom) {
      for (const [key, value] of Object.entries(payload.custom)) {
        // Ensure custom field keys have the 'custom_' prefix
        const fieldKey = key.startsWith('custom_') ? key : `custom_${key}`;
        createPayload[fieldKey] = value;
      }
    }
  
    const data: TestRailCaseDto = await testRailClient.addCase(payload.section_id, createPayload);
    
    // Normalize the response using the same logic as getCase
    const {
      id,
      title,
      section_id,
      type_id,
      priority_id,
      refs,
      created_on,
      updated_on,
      ...rest
    } = data;
  
    const custom: Record<string, unknown> = {};
    for (const [key, value] of Object.entries(rest)) {
      if (key.startsWith('custom_')) custom[key] = value;
    }
  
    return {
      id,
      title,
      section_id,
      type_id,
      priority_id,
      refs: refs ?? null,
      created_on,
      updated_on,
      custom: Object.keys(custom).length ? custom : undefined,
    };
  }

• src/services/testrailService.ts:52-59 (schema)

  TypeScript interface CaseCreatePayload defining the structure expected by the addCase service function.

  export interface CaseCreatePayload {
    title: string;
    section_id: number;
    type_id?: number;
    priority_id?: number;
    refs?: string | null;
    custom?: Record<string, unknown>;
  }

• src/clients/testrailClient.ts:469-488 (helper)

  HTTP client method that performs POST request to TestRail API endpoint /add_case/{sectionId} to create the case.

  async addCase(sectionId: number, caseData: TestRailCaseCreateDto): Promise<TestRailCaseDto> {
    try {
      const res = await this.http.post(`/add_case/${sectionId}`, caseData);
      if (res.status >= 200 && res.status < 300) {
        logger.info({
          message: 'Successfully created test case',
          sectionId,
          caseId: res.data.id,
          responseSize: JSON.stringify(res.data).length,
        });
        return res.data as TestRailCaseDto;
      }
      throw Object.assign(new Error(`HTTP ${res.status}`), { response: res });
    } catch (err) {
      const normalized = this.normalizeError(err);
      const safeDetails = this.getSafeErrorDetails(err);
      logger.error({ err: normalized, details: safeDetails, sectionId }, 'TestRail addCase failed');
      throw normalized;
    }
  }