get_task

Instructions

Implementation Reference

• src/tools/get_task.ts:134-242 (handler)

  Main handler function for the get_task tool. Validates input, calls DartClient.getTask(), generates deep link URL, optionally fetches comments, relationship counts, and expanded relationships, then returns GetTaskOutput.

  export async function handleGetTask(input: GetTaskInput): Promise<GetTaskOutput> {
    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
      );
    }
  
    // ============================================================================
    // Step 1: Validate input and dart_id
    // ============================================================================
    if (!input || typeof input !== 'object') {
      throw new DartAPIError(
        'input is required and must be an object',
        400
      );
    }
  
    // Accept id, task_id, or taskId as aliases for dart_id
    input.dart_id = resolveDartId(input as unknown as Record<string, unknown>);
  
    // Default include_relationships to true
    const includeRelationships = input.include_relationships !== false;
    const expandRelationships = input.expand_relationships === true;
  
    // ============================================================================
    // Step 2: Call DartClient.getTask()
    // ============================================================================
    const client = new DartClient({ token: DART_TOKEN });
  
    let task: DartTask;
    try {
      task = await client.getTask(input.dart_id);
    } catch (error) {
      // Handle 404 errors specifically
      if (error instanceof DartAPIError && error.statusCode === 404) {
        throw new DartAPIError(
          `Task not found: No task with dart_id "${input.dart_id}" exists in workspace`,
          404,
          error.response
        );
      }
      // Re-throw other errors with enhanced context
      if (error instanceof DartAPIError) {
        throw new DartAPIError(
          `Failed to retrieve task: ${error.message}`,
          error.statusCode,
          error.response
        );
      }
      throw error;
    }
  
    // ============================================================================
    // Step 3: Generate deep link URL
    // ============================================================================
    const deepLinkUrl = `https://app.dartai.com/task/${task.dart_id}`;
  
    // ============================================================================
    // Step 4: Optionally fetch comments
    // ============================================================================
    let comments: DartComment[] | undefined;
  
    if (input.include_comments) {
      // TODO: Implement comment fetching when API endpoint is available
      // For now, return empty array as placeholder
      comments = [];
  
      // Note: Once Dart API exposes /tasks/{dart_id}/comments endpoint:
      // try {
      //   comments = await client.getTaskComments(task.dart_id);
      // } catch (error) {
      //   // Log error but don't fail the entire request if comment fetch fails
      //   console.error(`Failed to fetch comments for task ${task.dart_id}:`, error);
      //   comments = [];
      // }
    }
  
    // ============================================================================
    // Step 5: Build output with relationship information
    // ============================================================================
    const output: GetTaskOutput = {
      // If include_relationships is false, strip the relationship fields from task
      task: includeRelationships ? task : stripRelationshipFields(task),
      url: deepLinkUrl,
    };
  
    // Only include comments field if include_comments was requested
    if (input.include_comments) {
      output.comments = comments;
    }
  
    // ============================================================================
    // Step 6: Add relationship counts and expanded relationships
    // ============================================================================
    if (includeRelationships) {
      // Always include relationship counts when relationships are included
      output.relationship_counts = calculateRelationshipCounts(task);
  
      // Optionally fetch expanded relationships (titles for related tasks)
      if (expandRelationships) {
        output.expanded_relationships = await fetchExpandedRelationships(client, task);
      }
    }
  
    return output;
  }

• src/types/index.ts:318-331 (schema)

  Input schema for get_task: dart_id (required), include_comments, include_relationships (default true), expand_relationships.

  export interface GetTaskInput {
    dart_id: string;
    include_comments?: boolean;
    /**
     * Include relationship fields in response (default: true).
     * When false, relationship arrays are omitted for smaller response.
     */
    include_relationships?: boolean;
    /**
     * Expand related task summaries (fetch titles for each related task).
     * Requires additional API calls. Only applies when include_relationships is true.
     */
    expand_relationships?: boolean;
  }

• src/types/index.ts:364-376 (schema)

  Output schema for get_task: task (DartTask), optional comments, url, relationship_counts, and expanded_relationships.

  export interface GetTaskOutput {
    task: DartTask;
    comments?: DartComment[];
    url: string;
    /**
     * Relationship counts for quick overview (when include_relationships is true)
     */
    relationship_counts?: RelationshipCounts;
    /**
     * Expanded relationship details with titles (when expand_relationships is true)
     */
    expanded_relationships?: ExpandedRelationships;
  }

• src/index.ts:343-368 (registration)

  Tool registration in the MCP server definition: name 'get_task', description, inputSchema with dart_id, include_comments, include_relationships, expand_relationships.

  {
    name: 'get_task',
    description: 'Get a specific task by dart_id with optional comments and relationship details. Returns task relationships (subtasks, blockers, blocking, duplicates, related) with counts and optional expanded titles.',
    inputSchema: {
      type: 'object',
      properties: {
        dart_id: {
          type: 'string',
          description: 'Task dart_id',
        },
        include_comments: {
          type: 'boolean',
          description: 'Include task comments in response (default: false)',
        },
        include_relationships: {
          type: 'boolean',
          description: 'Include relationship fields and counts in response (default: true). Set to false for smaller response.',
        },
        expand_relationships: {
          type: 'boolean',
          description: 'Fetch titles for all related tasks (default: false). Requires additional API calls. Only applies when include_relationships is true.',
        },
      },
      required: ['dart_id'],
    },
  },

• src/index.ts:1016-1025 (registration)

  Tool call handler for 'get_task' case: calls handleGetTask and returns JSON-stringified result.

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