get_dartboard

Instructions

Implementation Reference

• src/tools/get_dartboard.ts:25-82 (handler)

  Main handler function for get_dartboard tool. Validates input, resolves dartboard name to dart_id, calls API client to get details, returns dart_id, name, description, task_count, and url. Falls back to config data if API returns 404.

  export async function handleGetDartboard(input: GetDartboardInput): Promise<GetDartboardOutput> {
    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.dartboard_id || typeof input.dartboard_id !== 'string' || input.dartboard_id.trim() === '') {
      throw new ValidationError('dartboard_id is required and must be a non-empty string', 'dartboard_id');
    }
  
    // Resolve dartboard name to dart_id if needed
    const config = await handleGetConfig({ cache_bust: false });
    const dartboard = findDartboard(config.dartboards, input.dartboard_id.trim());
  
    if (!dartboard) {
      const dartboardNames = getDartboardNames(config.dartboards);
      throw new ValidationError(
        `Dartboard "${input.dartboard_id}" not found. Available: ${dartboardNames.slice(0, 5).join(', ')}${dartboardNames.length > 5 ? '...' : ''}`,
        'dartboard_id',
        dartboardNames
      );
    }
  
    const client = new DartClient({ token: DART_TOKEN });
    const dartboardId = typeof dartboard === 'string' ? dartboard : dartboard.dart_id;
    const dartboardName = typeof dartboard === 'string' ? dartboard : dartboard.name;
  
    try {
      const result = await client.getDartboard(dartboardId);
  
      return {
        dart_id: result.dart_id,
        name: result.name || dartboardName,
        description: result.description,
        task_count: result.task_count,
        url: `https://app.dartai.com/b/${result.dart_id}`,
      };
    } catch (error) {
      // If API call fails, return basic info from config
      if (error instanceof DartAPIError && error.statusCode === 404) {
        return {
          dart_id: dartboardId,
          name: dartboardName,
          url: `https://app.dartai.com/b/${dartboardId}`,
        };
      }
      throw error;
    }
  }

• src/types/index.ts:888-898 (schema)

  Input type: GetDartboardInput with dartboard_id (string). Output type: GetDartboardOutput with dart_id, name, optional description and task_count, and url.

  export interface GetDartboardInput {
    dartboard_id: string;
  }
  
  export interface GetDartboardOutput {
    dart_id: string;
    name: string;
    description?: string;
    task_count?: number;
    url: string;
  }

• src/index.ts:931-944 (registration)

  Tool registration in ListToolsRequestSchema handler. Defines name 'get_dartboard', description, and inputSchema requiring dartboard_id string.

  {
    name: 'get_dartboard',
    description: 'Get details about a dartboard including task count. Token-efficient lookup.',
    inputSchema: {
      type: 'object',
      properties: {
        dartboard_id: {
          type: 'string',
          description: 'Dartboard dart_id or name',
        },
      },
      required: ['dartboard_id'],
    },
  },

• src/index.ts:1244-1254 (registration)

  Tool call dispatch in CallToolRequestSchema handler. Case 'get_dartboard' calls handleGetDartboard and returns JSON-stringified result.

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

• src/types/index.ts:155-157 (helper)

  Helper function getDartboardNames: extracts names from dartboards array for error suggestions.

  export function getDartboardNames(dartboards: (DartBoard | string)[]): string[] {
    return dartboards.map(d => typeof d === 'string' ? d : d.name);
  }