Skip to content

Board & Visualization Tools

This document provides comprehensive documentation for all 3 board visualization tools available in the Gira MCP server. These tools provide enhanced board views, swimlane organization, and bulk operations for efficient project management and visualization.

📊 Tool Overview

Tool Description Category
get_enhanced_board_state Get comprehensive board view with analytics Visualization
get_swimlane_tickets Get tickets organized by epic or assignee Organization
move_tickets_bulk Move multiple tickets between statuses efficiently Bulk Operations

🎯 Visualization Tools

get_enhanced_board_state

Get a comprehensive board view with epic context, sprint information, and progress analytics.

Parameters: - include_tickets (boolean, optional): Include full ticket details in each column, default: false - include_epic_context (boolean, optional): Include epic information for tickets, default: false - include_sprint_context (boolean, optional): Include sprint information for tickets, default: false - status_filter (array[string], optional): Limit to specific statuses - assignee_filter (string, optional): Filter by assignee - epic_filter (string, optional): Filter by epic ID

Returns: Enhanced board state object containing: - board: Object with status columns and ticket counts - summary: Overall board statistics - epics: Epic context information (if requested) - sprints: Sprint context information (if requested) - filters_applied: Summary of applied filters - timestamp: State capture timestamp

Board Object Structure: 

{
  "backlog": {
    "count": 15,
    "tickets": [...] // If include_tickets=true
  },
  "todo": {
    "count": 8,
    "tickets": [...]
  },
  "in_progress": {
    "count": 5,
    "tickets": [...]
  },
  "review": {
    "count": 3,
    "tickets": [...]
  },
  "done": {
    "count": 12,
    "tickets": [...]
  }
}

Summary Object Structure: 

{
  "total_tickets": 43,
  "completed_tickets": 12,
  "in_progress_tickets": 5,
  "completion_percentage": 27.9,
  "active_epics": 3,
  "active_sprints": 1,
  "unassigned_tickets": 7
}

Examples: 

// Basic board state
{}

// Board with full ticket details
{"include_tickets": true}

// Board with epic and sprint context
{
  "include_tickets": true,
  "include_epic_context": true,
  "include_sprint_context": true
}

// Filtered board view
{
  "status_filter": ["todo", "in_progress", "review"],
  "epic_filter": "EPIC-001"
}

// Team-specific board
{
  "assignee_filter": "backend-team@example.com",
  "include_tickets": true
}

Epic Context (when included): 

{
  "epics": {
    "EPIC-001": {
      "title": "User Authentication",
      "status": "active",
      "progress_percentage": 65,
      "total_tickets": 8,
      "completed_tickets": 5
    }
  }
}

Sprint Context (when included): 

{
  "sprints": {
    "SPRINT-2024-01-15": {
      "name": "Q1 Sprint 3",
      "status": "active",
      "progress_percentage": 72,
      "total_tickets": 12,
      "completed_tickets": 9,
      "days_remaining": 3
    }
  }
}

Security: Read-only operation, rate limited to 60 calls per minute.

🏊‍♂️ Organization Tools

get_swimlane_tickets

Get tickets organized by epic or assignee with grouping and filtering capabilities.

Parameters: - status (string, required): Status/swimlane to get tickets from - group_by_epic (boolean, optional): Group tickets by epic, default: false - group_by_assignee (boolean, optional): Group tickets by assignee, default: false - include_no_epic (boolean, optional): Include tickets without epics, default: true - include_unassigned (boolean, optional): Include unassigned tickets, default: true - limit (integer, optional): Maximum tickets to return per group

Returns: Object containing organized ticket data: - status: The requested status - grouped_by_epic: Boolean indicating epic grouping - grouped_by_assignee: Boolean indicating assignee grouping - total_count: Total number of tickets - epic_groups or assignee_groups: Grouped ticket data - tickets: Flat ticket list (if no grouping)

Epic Grouping Structure: 

{
  "epic_groups": [
    {
      "epic_info": {
        "id": "EPIC-001",
        "title": "User Authentication",
        "status": "active"
      },
      "tickets": [
        {
          "id": "GCM-123",
          "title": "Login form validation",
          "priority": "high",
          "assignee": "dev@example.com"
        }
      ]
    },
    {
      "epic_info": {
        "id": null,
        "title": "No Epic",
        "status": null
      },
      "tickets": [...]
    }
  ]
}

