Metadata-Version: 2.4
Name: ctf_mcp_jira
Version: 0.1.2
Summary: MCP server for JIRA integration
Author-email: Tim Kitchens <timkitch@codingthefuture.ai>
License-Expression: MIT
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: anyio>=4.0.0
Requires-Dist: starlette>=0.36.0
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: platformdirs>=4.2.2
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: mdurl>=0.1.2
Requires-Dist: streamlit
Requires-Dist: requests>=2.31.0

# MCP JIRA Server

A Model Context Protocol (MCP) server that provides seamless JIRA integration for AI tools. Create and manage JIRA issues with rich markdown formatting, automatic conversion to Atlassian Document Format (ADF), and flexible field management.

## Quick Setup with Claude Code

### 🚀 Let AI Help You Set Up

Copy and paste one of these prompts to your AI coding assistant:

**For Automated Setup (Claude Code only):**
```
/quick-setup-jira
```

**For Guided Setup Help:**
```
Please help me set up the MCP JIRA Server for Claude Code. 
Read the setup guide at: SETUP_ASSISTANT_PROMPT.md
```

**For Usage Examples:**
```
Show me how to use MCP JIRA Server effectively.
Read the usage guide at: USAGE_ASSISTANT_PROMPT.md
```

### ⚡ Quick Install (if you know what you're doing)

```bash
# Install MCP JIRA Server as an isolated tool (recommended)
uv tool install ctf-mcp-jira

# Find the installed binary location
uv tool dir  # Note this path!

# Configure using the Web UI (recommended)
ctf-mcp-jira-config
# This opens a web interface to configure your JIRA connection

# Add to Claude Code's MCP configuration with the EXACT path from uv tool dir
# macOS/Linux (replace path if your uv tool dir is different):
claude mcp add mcp_jira stdio "$(uv tool dir)/ctf-mcp-jira/bin/ctf-mcp-jira-server"

# Windows (replace path if your uv tool dir is different):
claude mcp add mcp_jira stdio "$(uv tool dir)\ctf-mcp-jira\Scripts\ctf-mcp-jira-server.exe"
```

Then edit the config file and restart Claude Code (required to reload MCP servers). See full instructions below.

## Overview

This MCP server enables AI assistants to interact directly with JIRA instances through the JIRA REST API v3. It handles the complexity of markdown-to-ADF conversion, field mapping, and multi-site configuration, allowing AI tools to create well-formatted JIRA issues with minimal setup.

Key architectural components:
- **MCP Server**: FastMCP-based server with stdio/SSE transport support
- **JIRA Client**: Direct REST API integration with authentication handling
- **Markdown Converter**: Converts markdown to Atlassian Document Format (ADF)
- **Configuration System**: Multi-site JIRA configuration with flexible site selection
- **Field Management**: Support for both standard and custom JIRA fields

## Features

- **Rich Markdown Support**: Convert markdown descriptions to properly formatted ADF with support for:
  - Headers, paragraphs, and text formatting (bold, italic, inline code)
  - Fenced code blocks with syntax highlighting
  - Bullet and numbered lists
  - Tables and complex formatting elements

- **Flexible Field Management**:
  - Create and update JIRA issues with standard fields: project, summary, description, issue type.
  - Robust assignee handling: Provide an email address, and the server resolves it to the correct JIRA `accountId` for reliable assignment.
  - `additional_fields` parameter supports labels, priority, due dates, and other custom fields.
  - Graceful degradation for unavailable fields across different JIRA configurations.

- **Multi-Site Configuration**: Support for multiple JIRA instances with site aliases, configurable in `config.yaml`.
- **Comprehensive Error Handling**: Detailed error messages and logging.
- **Transport Flexibility**: Support for both stdio and SSE transport modes.

## Installation

### Recommended Method (Most Reliable)

Use `uv tool install` for complete isolation from other Python projects:

