TestRail MCP Server

Instructions

Implementation Reference

• src/server.ts:628-640 (handler)

  MCP tool handler for 'get_run': takes run_id, calls getRun service function, returns JSON stringified result as text content.

  async ({ run_id }) => {
    logger.debug(`Get run tool called with run_id: ${run_id}`);
    const result = await getRun(run_id);
    logger.debug(`Get run tool completed. Retrieved run: ${result.name}`);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  },

• src/server.ts:621-627 (schema)

  Input schema for 'get_run' tool using Zod: requires positive integer run_id.

  {
    title: 'Get TestRail Run',
    description: 'Returns an existing test run. Please see get tests for the list of included tests in this run.',
    inputSchema: {
      run_id: z.number().int().positive().describe('The ID of the test run'),
    },
  },

• src/server.ts:619-641 (registration)

  Registers the 'get_run' MCP tool with McpServer.registerTool, including title, description, input schema, and handler function.

  server.registerTool(
    'get_run',
    {
      title: 'Get TestRail Run',
      description: 'Returns an existing test run. Please see get tests for the list of included tests in this run.',
      inputSchema: {
        run_id: z.number().int().positive().describe('The ID of the test run'),
      },
    },
    async ({ run_id }) => {
      logger.debug(`Get run tool called with run_id: ${run_id}`);
      const result = await getRun(run_id);
      logger.debug(`Get run tool completed. Retrieved run: ${result.name}`);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    },
  );

• src/services/testrailService.ts:890-945 (helper)

  Service layer function getRun that calls client.getRun and normalizes the TestRailRunDetailDto response into RunDetailSummary, extracting custom fields.

  export async function getRun(runId: number): Promise<RunDetailSummary> {
    const response: TestRailRunDetailDto = await testRailClient.getRun(runId);
    
    // Extract custom fields (any fields not in the standard interface)
    const standardFields = [
      'id', 'name', 'description', 'suite_id', 'milestone_id', 'assignedto_id',
      'include_all', 'is_completed', 'completed_on', 'config', 'config_ids',
      'passed_count', 'blocked_count', 'untested_count', 'retest_count',
      'failed_count', 'custom_status1_count', 'custom_status2_count',
      'custom_status3_count', 'custom_status4_count', 'custom_status5_count',
      'custom_status6_count', 'custom_status7_count', 'project_id', 'plan_id',
      'created_on', 'updated_on', 'refs', 'start_on', 'due_on', 'url'
    ];
    
    const custom: Record<string, unknown> = {};
    Object.keys(response).forEach(key => {
      if (!standardFields.includes(key)) {
        custom[key] = response[key];
      }
    });
  
    return {
      id: response.id,
      name: response.name,
      description: response.description,
      suite_id: response.suite_id,
      milestone_id: response.milestone_id,
      assignedto_id: response.assignedto_id,
      include_all: response.include_all,
      is_completed: response.is_completed,
      completed_on: response.completed_on,
      config: response.config,
      config_ids: response.config_ids,
      passed_count: response.passed_count,
      blocked_count: response.blocked_count,
      untested_count: response.untested_count,
      retest_count: response.retest_count,
      failed_count: response.failed_count,
      custom_status1_count: response.custom_status1_count,
      custom_status2_count: response.custom_status2_count,
      custom_status3_count: response.custom_status3_count,
      custom_status4_count: response.custom_status4_count,
      custom_status5_count: response.custom_status5_count,
      custom_status6_count: response.custom_status6_count,
      custom_status7_count: response.custom_status7_count,
      project_id: response.project_id,
      plan_id: response.plan_id,
      created_on: response.created_on,
      updated_on: response.updated_on,
      refs: response.refs,
      start_on: response.start_on,
      due_on: response.due_on,
      url: response.url,
      custom: Object.keys(custom).length > 0 ? custom : undefined,
    };
  }

• src/clients/testrailClient.ts:980-1002 (helper)

  Client HTTP call to TestRail API /get_run/{runId}, handles errors and logging.

  async getRun(runId: number): Promise<TestRailRunDetailDto> {
    try {
      const res = await this.http.get(`/get_run/${runId}`);
      if (res.status >= 200 && res.status < 300) {
        logger.info({
          message: 'Successfully retrieved test run',
          runId,
          responseSize: JSON.stringify(res.data).length,
        });
        return res.data as TestRailRunDetailDto;
      }
      throw Object.assign(new Error(`HTTP ${res.status}`), { response: res });
    } catch (error) {
      const normalized = this.normalizeError(error);
      const safeDetails = this.getSafeErrorDetails(error);
      logger.error({
        message: 'Failed to retrieve test run',
        runId,
        error: normalized,
        details: safeDetails,
      });
      throw normalized;
    }