ticket-automation-mcp

v1.2.3

Published

17 days ago

MCP server for automated ticket fixing workflow with Jira and Bitbucket integration

0High
0Medium
0Low

vijaynkw

mcp jira bitbucket automation git

Ticket Automation MCP Server

An MCP (Model Context Protocol) server that automates the complete ticket-fixing workflow by orchestrating Jira, Bitbucket, and Git operations.

Overview

This MCP server provides a "fix it" workflow that:

Analyzes Jira tickets - Extracts version, type, components, and root cause
Creates version-aware branches - Automatic branch naming based on ticket version
Automates Git operations - Branch creation, commits, and pushes
Generates PR plans - Properly formatted PRs for Bitbucket
Creates RCA blocks - For Jira ticket updates

Features

✅ Version parsing from tickets (1.4.x, 2.0.1, hotfix-1.3.2, next)
✅ Automatic branch naming (bugfix/PROJ-123-v1.4.2-short-desc)
✅ Conventional commit format
✅ PR description templates
✅ RCA block generation
✅ Dry-run mode for testing
✅ Full workflow automation
🆕 Self-Driven Library Detection - Automatically detects if issue originates from node_modules library
🆕 Smart Routing - Routes fixes to library repo or consumer repo automatically
🆕 Multi-Repo Awareness - Identifies all consumer repos affected by library changes

Prerequisites

Node.js 16+
Git repository configured with Bitbucket remote
Jira and Bitbucket API tokens

📦 Installation

Option 1: Install from npm (Recommended)

npm install -g ticket-automation-mcp

Option 2: Clone and install

cd ticket-automation-mcp
npm install
npm run build

Configuration

Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):

Using npm package (Recommended)

{
  "mcpServers": {
    "ticket-automation": {
      "command": "npx",
      "args": ["ticket-automation-mcp"],
      "disabled": false,
      "env": {
        "JIRA_BASE_URL": "https://jira.company.com",
        "JIRA_API_TOKEN": "your-jira-personal-access-token",
        "BITBUCKET_URL": "https://bitbucket.company.com",
        "BITBUCKET_API_TOKEN": "your-bitbucket-personal-access-token",
        "BITBUCKET_USER_EMAIL": "[email protected]",
        "REPO_SEARCH_PATHS": "/Users/you/Desktop:/Users/you/projects"
      }
    }
  }
}

Required Environment Variables

| Variable | Description | Example | Required | |----------|-------------|---------|----------| | JIRA_BASE_URL | Jira server URL | https://jira.company.com | ✅ | | JIRA_API_TOKEN | Jira Personal Access Token | From your Jira profile settings | ✅ | | BITBUCKET_URL | Bitbucket server URL | https://bitbucket.company.com | ✅ | | BITBUCKET_API_TOKEN | Bitbucket Personal Access Token | From your Bitbucket account settings | ✅ | | BITBUCKET_USER_EMAIL | Your email address | [email protected] | ✅ | | REPO_SEARCH_PATHS | Colon-separated repo search paths | /Users/you/Desktop:/Users/you/projects | ⚠️ (for auto-discovery) |

Available Tools

1. analyze_ticket

Analyze a Jira ticket to extract version, type, and details.

{
  "ticketId": "PROJ-123"
}

2. create_branch_plan

Create version-aware branch plan based on ticket analysis.

{
  "ticketId": "PROJ-123"
}

3. setup_git_branch

Setup git branch - checkout base, pull latest, create working branch.

{
  "ticketId": "PROJ-123",
  "repoPath": "/path/to/repo",
  "remoteUrl": "[email protected]:PROJECT/repo.git",
  "dryRun": false
}

4. format_commit_message

Generate conventional commit message format.

{
  "ticketId": "PROJ-123",
  "summary": "prevent null pointer on login",
  "scope": "auth",
  "type": "fix"
}

5. create_pr_plan

Create pull request plan with title and description.

{
  "ticketId": "PROJ-123",
  "fixSummary": "Fix login null pointer",
  "sourceBranch": "bugfix/PROJ-123-v1.4.2-prevent-null-pointer",
  "destinationBranch": "release/1.4"
}

6. create_pr

Create Pull Request directly in Bitbucket via API.

{
  "projectKey": "PROJECT",
  "repositorySlug": "my-service",
  "sourceBranch": "bugfix/PROJ-123-v1.4.2-prevent-null-pointer",
  "destinationBranch": "release/1.4",
  "title": "[v1.4.2] PROJ-123 Fix login null pointer",
  "description": "## Jira Ticket Reference\nPROJ-123: Fix login null pointer..."
}

