# 🚀 Jira MCP Server

**Jira MCP Server** là cầu nối giữa AI và Jira Cloud. Thay vì phải vào web Jira để tạo issue, tìm kiếm, cập nhật trạng thái — bạn chỉ cần nói hoặc gõ lệnh, AI sẽ làm thay.

Ví dụ:
- *"Tạo issue bug cho project DEV, mô tả lỗi login bị 500"*
- *"Tìm tất cả issues đang In Progress được gán cho tôi"*
- *"Chuyển issue DEV-123 sang Done"*
- *"Phân tích yêu cầu này thành các task trong sprint"*

---

## ✨ Tính năng (16 Tools)

### 📋 Quản lý Issue
| Câu lệnh | Server làm |
|---|---|
| "Tạo issue mới" | Tạo issue với project, summary, type, priority, labels, assignee |
| "Xem issue DEV-123" | Lấy chi tiết issue (status, assignee, description ADF đẹp) |
| "Sửa issue DEV-123" | Cập nhật summary, description, priority, labels, assignee |
| "Xoá issue DEV-123" | Xoá vĩnh viễn |
| "Tìm issue bị lỗi" | Search bằng JQL — mạnh mẽ, linh hoạt |

### 💬 Comments & Workflow
| Câu lệnh | Server làm |
|---|---|
| "Thêm comment vào DEV-123" | Ghi comment |
| "Chuyển DEV-123 sang In Progress" | Chuyển trạng thái workflow |

### 📂 Projects & Sprint
| Câu lệnh | Server làm |
|---|---|
| "Liệt kê projects" | Danh sách projects |
| "Board nào đang có?" | Danh sách boards |
| "Tạo sprint mới" | Tạo sprint với tên, thời gian, mục tiêu |
| "Issues trong sprint 5?" | Tất cả issues trong sprint |

### 👤 Users
| Câu lệnh | Server làm |
|---|---|
| "Tìm user tên An" | Search users theo tên, email |

> **Mô tả issue tự động render đẹp:** khi bạn nhập description dạng Markdown (## heading, - bullet list), server tự động chuyển sang **Atlassian Document Format (ADF)** — hiển thị headings, lists, paragraphs rõ ràng trong Jira.

---

## 🛠️ Cài đặt

### Yêu cầu
- Python 3.10+
- Tài khoản Jira Cloud (free cũng được)
- Jira API Token
- Git (clone project)

### 1. Clone & cài đặt

```bash
git clone https://github.com/rifujin123/jira-mcp.git
cd jira-mcp

# Tạo môi trường ảo
python -m venv .venv

# Kích hoạt
# Windows:
.venv\Scripts\activate
# Mac / Linux:
source .venv/bin/activate

# Cài thư viện
pip install -r requirements.txt

# Tạo file .env từ mẫu
cp .env.example .env
```

### 2. Lấy Jira API Token

1. Vào https://id.atlassian.com/manage/api-tokens
2. Click **Create API token**
3. Đặt tên (VD: `"Jira MCP"`)
4. Copy token

### 3. Điền credentials

Sửa file `.env` với nội dung:

```env
JIRA_URL=https://ten-domain.atlassian.net
JIRA_EMAIL=email-cua-ban@gmail.com
JIRA_API_TOKEN=token-vua-tao
```

### 4. Kiểm tra kết nối

```bash
# Windows:
PYTHONIOENCODING=utf-8 .venv\Scripts\python jira_client.py
# Mac / Linux:
python jira_client.py
```

Nếu thấy danh sách projects là **OK**.

---

## 🔌 Kết nối với MCP Clients

### 🤖 Claude Code (CLI)

**Cách 1: Chạy trực tiếp từ thư mục project**

```bash
claude
```

Nếu đang ở thư mục `jira-mcp`, Claude Code tự động detect file `server.py`. Nếu không, chạy:

```bash
claude --mcp-server "python D:/GITHUB/Jira-mcp/server.py"
```

**Cách 2: Thêm vào config (không cần cd vào project)**

Mở file:
- **Windows:** `%APPDATA%\Claude Code\settings.json`
- **Mac:** `~/Library/Application Support/Claude Code/settings.json`

Thêm vào `mcpServers`:

```json
{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["D:/GITHUB/Jira-mcp/server.py"],
      "env": {
        "JIRA_URL": "https://ten-domain.atlassian.net",
        "JIRA_EMAIL": "email-cua-ban@gmail.com",
        "JIRA_API_TOKEN": "token-cua-ban"
      }
    }
  }
}
```

**Cách 3: Dùng uv (nhanh hơn, không cần cài thủ công)**

```bash
pip install uv
```

```json
{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/jira-mcp",
        "server.py"
      ],
      "env": {
        "JIRA_URL": "https://ten-domain.atlassian.net",
        "JIRA_EMAIL": "email-cua-ban@gmail.com",
        "JIRA_API_TOKEN": "token-cua-ban"
      }
    }
  }
}
```

---

### 🖥️ Claude Desktop App

Mở file config:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["D:/GITHUB/Jira-mcp/server.py"],
      "env": {
        "JIRA_URL": "https://ten-domain.atlassian.net",
        "JIRA_EMAIL": "email-cua-ban@gmail.com",
        "JIRA_API_TOKEN": "token-cua-ban"
      }
    }
  }
}
```

Sau đó **Restart Claude Desktop** → thấy icon cờ lê → Jira tools sẵn sàng.

---

### 📘 VS Code (Visual Studio Code)

Cài extension **Claude Code** hoặc dùng MCP client cho VS Code:

**1. Cài Claude Code extension:**
- Mở VS Code
- Extensions → tìm "Claude Code"
- Cài đặt

**2. Cấu hình trong VS Code:**
- File → Preferences → Settings
- Tìm `claude.mcpServers`
- Add:

```json
{
  "jira": {
    "command": "python",
    "args": ["D:/GITHUB/Jira-mcp/server.py"],
    "env": {
      "JIRA_URL": "https://ten-domain.atlassian.net",
      "JIRA_EMAIL": "email-cua-ban@gmail.com",
      "JIRA_API_TOKEN": "token-cua-ban"
    }
  }
}
```

Hoặc dùng file `.vscode/settings.json` trong project.

---

### ⌨️ Cursor

**1. Mở Cursor Settings:**
- File → Preferences → Cursor Settings
- Tab **MCP**

**2. Add MCP Server:**
```json
{
  "jira": {
    "command": "python",
    "args": ["D:/GITHUB/Jira-mcp/server.py"],
    "env": {
      "JIRA_URL": "https://ten-domain.atlassian.net",
      "JIRA_EMAIL": "email-cua-ban@gmail.com",
      "JIRA_API_TOKEN": "token-cua-ban"
    }
  }
}
```

---

### 🧰 Công cụ MCP Inspector (Test nhanh)

Dùng để test từng tool qua Web UI mà không cần AI client:

```bash
pip install "mcp[cli]"
mcp dev server.py
```

Mở `http://localhost:5173` → thử từng tool trực quan.

