# MCP JIRA Server

A comprehensive Model Context Protocol (MCP) server for JIRA built with **FastMCP** that provides full API access with Kerberos authentication and extensive custom fields support.

## Features

- **⚡ FastMCP Framework**: Built with FastMCP 2.0 for simplified, decorator-based server implementation
- **🔐 Kerberos/GSSAPI Authentication**: Native support for enterprise Kerberos authentication
- **🎫 Multiple Auth Methods**: Kerberos, API Token, and Basic Authentication
- **🔧 Custom Fields**: Automatic field resolution and type conversion
- **📝 Complete Operations**: Issues, Search, Comments, Attachments, Transitions, Projects
- **🔄 Retry Logic**: Automatic retry with backoff for failed requests
- **💾 Field Caching**: Efficient custom field metadata caching

## Installation

### Prerequisites

- Python 3.10 or higher
- Access to a JIRA instance
- For Kerberos: Valid Kerberos ticket or keytab file

### Install UV (Recommended)

If you don't have uv installed, install it first:

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv
```

### Create Virtual Environment and Install Dependencies

**Using uv (recommended - fast and efficient):**

```bash
cd /Users/hanuman/.gemini/antigravity/scratch/mcp-jira-server

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate  # Windows

# Install dependencies
uv pip install -e .
```

**Using pip (alternative):**

```bash
cd /Users/hanuman/.gemini/antigravity/scratch/mcp-jira-server

# Create virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate  # Windows

# Install dependencies
pip install -e .
```

> **Note**: This project uses **FastMCP 2.0**, which provides a streamlined decorator-based approach to building MCP servers. Using `uv` is recommended for faster dependency resolution and installation.

### Kerberos Setup

#### macOS

```bash
# Install Kerberos dependencies
brew install krb5

# Install Python Kerberos packages
pip install requests-gssapi
```

#### Linux (Ubuntu/Debian)

```bash
# Install Kerberos dependencies
sudo apt-get install libkrb5-dev krb5-user

# Install Python Kerberos packages
pip install requests-gssapi
```

#### Initialize Kerberos Ticket

```bash
# Using kinit (interactive)
kinit your.username@REALM

# Verify ticket
klist

# Or use keytab file (set in .env)
kinit -kt /path/to/your.keytab principal@REALM
```

## Configuration

Create a `.env` file in the project root:

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

Edit `.env` with your JIRA configuration:

```bash
# JIRA Configuration
JIRA_URL=https://jira.yourcompany.com

# Authentication Method
AUTH_METHOD=kerberos  # or api_token or basic

# Kerberos (when AUTH_METHOD=kerberos)
KERBEROS_PRINCIPAL=HTTP/jira.yourcompany.com@REALM
KERBEROS_KEYTAB_PATH=/path/to/your.keytab
KERBEROS_MUTUAL_AUTH=true

# API Token (when AUTH_METHOD=api_token)
JIRA_EMAIL=your.email@example.com
JIRA_API_TOKEN=your_api_token_here

# Optional Settings
LOG_LEVEL=INFO
CUSTOM_FIELDS_CACHE_TTL=3600
REQUEST_TIMEOUT=30
```

## Usage

### Running the Server

Make sure your virtual environment is activated first:

```bash
# Activate virtual environment if not already active
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate  # Windows

# Run as module
python -m mcp_jira

# Or use entry point (after installation)
mcp-jira-server
```

### MCP Client Configuration

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["-m", "mcp_jira"],
      "env": {
        "JIRA_URL": "https://jira.yourcompany.com",
        "AUTH_METHOD": "kerberos"
      }
    }
  }
}
```

#### Other MCP Clients

The server uses stdio transport and can be integrated with any MCP client that supports stdio.

## Available Tools

### Issue Operations

- **`jira_create_issue`**: Create new issue with custom fields
- **`jira_get_issue`**: Get issue details
- **`jira_update_issue`**: Update issue fields
- **`jira_delete_issue`**: Delete issue
- **`jira_assign_issue`**: Assign issue to user

### Search & Query

- **`jira_search_issues`**: Search using JQL with pagination

### Comments

