# 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)。