Metadata-Version: 2.4
Name: temet-jira
Version: 0.1.0a4
Summary: Comprehensive Jira API client and CLI tool
Project-URL: Homepage, https://temet.ai
Project-URL: Repository, https://github.com/temet-ai/temet-jira
Author: Dawid du Toit
License: MIT
License-File: LICENSE
Keywords: ai-agent,api,cli,jira,temet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.3.1
Requires-Dist: fastmcp>=3.1.1
Requires-Dist: pandas>=3.0.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: questionary>=2.1.1
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=14.3.3
Requires-Dist: tabulate>=0.10.0
Provides-Extra: dev
Requires-Dist: black>=26.3.1; extra == 'dev'
Requires-Dist: mypy>=1.19.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff>=0.15.6; extra == 'dev'
Requires-Dist: types-python-dateutil>=2.9.0.20260305; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20250915; extra == 'dev'
Requires-Dist: types-requests>=2.32.4.20260107; extra == 'dev'
Requires-Dist: types-tabulate>=0.10.0.20260308; extra == 'dev'
Description-Content-Type: text/markdown

# temet-jira

A comprehensive Jira API client and CLI tool for interacting with Jira Cloud instances.
Built for AI agents and automation workflows — retrieve tickets, create rich ADF content, and analyze workflow state durations.

## Table of Contents

