@pavi_thran_7/jira-mcp-server/README.md

MCP server for Jira integration with ticket creation and time logging

# Jira MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Jira for ticket management and time tracking operations.

## Features

- **Authentication & Configuration**: Secure connection to Jira instances
- **Ticket Management**: Create and retrieve Jira tickets with project and board assignment
- **Time Logging**: Log work hours against tickets with billing account support
- **Project & Board Discovery**: List available projects and boards
- **Billing Account Management**: Manage billing accounts for time tracking and cost allocation
- **Error Handling**: Comprehensive error handling with helpful messages
- **Rate Limiting**: Built-in rate limiting and retry mechanisms

## Installation

### Prerequisites

- Node.js 18.0.0 or higher
- Jira Cloud or Server instance
- Jira API token (for authentication)

### Install from npm

```bash
npm install -g @pavi_thran_7/jira-mcp-server
```

### Install from Source

```bash
git clone https://github.com/yourusername/jira-mcp-server.git
cd jira-mcp-server
npm install
```

### Configuration

#### Option 1: Environment Variables (Recommended)

Set these environment variables for automatic configuration:

```env
JIRA_BASE_URL=https://your-company.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-api-token
```

The server will automatically connect to Jira on startup if these variables are set.

#### Option 2: Manual Configuration

1. Create a `.env` file in the project root (optional):

```bash
cp .env.example .env
```

2. Edit the `.env` file with your Jira configuration (optional):

```env
JIRA_BASE_URL=https://your-company.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-api-token
```

3. Or use the `configure_jira` tool after the server starts.

## Usage

### Starting the Server

#### If installed globally:

```bash
jira-mcp-server
```

#### If installed from source:

```bash
npm start
```

For development with auto-reload:

```bash
npm run dev
```

### MCP Client Configuration

#### Claude Desktop Configuration

Add the server to your Claude Desktop configuration with environment variables:

```json
{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp-server",
      "env": {
        "JIRA_BASE_URL": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

Or if installed from source:

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/src/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

#### Generic MCP Client Configuration

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/src/index.js"]
    }
  }
}
```

## Available Tools

### 1. configure_jira

Configure Jira connection with credentials.

