info

Instructions

Implementation Reference

• src/tools/info.ts:548-587 (handler)

  Main handler function `handleInfo` that processes info tool requests. Accepts InfoInput with optional level ('overview'|'group'|'tool') and target, delegates to renderOverview/renderGroup/renderTool, and returns InfoOutput with level, content, and next_steps.

  export async function handleInfo(input: InfoInput): Promise<InfoOutput> {
    // Defensive: handle undefined/null input
    const safeInput = input || {};
  
    const level = safeInput.level || 'overview';
    const target = safeInput.target;
  
    let content: string;
  
    switch (level) {
      case 'overview':
        content = renderOverview();
        break;
  
      case 'group':
        if (!target) {
          content = 'Error: target parameter required when level=group\n\n' + renderOverview();
        } else {
          content = renderGroup(target);
        }
        break;
  
      case 'tool':
        if (!target) {
          content = 'Error: target parameter required when level=tool\n\n' + renderOverview();
        } else {
          content = renderTool(target);
        }
        break;
  
      default:
        content = `Error: Invalid level "${level}". Valid levels: overview, group, tool\n\n` + renderOverview();
    }
  
    return {
      level,
      content,
      next_steps: generateNextSteps(level, target),
    };
  }

• src/types/index.ts:266-275 (schema)

  Type definitions for InfoInput (level?: 'overview'|'group'|'tool', target?: string) and InfoOutput (level: string, content: string, next_steps: string[]).

  export interface InfoInput {
    level?: 'overview' | 'group' | 'tool';
    target?: string;
  }
  
  export interface InfoOutput {
    level: string;
    content: string;
    next_steps: string[];
  }

• src/index.ts:158-175 (registration)

  Registration of the 'info' tool in the ListToolsRequestSchema handler, defining its name, description, and inputSchema (level enum + target string).

  {
    name: 'info',
    description: 'Progressive discovery of dart-query capabilities - start here',
    inputSchema: {
      type: 'object',
      properties: {
        level: {
          type: 'string',
          enum: ['overview', 'group', 'tool'],
          description: 'Detail level: overview=categories, group=tools in category, tool=full documentation',
        },
        target: {
          type: 'string',
          description: 'Group name (when level=group) or tool name (when level=tool)',
        },
      },
    },
  },

• src/index.ts:968-978 (registration)

  Call-site in the tool dispatch switch-case that routes 'info' requests to handleInfo() and returns the content as text.

  case 'info': {
    const result = await handleInfo(args || {});
    return {
      content: [
        {
          type: 'text',
          text: result.content,
        },
      ],
    };
  }