- [Features](#features)
- [Quick Start](#quick-start)
  - [Installation](#installation)
  - [Configuration](#configuration)
  - [First Commands](#first-commands)
- [CLI Commands](#cli-commands)
- [MCP Server](#mcp-server)
- [Claude Code Integration](#claude-code-integration)
- [Python API](#python-api)
- [Development](#development)
- [Requirements](#requirements)

## Features

- **Agent-First Design** — Enable AI agents to retrieve tickets, parse requirements, and create implementation plans
- **Jira API Client** — Python and CLI interface to Jira Cloud REST API v3
- **Structured Data Export** — Export issues in JSON, JSONL, CSV formats optimized for agent processing
- **Document Builder** — Programmatically create ADF-formatted issues and epics with proper structure
- **Workflow Analysis** — Analyze state durations and bottlenecks for retrospectives
- **Epic Management** — Retrieve epics with children, filter by sprint, group by assignee/status
- **JQL Support** — Advanced filtering for complex queries and batch operations
- **Claude Code Integration** — Skills, slash commands, and an MCP server for AI-assisted workflows

## Quick Start

### Installation

**Recommended: install as a global tool with uv**

```bash
uv tool install temet-jira
```

**Alternative: pipx**

```bash
pipx install temet-jira
```

Verify:

```bash
temet-jira --help
```

### Configuration

Run the interactive setup wizard:

```bash
temet-jira setup
```

This guides you through:
1. Your Jira URL (e.g. `https://your-company.atlassian.net`)
2. Your email address
3. API token — generate one at https://id.atlassian.com/manage-profile/security/api-tokens
4. Optional default project key

Configuration is saved to `~/.config/temet-jira/config.yaml`.

**Alternative: environment variables**

```bash
export JIRA_BASE_URL="https://your-company.atlassian.net"
export JIRA_USERNAME="your-email@example.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_DEFAULT_PROJECT="PROJ"          # optional
export JIRA_DEFAULT_FORMAT="json"           # optional: table (default), json, jsonl, csv
```

Check your current configuration at any time:

```bash
temet-jira config show
```

**Multiple Jira instances (named profiles)**

Each profile is a separate Jira instance in `~/.config/temet-jira/config.yaml`:

```bash
temet-jira config profile add work          # setup wizard for the 'work' profile
temet-jira config profile list
temet-jira --profile work search "project = PROJ"
```

Profile selection precedence (highest first): `--profile` flag → a per-project
`./.temet-jira.yaml` (`profile:`) → `TEMET_JIRA_PROFILE` → `default_profile` →
`default`. A committed `.temet-jira.yaml` can also set non-sensitive defaults
(`project`, `component`, …) so `cd`-ing into a repo auto-selects the right instance —
credentials always stay in the named profile, never in the project file.

### First Commands

```bash
# Get issue details
temet-jira get PROJ-123

# Search for issues using JQL
temet-jira search "project = PROJ AND status = 'In Progress'"

# List available issue types for a project
temet-jira types --project PROJ

# Create a task
temet-jira create --project PROJ --type Task --summary "Fix login bug"

# Export to CSV
temet-jira export --project PROJ --format csv -o tickets.csv
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `setup` | Interactive setup wizard |
| `config` | View and manage configuration (`show`, `get`, `set`, `unset`, `path`, `edit`) |
| `get` | Get details of a Jira issue |
| `search` | Search for issues using JQL |
| `types` | List available issue types for a project |
| `create` | Create a new issue with ADF formatting |
| `update` | Update issue fields or transition status |
| `comment` | Add a comment to an issue |
| `transitions` | Show available status transitions for an issue |
| `epics` | List all epics in a project |
| `epic-details` | Get epic details with child issues |
| `export` | Export issues with filtering (JSON, JSONL, CSV, table) |
| `analyze` | Analyze workflow state durations |

**Examples:**

```bash
temet-jira get PROJ-123                                  # Issue details
temet-jira search "assignee = currentUser()"            # JQL search
temet-jira types --project PROJ                         # Available issue types
temet-jira create --project PROJ --type Story \
    --summary "New feature" --priority High             # Create issue
temet-jira update PROJ-123 --status "Done"              # Transition status
temet-jira comment PROJ-123 "Deployed to staging"       # Add comment
temet-jira export --project PROJ --format jsonl \
    -o issues.jsonl                                     # Export (streaming)
temet-jira analyze state-durations issues.json          # Workflow analysis
```

**Output formats:** `table` (console default), `json`, `jsonl` (streaming, best for large datasets), `csv`

## MCP Server

`temet-jira` ships with a built-in MCP server (`temet-jira-mcp`) compatible with any MCP-enabled client: Claude Code, Cursor, Windsurf, VS Code Copilot, Zed, and others.

**Guided setup:**

```bash
temet-jira mcp add
```

This scans your system for existing config files, asks where you want to install, and prints the exact JSON snippet to paste — including the right format for your client.

**List available tools:**

```bash
temet-jira mcp tools
```

**Exposed tools:**

| Tool | Description |
|------|-------------|
| `get_issue` | Fetch a single issue by key (supports expand: transitions, changelog) |
| `search_issues` | Search with JQL, returns paginated results |
| `create_issue` | Create a new issue with optional description, labels, priority |
| `update_issue` | Update fields or transition status |
| `add_comment` | Add a comment to an issue |
| `get_transitions` | List available status transitions for an issue |
| `transition_issue` | Move an issue to a new status |
| `get_epics` | List epics in a project |
| `get_issue_types` | List available issue types for a project |

**Manual config** (if you prefer): run `temet-jira mcp add` and choose "Other" for a generic snippet you can adapt to any client.

## Claude Code Integration

Slash commands are available in `.claude/commands/jira/` — use with the `/jira:` prefix in Claude Code:

| Command | Description |
|---------|-------------|
| `/jira:get PROJ-123` | Get ticket details |
| `/jira:search "JQL query"` | Search with JQL |
| `/jira:create` | Create an issue |
| `/jira:update PROJ-123` | Update an issue |
| `/jira:comment PROJ-123 "message"` | Add a comment |
| `/jira:export` | Export issues |
| `/jira:epics` | List epics |
| `/jira:epic-details PROJ-123` | Epic with children |
| `/jira:transitions PROJ-123` | Show transitions |

Skills in `.claude/skills/` provide reference documentation for Claude:

| Skill | Description |
|-------|-------------|
| `jira-api` | Jira REST API v3 documentation, endpoints, JQL patterns |
| `jira-builders` | CLI usage guide and best practices |
| `build-jira-document-format` | ADF builder patterns |
| `work-with-adf` | Atlassian Document Format creation |

## Python API

```python
from temet_jira import JiraClient, IssueBuilder, EpicBuilder

# Fetch an issue
client = JiraClient()
issue = client.get_issue("PROJ-123")

# Create a structured issue with ADF content
builder = IssueBuilder(title="New feature", story_points=8)
builder.add_description("Feature description")
builder.add_acceptance_criteria(["Criteria 1", "Criteria 2"])

client.create_issue({
    "project": {"key": "PROJ"},
    "summary": "New feature",
    "issuetype": {"name": "Story"},
    "description": builder.build(),
})
```

Also available: `JiraDocumentBuilder` (raw ADF builder), `SubtaskBuilder`, `StateDurationAnalyzer`.

## Development

```bash
# Clone and install dev dependencies
git clone https://github.com/temet-ai/temet-jira.git
cd temet-jira
uv sync --extra dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=temet_jira

# Lint and type check
uv run ruff check src/ tests/
uv run mypy src/

# After code changes, rebuild the installed binary
uv build && uv tool install . --force --refresh-package temet-jira
```

### Project Structure

```
temet-jira/
├── src/temet_jira/          # Main package
│   ├── client.py            # JiraClient API
│   ├── formatter.py         # Document builders (legacy entry point)
│   ├── cli.py               # CLI commands
│   ├── mcp_server.py        # MCP server
│   ├── document/            # ADF document builder
│   └── analysis/            # State duration analysis
├── .claude/
│   ├── commands/            # Slash commands for Claude Code
│   └── skills/              # Reference skills
├── tests/                   # Test suite
└── pyproject.toml
```

## Requirements

- **Python 3.11+**
- **uv** or **pipx** for installation
- **Jira Cloud** (REST API v3)
- **Valid Jira API token**

## License

MIT

## Support

- Open an issue at https://github.com/temet-ai/temet-jira/issues
