# mcp-tms-jira

Bản fork của [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) (tác giả sooperset, giấy phép MIT,
lấy từ commit `0a5d242`, sau v0.23.1). Bản fork thêm một kiểu xác thực **`chrome_cookie`** cho Jira Server/Data
Center: MCP dùng lại phiên đăng nhập đang có trong Chrome, không cần token. Kiểu này dành cho các Jira mà admin
đã chặn Personal Access Token và chỉ cho đăng nhập qua trình duyệt (SSO, F5…), ví dụ Jira VinFast TMS.

Các kiểu xác thực gốc (basic, PAT, OAuth, mTLS, external) và toàn bộ tool Jira/Confluence vẫn giữ nguyên.
README gốc ở [README.upstream.md](README.upstream.md), giấy phép ở [LICENSE](LICENSE).

## Cài

Cần Linux, [uv](https://docs.astral.sh/uv/) và Chrome đã đăng nhập vào Jira.

```bash
git clone https://github.com/hotamago/mcp-tms-jira.git && cd mcp-tms-jira
uv sync
ln -sf "$PWD/bin/mcp-tms-jira" ~/.local/bin/mcp-tms-jira
claude mcp add --scope user tms-jira -- ~/.local/bin/mcp-tms-jira
```

Sau đó reload MCP trong Claude Code (`/mcp`) hoặc mở lại phiên. Kiểm tra bằng `claude mcp get tms-jira`, kết quả
phải là `✔ Connected`.

Launcher `bin/mcp-tms-jira` đặt sẵn `JIRA_URL=https://tms.vinfast.vn`, `JIRA_AUTH_TYPE=chrome_cookie`,
`CHROME_PROFILE=auto` và `TOOLSETS=all`. Muốn dùng cho Jira khác thì truyền biến môi trường để ghi đè, ví dụ
`claude mcp add --scope user my-jira -e JIRA_URL=https://jira.example.com -- ~/.local/bin/mcp-tms-jira`.

## Cấu hình (biến môi trường)

| Biến | Mặc định | Ý nghĩa |
|---|---|---|
| `JIRA_URL` | (bắt buộc; launcher đặt TMS) | Gốc Jira, ví dụ `https://jira.example.com` |
| `JIRA_AUTH_TYPE` | (tự dò như bản gốc) | Đặt `chrome_cookie` để dùng cookie Chrome. Giá trị khác bị bỏ qua |
| `CHROME_BROWSER` | `chrome` | `chrome`, `chromium`, `brave` hoặc `edge` |
| `CHROME_PROFILE` | `auto` | `auto` nghĩa là thử các profile, profile có file Cookies mới nhất trước. Có thể đặt tên cụ thể: `Default`, `Profile 1`… |
| `CHROME_USER_DATA_DIR` | tự dò | Thư mục user-data của trình duyệt |
| `CHROME_COOKIE_TTL` | `60` | Số giây giữ cookie trong bộ nhớ |
| `TOOLSETS` | `default` (launcher đặt `all`) | Nhóm tool được bật, giống bản gốc |
| `READ_ONLY_MODE` | `false` | `true` thì tắt mọi tool ghi |
| `CONFLUENCE_URL` | trống | Không đặt thì Confluence tắt |
| `MCP_SERVER_INSTRUCTIONS` | (có sẵn) | Ghi đè phần hướng dẫn server gửi cho client |

Các biến khác (`JIRA_TIMEOUT`, `JIRA_SSL_VERIFY`, proxy, `JIRA_PROJECTS_FILTER`…) dùng như bản gốc.

## Cách `chrome_cookie` hoạt động

- Mỗi request tới đúng scheme/host/port của `JIRA_URL` được gắn cookie Chrome của host đó (`JSESSIONID`,
  `atlassian.xsrf.token`, cookie F5…), kèm header `X-Atlassian-Token: no-check`. Cookie được giữ trong bộ nhớ
  `CHROME_COOKIE_TTL` giây.
- Gặp 401/403, phản hồi `anonymous`, hoặc trang HTML trả về cho lời gọi `/rest/`: MCP đọc lại cookie từ Chrome và
  gửi lại **một lần**. Vẫn lỗi thì báo "Open <JIRA_URL> in Chrome, log in again". Nếu 403 vẫn còn sau lần đọc lại
  cookie thì đó là thiếu quyền thật, MCP trả lỗi như bản gốc.
- Không gửi cookie tới host khác. Bị chuyển hướng sang host khác hoặc sang trang đăng nhập thì dừng lại và báo lỗi
  đăng nhập.
- Cookie đọc từ DB của Chrome: chép DB vào thư mục tạm quyền 0700 rồi xoá ngay. Khoá `v11` lấy từ GNOME
  Keyring/libsecret. Giá trị cookie không bao giờ được ghi log hay in ra.

## Ghi lên Jira

Tool ghi (tạo, sửa, chuyển trạng thái, comment, worklog, link, sprint…) vẫn có. Phần hướng dẫn server gửi cho
client nhắc rằng **mọi thao tác ghi phải được người dùng duyệt nguyên văn trước**. Muốn chặn hẳn thì đặt
`READ_ONLY_MODE=true`.

## Giới hạn

- Chỉ chạy trên Linux, trong phiên desktop có D-Bus và GNOME Keyring **đã mở khoá**. Launcher tự đặt
  `DBUS_SESSION_BUS_ADDRESS` nếu MCP host không truyền biến này.
- Cookie hết hạn thì mở `JIRA_URL` trên Chrome, đăng nhập lại, rồi gọi lại tool.
- Trên Jira Server/DC, hai tool chỉ dành cho Cloud (`jira_move_issue`, `jira_batch_get_changelogs`) bị ẩn, giống
  bản gốc. Một số tool khác (ProForma forms, dev-status…) tuỳ plugin trên server có thể báo lỗi.
- Bản fork bỏ `.github/` của upstream (CI, publish), nên test `tests/unit/test_docker_versioning.py` cũng bị bỏ.

## Test

```bash
uv sync
uv run pytest tests/unit -q                       # toàn bộ unit test (giả HTTP, không cần mạng)
uv run pytest tests/unit/utils/test_cookie_auth.py -q   # riêng phần chrome_cookie
```

---

## English summary

Fork of [sooperset/mcp-atlassian](https://github.com/sooperset/mcp-atlassian) (MIT, based on commit `0a5d242`). It
adds a `chrome_cookie` auth type for Jira Server/Data Center. With it, the server reuses the Chrome login session of
the local user instead of a token, which helps when Personal Access Tokens are disabled. All upstream auth types and
tools are kept.

- **Install:** `uv sync`, symlink `bin/mcp-tms-jira` into `~/.local/bin`, then run
  `claude mcp add --scope user tms-jira -- ~/.local/bin/mcp-tms-jira`.
- **Configure:**
  - `JIRA_URL`
  - `JIRA_AUTH_TYPE=chrome_cookie`
  - optional: `CHROME_BROWSER`, `CHROME_PROFILE` (`auto`), `CHROME_USER_DATA_DIR`, `CHROME_COOKIE_TTL` (60 s)
  - `TOOLSETS=all`
  - `READ_ONLY_MODE=true` to disable writes
- **Behaviour:**
  - Cookies are attached only to the `JIRA_URL` origin, together with `X-Atlassian-Token: no-check`.
  - On 401/403, an anonymous reply, or an HTML reply to a `/rest/` call, cookies are re-read once.
  - Cross-host redirects and login-page redirects are refused.
  - Cookie values are never logged.
- **Write policy:** the server instructions tell the client that every write must be approved verbatim by the user
  first.
- **Limitations:**
  - Linux only, with a D-Bus session and an unlocked GNOME Keyring.
  - When the session expires, log in again in Chrome.