Jira-GitLab MCP Server

# Jira-GitHub Agent An automated agent that monitors Jira issues and creates GitHub branches automatically using the MCP (Model Context Protocol) server. ## Features - **Automated Branch Creation**: Monitors Jira issues with specific tags and automatically creates GitHub branches - **Intelligent Naming**: Generates unique branch names with configurable prefixes and suffixes - **Status Updates**: Updates Jira issue status when branches are created - **Error Handling**: Robust retry logic and error recovery - **Dry Run Mode**: Test the agent without making actual changes - **Concurrent Processing**: Handles multiple issues simultaneously with configurable limits ## Prerequisites 1. **MCP Server Running**: The Jira-GitHub MCP server must be running ```bash cd /path/to/mcp-jira-gitlab python mcp_server.py ``` 2. **Dependencies**: Install required Python packages ```bash pip install -r agents/requirements.txt ``` 3. **Configuration**: Update `agent_config.yaml` with your settings ## Configuration Edit `agents/agent_config.yaml`: ```yaml # MCP server connection mcp: host: "ws://localhost:8555" # MCP server WebSocket URL retries: 3 retry_delay: 10 # Jira settings jira: project_key: "DEMO" # Your Jira project key monitored_tags: - "urgent" # Issues with these labels will be processed - "auto-branch" - "AI-Fix" status_filters: - "To Do" # Only process issues in these statuses - "Open" check_interval: 300 # Check every 5 minutes # GitHub settings github: repo_owner: "your-username" # GitHub username or organization repo_name: "your-repo" # Repository name base_branch: "main" # Base branch for new branches branch_prefix: "feature/" # Prefix for branch names branch_suffixes: ["fix", "hotfix", "patch", "update"] # Agent behavior agent: max_concurrent_issues: 5 # Process up to 5 issues simultaneously log_level: "INFO" # DEBUG, INFO, WARNING, ERROR dry_run: false # Set to true for testing jira_status_on_branch_create: "In Development" skip_existing_branches: true continue_on_error: true ``` ## Usage ### Basic Usage 1. **Start the MCP server** (in one terminal): ```bash python mcp_server.py ``` 2. **Run the agent** (in another terminal): ```bash cd agents python jira_github_agent.py ``` ### Dry Run Mode Test the agent without making changes: ```bash # Edit agent_config.yaml and set dry_run: true python jira_github_agent.py ``` ### Custom Configuration Use a different config file: ```python from jira_github_agent import JiraGitHubAgent agent = JiraGitHubAgent(config_path="custom_config.yaml") await agent.start() ``` ## How It Works 1. **Monitoring**: Agent connects to MCP server and polls Jira for issues matching criteria 2. **Filtering**: Issues are filtered by: - Project key - Status (To Do, Open, etc.) - Labels/tags (urgent, auto-branch, etc.) 3. **Branch Creation**: For each new issue: - Generates unique branch name: `feature/DEMO-123-fix` - Creates branch in GitHub via MCP server - Handles naming conflicts with automatic suffixes 4. **Status Update**: Updates Jira issue status to "In Development" 5. **Tracking**: Remembers processed issues to avoid duplicates ## Branch Naming Convention Branches are named using the pattern: `{prefix}{issue_key}-{suffix}` Examples: - `feature/DEMO-123-fix` - `feature/PROJ-456-hotfix` - `feature/BUG-789-patch-2` (if conflict occurred) ## Error Handling The agent includes comprehensive error handling: - **Connection Failures**: Automatic retry with exponential backoff - **Branch Conflicts**: Generates alternative names with numeric suffixes - **API Errors**: Logs errors and continues processing other issues - **Network Issues**: Reconnects to MCP server automatically ## Logging Logs include: - Connection status to MCP server - Issues found and processed - Branch creation success/failure - Status update results - Error details with stack traces Example log output: ``` 2024-10-09 17:11:00 - jira_github_agent - INFO - Starting Jira-GitHub Agent 2024-10-09 17:11:01 - jira_github_agent - INFO - Successfully connected to MCP server 2024-10-09 17:11:01 - jira_github_agent - INFO - Starting monitoring loop (check every 300s) 2024-10-09 17:11:02 - jira_github_agent - INFO - Found 3 issues to evaluate 2024-10-09 17:11:02 - jira_github_agent - INFO - Processing 2 new issues 2024-10-09 17:11:03 - jira_github_agent - INFO - Creating GitHub branch 'feature/DEMO-123-fix' for issue DEMO-123 2024-10-09 17:11:04 - jira_github_agent - INFO - Successfully created branch 'feature/DEMO-123-fix' for issue DEMO-123 2024-10-09 17:11:05 - jira_github_agent - INFO - Updating DEMO-123 status to 'In Development' 2024-10-09 17:11:06 - jira_github_agent - INFO - Successfully processed issue DEMO-123 ``` ## Integration Examples ### CI/CD Pipeline Integration ```yaml # .github/workflows/auto-branch.yml name: Auto Branch Creation on: schedule: - cron: '*/5 * * * *' # Every 5 minutes jobs: auto-branch: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Python uses: actions/setup-python@v4 with: python-version: '3.9' - name: Install dependencies run: pip install -r agents/requirements.txt - name: Run agent run: python agents/jira_github_agent.py env: JIRA_TOKEN: ${{ secrets.JIRA_TOKEN }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` ### Docker Deployment ```dockerfile FROM python:3.9-slim WORKDIR /app COPY agents/ ./agents/ COPY mcp_server.py ./ COPY connectors/ ./connectors/ COPY utils/ ./utils/ RUN pip install -r agents/requirements.txt CMD ["python", "agents/jira_github_agent.py"] ``` ### Kubernetes Deployment ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: jira-github-agent spec: replicas: 1 selector: matchLabels: app: jira-github-agent template: metadata: labels: app: jira-github-agent spec: containers: - name: agent image: your-registry/jira-github-agent:latest env: - name: MCP_HOST value: "ws://mcp-server:8555" volumeMounts: - name: config mountPath: /app/agents/agent_config.yaml subPath: agent_config.yaml volumes: - name: config configMap: name: agent-config ``` ## Troubleshooting ### Common Issues 1. **Connection Failed** ``` ERROR - Failed to connect to MCP server after all retries ``` - Ensure MCP server is running on correct port - Check firewall settings - Verify WebSocket URL in config 2. **Authentication Errors** ``` ERROR - Failed to create branch: Unauthorized ``` - Check GitHub token permissions - Verify Jira credentials in MCP server config 3. **Branch Already Exists** ``` WARNING - Branch name conflict, trying alternative ``` - This is normal behavior, agent will try alternative names - Check if manual branches were created with same names 4. **No Issues Found** ``` DEBUG - No issues found matching criteria ``` - Verify JQL query in logs - Check if issues have required labels - Confirm project key is correct ### Debug Mode Enable debug logging: ```yaml agent: log_level: "DEBUG" ``` This will show: - Detailed JQL queries - Full API responses - WebSocket message details ## Security Considerations - **Credentials**: Store sensitive data in environment variables, not config files - **Network**: Use HTTPS/WSS in production - **Permissions**: Grant minimal required permissions to GitHub/Jira tokens - **Monitoring**: Monitor agent logs for suspicious activity ## Performance Tuning - **Concurrent Issues**: Adjust `max_concurrent_issues` based on API rate limits - **Check Interval**: Balance between responsiveness and API usage - **Batch Size**: Modify `max_results` in JQL queries for large projects ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests 5. Submit a pull request ## License This project is licensed under the MIT License.