• src/tools/info.ts:140-509 (helper)

  Helper functions: renderOverview(), renderGroup(target), renderTool(target), and generateNextSteps(level, target) that produce progressive documentation content. renderTool contains detailed docs for info, get_config, execute_dartql, batch_update_tasks, import_tasks_csv, and relationships.

  function renderOverview(): string {
    return `Dart Query MCP - Task Management with Batch Operations
  
  Tool Groups
  -----------
  Group       | Count | Purpose
  ----------- | ----- | -------
  discovery   | 1     | Progressive capability discovery
  config      | 1     | Workspace configuration
  task-crud   | 5     | Single task operations
  task-query  | 2     | Search and filter tasks
  task-batch  | 4     | Bulk operations on multiple tasks
  doc-crud    | 5     | Document management
  import      | 1     | CSV bulk import
  
  Quick Start:    info(level='group', target='task-crud')
  Batch Ops:      info(level='group', target='task-batch')
  DartQL Help:    info(level='tool', target='batch_update_tasks')
  Relationships:  info(level='tool', target='relationships')`;
  }
  
  /**
   * Render group: tools in specific category
   */
  function renderGroup(target: string): string {
    const group = TOOL_GROUPS[target as keyof typeof TOOL_GROUPS];
  
    if (!group) {
      const validGroups = Object.keys(TOOL_GROUPS).join(', ');
      return `Error: Unknown group "${target}". Valid groups: ${validGroups}`;
    }
  
    let output = `Tool Group: ${target}\n`;
    output += `Purpose: ${group.purpose}\n`;
    output += `Tools (${group.count}):\n\n`;
  
    group.tools.forEach((tool) => {
      output += `• ${tool.name}\n  ${tool.description}\n\n`;
    });
  
    output += `\nNext Steps:\n`;
    output += `- info(level='tool', target='${group.tools[0].name}') - Full documentation\n`;
    output += `- info(level='overview') - Return to overview`;
  
    return output;
  }
  
  /**
   * Render tool: full schema and examples
   */
  function renderTool(target: string): string {
    // Full tool documentation with schema and examples
    const toolDocs: Record<string, string> = {
      info: `Tool: info
  Description: Progressive discovery of dart-query capabilities - start here
  
  Input Schema:
    level?: 'overview' | 'group' | 'tool' (default: 'overview')
      Detail level for information display
  
    target?: string
      Group name (when level='group') or tool name (when level='tool')
  
  Output Schema:
    level: string (echoed back)
    content: string (formatted documentation)
    next_steps: string[] (suggested follow-up queries)
  
  Examples:
    info()
      → Shows overview table of all tool groups
  
    info(level='group', target='task-batch')
      → Shows batch operation tools
  
    info(level='tool', target='batch_update_tasks')
      → Shows full schema and DartQL syntax guide
  
  Token Budget: ~150 tokens (overview), ~200 tokens (group), ~500 tokens (tool)
  Performance: Instant (no API calls required)`,
  
      get_config: `Tool: get_config
  Description: Get workspace configuration: assignees, dartboards, statuses, tags, priorities, sizes
  
  Input Schema:
    cache_bust?: boolean (default: false)
      Force refresh cached config (default: 5-minute cache)
  
    include?: Array<'assignees' | 'dartboards' | 'statuses' | 'tags' | 'priorities' | 'sizes' | 'folders'>
      Limit response to specific config sections (default: all)
  
  Output Schema:
    assignees: Array<{dart_id, name, email, role}>
    dartboards: Array<{dart_id, name, description}>
    statuses: Array<{dart_id, name, color, order}>
    tags: Array<{dart_id, name, color}>
    priorities: Array<{value: 1-5, label}>
    sizes: Array<{value: 1-5, label}>
    folders: Array<{dart_id, name, space_id}>
    cached_at: iso8601 timestamp
    cache_ttl_seconds: integer
  
  Use Cases:
    - Get valid dartboard_ids before creating tasks
    - Validate assignee emails before CSV import
    - Resolve status names to dart_ids
  
  Examples:
    get_config()
      → Full workspace configuration (cached for 5 minutes)
  
    get_config(include=['dartboards', 'assignees'])
      → Only dartboards and assignees (token-efficient)
  
    get_config(cache_bust=true)
      → Force refresh cached config
  
  Token Budget: ~400 tokens
  Performance: Fast (cached) / Medium (API call)`,
  
      execute_dartql: `Tool: execute_dartql
  Description: Execute DartQL UPDATE/DELETE statements with template vars, array literals, and multi-statement support
  
  Input Schema:
    query: string (required)
      One or more DartQL statements separated by semicolons
  
    dry_run?: boolean (default: true)
      Preview matching tasks without executing (RECOMMENDED for first run)
  
    concurrency?: integer (default: 5)
      Max concurrent API calls per statement (1-20)
  
  Statement Syntax:
    UPDATE WHERE <expression> SET <field> = <value> [, ...] [COMMENT '<template>']
    DELETE WHERE <expression> [CONFIRM]
  
    Values: strings ('text'), numbers (42), NULL, arrays (['a', 'b'])
    Template vars: {field} in strings resolves to pre-update task values
  
  Examples:
    -- Set blocker relationships
    UPDATE WHERE dart_id = 'abc' SET blocker_ids = ['id1', 'id2']
  
    -- Batch status change with comment
    UPDATE WHERE status = 'Todo' SET status = 'Done' COMMENT 'Closed: {title}'
  
    -- Multi-statement
    UPDATE WHERE priority = 1 SET priority = 2;
    DELETE WHERE status = 'Archived' AND completed_at < '2025-01-01' CONFIRM
  
  Safety:
    - dry_run=true (default): preview only
    - DELETE requires CONFIRM keyword when dry_run=false
    - WHERE is mandatory (no accidental "update all")
  
  Output Schema:
    batch_operation_id: string
    dry_run: boolean
    statements: Array<StatementResult>
    total_matched, total_succeeded, total_failed: integer
    execution_time_ms: integer
  
  Token Budget: ~400 tokens
  Performance: Slow (depends on match count)`,
  
      batch_update_tasks: `Tool: batch_update_tasks [DEPRECATED: use execute_dartql instead]
  Description: Update multiple tasks matching a DartQL selector expression (SQL-like WHERE syntax)
  
  Input Schema:
    selector: string (required)
      DartQL WHERE clause (e.g., "status = 'Todo' AND priority >= 3")
  
    updates: object (required)
      Fields to update on all matching tasks
      Properties: status, priority, size, assignees, tags, due_at, start_at
  
    dry_run?: boolean (default: false)
      Preview matching tasks without updating (RECOMMENDED for first run)
  
    concurrency?: integer (default: 5)
      Max concurrent API calls (1-20)
  
  Output Schema:
    batch_operation_id: string
    selector_matched: integer (total tasks matching selector)
    dry_run: boolean
    preview_tasks?: Array<{dart_id, title, current_values}> (if dry_run=true)
    successful_updates: integer
    failed_updates: integer
    successful_dart_ids: string[]
    failed_items: Array<{dart_id, error, reason}>
    execution_time_ms: integer
  
  DartQL Syntax Guide (SQL-92 WHERE clause syntax):
    Operators: =, !=, <>, >, >=, <, <=, IN, NOT IN, LIKE, CONTAINS, IS NULL, IS NOT NULL, BETWEEN
    Logical: AND, OR, NOT
    Grouping: Use parentheses for precedence
    Aliases: INCLUDES/HAS → CONTAINS
    LIKE wildcards: % = any chars, _ = single char (case-insensitive)
  
    Examples:
      "status = 'Todo'"
      "priority >= 3 AND assignee = 'duid_user1'"
      "title LIKE 'Task%'"                           -- starts with
      "title LIKE '%bug%'"                            -- contains substring
      "tags CONTAINS 'urgent' AND due_at < '2026-02-01'"
      "(status = 'Todo' OR status = 'In Progress') AND NOT (priority = 1)"
  
  Workflow:
    1. batch_update_tasks(selector="...", updates={...}, dry_run=true)
       → Preview matching tasks
  
    2. Review preview, confirm selector is correct
  
    3. batch_update_tasks(selector="...", updates={...}, dry_run=false)
       → Execute update
  
  Token Budget: ~400 tokens
  Performance: Slow (depends on match count)`,
  
      import_tasks_csv: `Tool: import_tasks_csv
  Description: Bulk-create tasks from CSV data with validation and error recovery
  
  Input Schema:
    csv_data?: string
      Inline CSV content (first row must be headers)
  
    csv_file_path?: string
      Path to CSV file (alternative to csv_data)
  
    dartboard: string (required)
      Default dartboard dart_id (can be overridden per-row via 'dartboard' column)
  
    column_mapping?: object
      Custom column name mappings (e.g., {'Task Name': 'title', 'Assigned To': 'assignee'})
  
    validate_only?: boolean (default: false)
      Validate and preview without creating tasks (RECOMMENDED for first run)
  
    continue_on_error?: boolean (default: true)
      Continue processing if individual rows fail
  
    concurrency?: integer (default: 5)
      Max concurrent task creation calls
  
  CSV Format Guide:
    Required Columns:
      title - Task title (required)
  
    Optional Columns:
      description, status, priority, size, assignee, dartboard, tags, due_date, start_date, parent_task
  
    Flexible Column Names (case-insensitive):
      'Title' = 'title' = 'Task Name'
      'Assigned To' = 'assignee' = 'Owner'
      'Tags' = 'labels' (comma-separated)
  
  CSV Example:
    title,description,assignee,priority,tags,due_date
    "Fix login bug","Users can't login",engineer@company.com,5,"bug,urgent",2026-02-01
    "Update docs","API documentation",writer@company.com,2,documentation,2026-02-15
  
  Workflow:
    1. get_config() → Get dartboard_ids for reference resolution
  
    2. import_tasks_csv(csv_file_path='tasks.csv', dartboard='duid_board1', validate_only=true)
       → Validation errors, preview
  
    3. Fix CSV errors if any
  
    4. import_tasks_csv(csv_file_path='tasks.csv', dartboard='duid_board1', validate_only=false)
       → Execute import
  
  Token Budget: ~500 tokens
  Performance: Slow (depends on row count)`,
  
      relationships: `Topic: Task Relationships
  Description: Dart supports six relationship types to model task dependencies and connections
  
  Relationship Types:
    parent_task / subtask_ids
      Hierarchical parent-child relationships for breaking work into subtasks.
      A task can have one parent and multiple subtasks.
  
    blocker_ids / blocking_ids
      Dependency relationships where one task blocks another.
      blocker_ids: Tasks that must complete before this task can start.
      blocking_ids: Tasks that this task is blocking.
  
    duplicate_ids
      Links tasks that represent the same work (usually to consolidate).
      Bidirectional - marking A as duplicate of B links both.
  
    related_ids
      General-purpose links between related tasks.
      Use for reference without implying dependency or hierarchy.
  
  Creating Tasks with Relationships:
    create_task(
      title="Implement login",
      subtask_ids=["duid_task2", "duid_task3"],
      blocker_ids=["duid_task1"]
    )
  
  Updating Relationships:
    update_task(
      dart_id="duid_task1",
      subtask_ids=["duid_new1", "duid_new2"],  // Replaces existing
      related_ids=[]  // Clears all related tasks
    )
    Note: Relationship updates use full replacement, not append.
  
  Querying Relationships:
    get_task(dart_id="duid_task1", expand_relationships=true)
      → Includes relationship_counts and expanded relationship details
  
    list_tasks(has_parent=true)
      → Filter to subtasks only (tasks with a parent)
  
    list_tasks(has_parent=false)
      → Filter to root tasks only (tasks without a parent)
  
  API Limitation:
    The list_tasks endpoint only supports has_parent filter because the Dart
    API returns parent_task in list responses but does NOT return relationship
    arrays (subtask_ids, blocker_ids, etc.). To find tasks with relationships,
    use get_task() on individual tasks or filter by parent_task in DartQL.
  
  Relationship Filters (list_tasks):
    has_parent: boolean - Tasks with/without a parent task (SUPPORTED)
  
    Note: Other relationship filters (has_subtasks, has_blockers, is_blocking)
    are NOT available because the list API doesn't return taskRelationships.
  
  DartQL Relationship Queries (batch operations):
    Note: DartQL queries for batch_update_tasks/batch_delete_tasks fetch full
    task data, so relationship fields can be used in WHERE clauses:
  
    "parent_task IS NOT NULL"        - Subtasks (tasks with parent)
    "parent_task IS NULL"            - Root tasks (no parent)
  
  CSV Import:
    Relationship columns accept comma-separated dart_ids:
      subtask_ids,blocker_ids
      "duid_a,duid_b","duid_c"
  
  Best Practices:
    - Use expand_relationships=true sparingly (adds API calls)
    - Clear relationships with empty array [], not null
    - Validate dart_ids exist before creating relationships
    - Use get_task() to see full relationship data for a task
  
  Token Budget: ~600 tokens
  Performance: Varies by operation`,
    };
  
    const doc = toolDocs[target];
  
    if (!doc) {
      const availableTools = Object.keys(toolDocs).join(', ');
      return `Error: No documentation for tool "${target}".
  
  Available tools with full documentation: ${availableTools}
  
  For other tools, use: info(level='group', target='...')`;
    }
  
    return doc + "\n\nNext Steps:\n- info(level='overview') - Return to overview";
  }