```bash
# Install UV if not already installed
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Install from PyPI (recommended for stable release)
uv tool install ctf-mcp-jira

# Or install from GitHub (for latest development version)
uv tool install git+https://github.com/codingthefuturewithai/mcp_jira.git

# Find the exact installation path (you'll need this for Claude Desktop)
uv tool dir

# The binary will be at:
# macOS/Linux: $(uv tool dir)/ctf-mcp-jira/bin/ctf-mcp-jira-server
# Windows: $(uv tool dir)\ctf-mcp-jira\Scripts\ctf-mcp-jira-server.exe

# To verify the exact path, run:
# macOS/Linux:
ls -la $(uv tool dir)/ctf-mcp-jira/bin/ctf-mcp-jira-server

# Windows:
dir "$(uv tool dir)\ctf-mcp-jira\Scripts\ctf-mcp-jira-server.exe"
```

**Default installation paths:**
- **macOS/Linux**: `~/.local/share/uv/tools/ctf-mcp-jira/bin/ctf-mcp-jira-server`
- **Windows**: `%USERPROFILE%\.local\share\uv\tools\ctf-mcp-jira\Scripts\ctf-mcp-jira-server.exe`

### Quick Start (Use with Caution)

For quick testing with `uvx` (note: may cause dependency conflicts):

```bash
# Run directly without installation
uvx ctf-mcp-jira-server

# ⚠️ WARNING: This method may conflict with other Python projects
# If you experience issues, use the recommended method above
```

### From Source (Development)

```bash
# Clone the repository
git clone https://github.com/codingthefuturewithai/mcp_jira.git
cd mcp_jira

# Create and activate a virtual environment using UV
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
uv pip install -e .
```

### Troubleshooting Installation

**Dependency Conflicts:**
- If you encounter dependency conflicts, ensure you're using `uv tool install` (recommended method)
- The isolated installation prevents conflicts with other Python packages
- For development, always use a virtual environment

**Platform-Specific Issues:**
- **Windows**: Run PowerShell as Administrator if you encounter permission errors
- **macOS**: If you get SSL errors, ensure certificates are updated: `brew install ca-certificates`
- **Linux**: May need to install additional system packages: `sudo apt-get install python3-dev`

