get_suite
Retrieve detailed information about a specific TestRail test suite using its unique identifier to access test case data and suite configurations.
Instructions
Get details for a specific TestRail test suite by ID.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| suite_id | Yes | TestRail suite ID |
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, }; } }, );
- 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, }; }
- 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; } }