Ticket Management Tools¶

This document provides comprehensive documentation for all 12 ticket management tools available in the Gira MCP server. These tools provide complete lifecycle management for tickets, from creation to archival.

🎫 Tool Overview¶

Tool	Description	Category
list_tickets	List tickets with optional filtering	Query
get_ticket	Get detailed information about a specific ticket	Query
create_ticket	Create a new ticket	Create
update_ticket	Update an existing ticket's fields	Update
move_ticket	Move a ticket to a different status/swimlane	Update
assign_ticket	Assign a ticket to someone	Update
add_comment	Add a comment to a ticket	Comments
list_comments	List comments for a ticket	Comments
search_tickets	Search tickets using full-text search	Advanced Query
filter_tickets	Advanced filtering with multiple criteria	Advanced Query
get_board_state	Get current board state visualization	Board
bulk_update	Update multiple tickets with the same changes	Bulk Operations
archive_tickets	Archive completed tickets	Archive

📋 Query Tools¶

list_tickets¶

List tickets with optional filtering capabilities.

Parameters: - status (string, optional): Filter by status (todo, in_progress, review, done) - assignee (string, optional): Filter by assignee email or name - priority (string, optional): Filter by priority (low, medium, high, critical) - type (string, optional): Filter by type (task, bug, feature, epic, subtask) - epic (string, optional): Filter by epic ID - labels (array[string], optional): Filter by labels (must contain all specified) - limit (integer, optional): Maximum tickets to return (1-1000)

Returns: Array of ticket summaries containing: - id: Ticket identifier (e.g., GCM-123) - title: Ticket title - status: Current status - priority: Priority level - type: Ticket type - assignee: Assigned person (if any) - epic_id: Associated epic (if any) - labels: List of labels - created_at: Creation timestamp - updated_at: Last update timestamp

Examples:

// List all open tickets
{"status": "todo"}

// List high priority bugs
{"type": "bug", "priority": "high"}

// List tickets assigned to a specific person
{"assignee": "john@example.com", "limit": 20}

// List tickets in a specific epic
{"epic": "EPIC-001"}

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

get_ticket¶

Get detailed information about a specific ticket.

Parameters: - ticket_id (string, required): Ticket ID to retrieve

Returns: Detailed ticket object containing: - id: Ticket identifier - title: Ticket title
- description: Full description - status: Current status - priority: Priority level - type: Ticket type - reporter: Person who created the ticket - assignee: Assigned person (if any) - epic_id: Associated epic (if any) - parent_id: Parent ticket for subtasks (if any) - labels: List of labels - story_points: Estimation (if set) - custom_fields: Additional custom data - created_at: Creation timestamp - updated_at: Last update timestamp

Examples:

// Get ticket details
{"ticket_id": "GCM-123"}

// ID normalization is automatic
{"ticket_id": "123"}  // Becomes GCM-123
{"ticket_id": "gcm-123"}  // Becomes GCM-123

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

Security: Read-only operation, no rate limiting.

✨ Creation Tools¶

create_ticket¶

Create a new ticket with full metadata support.

Parameters: - title (string, required): Ticket title (1-200 characters) - description (string, optional): Detailed description - priority (string, optional): Priority level, default: "medium" - type (string, optional): Ticket type, default: "task" - assignee (string, optional): Assignee email or name - epic (string, optional): Epic ID to associate with - parent (string, optional): Parent ticket ID for subtasks - labels (array[string], optional): List of labels - story_points (integer, optional): Story points estimate (0-100) - status (string, optional): Initial status (uses project default if not specified) - custom_fields (object, optional): Custom field values

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

Examples:

// Basic ticket creation
{
  "title": "Fix login bug",
  "type": "bug",
  "priority": "high"
}

// Feature with epic and estimation
{
  "title": "Add user dashboard",
  "description": "Create a personalized dashboard for users",
  "type": "feature",
  "epic": "EPIC-001",
  "story_points": 8,
  "labels": ["frontend", "dashboard"]
}

// Subtask creation
{
  "title": "Write unit tests",
  "parent": "GCM-123",
  "type": "subtask",
  "assignee": "developer@example.com"
}

