Redmine MCP Server

# API 參考文件 本文件詳細說明 Redmine MCP Server 提供的所有 MCP 工具及其參數。 ## 📋 目錄 1. [基本工具](#基本工具) 2. [議題查詢工具](#議題查詢工具) 3. [議題操作工具](#議題操作工具) 4. [專案管理工具](#專案管理工具) 5. [搜尋工具](#搜尋工具) 6. [參數類型說明](#參數類型說明) 7. [錯誤處理](#錯誤處理) ## 🔧 基本工具 ### server_info 取得服務器資訊和狀態。 **參數：** 無 **回傳：** ``` Redmine MCP 服務器已啟動 - Redmine 網域: https://your-redmine.com - 除錯模式: false - API 逾時: 30秒 ``` **使用範例：** ```python # 在 Claude Code 中 顯示服務器資訊 ``` --- ### health_check 健康檢查工具，確認服務器正常運作。 **參數：** 無 **回傳：** - 成功：`✓ 服務器正常運作，已連接到 {domain}` - 失敗：`✗ 無法連接到 Redmine 服務器: {domain}` 或 `✗ 服務器異常: {error}` **使用範例：** ```python # 在 Claude Code 中 執行健康檢查 ``` ## 📄 議題查詢工具 ### get_issue 取得指定的 Redmine 議題詳細資訊。 **參數：** - `issue_id` (int, 必填)：議題 ID - `include_details` (bool, 可選)：是否包含詳細資訊（預設 true） **回傳：** 議題的詳細資訊，包含基本資訊和描述 **使用範例：** ```python # 在 Claude Code 中 取得議題 #123 的詳細資訊 取得議題 #456 的基本資訊（不包含詳細資料） ``` --- ### list_project_issues 列出專案的議題。 **參數：** - `project_id` (int, 必填)：專案 ID - `status_filter` (str, 可選)：狀態篩選，可選值 "open", "closed", "all"（預設 "open"） - `limit` (int, 可選)：最大回傳數量，範圍 1-100（預設 20） **回傳：** 專案議題列表，以表格格式呈現 **使用範例：** ```python # 在 Claude Code 中 列出專案 1 的所有開放議題 顯示專案 2 中已關閉的議題，限制 10 筆 列出專案 3 的所有議題 ``` --- ### get_my_issues 取得指派給當前用戶的議題列表。 **參數：** - `status_filter` (str, 可選)：狀態篩選，可選值 "open", "closed", "all"（預設 "open"） - `limit` (int, 可選)：最大回傳數量，範圍 1-100（預設 20） **回傳：** 當前用戶的議題列表 **使用範例：** ```python # 在 Claude Code 中 顯示我的所有開放議題 取得我的已完成議題，限制 15 筆 ``` ## ✏️ 議題操作工具 ### create_new_issue 建立新的 Redmine 議題。 **參數：** - `project_id` (int, 必填)：專案 ID - `subject` (str, 必填)：議題標題 - `description` (str, 可選)：議題描述 - `tracker_id` (int, 可選)：追蹤器 ID - `priority_id` (int, 可選)：優先級 ID - `assigned_to_id` (int, 可選)：指派給的用戶 ID **回傳：** 建立結果訊息，包含新議題的基本資訊 **使用範例：** ```python # 在 Claude Code 中 在專案 1 中建立議題「修復登入錯誤」，描述「用戶無法正常登入」 建立議題：標題「新功能開發」，專案 ID 2，追蹤器 ID 2，優先級 ID 3 ``` --- ### update_issue_status 更新議題狀態。 **參數：** - `issue_id` (int, 必填)：議題 ID - `status_id` (int, 必填)：新的狀態 ID - `notes` (str, 可選)：更新備註 **回傳：** 更新結果訊息 **使用範例：** ```python # 在 Claude Code 中 將議題 #123 狀態更新為 3（已解決） 更新議題 #456 狀態為 2，備註「開始處理此問題」 ``` --- ### update_issue_content 更新議題內容（標題、描述、優先級、完成度等）。 **參數：** - `issue_id` (int, 必填)：議題 ID - `subject` (str, 可選)：新的議題標題 - `description` (str, 可選)：新的議題描述 - `priority_id` (int, 可選)：新的優先級 ID - `done_ratio` (int, 可選)：新的完成百分比 0-100 **回傳：** 更新結果訊息 **使用範例：** ```python # 在 Claude Code 中 更新議題 #123 的標題為「修復用戶登入問題」 將議題 #456 完成度設為 80% 更新議題 #789 的描述和優先級 ``` --- ### add_issue_note 為議題新增備註。 **參數：** - `issue_id` (int, 必填)：議題 ID - `notes` (str, 必填)：備註內容 - `private` (bool, 可選)：是否為私有備註（預設 false） **回傳：** 新增結果訊息 **使用範例：** ```python # 在 Claude Code 中 為議題 #123 新增備註「已完成初步分析」 為議題 #456 新增私有備註「內部討論結果」 ``` --- ### assign_issue 指派議題給用戶。 **參數：** - `issue_id` (int, 必填)：議題 ID - `user_id` (int, 可選)：指派給的用戶 ID（如果為 None 則取消指派） - `notes` (str, 可選)：指派備註 **回傳：** 指派結果訊息 **使用範例：** ```python # 在 Claude Code 中 將議題 #123 指派給用戶 ID 5 取消議題 #456 的指派 指派議題 #789 給用戶 3，備註「請協助處理」 ``` --- ### close_issue 關閉議題（設定為已完成狀態）。 **參數：** - `issue_id` (int, 必填)：議題 ID - `notes` (str, 可選)：關閉備註 - `done_ratio` (int, 可選)：完成百分比（預設 100） **回傳：** 關閉結果訊息 **使用範例：** ```python # 在 Claude Code 中 關閉議題 #123 關閉議題 #456，備註「問題已解決」 關閉議題 #789，完成度 100%，備註「測試通過」 ``` ## 🗂️ 專案管理工具 ### get_projects 取得可存取的專案列表。 **參數：** 無 **回傳：** 格式化的專案列表，包含 ID、識別碼、名稱、狀態 **使用範例：** ```python # 在 Claude Code 中 顯示所有可存取的專案 取得專案列表 ``` --- ### get_issue_statuses 取得所有可用的議題狀態列表。 **參數：** 無 **回傳：** 格式化的狀態列表，包含 ID、名稱、是否已關閉 **使用範例：** ```python # 在 Claude Code 中 顯示所有可用的議題狀態 取得狀態列表 ``` ## 🔍 搜尋工具 ### search_issues 搜尋議題（在標題或描述中搜尋關鍵字）。 **參數：** - `query` (str, 必填)：搜尋關鍵字 - `project_id` (int, 可選)：限制在特定專案中搜尋 - `limit` (int, 可選)：最大回傳數量，範圍 1-50（預設 10） **回傳：** 符合搜尋條件的議題列表 **使用範例：** ```python # 在 Claude Code 中 搜尋包含「登入」的議題 在專案 1 中搜尋「效能」相關議題 搜尋「錯誤」關鍵字，限制 20 筆結果 ``` ## 📝 參數類型說明 ### 資料類型 | 類型 | 說明 | 範例 | |------|------|------| | `int` | 整數 | `123`, `0`, `-5` | | `str` | 字串 | `"議題標題"`, `"備註內容"` | | `bool` | 布林值 | `true`, `false` | ### 常用 ID 對應 #### 狀態 ID (status_id) 通常的對應關係（可能因 Redmine 設定而異）： - `1`: 新建 - `2`: 進行中 - `3`: 已解決 - `4`: 回饋中 - `5`: 已關閉 - `6`: 已拒絕 #### 優先級 ID (priority_id) 通常的對應關係： - `1`: 低 - `2`: 正常 - `3`: 高 - `4`: 緊急 - `5`: 立即 #### 追蹤器 ID (tracker_id) 通常的對應關係： - `1`: Bug - `2`: 功能 - `3`: 支援 ### 特殊值 #### status_filter 參數 - `"open"`: 所有開放狀態的議題 - `"closed"`: 所有已關閉狀態的議題 - `"all"`: 所有狀態的議題 ## ⚠️ 錯誤處理 ### 常見錯誤類型 #### 認證錯誤 ``` 認證失敗：請檢查 API 金鑰是否正確 ``` **解決方案：** 檢查 `.env` 檔案中的 `REDMINE_API_KEY` 設定 #### 權限錯誤 ``` 權限不足：您沒有執行此操作的權限 ``` **解決方案：** 確認用戶有足夠權限執行該操作 #### 資源不存在 ``` 找不到指定的議題，請確認議題 ID 是否正確 ``` **解決方案：** 檢查提供的 ID 是否正確 #### 資料驗證錯誤 ``` 資料格式錯誤：請檢查輸入的資料是否符合要求 ``` **解決方案：** 檢查參數格式和必填欄位 #### 連線錯誤 ``` 連線失敗：請檢查網路連線和 Redmine 伺服器狀態 ``` **解決方案：** 檢查網路連線和服務器狀態 ### 除錯模式 啟用除錯模式可取得更詳細的錯誤資訊： ```env DEBUG_MODE=true ``` ### 參數驗證 所有工具都包含參數驗證： #### 必填參數檢查 - 確保所有必填參數都有提供 - 檢查參數類型是否正確 #### 數值範圍檢查 - `limit` 參數限制在合理範圍內 - `done_ratio` 必須在 0-100 之間 - ID 參數必須為正整數 #### 字串長度檢查 - 議題標題不得超過 255 字元 - 描述不得超過 65535 字元 ## 🔄 工具執行流程 ### 1. 參數驗證 所有輸入參數都會經過驗證，確保格式正確 ### 2. API 呼叫 使用 Redmine REST API 執行實際操作 ### 3. 結果處理 將 API 回應轉換為友善的使用者介面格式 ### 4. 錯誤處理 捕捉並轉換錯誤訊息為易懂的中文說明 ## 💡 最佳實務 ### 參數使用建議 1. **使用有意義的 ID** ```python # 好的做法 取得議題 #123 的詳細資訊 # 避免 取得議題 #999999（不存在的 ID） ``` 2. **提供完整描述** ```python # 好的做法 建立議題「修復用戶登入問題」，描述「用戶回報無法正常登入，錯誤訊息為 500 錯誤」 # 避免 建立議題「修復」（描述太簡略） ``` 3. **適當的分頁限制** ```python # 好的做法 列出專案 1 的議題，限制 20 筆 # 避免 列出專案 1 的議題，限制 1000 筆（可能影響效能） ``` ### 工作流程建議 1. **先查詢再操作** ```python # 建議流程 1. 取得專案列表 2. 選擇目標專案 3. 建立或更新議題 ``` 2. **提供適當備註** ```python # 好的做法 更新議題狀態時加上有意義的備註說明進度或變更原因 ``` --- 更多詳細資訊請參考 [使用範例](USAGE_EXAMPLES.md) 或 [README.md](../README.md)。