- **`jira_add_comment`**: Add comment to issue

### Attachments

- **`jira_upload_attachment`**: Upload file to issue

### Workflow

- **`jira_get_transitions`**: Get available transitions
- **`jira_transition_issue`**: Move issue through workflow

### Metadata

- **`jira_list_projects`**: List accessible projects
- **`jira_get_custom_fields`**: Get custom field definitions

## Available Resources

- **`jira://projects`**: List of all projects
- **`jira://custom-fields`**: Custom field definitions
- **`jira://current-user`**: Current user information

## Examples

### Create Issue with Custom Fields

```python
{
  "tool": "jira_create_issue",
  "arguments": {
    "project": "PROJ",
    "summary": "Example issue",
    "issue_type": "Bug",
    "description": "This is a test issue",
    "priority": "High",
    "custom_fields": {
      "Story Points": 5,
      "Sprint": "Sprint 23",
      "Custom Date Field": "2024-12-31"
    }
  }
}
```

### Search Issues

```python
{
  "tool": "jira_search_issues",
  "arguments": {
    "jql": "project = PROJ AND status = 'In Progress'",
    "max_results": 50
  }
}
```

### Transition Issue

```python
{
  "tool": "jira_transition_issue",
  "arguments": {
    "issue_key": "PROJ-123",
    "transition": "In Progress",
    "comment": "Starting work on this issue"
  }
}
```

## Custom Fields

The server automatically resolves custom field names to IDs and handles type conversion:

- **Text fields**: Single/multi-line text
- **Select fields**: Single/multi-select options
- **Date fields**: Date and DateTime
- **User fields**: User picker
- **Number fields**: Numeric values
- **Arrays**: Multi-value fields

### Custom Field Usage

You can reference custom fields by name or ID:

```python
# By name
"custom_fields": {
  "Story Points": 5,
  "Epic Link": "PROJ-100"
}

# By ID
"custom_fields": {
  "customfield_10016": 5,
  "customfield_10014": "PROJ-100"
}
```

## Troubleshooting

### Kerberos Issues

**Problem**: `No valid Kerberos ticket found`

**Solution:**
```bash
# Initialize ticket
kinit your.username@REALM

# Verify
klist
```

**Problem**: `Server not found in Kerberos database`

**Solution:** Verify `KERBEROS_PRINCIPAL` matches your JIRA server's SPN

### Connection Issues

**Problem**: `Failed to connect to JIRA`

**Solution:**
- Verify `JIRA_URL` is correct
- Check network connectivity
- Verify authentication credentials
- Check logs for detailed error messages

### Custom Fields Not Found

**Problem**: Custom field not resolved

**Solution:**
```bash
# List all custom fields
# Use jira_get_custom_fields tool to see available fields

# Clear cache if fields were recently added
# Restart the server
```

## Development

### Running Tests

```bash
# Install dev dependencies with uv
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run with coverage
pytest --cov=mcp_jira tests/
```

### Code Quality

```bash
# Format code
black src/

# Type checking
mypy src/

# Linting
ruff check src/
```

## Architecture

The server uses **FastMCP** for a streamlined, decorator-based implementation with a layered architecture:

