list_comments

Instructions

Implementation Reference

• src/tools/list_comments.ts:23-81 (handler)

  Main handler function for the list_comments tool. Validates inputs (task_id, limit, offset), calls the DartClient.listComments API, maps results to DartComment type, and returns paginated output.

  export async function handleListComments(input: ListCommentsInput): Promise<ListCommentsOutput> {
    const DART_TOKEN = process.env.DART_TOKEN;
  
    if (!DART_TOKEN) {
      throw new DartAPIError(
        'DART_TOKEN environment variable is required. Get your token from: https://app.dartai.com/?settings=account',
        401
      );
    }
  
    // Validate input
    if (!input || typeof input !== 'object') {
      throw new ValidationError('Input must be an object', 'input');
    }
  
    if (!input.task_id || typeof input.task_id !== 'string' || input.task_id.trim() === '') {
      throw new ValidationError('task_id is required and must be a non-empty string', 'task_id');
    }
  
    // Validate pagination params
    const limit = input.limit ?? 50;
    if (typeof limit !== 'number' || limit < 1 || limit > 100) {
      throw new ValidationError('limit must be a number between 1 and 100', 'limit');
    }
  
    const offset = input.offset ?? 0;
    if (typeof offset !== 'number' || offset < 0) {
      throw new ValidationError('offset must be a non-negative number', 'offset');
    }
  
    const client = new DartClient({ token: DART_TOKEN });
  
    const result = await client.listComments({
      task_id: input.task_id.trim(),
      limit,
      offset,
    });
  
    const returnedCount = result.comments.length;
    const hasMore = (offset + returnedCount) < result.total;
  
    // Map to DartComment type
    const comments: DartComment[] = result.comments.map(c => ({
      comment_id: c.comment_id,
      text: c.text,
      author: c.author,
      created_at: c.created_at,
      parent_id: c.parent_id,
    }));
  
    return {
      comments,
      total_count: result.total,
      returned_count: returnedCount,
      has_more: hasMore,
      next_offset: hasMore ? offset + returnedCount : null,
      task_id: input.task_id.trim(),
    };
  }

• src/types/index.ts:120-127 (schema)

  DartComment interface - the comment data structure returned by the tool.

  export interface DartComment {
    comment_id: string;
    dart_id?: string; // task id (optional in list responses)
    text: string;
    author: string;
    created_at?: string;
    parent_id?: string; // For threaded comments
  }

• src/types/index.ts:805-818 (schema)

  ListCommentsInput and ListCommentsOutput type definitions with task_id, limit, offset, pagination metadata.

  export interface ListCommentsInput {
    task_id: string;
    limit?: number;
    offset?: number;
  }
  
  export interface ListCommentsOutput {
    comments: DartComment[];
    total_count: number;
    returned_count: number;
    has_more: boolean;
    next_offset: number | null;
    task_id: string;
  }

• src/index.ts:823-844 (registration)

  Tool registration entry defining name 'list_comments', description, and JSON Schema input schema (task_id required, limit/offset optional).

  {
    name: 'list_comments',
    description: 'List comments on a task with pagination. Token-efficient: returns minimal comment data.',
    inputSchema: {
      type: 'object',
      properties: {
        task_id: {
          type: 'string',
          description: 'Task dart_id to list comments for',
        },
        limit: {
          type: 'integer',
          description: 'Max comments to return (default: 50, max: 100)',
        },
        offset: {
          type: 'integer',
          description: 'Pagination offset (default: 0)',
        },
      },
      required: ['task_id'],
    },
  },

• src/index.ts:1196-1206 (registration)

  Router case dispatching 'list_comments' tool calls to handleListComments handler.

  case 'list_comments': {
    const result = await handleListComments((args || {}) as any);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }