Epic Management Tools¶

This document provides comprehensive documentation for all 7 epic management tools available in the Gira MCP server. These tools enable you to organize work into larger initiatives, track progress across multiple tickets, and manage strategic objectives.

🎯 Tool Overview¶

Tool	Description	Category
list_epics	List epics with optional filtering	Query
get_epic	Get detailed information about a specific epic	Query
create_epic	Create a new epic	Create
update_epic	Update an existing epic	Update
add_tickets_to_epic	Add tickets to an epic	Association
remove_tickets_from_epic	Remove tickets from an epic	Association
get_epic_tickets	Get all tickets in an epic	Query

📋 Query Tools¶

list_epics¶

List epics with optional filtering capabilities.

Parameters: - status (string, optional): Filter by status (draft, active, completed, archived) - owner (string, optional): Filter by epic owner email or name - label (string, optional): Filter by label - limit (integer, optional): Maximum epics to return (1-100)

Returns: Array of epic summaries containing: - id: Epic identifier (e.g., EPIC-001) - title: Epic title - status: Current status - owner: Epic owner - description: Brief description - labels: List of labels - ticket_count: Number of associated tickets - completed_tickets: Number of completed tickets - progress_percentage: Completion percentage (0-100) - start_date: Epic start date (if set) - target_date: Target completion date (if set) - created_at: Creation timestamp - updated_at: Last update timestamp

Examples:

// List all active epics
{"status": "active"}

// List epics owned by specific person
{"owner": "product@example.com"}

// List epics with specific label
{"label": "q4-initiative"}

// Get recent epics
{"limit": 10}

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

get_epic¶

Get detailed information about a specific epic.

Parameters: - epic_id (string, required): Epic ID to retrieve

Returns: Detailed epic object containing: - id: Epic identifier - title: Epic title - description: Full description - status: Current status - owner: Epic owner - labels: List of labels - start_date: Epic start date - target_date: Target completion date - actual_completion_date: Actual completion date (if completed) - ticket_count: Total associated tickets - completed_tickets: Completed tickets count - in_progress_tickets: In-progress tickets count - todo_tickets: Todo tickets count - progress_percentage: Completion percentage - estimated_story_points: Total estimated story points - completed_story_points: Completed story points - custom_fields: Additional custom data - created_at: Creation timestamp - updated_at: Last update timestamp

Examples:

// Get epic details
{"epic_id": "EPIC-001"}

// ID normalization is automatic
{"epic_id": "1"}  // Becomes EPIC-001
{"epic_id": "epic-001"}  // Becomes EPIC-001

Error Handling: - Returns error if epic not found - Validates epic ID format

Security: Read-only operation, no rate limiting.

get_epic_tickets¶

Get all tickets associated with an epic.

Parameters: - epic_id (string, required): Epic ID to get tickets for - status (string, optional): Filter tickets by status - include_subtasks (boolean, optional): Include subtasks, default: true - limit (integer, optional): Maximum tickets to return

Returns: Object containing: - epic: Epic summary information - tickets: Array of associated tickets - total_count: Total number of tickets - status_breakdown: Count of tickets by status - progress_summary: Progress statistics

Examples:

// Get all tickets in epic
{"epic_id": "EPIC-001"}

// Get only in-progress tickets
{"epic_id": "EPIC-001", "status": "in_progress"}

// Get tickets without subtasks
{"epic_id": "EPIC-001", "include_subtasks": false}

Security: Read-only operation.

✨ Creation Tools¶

create_epic¶

Create a new epic for organizing work initiatives.

Parameters: - title (string, required): Epic title (1-200 characters) - description (string, optional): Detailed description - owner (string, optional): Epic owner email or name - status (string, optional): Initial status, default: "draft" - labels (array[string], optional): List of labels - start_date (string, optional): Epic start date (YYYY-MM-DD) - target_date (string, optional): Target completion date (YYYY-MM-DD) - custom_fields (object, optional): Custom field values

Returns: Created epic object with: - id: Newly assigned epic ID - success: True if created successfully - epic: Full epic details

Examples:

// Basic epic creation
{
  "title": "User Authentication System",
  "description": "Implement secure user authentication with OAuth2 support",
  "owner": "product@example.com"
}

// Epic with timeline and labels
{
  "title": "Mobile App MVP",
  "description": "Develop minimum viable product for mobile application",
  "owner": "mobile-team@example.com",
  "start_date": "2024-02-01",
  "target_date": "2024-05-01",
  "labels": ["mobile", "mvp", "q2-release"]
}

// Active epic ready for work
{
  "title": "Performance Optimization",
  "status": "active",
  "owner": "backend@example.com",
  "labels": ["performance", "infrastructure"]
}

Validation: - Title must be 1-200 characters - Status must be valid (draft, active, completed, archived) - Dates must be in YYYY-MM-DD format - Owner is validated if provided

Security: Requires confirmation if configured, audit logged.

🔄 Update Tools¶

update_epic¶

Update an existing epic's fields.

Parameters: - epic_id (string, required): Epic ID to update - title (string, optional): New title - description (string, optional): New description - owner (string, optional): New owner - status (string, optional): New status - labels (array[string], optional): Replace labels - start_date (string, optional): New start date - target_date (string, optional): New target date - custom_fields (object, optional): Update custom fields

Returns: - success: True if updated successfully - updated_fields: List of fields that were changed - epic: Updated epic details

Examples:

// Update status and owner
{
  "epic_id": "EPIC-001",
  "status": "active",
  "owner": "new-owner@example.com"
}