```mermaid
graph TB
    subgraph "MCP Clients"
        CD[Claude Desktop]
        OC[Other MCP Clients]
    end

    subgraph "MCP JIRA Server"
        subgraph "Server Layer"
            MCP[FastMCP Server<br/>mcp_server.py]
            TOOLS["@mcp.tool() Decorators"]
            RES["@mcp.resource() Decorators"]
        end

        subgraph "Operations Layer"
            ISS[Issues<br/>issues.py]
            SRCH[Search<br/>search.py]
            CMT[Comments<br/>comments.py]
            ATT[Attachments<br/>attachments.py]
            TRN[Transitions<br/>transitions.py]
            PRJ[Projects<br/>projects.py]
        end

        subgraph "Client Layer"
            JC[JIRA Client<br/>jira_client.py]
            CF[Custom Fields Manager<br/>custom_fields.py]
        end

        subgraph "Authentication Layer"
            AM[Auth Manager<br/>auth_manager.py]
            KRB[Kerberos Auth<br/>kerberos_auth.py]
            ADFS[ADFS Auth<br/>adfs_auth.py]
            API[API Token /<br/>Basic Auth]
        end

        subgraph "Configuration"
            CFG[Config<br/>config.py]
            ENV[.env File]
        end

        subgraph "Models"
            MDL[Pydantic Types<br/>types.py]
        end
    end

    subgraph "External Services"
        JIRA[(JIRA Server<br/>REST API)]
        KDC[Kerberos KDC]
        ADFSS[ADFS Server]
    end

    CD <-->|stdio| MCP
    OC <-->|stdio| MCP
    
    MCP --> TOOLS
    MCP --> RES
    TOOLS --> ISS
    TOOLS --> SRCH
    TOOLS --> CMT
    TOOLS --> ATT
    TOOLS --> TRN
    TOOLS --> PRJ
    RES --> PRJ
    
    ISS --> JC
    SRCH --> JC
    CMT --> JC
    ATT --> JC
    TRN --> JC
    PRJ --> JC
    
    JC --> CF
    JC --> AM
    
    AM --> KRB
    AM --> ADFS
    AM --> API
    
    KRB --> KDC
    ADFS --> ADFSS
    JC --> JIRA
    
    CFG --> ENV
    MCP --> CFG
    JC --> CFG

    classDef serverLayer fill:#4a90d9,stroke:#2c5aa0,color:#fff
    classDef opsLayer fill:#50b356,stroke:#2d7a32,color:#fff
    classDef clientLayer fill:#f5a623,stroke:#c78515,color:#fff
    classDef authLayer fill:#9b59b6,stroke:#6c3483,color:#fff
    classDef external fill:#e74c3c,stroke:#a93226,color:#fff
    classDef config fill:#95a5a6,stroke:#717d7e,color:#fff

    class MCP,TOOLS,RES serverLayer
    class ISS,SRCH,CMT,ATT,TRN,PRJ opsLayer
    class JC,CF clientLayer
    class AM,KRB,ADFS,API authLayer
    class JIRA,KDC,ADFSS external
    class CFG,ENV,MDL config
```

### Component Overview

| Layer | Components | Responsibility |
|-------|------------|----------------|
| **Server** | `mcp_server.py` | FastMCP server with `@mcp.tool()` and `@mcp.resource()` decorators |
| **Operations** | `issues.py`, `search.py`, `comments.py`, `attachments.py`, `transitions.py`, `projects.py` | JIRA API operations and business logic |
| **Client** | `jira_client.py`, `custom_fields.py` | HTTP client, retry logic, and custom field resolution |
| **Authentication** | `auth_manager.py`, `kerberos_auth.py`, `adfs_auth.py` | Multi-method auth (Kerberos, ADFS, API Token, Basic) |
| **Models** | `types.py` | Pydantic type definitions for request/response validation |
| **Config** | `config.py` | Environment-based configuration management |

### Directory Structure

```
mcp-jira-server/
├── src/mcp_jira/
│   ├── auth/              # Authentication (Kerberos, ADFS, API token, basic)
│   ├── client/            # JIRA client and custom fields manager
│   ├── models/            # Pydantic type definitions
│   ├── operations/        # JIRA operations (issues, search, etc.)
│   ├── server/
│   │   └── mcp_server.py  # FastMCP server with @mcp.tool and @mcp.resource decorators
│   ├── config.py          # Configuration management
│   └── __main__.py        # Entry point
├── tests/                 # Test suite
├── pyproject.toml         # Project metadata
└── .env.example           # Example configuration
```

### Key Design Principles

- **Layered Architecture**: Clear separation between server, operations, client, and auth layers
- **Decorator-Based Tools**: Simple `@mcp.tool()` and `@mcp.resource()` decorators for MCP integration
- **Pluggable Authentication**: Support for multiple auth methods via AuthManager abstraction
- **Automatic Type Conversion**: Parameter validation and type conversion from function signatures
- **Custom Field Resolution**: Automatic field name-to-ID mapping with caching

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions:
- Check the troubleshooting section
- Review JIRA API documentation
- Check MCP protocol documentation