For detailed troubleshooting, see the [Confluence documentation](https://codingthefuturewithai.atlassian.net/wiki/spaces/ACT/pages/89161729).

## Configuration

### Web UI Configuration (Recommended)

The easiest way to configure the MCP JIRA Server is through the web interface:

```bash
# Launch the configuration UI
ctf-mcp-jira-config
```

This will:
1. Open a web browser with the configuration interface
2. Create a config template if none exists
3. Allow you to add/edit JIRA sites and credentials
4. Save the configuration automatically

### Manual Configuration

The server requires a `config.yaml` file to connect to your JIRA instance(s). The server will attempt to load this file from the following locations, in order of precedence:

1.  The path specified by the `--config` command-line argument.
2.  The path specified by the `MCP_JIRA_CONFIG_PATH` environment variable.
3.  The default OS-specific user configuration directory:
    *   **Linux**: `~/.config/mcp_jira/config.yaml`
    *   **macOS**: `~/Library/Application Support/mcp_jira/config.yaml`
    *   **Windows**: `%APPDATA%\MCPJira\mcp_jira\config.yaml` (Note: `%APPDATA%` usually resolves to `C:\Users\<username>\AppData\Roaming`)

If the configuration file is not found at any of these locations, the server will automatically create the necessary directory (if it doesn't exist) and a template `config.yaml` file at the default OS-specific path. You will then need to edit this template with your actual JIRA site details.

Example of a filled-in `config.yaml`:
```yaml
name: "My Company JIRA Integration"
log_level: "INFO" # Supported levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

default_site_alias: "prod_jira"

sites:
  prod_jira:
    url: "https://mycompany.atlassian.net"
    email: "automation-user@mycompany.com"
    api_token: "abc123xyz789efg_your_token_here_jkl"
    cloud: true

  dev_jira:
    url: "https://dev-mycompany.atlassian.net"
    email: "dev-automation@mycompany.com"
    api_token: "another_token_for_dev_environment"
    cloud: true

# Optional: Advanced logging configuration (defaults are usually sufficient)
# log_file_path: "/var/log/custom_mcp_jira/activity.log" # Overrides default log file paths
# log_max_bytes: 20971520  # Max log file size in bytes (e.g., 20MB)
# log_backup_count: 10     # Number of backup log files to keep
```

### JIRA API Token

1. Log into your JIRA instance.
2. Go to **Account Settings** (usually by clicking your avatar/profile picture).
3. Navigate to **Security** > **API token** (the exact path might vary slightly depending on your JIRA version).
4. Click **Create API token**.
5. Give your token a descriptive label (e.g., `mcp_jira_server_token`).
6. Copy the generated token immediately. **You will not be able to see it again.**
7. Add the copied token to your `config.yaml` file.

## Configuration Editor UI

This project includes a web-based configuration editor built with Streamlit to easily manage your `config.yaml` file.

### Features
- View and edit all general settings (Server Name, Log Level, Default Site Alias).
- View, edit, add, and delete JIRA site configurations (Alias, URL, Email, API Token, Cloud status).
- Changes are saved directly to the `config.yaml` file used by the MCP server.
- The editor automatically uses the same configuration file path logic as the server itself (CLI override, environment variable, or OS-specific default).

### Running the Editor
1.  Ensure all project dependencies, including Streamlit, are installed:
    ```bash
    uv pip install -e .
    ```
2.  From the root of the project directory, run:
    ```bash
    streamlit run mcp_jira/ui/app.py
    ```
    Or, if `mcp_jira` is installed in your environment and your `PYTHONPATH` is set up:
    ```bash
    PYTHONPATH=. streamlit run mcp_jira/ui/app.py
    ```
3.  Open the URL provided by Streamlit in your web browser.

### Screenshot

![MCP JIRA Server Configuration Editor](docs/images/mcp-server-config-editor.png)

## Usage

### Running the MCP Server

```bash
# Run with stdio transport (default)
ctf-mcp-jira-server

# Run with SSE transport
ctf-mcp-jira-server --transport sse --port 3001

# Use custom configuration file
ctf-mcp-jira-server --config /path/to/config.yaml
```

### Available Tools

This server exposes the following tools for interacting with JIRA:

#### create_jira_issue

Creates a new JIRA issue. You can specify the project, summary, a detailed description in markdown (which will be converted to JIRA's rich text format), issue type, assignee, and other custom fields.

#### update_jira_issue

Updates an existing JIRA issue. You can modify fields such as the summary, description (markdown supported), assignee, issue type, or other custom fields. Only the fields you provide will be changed.

#### search_jira_issues

Search for JIRA issues using JQL (JIRA Query Language) syntax. Specify a JQL query to find issues matching your criteria.

**Parameters:**
- `query` (required): JQL query string to search for issues
- `site_alias` (optional): Site alias for multi-site configurations
- `basic_only` (optional, default: False): Controls the level of detail returned
  - When `False` (default): Returns comprehensive issue data including all standard fields, issue links, remote links, comments, and worklogs
  - When `True`: Returns only key, summary, and description for better performance

**Returns:**
- In basic mode: Issue key, summary, and description
- In full mode: Complete issue details including:
  - Standard fields (project, type, status, priority, assignee, dates)
  - Issue links (relationships to other JIRA issues like blocks, is blocked by, relates to, etc.)
  - Remote links (web links, Confluence pages, etc.)
  - Comments with author and timestamp
  - Worklogs with time tracking information

Example queries:
- `project = MYPROJECT`
- `project = MYPROJECT AND status = 'In Progress'`
- `assignee = currentUser() AND created >= -7d`

Example usage:
```
# Get basic issue information (faster)
search_jira_issues(query="project = ABC", basic_only=True)

# Get comprehensive issue details (default)
search_jira_issues(query="project = ABC AND updated >= -7d")
```

## Logging

The server logs activity to both stderr and a rotating log file.

**Log File Locations:**
Log files are stored in OS-specific locations by default:
- **macOS**: `~/Library/Logs/mcp_jira/mcp_jira.log`
- **Linux**:
  - If running as root: `/var/log/mcp_jira/mcp_jira.log`
  - If running as non-root: `~/.local/state/mcp_jira/mcp_jira.log`
- **Windows**: `%LOCALAPPDATA%\MCPJira\mcp_jira\Logs\mcp_jira.log` (Note: `%LOCALAPPDATA%` usually resolves to `C:\Users\<username>\AppData\Local`)

**Configuration:**
Logging behavior (level, file path, rotation settings) is configured via the `config.yaml` file. See the example `config.yaml` in the "Configuration" section for details on `log_level`, `log_file_path`, `log_max_bytes`, and `log_backup_count`.

The log level can also be overridden using the `MCP_JIRA_LOG_LEVEL` environment variable. If set, this environment variable takes precedence over the `log_level` in `config.yaml`.

```bash
# Example: Set log level to DEBUG for detailed API communication
MCP_JIRA_LOG_LEVEL=DEBUG ctf-mcp-jira-server
```
Valid log levels: `DEBUG`, `INFO` (default if not specified), `WARNING`, `ERROR`, `CRITICAL`.

## Requirements

- Python 3.11 or later (< 3.13)
- Operating Systems: Linux, macOS, Windows
- Network access to JIRA instance(s)
- Valid JIRA API token(s)

## Development

### Setting up the Development Environment

1. **Clone the repository**:
```bash
git clone https://github.com/codingthefuturewithai/mcp_jira.git
cd mcp_jira
```

2. **Install UV** (if not already installed):
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

3. **Create a virtual environment and install dependencies**:
```bash
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
```

### Building the Package

1. **Clean previous builds**:
```bash
rm -rf dist/ build/ *.egg-info/
```

2. **Build the package**:
```bash
uv pip install build
python -m build
```

This creates both wheel and source distributions in the `dist/` directory.

### Publishing to PyPI

1. **Install publishing tools**:
```bash
uv pip install twine
```

2. **Build the package** (if not already done):
```bash
python -m build
```

3. **Upload to PyPI Test** (recommended first):
```bash
python -m twine upload --repository testpypi dist/*
```

4. **Test installation from PyPI Test**:
```bash
uv tool install --index-url https://test.pypi.org/simple/ ctf-mcp-jira
```

5. **Upload to PyPI** (after successful testing):
```bash
python -m twine upload dist/*
```

### Running Tests

```bash
# Run all tests
pytest

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

### Code Quality

```bash
# Format code
black mcp_jira tests

# Lint code
ruff check mcp_jira tests

# Type checking
mypy mcp_jira
```

### Release Process

1. Update version in `pyproject.toml`
2. Update CHANGELOG (if exists)
3. Commit changes: `git commit -am "Bump version to X.Y.Z"`
4. Tag release: `git tag vX.Y.Z`
5. Push changes: `git push && git push --tags`
6. Build and publish to PyPI (see above)

## Troubleshooting

### Common Issues

**Authentication Errors**
- Verify API token is correct and hasn't expired
- Ensure email address matches JIRA account
- Check JIRA instance URL is accessible

**Field Errors**
- Use `additional_fields` for custom or optional fields
- Check field availability in your JIRA configuration
- Server gracefully ignores unavailable fields

**Markdown Conversion Issues**
- Ensure fenced code blocks use proper syntax
- Complex tables may need manual formatting
- Check logs for conversion warnings

**Connection Issues**
- Verify network connectivity to JIRA instance
- Check firewall/proxy settings
- Ensure JIRA REST API v3 is accessible

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Author

**Coding the Future with AI**
- GitHub: [codingthefuturewithai](https://github.com/codingthefuturewithai)
- Email: codingthefuturewithai@gmail.com
