TestRail MCP Server

Instructions

Implementation Reference

• src/services/testrailService.ts:296-326 (handler)

  Core handler function that fetches a single TestRail test case by ID via the TestRail client, destructures the response, extracts custom fields, and returns a normalized CaseSummary object.

  export async function getCase(caseId: number): Promise<CaseSummary> {
    const data: TestRailCaseDto = await testRailClient.getCase(caseId);
    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/server.ts:19-60 (registration)

  Registers the 'get_case' MCP tool, including input schema validation with Zod (case_id as positive integer), description, and the handler wrapper that invokes getCase from testrailService and formats the response as JSON text.

  server.registerTool(
    'get_case',
    {
      title: 'Get TestRail Case',
      description: 'Fetch a TestRail test case by ID.',
      inputSchema: {
        case_id: z.number().int().positive().describe('TestRail case ID'),
      },
    },
    async ({ case_id }) => {
      logger.debug(`Tool called with case_id: ${case_id}`);
      try {
        const result = await getCase(case_id);
        logger.debug(`Tool completed successfully for case_id: ${case_id}`);
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (err) {
        logger.error({ err }, `Tool failed for case_id: ${case_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 = `Case ${case_id} not found`;
        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/services/testrailService.ts:31-41 (schema)

  TypeScript interface defining the structure of the normalized case data returned by the getCase handler, including core fields and optional custom fields.

  export interface CaseSummary {
    id: number;
    title: string;
    section_id?: number;
    type_id?: number;
    priority_id?: number;
    refs?: string | null;
    created_on?: number;
    updated_on?: number;
    custom?: Record<string, unknown> | undefined;
  }