Redmine MCP Server

# Redmine 完整設定指南 本指南提供詳細的 Redmine 初始化設定步驟，確保能夠正常使用 redmine-mcp 工具。 ## 🎯 設定概覽 Redmine 設定需要以下步驟： 1. ✅ 啟用 REST API 2. ✅ 設定系統基本資料 3. ✅ 建立專案 4. ✅ 取得 API 金鑰 ## 📋 詳細設定步驟 ### 1. 啟用 REST API > **必須以管理員身份執行** 1. 登入 Redmine 管理介面 2. 前往 **管理** → **設定** → **API** 3. 勾選 **「啟用 REST 網路服務技術（Web Service）」** 4. 點擊 **儲存** ### 2. 設定角色與權限 > **建議的最小權限設定** **建立角色** 1. 前往 **管理** → **角色與權限** 2. 點擊 **新增角色** 3. 建立以下角色： | 角色名稱 | 建議權限 | |---------|---------| | 開發者 | 查看議題、新增議題、編輯議題、新增備註、管理議題觀察者 | | 測試者 | 查看議題、新增議題、編輯議題、新增備註 | | 專案經理 | 所有議題相關權限、查看專案、管理成員 | **關鍵權限設定** - ✅ **查看議題** - 必要，用於 `get_issue`、`list_project_issues` 等 - ✅ **新增議題** - 必要，用於 `create_new_issue` - ✅ **編輯議題** - 必要，用於 `update_issue_status`、`assign_issue` 等 - ✅ **新增備註** - 必要，用於 `add_issue_note` - ✅ **管理議題觀察者** - 選擇性，用於觀察者功能 ### 3. 設定追蹤器 > **建議的基本追蹤器類型** 1. 前往 **管理** → **追蹤器** 2. 建立以下追蹤器： | 追蹤器名稱 | 用途 | 預設狀態 | |-----------|------|---------| | 缺陷 (Bug) | 軟體錯誤追蹤 | 新建 | | 功能 (Feature) | 新功能需求 | 新建 | | 支援 (Support) | 技術支援請求 | 新建 | **設定追蹤器屬性** - 設定每個追蹤器的**預設狀態** - 選擇適用的**自訂欄位**（如果有的話） ### 4. 設定議題狀態 > **建議的基本狀態設定** 1. 前往 **管理** → **議題狀態** 2. 建立以下狀態： | 狀態名稱 | 是否已關閉 | 用途 | |---------|-----------|------| | 新建 | ❌ | 剛建立的議題 | | 進行中 | ❌ | 正在處理的議題 | | 等待回饋 | ❌ | 等待用戶回應 | | 已解決 | ❌ | 已修復但待驗證 | | 已關閉 | ✅ | 已完成的議題 | | 已拒絕 | ✅ | 不會處理的議題 | **重要設定** - 至少要有一個「已關閉」狀態（用於 `close_issue` 工具） - 設定適當的**狀態顏色**以便視覺區分 ### 6. 設定議題優先級 > **定義議題重要性等級** 1. 前往 **管理** → **列舉值** → **議題優先級** 2. 建立或編輯優先級： | 優先級名稱 | 建議用途 | 設為預設 | |-----------|---------|---------| | 低 | 非緊急的改善 | ❌ | | 正常 | 一般議題 | ✅ | | 高-這邊拜處理 | 重要功能或錯誤，優先處理 | ❌ | | 速-這兩天處理 | 緊急議題，需在2天內處理 | ❌ | | 急-馬上處理 | 嚴重錯誤，需立即處理 | ❌ | ### 7. 設定時間追蹤活動 > **定義工作類型（如果啟用時間追蹤模組）** 1. 前往 **管理** → **列舉值** → **時間追蹤的活動** 2. 建立活動類型： | 活動名稱 | 用途 | 設為預設 | |---------|------|---------| | 設計 | 系統設計和規劃 | ✅ | | 開發 | 程式開發和編碼 | ❌ | | 除錯 | 程式錯誤修復 | ❌ | | 調查 | 問題分析和研究 | ❌ | | 討論 | 會議和技術討論 | ❌ | | 測試 | 測試和品質保證 | ❌ | | 維護 | 系統維護和支援 | ❌ | | 文件 | 文件撰寫和維護 | ❌ | | 教學 | 培訓和知識分享 | ❌ | | 翻譯 | 多語言本地化工作 | ❌ | | 其他 | 其他類型的工作 | ❌ | ### 8. 設定文件分類 > **定義文件組織類別（如果啟用文件模組）** 1. 前往 **管理** → **列舉值** → **文件分類** 2. 建立文件分類： | 分類名稱 | 用途 | 設為預設 | |---------|------|---------| | 使用手冊 | 使用者操作手冊和說明 | ✅ | | 技術文件 | 技術規格和設計文件 | ❌ | | 申請表單 | 各種申請和表單文件 | ❌ | | 需求文件 | 系統需求和功能說明 | ❌ | ### 9. 設定工作流程 > **定義狀態轉換規則** 1. 前往 **管理** → **工作流程** 2. 選擇**角色**和**追蹤器**組合 3. 設定允許的狀態轉換 **建議的基本工作流程** ``` 新建 → 進行中 → 已解決 → 已關閉 ↓ ↓ ↓ 等待回饋 ← ← ← ← ← ← ← ← ← (任何狀態) ↓ 已拒絕 ``` **重要提醒** - 確保每個角色都能進行基本的狀態轉換 - 測試關鍵路徑：新建 → 進行中 → 已關閉 - 確認 `close_issue` 工具需要的轉換路徑可用 ### 10. 建立專案 > **設定第一個測試專案** 1. 前往 **專案** → **新增專案** 2. 填寫專案資訊： - **名稱**：測試專案 - **識別碼**：test-project（用於 API 呼叫） - **描述**：用於測試 MCP 工具的專案 - **首頁**：（選填） 3. **選擇模組**： - ✅ 議題跟蹤 - ✅ 時間追蹤（選擇性） - ✅ 文件（選擇性） - ✅ 檔案（選擇性） 4. **設定追蹤器**： - 選擇專案要使用的追蹤器類型 - 建議至少選擇「缺陷」和「功能」 5. **指派成員**： - 新增用戶到專案 - 分配適當的角色 ### 11. 驗證設定 > **測試基本功能是否正常** **使用 MCP 工具測試** 1. 取得 API 金鑰並設定環境變數 2. 執行以下測試： ```bash # 測試連線 uv run python -c " from redmine_mcp.server import health_check print(health_check()) " # 測試專案列表 uv run python -c " from redmine_mcp.server import get_projects print(get_projects()) " # 測試狀態列表 uv run python -c " from redmine_mcp.server import get_issue_statuses print(get_issue_statuses()) " # 測試追蹤器列表 uv run python -c " from redmine_mcp.server import get_trackers print(get_trackers()) " # 測試優先級列表 uv run python -c " from redmine_mcp.server import get_priorities print(get_priorities()) " # 測試時間追蹤活動列表 uv run python -c " from redmine_mcp.server import get_time_entry_activities print(get_time_entry_activities()) " # 測試文件分類列表 uv run python -c " from redmine_mcp.server import get_document_categories print(get_document_categories()) " ``` **手動測試建立議題** 1. 在專案中手動建立一個測試議題 2. 嘗試變更議題狀態 3. 新增備註測試 ## 🚨 常見問題 ### 問題：無法建立議題 **可能原因** - 工作流程未正確設定 - 用戶權限不足 - 追蹤器設定問題 **解決方法** 1. 檢查工作流程中是否允許從「無狀態」到「新建」 2. 確認用戶在專案中有「新增議題」權限 3. 確認追蹤器已啟用且有預設狀態 ### 問題：無法更新議題狀態 **可能原因** - 工作流程不允許該狀態轉換 - 用戶角色權限不足 **解決方法** 1. 檢查工作流程設定 2. 確認用戶有「編輯議題」權限 3. 測試手動狀態轉換 ### 問題：找不到專案或議題 **可能原因** - 用戶沒有查看權限 - 專案狀態為封存 **解決方法** 1. 確認用戶是專案成員 2. 檢查專案狀態是否為「啟用」 3. 確認用戶有「查看議題」權限 ## 📝 設定檢查清單 在開始使用 redmine-mcp 之前，請確認： - [ ] ✅ REST API 已啟用 - [ ] ✅ 至少建立一個角色（具備基本議題權限） - [ ] ✅ 至少建立一個追蹤器 - [ ] ✅ 建立基本的議題狀態（包含至少一個「已關閉」狀態） - [ ] ✅ 設定議題優先級（建議至少有：低、正常、高、緊急） - [ ] ✅ 設定時間追蹤活動（如果使用時間追蹤功能） - [ ] ✅ 設定文件分類（如果使用文件模組） - [ ] ✅ 設定基本的工作流程（允許狀態轉換） - [ ] ✅ 建立至少一個專案 - [ ] ✅ 將用戶加入專案並分配角色 - [ ] ✅ 取得 API 金鑰 - [ ] ✅ 測試基本 MCP 功能 ## 🔗 相關資源 - [Redmine 管理指南](https://www.redmine.org/projects/redmine/wiki/RedmineAdministration) - [Redmine REST API 文件](https://www.redmine.org/projects/redmine/wiki/Rest_api) - [工作流程設定](https://www.redmine.org/projects/redmine/wiki/RedmineWorkflow) - [角色與權限](https://www.redmine.org/projects/redmine/wiki/RedmineRoles) --- 完成這些設定後，您就可以開始使用 redmine-mcp 的所有功能了！