---

## 📚 JQL Examples

```jql
// Tất cả issues của project DEV
project = DEV

// Issues đang In Progress, gán cho tôi
assignee = currentUser() AND status = "In Progress"

// Tìm theo từ khoá
text ~ "database error"

// Issues được tạo trong 7 ngày gần đây
created >= -7d

// Priority cao nhất
project = DEV ORDER BY priority DESC, created ASC

// Issues trong sprint cụ thể
sprint = 5

// Bugs chưa được assign
issuetype = Bug AND assignee IS NULL
```

---

## 🧠 Kiến trúc

```
Bạn ── nói ──► AI (Claude/Cursor/...) ── JSON-RPC ──► Jira MCP Server ── HTTP ──► Jira Cloud API
                                                        │
                                                        ▼
                                                16 tools sẵn sàng
```

| Layer | Công nghệ |
|---|---|
| **Transport** | stdio (process-to-process) |
| **Protocol** | MCP (Model Context Protocol) |
| **Jira SDK** | atlassian-python-api |
| **MCP SDK** | FastMCP (Python) |
| **Auth** | Basic Auth (email + API token) |
| **Description** | ADF (Atlassian Document Format) — rich text |

---

## 📁 Cấu trúc project

```
jira-mcp/
├── server.py          # ★ File chính — MCP server, 16 tools
├── jira_client.py     # JiraClient — gọi API, xử lý lỗi, ADF format
├── requirements.txt   # Thư viện cần cài
├── .env               # Credentials Jira (đã có .gitignore)
├── .env.example       # Mẫu file .env
└── README.md          # Bạn đang đọc đây
```

---

## ⚠️ Lỗi thường gặp

| Lỗi | Nguyên nhân | Cách fix |
|---|---|---|
| "Authentication failed" | Sai email hoặc API token | Kiểm tra lại `.env` |
| "Resource not found" | Sai issue key, project key | Kiểm tra lại key |
| "Site temporarily unavailable" | Jira site chưa active | Vào browser kiểm tra |
| "Rate limit exceeded" | Gọi API quá nhanh | Chờ 1 lúc rồi thử lại |
| "Jira Software license" | Board/sprint không có | Nâng cấp plan hoặc bỏ qua |
| `cp1252` encode error | Windows terminal | Thêm `PYTHONIOENCODING=utf-8` |

---

## 📄 License

MIT — tự do dùng, sửa, chia sẻ.