Validation: - Title must be 1-200 characters - Priority must be valid (low, medium, high, critical) - Type must be valid (task, bug, feature, epic, subtask) - Story points must be 0-100 - Epic and parent IDs are validated if provided

Security: Requires confirmation if configured, audit logged.

🔄 Update Tools¶

update_ticket¶

Update an existing ticket's fields.

Parameters: - ticket_id (string, required): Ticket ID to update - title (string, optional): New title - description (string, optional): New description - priority (string, optional): New priority - type (string, optional): New type - assignee (string, optional): New assignee - epic (string, optional): New epic association - parent (string, optional): New parent ticket - labels (array[string], optional): Replace labels - story_points (integer, optional): New story points - custom_fields (object, optional): Update custom fields

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

Examples:

// Update priority and assignee
{
  "ticket_id": "GCM-123",
  "priority": "critical",
  "assignee": "jane@example.com"
}

// Add story points and labels
{
  "ticket_id": "GCM-456", 
  "story_points": 5,
  "labels": ["backend", "api", "high-priority"]
}

// Move to different epic
{
  "ticket_id": "GCM-789",
  "epic": "EPIC-002"
}

Security: Requires confirmation if configured, audit logged.

move_ticket¶

Move a ticket to a different status/swimlane.

Parameters: - ticket_id (string, required): Ticket ID to move - target_status (string, required): Target status - comment (string, optional): Comment about the move

Returns: - success: True if moved successfully - old_status: Previous status - new_status: New status - ticket: Updated ticket details

Examples:

// Move ticket to in progress
{
  "ticket_id": "GCM-123",
  "target_status": "in_progress",
  "comment": "Starting work on this"
}

// Complete a ticket
{
  "ticket_id": "GCM-456",
  "target_status": "done"
}

Validation: - Target status must be valid for the project - Validates ticket exists and is moveable

Security: Audit logged, comment auto-generated if not provided.

assign_ticket¶

Assign a ticket to someone.

Parameters: - ticket_id (string, required): Ticket ID to assign - assignee (string, required): Assignee email or name - comment (string, optional): Comment about the assignment

Returns: - success: True if assigned successfully - old_assignee: Previous assignee (if any) - new_assignee: New assignee - ticket: Updated ticket details

Examples:

// Assign to team member
{
  "ticket_id": "GCM-123",
  "assignee": "developer@example.com",
  "comment": "Best person for this task"
}

// Unassign ticket  
{
  "ticket_id": "GCM-456",
  "assignee": "",
  "comment": "Putting back in pool"
}

Security: Audit logged, validates assignee exists.

💬 Comment Tools¶

add_comment¶

Add a comment to a ticket.

Parameters: - ticket_id (string, required): Ticket ID to comment on - content (string, required): Comment content - author (string, optional): Comment author (defaults to system user)

Returns: - success: True if comment added - comment_id: ID of the new comment - comment: Full comment details

Examples:

// Add progress update
{
  "ticket_id": "GCM-123",
  "content": "Updated the user interface as requested"
}

// Add comment with specific author
{
  "ticket_id": "GCM-456", 
  "content": "Needs more testing before release",
  "author": "qa@example.com"
}

Security: Audit logged, content length limited.

list_comments¶

List comments for a ticket.

Parameters: - ticket_id (string, required): Ticket ID to get comments for - limit (integer, optional): Maximum comments to return

Returns: Array of comments containing: - id: Comment ID - content: Comment text - author: Comment author - created_at: Creation timestamp - ticket_id: Associated ticket ID

Examples:

// Get all comments
{"ticket_id": "GCM-123"}

// Get recent comments
{"ticket_id": "GCM-123", "limit": 5}

Security: Read-only operation.

🔍 Advanced Query Tools¶

search_tickets¶

Search tickets using full-text search across titles, descriptions, and comments.

Parameters: - query (string, required): Search query - status (string, optional): Limit to specific status - type (string, optional): Limit to specific type - limit (integer, optional): Maximum results (default: 50)

Returns: Array of matching tickets with relevance scores: - Standard ticket summary fields - relevance_score: Search relevance (0-1) - matched_fields: Which fields matched the query

Examples:

// Search for bug tickets
{
  "query": "login error authentication",
  "type": "bug"
}

