Phase 3: Add JIRA Integration via IssueTracker Interface

[acreeger]

This is a potential Phase 3 task for implementing JIRA ticketing integration (see parent issue #210).

Research conducted by Opus agent with comprehensive findings on JIRA integration feasibility.

Executive Summary

JIRA integration into iloom's IssueTracker interface abstraction is feasible and architecturally sound, but presents more complexity than GitHub or Linear due to JIRA's enterprise-grade feature set, multiple deployment models (Cloud vs Server/Data Center), and alphanumeric issue key format.

Recommendation: JIRA as Phase 3 candidate with 8-12 days estimated effort.

Prerequisites

• Phase 1 (Phase 1: Abstract GitHub CLI into IssueTracker Interface #236) must be completed (IssueTracker interface abstraction)
• Phase 2 (Phase 2: Add Linear CLI Support via IssueTracker Interface #237) recommended but not required (Linear integration provides multi-provider validation)

Overview

Add JIRA integration through the IssueTracker interface abstraction, enabling full JIRA ticketing functionality while maintaining provider abstraction pattern.

---

1. Recommended CLI Tool: ankitpokhrel/jira-cli

Best option for iloom integration:

• GitHub: https://github.com/ankitpokhrel/jira-cli
• JSON Output: jira issue list --raw provides machine-readable output
• Comprehensive Operations: Issue create, view, edit, assign, move/transition, link, comment
• Authentication: Basic auth (API token), Bearer (PAT), MTLS (certificates)
• Cross-Platform: Available via Homebrew, Scoop, or binary releases

Example Commands:

# Get issue in JSON format
jira issue view PROJ-123 --raw

# List issues with JQL
jira issue list --jql "project = PROJ AND status = 'In Progress'" --raw

# Create issue
jira issue create --project PROJ --type Story --summary "Title" --body "Description"

# Transition issue
jira issue move PROJ-123 "In Progress"

Alternative: Atlassian ACLI (Official)

• Official Atlassian Command Line Interface
• JSON flag: acli jira workitem view KEY-123 --json
• Multi-product: Works with Jira, Confluence, Bitbucket

---

2. IssueTracker Interface Implementation

JIRA-Specific Adaptations

interface JiraIssue extends Issue {
  key: string           // "PROJ-123" format
  projectKey: string    // "PROJ" 
  issueType: string     // "Story", "Bug", "Task", etc.
  priority?: string     // JIRA-specific
  components?: string[] // JIRA-specific
  fixVersions?: string[] // JIRA-specific
}

class JiraService implements IssueTracker {
  private config: {
    baseUrl: string      // https://company.atlassian.net
    projectKey: string   // Default project for new issues
    authMethod: 'api-token' | 'pat' | 'oauth'
    deployment: 'cloud' | 'server' | 'datacenter'
  }
  
  async fetchIssue(identifier: string): Promise<Issue> {
    // identifier could be "PROJ-123" or just "123" (with configured project)
    const key = this.resolveIssueKey(identifier)
    // Use jira-cli: jira issue view PROJ-123 --raw
  }
  
  // Extract numeric part for port calculation
  extractIssueNumber(key: string): number {
    // "PROJ-123" -> 123
    const match = key.match(/-(\d+)$/)
    return match ? parseInt(match[1], 10) : 0
  }
}

---

3. Authentication Approaches

JIRA Cloud (Recommended)

1. API Token: Generate at https://id.atlassian.com/manage-profile/security/api-tokens

   • Usage: username:api_token as Basic auth
   • Environment variable: JIRA_API_TOKEN

2. OAuth 2.0 (3LO): For apps requiring user consent

JIRA Server/Data Center

1. Personal Access Token (PAT): Generate in user profile settings
   • Usage: Bearer token authentication
   • More secure than basic auth

Recommended Configuration

{
  "issueManagement": {
    "provider": "jira",
    "jira": {
      "baseUrl": "https://company.atlassian.net",
      "defaultProject": "PROJ",
      "deployment": "cloud",
      "authMethod": "api-token",
      "defaultIssueType": "Story"
    }
  }
}

---

4. Issue Identifier Format

JIRA Key Format

• Format: <PROJECT_KEY>-<NUMBER> (e.g., PROJ-123, ABC-1, R2D2-42)
• Project key: 2+ uppercase letters, can include underscores and numbers
• Maximum project key length: 10 characters

Impact on iloom

// Port calculation: extract numeric part
function calculatePort(jiraKey: string, basePort: number = 3000): number {
  const match = jiraKey.match(/-(\d+)$/)
  if (!match) throw new Error(`Invalid JIRA key format: ${jiraKey}`)
  return basePort + parseInt(match[1], 10)
}

// Examples:
// PROJ-123  -> port 3123
// ABC-42    -> port 3042
// DEV-1000  -> port 4000

// Workspace naming: include full key for uniqueness
// "PROJ-123", "Add dark mode" -> "proj-123-add-dark-mode"

---

5. MCP Server Integration

Official Atlassian MCP Server (Cloud Only)

{
  "mcpServers": {
    "Atlassian": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.atlassian.com/v1/sse"]
    }
  }
}

Community MCP Server: mcp-atlassian

Available Tools:

• Read: jira_search, jira_get_issue, jira_get_all_projects, jira_get_transitions
• Write: jira_create_issue, jira_update_issue, jira_add_comment, jira_transition_issue
• Agile: jira_get_agile_boards, jira_get_sprint_issues

---

6. JIRA-Specific Features

Complex Workflows

• JIRA workflows are highly customizable and project-specific
• Transitions vary by workflow (not just open/closed)
• May require specific fields or conditions

// Get available transitions for an issue
async getAvailableTransitions(key: string): Promise<JiraTransition[]>

// Transition an issue (e.g., "To Do" -> "In Progress")  
async transitionIssue(key: string, transitionName: string): Promise<void>

Issue Types

• Multiple types: Story, Bug, Task, Epic, Sub-task
• Affect available workflows and fields
• Configurable per project

Custom Fields

• Enterprise-specific configurations
• Identified by IDs (customfield_10001)
• May require instance-specific mapping

---

7. Implementation Challenges

Challenge	Impact	Mitigation
Cloud vs Server API differences	Different auth, field handling	Detect deployment type, use appropriate adapter
Alphanumeric keys	Port/naming calculation	Extract numeric part, support full key input
Complex workflows	Status transitions vary	Fetch available transitions dynamically
Custom fields	Field IDs not names	Optional field mapping configuration
Project context required	Can't operate without project	Require defaultProject in config

---

8. Files to Create

• /src/lib/JiraService.ts - JIRA implementation (~400-500 LOC)
• /src/utils/jira.ts - JIRA CLI utilities (~200 LOC)
• /src/types/jira.ts - JIRA type definitions (~150 LOC)
• /src/adapters/JiraCloudAdapter.ts - Cloud-specific logic (~150 LOC)
• /src/adapters/JiraServerAdapter.ts - Server-specific logic (~150 LOC)

Files to Modify

• /src/lib/IssueTrackerFactory.ts - Add JiraService instantiation
• /src/lib/SettingsManager.ts - Add JIRA-specific settings
• /src/utils/mcp.ts - Add JIRA MCP configuration
• /src/commands/init.ts - JIRA setup and authentication
• /src/utils/port.ts - Support alphanumeric identifiers
• /src/utils/branch.ts - JIRA branch naming format
• /README.md - Document JIRA integration
• Settings schema - JIRA configuration options

---

9. Implementation Steps

1. Create JiraService Class - Implement IssueTracker interface
2. Add Cloud/Server Adapters - Handle deployment differences
3. Add JIRA Utilities - CLI wrapper and helper functions
4. Update Factory - Add JIRA provider instantiation
5. Extend Settings Schema - JIRA-specific configuration
6. Update Init Command - JIRA setup and API key configuration
7. Add MCP Configuration - Both official and community MCP servers
8. Update Port/Branch Logic - Support alphanumeric identifiers
9. Update Documentation - JIRA integration guide

---

10. Acceptance Criteria

• JiraService implements all IssueTracker interface methods
• JIRA issues can be fetched via jira-cli or ACLI
• JIRA comments can be created via MCP server
• Settings support JIRA project/deployment configuration
• Init command can configure JIRA authentication
• Alphanumeric identifiers work for port calculation
• Branch naming supports JIRA key format (PROJ-123)
• MCP configuration selects JIRA provider when configured
• Support both Cloud and Server deployments
• Issue transitions work through JIRA workflows
• All existing GitHub/Linear functionality remains unchanged
• TypeScript compilation succeeds
• Tests pass for all providers (GitHub, Linear, JIRA)

---

11. Testing Strategy

• Unit tests for JiraService implementation
• Adapter tests for Cloud vs Server differences
• Integration tests with JIRA API (mocked)
• Factory tests for JIRA provider selection
• Settings validation for JIRA configuration
• Port calculation tests with alphanumeric identifiers
• Workflow transition tests
• End-to-end workflow tests with JIRA provider

---

12. Complexity Assessment

Rating: Medium-High (compared to Linear: Medium, GitHub: Low)

Estimated Effort: 8-12 days

Effort Breakdown

• JiraService class: 2-3 days
• Cloud/Server adapters: 1-2 days
• Settings schema: 0.5 day
• Input detection: 1 day
• Port calculation: 0.5 day
• Workflow transitions: 1 day
• MCP server integration: 1 day
• Testing: 2-3 days

Why More Complex Than Linear?

1. Two deployment models (Cloud vs Server)
2. Project-centric operations
3. Complex, customizable workflows
4. Enterprise-specific custom fields
5. Alphanumeric keys requiring parsing

---

Dependencies

• Phase 1 (Phase 1: Abstract GitHub CLI into IssueTracker Interface #236) completion - IssueTracker interface abstraction
• jira-cli or Atlassian ACLI availability
• JIRA API access (Cloud or Server instance)
• Appropriate authentication credentials
• Optional: Phase 2 (Phase 2: Add Linear CLI Support via IssueTracker Interface #237) for multi-provider validation

---

Configuration Example

{
  "issueManagement": {
    "provider": "jira",
    "jira": {
      "baseUrl": "https://company.atlassian.net",
      "defaultProject": "PROJ",
      "deployment": "cloud",
      "authMethod": "api-token",
      "defaultIssueType": "Story",
      "boardId": 123
    }
  }
}

Environment variables:

JIRA_BASE_URL=https://company.atlassian.net
JIRA_USERNAME=user@company.com
JIRA_API_TOKEN=your-api-token
# OR for Server/DC:
JIRA_PAT=your-personal-access-token

---

Benefits After Completion

• Full JIRA integration for enterprise teams
• Support for both Cloud and Server deployments
• Project-by-project provider selection between GitHub, Linear, and JIRA
• Enhanced AI capabilities via JIRA MCP servers
• Maintained abstraction for future providers
• Enterprise-grade workflow support

---

Parent Issue: #210
Phase: 3 of 3 (potential)
Prerequisites: #236 (required), #237 (recommended)
Estimated LOC: ~1,200-1,500
Files Impact: ~5 new, ~10 modified
Deployment Support: JIRA Cloud, Server, Data Center

---

Research Sources

CLI Tools

• ankitpokhrel/jira-cli - GitHub
• Atlassian ACLI Documentation

API Documentation

• Jira Cloud REST API v3
• Basic Auth for REST APIs

MCP Servers

• Atlassian MCP Server - GitHub
• mcp-atlassian - PyPI

Comprehensive research findings documented above based on Opus agent analysis.

[acreeger]

FYI: MCP-to-MCP Communication Research

Context: Research was conducted on how MCP servers can call other MCP servers, which could be particularly relevant for JIRA integration given the official Atlassian MCP server availability.

Key Findings

✅ MCP-to-MCP Communication is Possible

• The TypeScript MCP SDK provides both Client and Server classes that can be used together
• Production examples exist: IBM MCP Context Forge, Multi-MCP, FastMCP
• Multiple transport options: stdio (subprocess), HTTP, SSE, WebSocket

🔮 Especially Relevant for JIRA
JIRA has multiple MCP server options available:

• Official Atlassian MCP Server: npx -y mcp-remote@latest https://mcp.atlassian.com/v1/sse
• Community MCP Server: mcp-atlassian with comprehensive tool set
• This could provide richer integration than CLI-only approach

🏗️ Potential Future Architecture

Claude/LLM
    ↓ (MCP Protocol)
Issue Tracker MCP  ← Our abstraction layer
    ↓ (MCP Protocol) 
GitHub MCP | Linear MCP | JIRA MCP

📋 Current Implementation Plan (Unchanged)
For Phase 3 (JIRA integration), we're still planning to:

• Use the ankitpokhrel/jira-cli tool directly (not JIRA MCP servers)
• Implement JiraService that calls CLI commands and parses JSON output
• Follow the same pattern as GitHubService and LinearService

🔮 Future Enhancement Path
The MCP-to-MCP research provides options for JIRA integration enhancement:

• Option A: CLI-only (current plan) - simpler, more predictable
• Option B: MCP delegation to Atlassian MCP - richer integration, potentially more complex
• Option C: Hybrid approach - CLI for basic ops, MCP for advanced features

Current implementation remains CLI-focused as planned. This research is documented for future architectural decisions and potential JIRA-specific enhancements.

---

Research Details: Comprehensive MCP-to-MCP findings available including authentication patterns, error handling, and performance considerations.

[NoahCardoza]

Hi @acreeger, I've had tons of fun working with this project the past few days. I was about to implement something nearly identical. While researching, I came across this project.

My organization uses Jira and BitBucket, so the last few days, I've been working on adding Jira and BitBucket providers along with some other "nice-to-haves" that help iloom conform to the internal standards we use at Quicken. Too bad I didn't see this issue first, otherwise I could have included all this research in my initial changes.

Much of my work was quick and dirty to get something working and be able to test this project out. I'd be interested in cleaning it up and helping integrate it into iloom when you are ready to move forward with adding Jira and BitBucket support.

Here is the branch I've been operating on NoahCardoza#1. I started with the Copilot in the Cloud for the initial changes and then moved to using Claude Code locally when it came to the small bugs that cropped up while actually using it to solve issue. Because of this, that PR description isn't up to date.

Here is a progress report (generated by Claude Code) of what I've added thus far:

Architectural Improvements (Non-Provider-Specific)

These changes improve the codebase structure and could be merged independently:

1. VersionControlProvider Interface

A clean abstraction separating VCS operations from issue tracking. This allows supporting multiple VCS platforms through a unified interface.

export interface VersionControlProvider {
  readonly providerName: string
  readonly supportsForks: boolean
  readonly supportsDraftPRs: boolean

  checkForExistingPR(branchName: string, cwd?: string): Promise<ExistingPR | null>
  createPR(branchName: string, title: string, body: string, baseBranch: string, cwd?: string): Promise<string>
  fetchPR(prNumber: number, cwd?: string): Promise<PullRequest>
  // ... and more
}

Location: src/lib/VersionControlProvider.ts

2. ProviderCoordinator

Orchestrates workflows between issue trackers and VCS providers. Handles cross-provider coordination like:

• Routing agent output to the correct destination (issue vs PR)
• Coordinating PR creation with issue state transitions
• Extracting PR numbers from various URL formats (GitHub, BitBucket)

Location: src/lib/ProviderCoordinator.ts

3. VCSProviderFactory

Factory pattern for creating VCS providers based on settings configuration. Currently returns null for GitHub (uses existing PRManager) but provides the extension point for future providers.

Location: src/lib/VCSProviderFactory.ts (with 254 lines of tests)

4. Extended remote.ts URL Parsing

The extractOwnerRepoFromUrl function now supports both GitHub and BitBucket URL formats:

• GitHub HTTPS: https://github.com/owner/repo
• GitHub SSH: git@github.com:owner/repo
• BitBucket HTTPS: https://bitbucket.org/workspace/repo
• BitBucket SSH: git@bitbucket.org:workspace/repo

Location: src/utils/remote.ts

5. IssueTracker Interface Enhancement

Added moveIssueToReadyForReview method to the IssueTracker interface for workflow state transitions when finishing work.

moveIssueToReadyForReview?(identifier: string | number): Promise<void>

Location: src/lib/IssueTracker.ts

6. Issue Number Case Preservation

Modified metadata handling to preserve issue number case, which is important for case-sensitive issue trackers (Jira uses PROJ-123, not proj-123).

7. Debug Subcommand for Integration Testing

Added il debug command (only available when ILOOM_DEBUG=true) for testing provider integrations. Currently includes il debug bitbucket resolve-reviewer-ids for debugging reviewer ID resolution.

Location: src/cli.ts

---

Jira Integration

Full Jira Cloud support as an issue tracker:

• JiraApiClient: REST API v3 client with Basic Auth
• JiraIssueTracker: Implements the IssueTracker interface
• JiraIssueManagementProvider: MCP server integration for Claude Code
• ADF ↔ Markdown Converter: Bidirectional conversion between Atlassian Document Format and Markdown (uses extended-markdown-adf-parser library)
  • Handles <details>/<summary> HTML → ADF expand syntax conversion
  • Sanitizes code marks per ADF spec (code marks must be standalone)

Test Coverage: 663 lines of tests for AdfMarkdownConverter alone

Configuration

{
  "issueManagement": {
    "provider": "jira",
    "jira": {
      "host": "https://yourcompany.atlassian.net",
      "username": "your.email@company.com",
      "projectKey": "PROJ",
      "boardId": "123",
      "transitionMappings": {
        "In Review": "Start Review"
      }
    }
  }
}

---

BitBucket Integration

Full BitBucket Cloud support for pull requests:

• BitBucketApiClient: REST API 2.0 client with API token auth
• BitBucketVCSProvider: Implements VersionControlProvider interface
• PR Reviewers: Auto-resolves usernames to BitBucket account IDs
• Current User Exclusion: Automatically excludes PR author from reviewer list

Test Coverage: 445 lines for ApiClient + 381 lines for VCSProvider

Configuration

{
  "versionControl": {
    "provider": "bitbucket",
    "bitbucket": {
      "username": "your-username",
      "workspace": "your-workspace",
      "reviewers": ["alice.jones", "bob.smith"]
    }
  },
  "mergeBehavior": {
    "mode": "bitbucket-pr"
  }
}

---

Settings Schema Updates

Extended the Zod validation schemas to include:

• issueManagement.jira configuration block
• versionControl configuration block (new top-level key)
• mergeBehavior.mode: "bitbucket-pr" option
• mergeBehavior.prTitlePrefix option (prefix PR titles with issue number)

---

Files Changed Summary

Category	Files	Purpose
Core Interfaces	2	VersionControlProvider.ts, ProviderCoordinator.ts
Factories	2	VCSProviderFactory.ts, IssueManagementProviderFactory.ts
Jira Provider	4	ApiClient, IssueTracker, MCP Provider, ADF Converter
BitBucket Provider	3	ApiClient, VCSProvider, index
Settings	1	Extended schema validation
Utils	2	remote.ts, mcp.ts updates
Commands	3	finish.ts, commit, CLI debug commands
Tests	6	Comprehensive test coverage
Docs	1	README with setup instructions

---

Branch: copilot/add-jira-bitbucket-integration
Base: main at commit f869501