Assignee Grouping Structure: 

{
  "assignee_groups": [
    {
      "assignee_info": {
        "name": "John Developer",
        "email": "john@example.com",
        "ticket_count": 5
      },
      "tickets": [...]
    },
    {
      "assignee_info": {
        "name": "Unassigned",
        "email": null,
        "ticket_count": 3
      },
      "tickets": [...]
    }
  ]
}

Examples: 

// Get todo tickets grouped by epic
{
  "status": "todo",
  "group_by_epic": true
}

// Get in-progress tickets grouped by assignee
{
  "status": "in_progress",
  "group_by_assignee": true
}

// Get review tickets with limited results per group
{
  "status": "review",
  "group_by_epic": true,
  "limit": 10
}

// Get done tickets without grouping
{
  "status": "done",
  "limit": 20
}

// Exclude tickets without epics
{
  "status": "todo",
  "group_by_epic": true,
  "include_no_epic": false
}

Security: Read-only operation, rate limited to 40 calls per minute.

🚀 Bulk Operations

move_tickets_bulk

Move multiple tickets between statuses/swimlanes efficiently with automatic comment generation.

Parameters: - ticket_ids (array[string], required): List of ticket IDs to move - target_status (string, required): Target status for all tickets - comment (string, optional): Comment to add to all moved tickets

Returns: Bulk operation results: - success: True if operation completed - target_status: The target status - comment: Comment added (auto-generated if not provided) - total_processed: Total number of tickets processed - successful_updates: Number of successfully moved tickets - already_in_status: Tickets already in target status - not_found: Tickets that couldn't be found - updated_tickets: List of successfully updated ticket summaries

Examples: 

// Move multiple tickets to done
{
  "ticket_ids": ["GCM-123", "GCM-456", "GCM-789"],
  "target_status": "done",
  "comment": "Completed during sprint review"
}

// Bulk move to in_progress
{
  "ticket_ids": ["GCM-100", "GCM-101", "GCM-102"],
  "target_status": "in_progress"
}

// Move tickets back to todo (rollback)
{
  "ticket_ids": ["GCM-200", "GCM-201"],
  "target_status": "todo",
  "comment": "Rolling back due to blocking dependencies"
}

// Large batch operation
{
  "ticket_ids": [
    "GCM-301", "GCM-302", "GCM-303", "GCM-304", "GCM-305",
    "GCM-306", "GCM-307", "GCM-308", "GCM-309", "GCM-310"
  ],
  "target_status": "review",
  "comment": "Ready for QA review"
}

Response Example: 

{
  "success": true,
  "target_status": "done",
  "comment": "Completed during sprint review",
  "total_processed": 3,
  "successful_updates": 2,
  "already_in_status": ["GCM-456"],
  "not_found": [],
  "updated_tickets": [
    {
      "id": "GCM-123",
      "title": "Fix login bug",
      "old_status": "in_progress",
      "new_status": "done"
    },
    {
      "id": "GCM-789", 
      "title": "Update documentation",
      "old_status": "review",
      "new_status": "done"
    }
  ]
}

Validation: - All ticket IDs are normalized (GCM- prefix added if missing) - Target status must be valid for the project - Maximum of 50 tickets per bulk operation - Validates that target status transitions are allowed

Security: High-impact operation, requires confirmation, heavily audit logged, rate limited to 10 calls per minute.

📊 Board Analytics & Insights

Visual Board Metrics

Column Distribution: - Ticket counts per status - Story points per column - Age distribution (how long tickets have been in each status) - Priority distribution across columns

Flow Metrics: - Lead Time: Time from creation to completion - Cycle Time: Time from start to completion - Throughput: Tickets completed per time period - Work in Progress (WIP): Active tickets count

Bottleneck Analysis: - Columns with highest ticket age - Statuses with lowest throughput - Blockers and impediments - Capacity constraints

Epic Visualization

Epic Progress on Board: - Epic completion percentage - Tickets distribution across statuses per epic - Epic timeline alignment - Cross-epic dependencies