7. add_rca_comment

Add RCA (Root Cause Analysis) comment to Jira ticket.

{
  "ticketId": "PROJ-123",
  "fixSummary": "Added null check before accessing user object"
}

8. move_to_code_review

Move Jira ticket to Code Review status.

{
  "ticketId": "PROJ-123",
  "comment": "Pull Request created: https://bitbucket.company.com/..."
}

9. fix_ticket (Complete Workflow)

Full automation: Analyze, branch, commit, create PR, and update Jira.

{
  "ticketId": "PROJ-123",
  "repoPath": "/path/to/repo",
  "remoteUrl": "[email protected]:PROJECT/repo.git",
  "dryRun": false
}

10. detect_library_issue (🆕 Smart Detection)

Analyzes if a ticket issue originates from a library dependency.

{
  "ticketId": "PROJ-123",
  "consumerRepoPath": "/path/to/consumer/repo",
  "searchPaths": ["/Users/you/Desktop"]
}

11. smart_ticket_workflow (🆕 Self-Driven)

Automatically detects library issues and routes fixes to correct repo.

{
  "ticketId": "PROJ-123",
  "consumerRepoPath": "/path/to/consumer/repo",
  "fixSummary": "Fixed DataTable button click handler",
  "dryRun": false
}

Version-Aware Branching Strategy

| Ticket Version | Source Branch | Working Branch Pattern | |----------------|---------------|----------------------| | 1.4.x | release/1.4 | bugfix/PROJ-123-v1.4.x-short-desc | | 2.0.1 | release/2.0 | feature/PROJ-123-v2.0.1-short-desc | | hotfix-1.3.2 | hotfix/1.3.2 | bugfix/PROJ-123-v1.3.2-short-desc | | next | develop | feature/PROJ-123-vnext-short-desc |

Commit Message Format

<type>(<scope>): <ticket-id> [<version>] <summary>

Examples:
fix(auth): PROJ-456 [v1.4.2] prevent null pointer on login
feat(ui): PROJ-789 [v2.0.0] add theme selector

Workflow Steps

When you say "fix it" with a ticket:

Analyze Ticket - Parse version, type, components via Jira API
Branch Strategy - Determine source and working branches
Git Setup - Create branch, checkout, pull latest
Implement Fix - (Manual or automated)
Commit - Format: <type>: <ticket> [<version>] <summary>
Push - Push to origin
Create PR - Create PR in Bitbucket via API
Move to Code Review - Transition Jira ticket via API
Add RCA - Add RCA comment to Jira ticket via API

Usage Examples

Basic Single-Repo Workflow

Start with: "Fix ticket PROJ-123"
MCP will:
- Analyze PROJ-123 via Jira REST API
- Create branch plan (e.g., bugfix/PROJ-123-v1.4.2-null-pointer)
- Setup git branch
- Generate commit message format
- Create PR directly via Bitbucket API
- Move ticket to Code Review via Jira API
- Add RCA comment via Jira API
All done automatically - no manual MCP calls needed!

Smart Library-Aware Workflow (🆕)

Start with: "Fix ticket PROJ-123"
MCP will:
- Analyze PROJ-123 via Jira REST API
- Detect if issue originates from library dependency (e.g., @qualys/react-ui-library)
- Route fix to correct repo:
  - If library issue: Fix in library repo, list affected consumer repos
  - If consumer issue: Fix in consumer repo directly
- Create appropriate branch and PR
- Move ticket to Code Review
- Add RCA with library/consumer context
Fully automated with intelligent routing!

Error Handling

Missing version: Explicitly pauses and asks for version
Unclean working directory: Requires stash or commit first
Branch conflicts: Fetches latest before creating branch
Invalid ticket ID: Reports via MCP error

📚 Documentation

Library Detection Guide - Complete guide to self-driven library detection
Workflow Guide - Detailed workflow documentation

Development

# Build
npm run build

# Development mode
npm run dev

# Test
npm test

# Publish to npm
npm publish

📦 Package Information

Package name: ticket-automation-mcp
Version: 1.0.0
Registry: https://www.npmjs.com/package/ticket-automation-mcp
Size: 66.5 kB (334.1 kB unpacked)
Files: 30 (includes TypeScript source, compiled JS, and documentation)

🚀 Quick Start

Install: npm install -g ticket-automation-mcp
Configure: Add MCP configuration with your Jira/Bitbucket tokens
Set environment: Add REPO_SEARCH_PATHS for repo auto-discovery
Test: Run detect_library_issue on a real ticket
Use: Say "Fix ticket PROJ-123" for complete automation

License

MIT