TestRail MCP Server

Instructions

Implementation Reference

• src/server.ts:197-227 (handler)

  MCP tool handler for 'get_projects': calls service getProjects(), returns JSON-stringified list of projects or error message.

  async () => {
    logger.debug('Get projects tool called');
    try {
      const result = await getProjects();
      logger.debug(`Get projects tool completed successfully. Found ${result.length} projects`);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (err) {
      logger.error({ err }, 'Get projects 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:190-228 (registration)

  Registers the 'get_projects' tool on the MCP server with empty input schema (no parameters) and associated handler.

  server.registerTool(
    'get_projects',
    {
      title: 'Get TestRail Projects',
      description: 'List all TestRail projects.',
      inputSchema: {}, // No parameters required
    },
    async () => {
      logger.debug('Get projects tool called');
      try {
        const result = await getProjects();
        logger.debug(`Get projects tool completed successfully. Found ${result.length} projects`);
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (err) {
        logger.error({ err }, 'Get projects 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:80-92 (schema)

  TypeScript interface defining the normalized ProjectSummary structure used in tool output.

  export interface ProjectSummary {
    id: number;
    name: string;
    announcement?: string;
    show_announcement?: boolean;
    is_completed: boolean;
    completed_on?: number | null;
    suite_mode: number;
    url: string;
    created_on?: number;
    created_by?: number;
    custom?: Record<string, unknown> | undefined;
  }

• src/services/testrailService.ts:432-469 (helper)

  Helper function that fetches raw TestRail projects via client and normalizes response by isolating custom fields.

  export async function getProjects(): Promise<ProjectSummary[]> {
    const projects: TestRailProjectDto[] = await testRailClient.getProjects();
    
    return projects.map((project) => {
      const {
        id,
        name,
        announcement,
        show_announcement,
        is_completed,
        completed_on,
        suite_mode,
        url,
        created_on,
        created_by,
        ...rest
      } = project;
  
      const custom: Record<string, unknown> = {};
      for (const [key, value] of Object.entries(rest)) {
        if (key.startsWith('custom_')) custom[key] = value;
      }
  
      return {
        id,
        name,
        announcement,
        show_announcement,
        is_completed,
        completed_on,
        suite_mode,
        url,
        created_on,
        created_by,
        custom: Object.keys(custom).length ? custom : undefined,
      };
    });
  }