Epic Swimlanes: - Organize board by epic - Show epic progress within each status - Identify epic-specific bottlenecks - Track epic delivery timelines

Team Performance

Assignee Distribution: - Workload balance across team members - Individual completion rates - Collaboration patterns - Capacity utilization

Team Flow: - Collective throughput - Handoff efficiency between team members - Pair programming indicators - Knowledge sharing patterns

🔍 Advanced Board Queries

Custom Board Views

// Executive dashboard view
{
  "include_epic_context": true,
  "include_sprint_context": true,
  "status_filter": ["in_progress", "review", "done"]
}

// Development team view
{
  "include_tickets": true,
  "assignee_filter": "dev-team@example.com",
  "include_epic_context": true
}

// Quality assurance view
{
  "status_filter": ["review"],
  "include_tickets": true,
  "group_by_epic": true
}

Swimlane Organization

// Epic-based planning view
{
  "status": "todo",
  "group_by_epic": true,
  "include_no_epic": true
}

// Team capacity view
{
  "status": "in_progress", 
  "group_by_assignee": true
}

// Release planning view
{
  "status": "done",
  "group_by_epic": true,
  "limit": 50
}

Bulk Board Operations

// Sprint completion ceremony
{
  "ticket_ids": ["GCM-sprint-tickets..."],
  "target_status": "done",
  "comment": "Sprint 15 completion"
}

// Emergency rollback
{
  "ticket_ids": ["GCM-problematic-tickets..."],
  "target_status": "todo",
  "comment": "Rolling back due to deployment issues"
}

🔒 Security & Best Practices

Rate Limiting

  • get_enhanced_board_state: 60 calls/minute
  • get_swimlane_tickets: 40 calls/minute
  • move_tickets_bulk: 10 calls/minute (high-impact operation)

Confirmation Requirements

These operations require confirmation when require_confirmation=true: - move_tickets_bulk (always, due to bulk nature)

Audit Logging

All board operations are logged with: - Timestamp - Operation name - Parameters and filters applied - Number of tickets affected - Success/failure status - Performance metrics

Input Validation

  • Ticket IDs are normalized and validated
  • Status values are validated against project configuration
  • Bulk operation limits are enforced (max 50 tickets)
  • Filter parameters are sanitized

Error Handling

Common error scenarios: - ValidationError: Invalid status or parameters - NotFoundError: Tickets don't exist - BulkOperationError: Partial failure in bulk operations - RateLimitError: Too many requests - CapacityError: Bulk operation too large

🎨 Board Customization

Status Configuration

Board tools work with any project status configuration: - Default Statuses: backlog, todo, in_progress, review, done - Custom Statuses: Any project-defined status values - Status Transitions: Respects project workflow rules - Status Metadata: Includes status descriptions and colors

Filtering and Views

  • Multi-dimensional Filtering: Status, assignee, epic, priority
  • Temporal Filtering: Date ranges, age-based filters
  • Custom Views: Save frequently used filter combinations
  • Real-time Updates: Fresh data on each request

Integration Patterns

  • Dashboard Integration: Embed board state in dashboards
  • Notification Systems: Alert on board state changes
  • Automation Triggers: React to board state patterns
  • Reporting Systems: Historical board state analysis

📈 Board Performance Optimization

Efficient Data Loading

  • Lazy Loading: Include detailed data only when needed
  • Filtered Queries: Request only relevant tickets
  • Pagination: Use limits for large datasets
  • Caching Strategy: Cache board state for brief periods

Bulk Operation Best Practices

  • Batch Size: Keep bulk operations under 50 tickets
  • Progress Tracking: Monitor bulk operation results
  • Error Recovery: Handle partial failures gracefully
  • Audit Trail: Maintain detailed logs for bulk changes

Visualization Performance

  • Progressive Enhancement: Start with basic views, add details
  • Context Loading: Load epic/sprint context only when needed
  • Responsive Design: Adapt to different screen sizes
  • Accessibility: Support screen readers and keyboard navigation

For individual ticket operations, see Ticket Tools. For epic-based organization, see Epic Tools. For sprint-based planning, see Sprint Tools.