// Update timeline
{
  "epic_id": "EPIC-002",
  "start_date": "2024-03-01", 
  "target_date": "2024-06-30"
}

// Add labels and update description
{
  "epic_id": "EPIC-003",
  "description": "Updated scope to include additional security features",
  "labels": ["security", "compliance", "high-priority"]
}

// Mark epic as completed
{
  "epic_id": "EPIC-004",
  "status": "completed"
}

Security: Requires confirmation if configured, audit logged.

🔗 Association Tools¶

add_tickets_to_epic¶

Add tickets to an epic to organize them under a larger initiative.

Parameters: - epic_id (string, required): Epic ID to add tickets to - ticket_ids (array[string], required): List of ticket IDs to add - comment (string, optional): Comment about the association

Returns: - success: True if tickets were added successfully - added_count: Number of tickets successfully added - already_in_epic: Tickets that were already in the epic - not_found: Tickets that couldn't be found - added_tickets: List of successfully added ticket summaries

Examples:

// Add multiple tickets to epic
{
  "epic_id": "EPIC-001",
  "ticket_ids": ["GCM-123", "GCM-456", "GCM-789"],
  "comment": "Core features for authentication epic"
}

// Add single ticket
{
  "epic_id": "EPIC-002",
  "ticket_ids": ["GCM-999"]
}

Validation: - Epic must exist - Ticket IDs are normalized (GCM- prefix added if missing) - Validates that tickets exist

Security: Audit logged, validates epic and ticket permissions.

remove_tickets_from_epic¶

Remove tickets from an epic.

Parameters: - epic_id (string, required): Epic ID to remove tickets from - ticket_ids (array[string], required): List of ticket IDs to remove - comment (string, optional): Comment about the removal

Returns: - success: True if tickets were removed successfully - removed_count: Number of tickets successfully removed - not_in_epic: Tickets that weren't in the epic - not_found: Tickets that couldn't be found - removed_tickets: List of successfully removed ticket summaries

Examples:

// Remove tickets from epic
{
  "epic_id": "EPIC-001",
  "ticket_ids": ["GCM-123", "GCM-456"],
  "comment": "Moving to different epic"
}

// Remove all tickets from epic (for epic restructuring)
{
  "epic_id": "EPIC-002",
  "ticket_ids": ["GCM-100", "GCM-101", "GCM-102", "GCM-103"]
}

Security: Audit logged, validates epic and ticket permissions.

📊 Epic Lifecycle Management¶

Epic Status Progression¶

Epics typically follow this lifecycle: 1. draft - Initial planning phase 2. active - Work is in progress 3. completed - All work finished 4. archived - Historical reference

Progress Tracking¶

Epic progress is automatically calculated based on associated tickets: - Progress Percentage: (Completed Tickets / Total Tickets) × 100 - Story Points Progress: (Completed Story Points / Total Story Points) × 100 - Status Breakdown: Count of tickets in each status

Best Practices¶

Epic Creation: - Use descriptive, outcome-focused titles - Include clear success criteria in description - Set realistic timelines - Assign a clear owner

Ticket Association: - Group related tickets that contribute to the same outcome - Keep epics focused - avoid making them too broad - Consider breaking large epics into smaller ones

Progress Monitoring: - Regular check-ins on epic progress - Update epic status as work progresses - Use epic queries to track multiple initiatives

🔍 Advanced Epic Queries¶

Complex Epic Filtering¶

// Active epics with progress details
{
  "status": "active",
  "limit": 20
}

// Epics by team ownership
{
  "owner": "backend-team@example.com"
}

// Overdue epics (requires custom implementation)
{
  "status": "active",
  "target_date_before": "2024-01-01"
}

Epic Reporting Patterns¶

// Get epic with full ticket breakdown
{
  "epic_id": "EPIC-001",
  "include_subtasks": true
}

// Track epic velocity
{
  "epic_id": "EPIC-002",
  "status": "in_progress"
}

🔒 Security & Best Practices¶

Rate Limiting¶

list_epics: 30 calls/minute
get_epic: No limit (read-only)
get_epic_tickets: 20 calls/minute
create_epic: 10 calls/minute
update_epic: 20 calls/minute
add_tickets_to_epic: 15 calls/minute
remove_tickets_from_epic: 15 calls/minute

Confirmation Requirements¶

These operations require confirmation when require_confirmation=true: - create_epic - update_epic - add_tickets_to_epic (for bulk operations) - remove_tickets_from_epic (for bulk operations)

Audit Logging¶

All epic operations are logged with: - Timestamp - Operation name - Epic ID and affected tickets - Parameters (if verbose logging enabled) - Success/failure status

Input Validation¶

Epic IDs are normalized (EPIC- prefix added if missing)
String lengths are enforced
Date formats are validated (YYYY-MM-DD)
Enum values are checked

Error Handling¶

Common error scenarios: - NotFoundError: Epic or tickets don't exist - ValidationError: Invalid parameters or dates - MCPToolError: General operation failures - PermissionError: Security restrictions

📈 Epic Analytics¶

Progress Metrics¶

Completion Rate: Percentage of tickets completed
Velocity: Story points completed per time period
Burndown: Remaining work over time
Timeline Tracking: Actual vs. planned progress

Status Distribution¶

Active Work: Tickets in progress
Blocked Items: Tickets that can't proceed
Ready Items: Tickets ready to start
Completed Work: Finished tickets

For ticket management within epics, see Ticket Tools. For sprint planning with epics, see Sprint Tools. For epic visualization, see Board Tools.