TestRail MCP Server

Instructions

Implementation Reference

• src/server.ts:331-362 (handler)

  MCP tool handler function for 'get_suite': validates input, calls testrailService.getSuite(suite_id), formats response as JSON text content or error message.

  async ({ suite_id }) => {
    logger.debug(`Get suite tool called with suite_id: ${suite_id}`);
    try {
      const result = await getSuite(suite_id);
      logger.debug(`Get suite tool completed successfully for suite_id: ${suite_id}`);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (err) {
      logger.error({ err }, `Get suite tool failed for suite_id: ${suite_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 = `Suite ${suite_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/server.ts:327-329 (schema)

  Zod input schema defining the required 'suite_id' parameter as a positive integer.

  inputSchema: {
    suite_id: z.number().int().positive().describe('TestRail suite ID'),
  },

• src/server.ts:322-363 (registration)

  Registration of the 'get_suite' MCP tool with title, description, input schema, and handler function.

  server.registerTool(
    'get_suite',
    {
      title: 'Get TestRail Suite',
      description: 'Get details for a specific TestRail test suite by ID.',
      inputSchema: {
        suite_id: z.number().int().positive().describe('TestRail suite ID'),
      },
    },
    async ({ suite_id }) => {
      logger.debug(`Get suite tool called with suite_id: ${suite_id}`);
      try {
        const result = await getSuite(suite_id);
        logger.debug(`Get suite tool completed successfully for suite_id: ${suite_id}`);
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (err) {
        logger.error({ err }, `Get suite tool failed for suite_id: ${suite_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 = `Suite ${suite_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:508-549 (helper)

  Service layer function getSuite that fetches raw suite data from client and normalizes it into SuiteSummary, extracting custom fields.

  export async function getSuite(suiteId: number): Promise<SuiteSummary> {
    const suite: TestRailSuiteDto = await testRailClient.getSuite(suiteId);
    
    const {
      id,
      name,
      description,
      project_id,
      url,
      is_baseline,
      is_master,
      is_completed,
      completed_on,
      created_on,
      created_by,
      updated_on,
      updated_by,
      ...rest
    } = suite;
  
    const custom: Record<string, unknown> = {};
    for (const [key, value] of Object.entries(rest)) {
      if (key.startsWith('custom_')) custom[key] = value;
    }
  
    return {
      id,
      name,
      description,
      project_id,
      url,
      is_baseline,
      is_master,
      is_completed,
      completed_on,
      created_on,
      created_by,
      updated_on,
      updated_by,
      custom: Object.keys(custom).length ? custom : undefined,
    };
  }

• src/clients/testrailClient.ts:580-599 (helper)

  Low-level HTTP client method that calls TestRail API /get_suite/{suiteId} endpoint, handles errors and retries.

  async getSuite(suiteId: number): Promise<TestRailSuiteDto> {
    try {
      const res = await this.http.get(`/get_suite/${suiteId}`);
      logger.info({ 
        status: res.status, 
        dataType: typeof res.data,
        suiteId 
      }, 'TestRail getSuite response info');
      
      if (res.status >= 200 && res.status < 300) {
        return res.data as TestRailSuiteDto;
      }
      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, suiteId }, 'TestRail getSuite failed');
      throw normalized;
    }
  }