TestRail MCP Server

Instructions

Implementation Reference

• src/server.ts:902-932 (handler)

  MCP tool handler function for 'get_case_fields'. Calls the service layer getCaseFields(), handles errors with specific messages, and returns JSON-formatted result or error.

  async () => {
    logger.debug('Get case fields tool called');
    try {
      const result = await getCaseFields();
      logger.debug(`Get case fields tool completed successfully. Found ${result.length} fields`);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (err) {
      logger.error({ err }, 'Get case fields tool failed');
      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 === '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:897-901 (schema)

  Input schema for the get_case_fields tool: no parameters required (empty schema).

  {
    title: 'Get TestRail Case Fields',
    description: 'Returns a list of available test case custom fields.',
    inputSchema: {},
  },

• src/server.ts:895-933 (registration)

  Registration of the 'get_case_fields' MCP tool using server.registerTool, including name, metadata/schema, and handler function.

  server.registerTool(
    'get_case_fields',
    {
      title: 'Get TestRail Case Fields',
      description: 'Returns a list of available test case custom fields.',
      inputSchema: {},
    },
    async () => {
      logger.debug('Get case fields tool called');
      try {
        const result = await getCaseFields();
        logger.debug(`Get case fields tool completed successfully. Found ${result.length} fields`);
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (err) {
        logger.error({ err }, 'Get case fields tool failed');
        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 === '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:1129-1142 (helper)

  Service layer function getCaseFields that fetches raw fields from client and maps to summary format (CaseFieldSummary[]). Called by MCP handler.

  export async function getCaseFields(): Promise<CaseFieldSummary[]> {
    const fields: TestRailCaseFieldDto[] = await testRailClient.getCaseFields();
    
    return fields.map((field) => ({
      id: field.id,
      label: field.label,
      name: field.name,
      system_name: field.system_name,
      type_id: field.type_id,
      description: field.description,
      display_order: field.display_order,
      configs: field.configs,
    }));
  }

• src/clients/testrailClient.ts:652-682 (helper)

  Client layer HTTP call to TestRail API endpoint '/get_case_fields', with response validation, logging, and error normalization. Called by service layer.

  async getCaseFields(): Promise<TestRailCaseFieldDto[]> {
    try {
      const res = await this.http.get('/get_case_fields');
      logger.info({ 
        status: res.status, 
        dataType: typeof res.data,
        dataIsArray: Array.isArray(res.data)
      }, 'TestRail getCaseFields response info');
      
      if (res.status >= 200 && res.status < 300) {
        if (Array.isArray(res.data)) {
          return res.data as TestRailCaseFieldDto[];
        } else {
          logger.error({ 
            status: res.status, 
            responseData: res.data,
            dataType: typeof res.data 
          }, 'TestRail getCaseFields returned non-array response');
          throw Object.assign(new Error('API returned non-array response'), { 
            response: { status: 200 } // Make it look like a server error
          });
        }
      }
      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 }, 'TestRail getCaseFields failed');
      throw normalized;
    }
  }