// Search in specific status
{
  "query": "dashboard feature",
  "status": "in_progress",
  "limit": 10
}

Security: Read-only operation, rate limited.

filter_tickets¶

Advanced filtering of tickets with multiple criteria and sorting.

Parameters: - filters (object, required): Complex filter criteria - sort_by (string, optional): Sort field - sort_order (string, optional): asc or desc - limit (integer, optional): Maximum results

Returns: Array of filtered tickets with metadata: - Filtered ticket summaries - total_count: Total matching tickets - filters_applied: Summary of applied filters

Examples:

// Complex filtering
{
  "filters": {
    "priority": ["high", "critical"],
    "assignee": "team@example.com",
    "created_after": "2024-01-01",
    "labels_any": ["urgent", "customer-facing"]
  },
  "sort_by": "updated_at",
  "sort_order": "desc"
}

Security: Read-only operation, complex filters may be rate limited.

📊 Board Tools¶

get_board_state¶

Get current board state visualization with ticket counts and summaries.

Parameters: - include_tickets (boolean, optional): Include full ticket details - status_filter (array[string], optional): Limit to specific statuses

Returns: Board state object containing: - columns: Board columns with ticket counts - tickets: Tickets organized by status (if requested) - summary: Overall board statistics - timestamp: State capture time

Examples:

// Basic board state
{}

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

// Limited to active work
{"status_filter": ["todo", "in_progress", "review"]}

Security: Read-only operation.

🔧 Bulk Operations¶

bulk_update¶

Update multiple tickets with the same changes efficiently.

Parameters: - ticket_ids (array[string], required): List of ticket IDs to update - updates (object, required): Fields to update on all tickets - comment (string, optional): Comment to add to all tickets

Returns: - success: True if operation completed - updated_count: Number of tickets successfully updated - failed_tickets: List of tickets that couldn't be updated - updated_tickets: List of successfully updated ticket summaries

Examples:

// Bulk priority update
{
  "ticket_ids": ["GCM-123", "GCM-456", "GCM-789"],
  "updates": {
    "priority": "high"
  },
  "comment": "Escalated due to customer impact"
}

// Bulk epic assignment
{
  "ticket_ids": ["GCM-100", "GCM-101", "GCM-102"],
  "updates": {
    "epic": "EPIC-001",
    "labels": ["q4-release"]
  }
}

Security: High-impact operation, requires confirmation, heavily audit logged.

📦 Archive Tools¶

archive_tickets¶

Archive completed tickets to clean up the active board.

Parameters: - criteria (object, optional): Criteria for auto-archiving - ticket_ids (array[string], optional): Specific tickets to archive - dry_run (boolean, optional): Preview what would be archived

Returns: - success: True if archiving completed - archived_count: Number of tickets archived - archived_tickets: List of archived ticket summaries - skipped_tickets: Tickets that couldn't be archived

Examples:

// Archive all done tickets older than 30 days
{
  "criteria": {
    "status": "done",
    "completed_before": "2024-01-01"
  }
}

// Archive specific tickets
{
  "ticket_ids": ["GCM-123", "GCM-456"]
}

// Preview archiving
{
  "criteria": {"status": "done"},
  "dry_run": true
}

Security: Destructive operation, requires confirmation, heavily audit logged.

🔒 Security & Best Practices¶

Rate Limiting¶

list_tickets: 50 calls/minute
search_tickets: 20 calls/minute
filter_tickets: 10 calls/minute
bulk_update: 5 calls/minute
archive_tickets: 2 calls/minute

Confirmation Requirements¶

These operations require confirmation when require_confirmation=true: - create_ticket - update_ticket - move_ticket - assign_ticket - bulk_update - archive_tickets

Audit Logging¶

All operations are logged with: - Timestamp - Operation name - Parameters (if verbose logging enabled) - Success/failure status - User context

Input Validation¶

All ticket IDs are normalized (GCM- prefix added if missing)
String lengths are enforced
Enum values are validated
Required fields are checked

Error Handling¶

Common error scenarios: - NotFoundError: Ticket doesn't exist - ValidationError: Invalid parameters - MCPToolError: General operation failures - PermissionError: Security restrictions

For board visualization tools, see Board Tools. For epic management, see Epic Tools. For sprint planning, see Sprint Tools.