**Parameters:**
- `baseUrl` (required): Jira instance URL (e.g., https://company.atlassian.net)
- `email` (required): User's Jira account email
- `apiToken` (required): Jira API token for authentication

**Example:**
```json
{
  "tool": "configure_jira",
  "arguments": {
    "baseUrl": "https://mycompany.atlassian.net",
    "email": "john.doe@company.com",
    "apiToken": "ATATT3xFfGF0T..."
  }
}
```

### 2. create_ticket

Create a new Jira ticket with project and board assignment.

**Parameters:**
- `projectKey` (required): Project identifier (e.g., "PROJ", "DEV")
- `summary` (required): Ticket title/summary
- `issueType` (required): Type of issue (Task, Bug, Story, Epic)
- `description` (optional): Detailed ticket description
- `priority` (optional): Priority level (Highest, High, Medium, Low, Lowest)
- `assignee` (optional): User account ID or email to assign ticket
- `labels` (optional): Array of label strings
- `boardId` (optional): Specific board ID to add ticket to

**Example:**
```json
{
  "tool": "create_ticket",
  "arguments": {
    "projectKey": "PROJ",
    "summary": "Fix login page CSS issues",
    "description": "The login button is misaligned on mobile devices",
    "issueType": "Bug",
    "priority": "High",
    "labels": ["frontend", "mobile"],
    "boardId": "123"
  }
}
```

### 3. get_ticket

Retrieve ticket details and current status.

**Parameters:**
- `issueKey` (required): Ticket identifier (e.g., "PROJ-123")

**Example:**
```json
{
  "tool": "get_ticket",
  "arguments": {
    "issueKey": "PROJ-123"
  }
}
```

### 4. log_work

Log work hours against existing tickets.

**Parameters:**
- `issueKey` (required): Ticket identifier (e.g., "PROJ-123")
- `timeSpent` (required): Time duration (e.g., "2h 30m", "1d", "45m")
- `comment` (optional): Description of work performed
- `started` (optional): ISO date when work started (defaults to now)
- `billingAccountId` (optional): Billing account ID for invoicing/cost tracking

**Example:**
```json
{
  "tool": "log_work",
  "arguments": {
    "issueKey": "PROJ-456",
    "timeSpent": "2h 30m",
    "comment": "Implemented responsive design fixes",
    "billingAccountId": "10001"
  }
}
```

### 5. list_projects

Get available projects user has access to.

**Example:**
```json
{
  "tool": "list_projects",
  "arguments": {}
}
```

### 6. list_boards

Get available boards for a project.

**Parameters:**
- `projectKey` (optional): Filter boards by project key

**Example:**
```json
{
  "tool": "list_boards",
  "arguments": {
    "projectKey": "PROJ"
  }
}
```

### 7. list_billing_accounts

Get available billing accounts for time logging.

**Parameters:**
- `projectKey` (optional): Filter billing accounts by project

**Example:**
```json
{
  "tool": "list_billing_accounts",
  "arguments": {
    "projectKey": "PROJ"
  }
}
```

## Time Format

The server supports flexible time formats for work logging:

- **Minutes**: `30m`, `45m`
- **Hours**: `2h`, `1.5h`
- **Days**: `1d`, `0.5d`
- **Weeks**: `1w`, `2w`
- **Combined**: `1w 2d 3h 30m`, `2h 30m`, `1d 4h`

## Error Handling

The server provides comprehensive error handling:

- **Authentication Errors**: Clear messages for invalid credentials
- **Permission Errors**: Specific permission error messages
- **Not Found Errors**: Helpful suggestions for invalid project/board IDs
- **Rate Limiting**: Automatic retry with exponential backoff
- **Network Errors**: Graceful degradation with retry mechanisms

## API Endpoints Used

The server interacts with the following Jira REST API endpoints:

- `GET /rest/api/3/myself` - Authentication test
- `GET /rest/api/3/project/search` - List projects
- `GET /rest/agile/1.0/board` - List boards
- `GET /rest/api/3/issuetype/project` - Get issue types
- `GET /rest/api/3/priority` - Get priorities
- `POST /rest/api/3/issue` - Create issues
- `GET /rest/api/3/issue/{issueKey}` - Get issue details
- `POST /rest/api/3/issue/{issueKey}/worklog` - Log work
- `GET /rest/api/3/user/search` - Search users
- `GET /rest/api/3/project/{projectKey}/worklogscheme` - Get worklog schemes
- `GET /rest/api/3/worklogscheme/{id}` - Get worklog scheme details

## Security Considerations

- API tokens are never logged in plain text
- All API calls use HTTPS
- Input validation prevents injection attacks
- Proper error messages without exposing sensitive data
- Session management handled securely

## Supported Jira Versions

- **Jira Cloud**: Fully supported
- **Jira Server/Data Center**: Supported (API v3)
- **Jira Server (Legacy)**: May require API endpoint adjustments

## Development

### Project Structure

```
jira-mcp-server/
├── package.json
├── src/
│   ├── index.js          # Main server entry point
│   ├── jira-client.js    # Jira API client
│   ├── tools/
│   │   ├── configure.js  # Configuration tool
│   │   ├── tickets.js    # Ticket management tools
│   │   ├── worklog.js    # Time logging tools
│   │   ├── discovery.js  # Project/board discovery
│   │   └── billing.js    # Billing account management
│   └── types/
│       └── jira.js       # JSDoc type definitions
├── README.md
└── .env.example
```

### Code Style

- ES6 modules with Node.js 18+
- JSDoc for type safety and documentation
- Comprehensive error handling
- Async/await for all API calls
- Proper input validation and sanitization

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License

## Support

For issues and questions:

1. Check the error messages - they're designed to be helpful
2. Verify your Jira permissions and API token
3. Ensure your Jira instance is accessible
4. Check the console output for detailed error information

## Changelog

### 1.0.0

- Initial release
- Basic ticket creation and management
- Time logging with billing account support
- Project and board discovery
- Comprehensive error handling
- Rate limiting and retry mechanisms