CLAUDE.md•7.64 kB
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 專案概述
這是一個 MCP (Model Context Protocol) 伺服器專案，用於與 Redmine 系統整合。使用 Python 3.12+ 和 uv 包管理器。
## 開發環境設置
### 依賴管理
- 使用 `uv` 作為包管理器
- 安裝依賴：`uv sync`
- 執行測試：`uv run python -m pytest`
### 專案結構
```
redmine-mcp/
├── src/redmine_mcp/ # 主要原始碼
│ ├── __init__.py # 套件初始化
│ ├── server.py # MCP 服務器主程式 ✓ 已完成
│ ├── redmine_client.py # Redmine API 客戶端 ✓ 已完成
│ ├── config.py # 配置管理 ✓ 已完成
├── tests/ # 測試檔案
├── docs/ # 文件目錄
│ ├── issues/ # 開發問題記錄
│ └── manuals/ # 技術手冊
├── pyproject.toml # 專案配置和依賴
├── uv.lock # 鎖定的依賴版本
└── .env # 環境變數 (待建立)
```
## MCP 開發說明
### 技術棧
- **MCP SDK**: mcp[cli] >= 1.9.4 (使用 FastMCP)
- **HTTP 客戶端**: requests >= 2.31.0
- **配置管理**: python-dotenv >= 1.0.0
- **Python 版本**: >= 3.12
### MCP 服務器架構
- 使用 FastMCP 建立服務器
- 工具註冊使用 `@mcp.tool()` 裝飾器
- 支援非同步操作和類型安全
### Redmine API 整合
- **議題管理**: 查詢、建立、更新、刪除議題
- **專案管理**: 查詢、建立、更新、刪除、封存專案
- **用戶管理**: 查詢用戶、取得當前用戶資訊
- **元數據查詢**: 狀態、優先級、追蹤器列表
- **觀察者管理**: 新增/移除議題觀察者
- **完整篩選支援**: 多條件篩選和排序
## Claude Code 整合
### 安裝到 Claude Code
```bash
# 安裝 MCP 服務器
uv tool install .
# 或使用 pip
pip install .
# 添加到 Claude Code
claude mcp add redmine "redmine-mcp" \
-e REDMINE_DOMAIN="https://your-redmine-domain.com" \
-e REDMINE_API_KEY="your_api_key_here" \
-e REDMINE_MCP_LOG_LEVEL="INFO" \
-e REDMINE_MCP_TIMEOUT="30"
```
### 環境變數說明
為避免與其他專案的環境變數衝突，redmine-mcp 使用專屬前綴：
- **必要變數**：
- `REDMINE_DOMAIN`: Redmine 伺服器網址
- `REDMINE_API_KEY`: Redmine API 金鑰
- **日誌級別控制**：
- `REDMINE_MCP_LOG_LEVEL`: 本專案專屬日誌級別（預設：INFO）
- `FASTMCP_LOG_LEVEL`: FastMCP 內建變數（可選）
- 如果不設定，系統會自動使用 `REDMINE_MCP_LOG_LEVEL` 的值
- 設定此變數可單獨控制 FastMCP 的日誌輸出
- **其他配置**：
- `REDMINE_MCP_TIMEOUT`: 請求超時時間（秒）
- `REDMINE_TIMEOUT`: 向後相容的超時設定
### 可用的 MCP 工具（22 個）
- **管理工具**: server_info, health_check, refresh_cache ✨ 新增
- **查詢工具**: get_issue, list_project_issues, get_projects, get_issue_statuses, get_trackers, get_priorities, get_time_entry_activities, get_document_categories, search_issues, get_my_issues
- **用戶工具**: search_users, list_users, get_user ✨ 新增
- **編輯工具**: update_issue_status, update_issue_content, add_issue_note ✨ 時間記錄支援, assign_issue, close_issue ✨ 名稱參數支援
- **建立工具**: create_new_issue ✨ 名稱參數支援
## 常用指令
```bash
# 安裝依賴
uv sync
# 執行 MCP 服務器
uv run python -m redmine_mcp.server
# 測試 Claude Code 整合
uv run python tests/scripts/claude_integration.py
# 執行單元測試
uv run python -m pytest tests/unit/
# 執行所有測試
uv run python -m pytest tests/
# 添加新依賴
uv add <package-name>
```
## 智慧快取系統 ✨
### 快取機制特色
- **Multi-Domain 支援**: 根據 Redmine domain 自動建立獨立快取檔案
- **自動更新**: 24小時自動刷新快取資料
- **完整覆蓋**: 快取列舉值（優先權、狀態、追蹤器）和用戶資料
- **檔案位置**: `~/.redmine_mcp/cache_{domain}_{hash}.json`
### 可用的輔助函數
```python
client = get_client()
# 列舉值查詢
priority_id = client.find_priority_id_by_name("低") # → 5
status_id = client.find_status_id_by_name("實作中") # → 2
tracker_id = client.find_tracker_id_by_name("臭蟲") # → 1
# 用戶查詢
user_id = client.find_user_id("Redmine Admin") # 智慧查詢（姓名或登入名）
user_id = client.find_user_id_by_name("Redmine Admin") # 僅姓名查詢
user_id = client.find_user_id_by_login("admin") # 僅登入名查詢
# 時間追蹤活動查詢
activity_id = client.find_time_entry_activity_id_by_name("開發") # → 11
# 取得所有選項
priorities = client.get_available_priorities() # {"低": 5, "正常": 6, ...}
users = client.get_available_users() # {"by_name": {...}, "by_login": {...}}
activities = client.get_available_time_entry_activities() # {"設計": 10, "開發": 11, ...}
# 手動刷新
client.refresh_cache()
```
### MCP 工具
- `refresh_cache()`: 手動刷新快取並顯示統計資訊
## 名稱參數支援 ✨
### 支援名稱參數的 MCP 工具
以下工具現在支援使用名稱而不僅僅是 ID：
```python
# 更新議題狀態（使用名稱）
update_issue_status(issue_id=1, status_name="實作中")
# 更新議題內容（使用名稱）
update_issue_content(
issue_id=1,
priority_name="高",
tracker_name="臭蟲"
)
# 指派議題（使用名稱）
assign_issue(issue_id=1, user_name="Redmine Admin")
assign_issue(issue_id=1, user_login="admin")
# 建立新議題（使用名稱）
create_new_issue(
project_id=1,
subject="新功能開發",
priority_name="正常",
tracker_name="功能",
assigned_to_name="Redmine Admin"
)
```
### 錯誤處理
如果提供的名稱不存在，工具會自動顯示可用選項：
```
找不到優先級名稱：「超高」
可用優先級：
- 低
- 正常
- 高
- 緊急
```
## 時間記錄功能 ✨
### add_issue_note 時間記錄支援
現在可以在新增議題備註時同時記錄工作時間：
```python
# 新增備註並記錄時間（使用活動名稱）
add_issue_note(
issue_id=1,
notes="完成功能開發",
spent_hours=2.5,
activity_name="開發"
)
# 新增備註並記錄時間（使用活動 ID）
add_issue_note(
issue_id=1,
notes="修復 bug",
spent_hours=1.0,
activity_id=12,
spent_on="2025-06-25" # 指定記錄日期
)
# 私有備註 + 時間記錄
add_issue_note(
issue_id=1,
notes="內部討論記錄",
private=True,
spent_hours=0.5,
activity_name="討論"
)
# 僅新增備註（向後相容）
add_issue_note(issue_id=1, notes="一般備註")
```
### 時間追蹤活動支援
系統支援以下預設活動：
- 設計 (ID: 10)
- 開發 (ID: 11)
- 除錯 (ID: 12)
- 調查 (ID: 13)
- 討論 (ID: 14)
- 測試 (ID: 15)
- 維護 (ID: 16)
- 文件 (ID: 17)
- 教學 (ID: 18)
- 翻譯 (ID: 19)
- 其他 (ID: 20)
### 特色功能
- **智慧快取**: 時間追蹤活動資訊自動快取，提升查詢效率
- **名稱參數**: 支援使用活動名稱而非 ID，使用更直觀
- **向後相容**: 保持原有 `add_issue_note` 功能完全相容
- **錯誤提示**: 無效活動名稱時自動顯示可用選項
- **彈性日期**: 可指定記錄日期，預設為今日
## 注意事項
- 專案正在開發初期階段
- 後續會根據開發進度更新此檔案內容