# Jira MCP Server

將 Jira Data Center 操作封裝為 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 工具，讓 AI 助手能直接操作 Jira。

## 特色

- 使用 Streamable HTTP 傳輸，支援多 session 並行
- 純 JavaScript (CommonJS)，無 TypeScript、無建置步驟
- 所有模組皆採用 Factory Function + Dependency Injection，方便測試
- 零外部測試框架，使用 Node.js 22 內建 `node:test` + `node:assert`

## 需求

- Node.js >= 22
- Jira Data Center（REST API v2）

## 快速開始

### 1. 安裝依賴

```bash
npm install
```

### 2. 設定環境變數

複製 `.env.example` 為 `.env` 並填入：

```bash
JIRA_URL=https://your-jira-server.com
JIRA_USERNAME=your-username
JIRA_PASSWORD='your-password'
```

| 變數 | 說明 |
|---|---|
| `JIRA_URL` | Jira 伺服器 URL（結尾斜線會自動移除） |
| `JIRA_USERNAME` | Jira 登入帳號 |
| `JIRA_PASSWORD` | Jira 登入密碼（密碼含 `$` 時用單引號包裹） |

伺服器在缺少任一變數時會立即結束並提示錯誤。

### 3. 啟動伺服器

```bash
npm start
```

伺服器啟動於 `http://localhost:55522/mcp`。

## MCP 工具一覽

| 工具 | 說明 |
|---|---|
| `jira_get_projects` | 列出所有 Jira 專案 |
| `jira_create_issue` | 建立新工作單（支援 Epic Link、Implementer 等自訂欄位） |
| `jira_get_issue` | 取得工作單詳細資訊 |
| `jira_update_issue` | 更新工作單欄位 |
| `jira_search_issues` | 用 JQL 搜尋 Issues |
| `jira_transition_issue` | 變更工作單狀態（如：In Progress、Done） |
| `jira_add_comment` | 對工作單新增留言 |
| `jira_get_my_issues` | 取得目前登入者的未完成工作單 |
| `jira_list_fields` | 列出所有欄位（用於查詢 custom field ID） |

## 自訂欄位對應

| 欄位 ID | 語義名稱 | 格式 |
|---|---|---|
| `customfield_10108` | Start Date (Gantt) | `YYYY-MM-DDT00:00:00.000+0800` |
| `customfield_10109` | End Date (Gantt) | `YYYY-MM-DDT23:59:00.000+0800` |
| `customfield_10101` | Epic Link | Issue Key（如 `P26-10`） |
| `customfield_10111` | Implementer | `{ name: "username" }` |

## 專案結構

```
jira-mcp-server.js          # 入口點：loadEnv → createConfig → createJiraClient → main()
src/
  load-env.js                # .env 檔案解析
  config.js                  # 環境變數驗證，產生 config 物件
  jira-client.js             # HTTP client（Basic Auth，支援自簽憑證）
  tool-definitions.js        # 9 個工具的 JSON Schema 定義
  tool-handlers.js           # 工具實作邏輯 + 自訂欄位常數
  server.js                  # Express + MCP Server 設定
test/
  *.test.js                  # 對應每個模組的測試
```

## 測試

```bash
npm test
```

## 在 AI 助手中使用

先啟動伺服器（`npm start`），再依據需求選擇合適的設定層級。

### Claude Code

Claude Code 支援三種 MCP 設定層級，優先順序為 **local > project > user**：

| 層級 | 檔案位置 | 共享 | 適用情境 |
|---|---|---|---|
| **user** | `~/.claude.json` | 否 | 個人常用，所有專案皆可使用 |
| **local**（預設） | `~/.claude.json` | 否 | 僅在特定專案目錄內生效 |
| **project** | `<專案根目錄>/.mcp.json` | 是（提交至 git） | 團隊共用，成員首次使用時會提示確認 |

#### 方法一：CLI 指令

```bash
# user 層級 — 所有專案都能用
claude mcp add jira --transport http --scope user http://localhost:55522/mcp

# local 層級 — 僅目前專案（預設）
claude mcp add jira --transport http http://localhost:55522/mcp

# project 層級 — 團隊共用（會寫入 .mcp.json）
claude mcp add jira --transport http --scope project http://localhost:55522/mcp
```

#### 方法二：手動編輯設定檔

**user / local**（`~/.claude.json`）：

```json
{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "http://localhost:55522/mcp"
    }
  }
}
```

**project**（專案根目錄 `.mcp.json`，提交至版本控制）：

```json
{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "http://localhost:55522/mcp"
    }
  }
}
```

### 其他 MCP 相容客戶端

任何支援 MCP Streamable HTTP 傳輸的客戶端皆可連線，端點為：

```
http://localhost:55522/mcp
```

## 致謝

原始版本由 **Bob Chen** 開發，後續由 Danny Chou 維護與修改。