TestRail MCP Server

Instructions

Implementation Reference

• src/server.ts:277-317 (registration)

  Registers the MCP 'get_suites' tool with input schema (project_id) and handler that delegates to testrailService.getSuites(project_id), formats result as JSON text content, and handles errors.
  server.registerTool( 'get_suites', { title: 'Get TestRail Suites', description: 'Get all test suites for a specific TestRail project by ID.', inputSchema: { project_id: z.number().int().positive().describe('TestRail project ID'), }, }, async ({ project_id }) => { logger.debug(`Get suites tool called with project_id: ${project_id}`); try { const result = await getSuites(project_id); logger.debug(`Get suites tool completed successfully for project_id: ${project_id}. Found ${result.length} suites`); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } catch (err) { logger.error({ err }, `Get suites tool failed for project_id: ${project_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 = `Project ${project_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:286-316 (handler)

  MCP tool handler function for get_suites: calls service layer, returns JSON suites or error message.
  async ({ project_id }) => { logger.debug(`Get suites tool called with project_id: ${project_id}`); try { const result = await getSuites(project_id); logger.debug(`Get suites tool completed successfully for project_id: ${project_id}. Found ${result.length} suites`); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } catch (err) { logger.error({ err }, `Get suites tool failed for project_id: ${project_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 = `Project ${project_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:279-284 (schema)

  Tool metadata and input schema validation using Zod for project_id parameter.
  { title: 'Get TestRail Suites', description: 'Get all test suites for a specific TestRail project by ID.', inputSchema: { project_id: z.number().int().positive().describe('TestRail project ID'), },
• src/services/testrailService.ts:551-594 (helper)

  Service layer getSuites: fetches raw suites from client, normalizes custom fields into SuiteSummary[]
  export async function getSuites(projectId: number): Promise<SuiteSummary[]> { const suites: TestRailSuiteDto[] = await testRailClient.getSuites(projectId); return suites.map((suite) => { 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:601-649 (helper)

  HTTP client implementation: GET /get_suites/{projectId}, handles direct/paginated responses, error normalization.
  async getSuites(projectId: number): Promise<TestRailSuiteDto[]> { try { const res = await this.http.get(`/get_suites/${projectId}`); logger.info({ status: res.status, dataType: typeof res.data, dataIsArray: Array.isArray(res.data), projectId }, 'TestRail getSuites response info'); if (res.status >= 200 && res.status < 300) { // Handle both direct array and paginated response formats let suites: TestRailSuiteDto[]; if (Array.isArray(res.data)) { // Direct array format (most common) suites = res.data as TestRailSuiteDto[]; } else if (res.data && typeof res.data === 'object' && 'suites' in res.data) { // Paginated format (if TestRail supports it) const paginatedResponse = res.data as { suites: TestRailSuiteDto[] }; if (!Array.isArray(paginatedResponse.suites)) { throw Object.assign(new Error('API returned paginated response with non-array suites field'), { response: { status: 200 } // Make it look like a server error }); } suites = paginatedResponse.suites; logger.info({ returnedSuites: suites.length }, 'TestRail paginated suites response'); } else { logger.error({ status: res.status, responseData: res.data, dataType: typeof res.data }, 'TestRail getSuites returned unexpected response format'); throw Object.assign(new Error('API returned unexpected response format'), { response: { status: 200 } // Make it look like a server error }); } return suites; } 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, projectId }, 'TestRail getSuites failed'); throw normalized; }