TestRail MCP Server

Instructions

Implementation Reference

• src/server.ts:665-715 (handler)

  MCP handler function for the 'update_run' tool. Processes input parameters, removes undefined fields, calls the service layer updateRun, formats the response as MCP content or error.
  async ({ run_id, name, description, milestone_id, include_all, case_ids, config, config_ids, refs, start_on, due_on, custom }) => { logger.debug(`Update run tool called with run_id: ${run_id}`); try { const updates = { name, description, milestone_id, include_all, case_ids, config, config_ids, refs, start_on, due_on, custom, }; // Remove undefined values to avoid sending empty fields const cleanUpdates = Object.fromEntries( Object.entries(updates).filter(([, value]) => value !== undefined) ); const result = await updateRun(run_id, cleanUpdates); logger.debug(`Update run tool completed successfully for run_id: ${run_id}`); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } catch (err) { logger.error({ err }, `Update run tool failed for run_id: ${run_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 = `Run ${run_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:650-663 (schema)

  Zod input schema defining parameters for the 'update_run' tool, including run_id (required) and optional update fields.
  inputSchema: { run_id: z.number().int().positive().describe('The ID of the test run to be updated'), name: z.string().min(1).optional().describe('The name of the test run'), description: z.string().optional().describe('The description of the test run'), milestone_id: z.number().int().positive().optional().describe('The ID of the milestone'), include_all: z.boolean().optional().describe('True for including all test cases and false for a custom case selection'), case_ids: z.array(z.number().int().positive()).optional().describe('An array of case IDs for the custom case selection'), config: z.string().optional().describe('A comma-separated list of configuration IDs'), config_ids: z.array(z.number().int().positive()).optional().describe('An array of configuration IDs'), refs: z.string().optional().describe('A string of external requirements'), start_on: z.number().int().optional().describe('The start date (Unix timestamp)'), due_on: z.number().int().optional().describe('The due date (Unix timestamp)'), custom: z.record(z.string(), z.unknown()).optional().describe('Custom fields (key-value pairs)'), },
• src/server.ts:645-716 (registration)

  Registration of the 'update_run' MCP tool using server.registerTool, including title, description, input schema, and handler function.
  server.registerTool( 'update_run', { title: 'Update TestRail Run', description: 'Updates an existing test run. Partial updates are supported.', inputSchema: { run_id: z.number().int().positive().describe('The ID of the test run to be updated'), name: z.string().min(1).optional().describe('The name of the test run'), description: z.string().optional().describe('The description of the test run'), milestone_id: z.number().int().positive().optional().describe('The ID of the milestone'), include_all: z.boolean().optional().describe('True for including all test cases and false for a custom case selection'), case_ids: z.array(z.number().int().positive()).optional().describe('An array of case IDs for the custom case selection'), config: z.string().optional().describe('A comma-separated list of configuration IDs'), config_ids: z.array(z.number().int().positive()).optional().describe('An array of configuration IDs'), refs: z.string().optional().describe('A string of external requirements'), start_on: z.number().int().optional().describe('The start date (Unix timestamp)'), due_on: z.number().int().optional().describe('The due date (Unix timestamp)'), custom: z.record(z.string(), z.unknown()).optional().describe('Custom fields (key-value pairs)'), }, }, async ({ run_id, name, description, milestone_id, include_all, case_ids, config, config_ids, refs, start_on, due_on, custom }) => { logger.debug(`Update run tool called with run_id: ${run_id}`); try { const updates = { name, description, milestone_id, include_all, case_ids, config, config_ids, refs, start_on, due_on, custom, }; // Remove undefined values to avoid sending empty fields const cleanUpdates = Object.fromEntries( Object.entries(updates).filter(([, value]) => value !== undefined) ); const result = await updateRun(run_id, cleanUpdates); logger.debug(`Update run tool completed successfully for run_id: ${run_id}`); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } catch (err) { logger.error({ err }, `Update run tool failed for run_id: ${run_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 = `Run ${run_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:947-1025 (helper)

  Service layer helper: transforms MCP updates to TestRailRunUpdateDto, ensures custom_ prefix, calls client.updateRun, normalizes response to RunDetailSummary.
  export async function updateRun(runId: number, updates: RunUpdatePayload): Promise<RunDetailSummary> { // Transform the payload to match TestRail API format const updatePayload: TestRailRunUpdateDto = { name: updates.name, description: updates.description, milestone_id: updates.milestone_id, include_all: updates.include_all, case_ids: updates.case_ids, config: updates.config, config_ids: updates.config_ids, refs: updates.refs, start_on: updates.start_on, due_on: updates.due_on, }; // Add custom fields with proper naming convention if (updates.custom) { for (const [key, value] of Object.entries(updates.custom)) { // Ensure custom field keys have the 'custom_' prefix const fieldKey = key.startsWith('custom_') ? key : `custom_${key}`; updatePayload[fieldKey] = value; } } const data: TestRailRunDetailDto = await testRailClient.updateRun(runId, updatePayload); // Normalize the response using the same logic as getRun 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(data).forEach(key => { if (!standardFields.includes(key)) { custom[key] = data[key]; } }); return { id: data.id, name: data.name, description: data.description, suite_id: data.suite_id, milestone_id: data.milestone_id, assignedto_id: data.assignedto_id, include_all: data.include_all, is_completed: data.is_completed, completed_on: data.completed_on, config: data.config, config_ids: data.config_ids, passed_count: data.passed_count, blocked_count: data.blocked_count, untested_count: data.untested_count, retest_count: data.retest_count, failed_count: data.failed_count, custom_status1_count: data.custom_status1_count, custom_status2_count: data.custom_status2_count, custom_status3_count: data.custom_status3_count, custom_status4_count: data.custom_status4_count, custom_status5_count: data.custom_status5_count, custom_status6_count: data.custom_status6_count, custom_status7_count: data.custom_status7_count, project_id: data.project_id, plan_id: data.plan_id, created_on: data.created_on, updated_on: data.updated_on, refs: data.refs, start_on: data.start_on, due_on: data.due_on, url: data.url, custom: Object.keys(custom).length > 0 ? custom : undefined, }; }
• src/clients/testrailClient.ts:1005-1028 (helper)

  HTTP client method that performs POST to TestRail API /update_run/{runId} with updates payload, handles response and errors.
  async updateRun(runId: number, updates: TestRailRunUpdateDto): Promise<TestRailRunDetailDto> { try { const res = await this.http.post(`/update_run/${runId}`, updates); if (res.status >= 200 && res.status < 300) { logger.info({ message: 'Successfully updated 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 update test run', runId, error: normalized, details: safeDetails, }); throw normalized; } }