litejira-mcp

讓你的 AI 助手（Claude Code / Cursor / ChatGPT Desktop）直接讀寫 LiteJira 工單系統。

這是一個 MCP server（純客戶端包裝）。它只負責「怎麼跟 LiteJira API 對話」，不含任何工單資料、後端邏輯或祕密——就像 chrome-devtools-mcp 不含 Chrome 的原始碼。你的存取權杖只存在你自己電腦上。

安裝（一句指令）

前提：Node.js 18 以上。

推薦：全域安裝（更新最穩，避開 npx 快取與多開 session 兩個已知坑）

npm install -g litejira-mcp
claude mcp add litejira --scope user -- litejira-mcp

快速：用 npx（免全域安裝，但多開 session 偶爾連不上、更新需清快取）

claude mcp add litejira --scope user -- npx -y litejira-mcp@latest

裝完設定一次權杖（見下），重啟 AI 工具即可用。

Related MCP server: Personal JIRA MCP

更新（一句指令）

全域安裝者：

npm update -g litejira-mcp

然後完全關閉並重新打開你的 AI 工具。沒有手動拉檔、不用清快取。

npx 安裝者：npx 會快取舊版，重啟未必更新到最新；要更新請跑 npx --cache-clear 後重啟，或改用上面的全域安裝。

設定權杖（一次性）

1. 找 admin 在 LiteJira webapp「設定 → Token」幫你建一把 PAT（ltj_pat_xxxxx），順便要 LTJ_API_URL。

2. 在你電腦的家目錄建檔 ~/.litejira/credentials.env：

Mac / Linux

mkdir -p ~/.litejira
cat > ~/.litejira/credentials.env << 'EOF'
LTJ_API_URL=<向 admin 索取>
LTJ_API_TOKEN=<貼你的 ltj_pat_ 權杖>
LTJ_MCP_ENABLE_WRITES=true
EOF

Windows（PowerShell）

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.litejira"
@"
LTJ_API_URL=<向 admin 索取>
LTJ_API_TOKEN=<貼你的 ltj_pat_ 權杖>
LTJ_MCP_ENABLE_WRITES=true
"@ | Set-Content "$env:USERPROFILE\.litejira\credentials.env"

權杖只存在你電腦上、不進 git。離職或不用了，找 admin 在 webapp 撤銷。

測試

跟 AI 說：「用 LiteJira 搜尋最新的 BUG」。看到工單列表 = 成功。

進階：dev / prod 雙環境（維護者用）

一般使用者忽略本段。若你要同時連正式與測試兩套 LiteJira，啟動器接受一個環境參數：

.mcp.json 範例（兩條並存）：

"litejira":     { "command": "litejira-mcp", "args": ["prod"] },
"litejira-dev": { "command": "litejira-mcp", "args": ["dev"] }

能做什麼

AI 會自動載入成員清單、版本列表、工作流規則。

搜尋預設使用 compact 模式，每張只回 12 個清單判讀需要的核心欄位，降低大型結果對 AI 上下文的占用。只需要數量時可指定 responseMode=count；只有確實需要清單完整欄位時才用 responseMode=full，單張完整內容優先讀 litejira://ticket/{id}。

故障排除

第二段取結果失敗（leg2_result_unavailable）

2.12.3 新增結果回跳辨識與第一次失敗資訊保留。此版本修正錯誤分類，未解決間歇性結果取得失敗。

呼叫分兩段跑：第一段 POST /exec 觸發指令碼，第二段再去取回結果。 取結果的請求有時被 302 導回應用程式入口，也可能先回 404、重取時才發生這個導向； 那個入口用 GET 打會回一頁 HTTP 200 的「無權限」HTML，看起來很像權限問題， 但本工具只能證明「結果取不回來」，不知道 Google 端內部原因， 不能反過來斷定帳號或工單權限沒問題。本工具認得這種導向：不會發出那個 GET， 也不會繼續重取同一網址，並改報 leg2_result_unavailable，保留先前的失敗資訊。

• 本工具只能分類與止血：無法確認上游根因，也無法讓結果變回來。重跑有機會過， 但不保證。

• 寫入動作請先查現況再重送：無法確認指令碼是否已執行完，留言／連結／狀態變更 仍可能已生效，只是結果取不回來。伺服器端不對 idempotencyKey 去重， 直接重送有可能寫第二遍。錯誤訊息會標示「寫入仍可能已生效」，並帶 transient=false 擋掉呼叫端的自動重試。

零外部相依，只需 Node.js 18+。

License

MIT