# 🚀 OpenProject MCP Server & Skill Suite

Bộ ứng dụng **Model Context Protocol (MCP) Server & Skill Suite** hoàn chỉnh cho OpenProject API v3, cho phép các AI Agent (Gemini, Claude, Antigravity, VS Code, Cursor...) tự động đọc, tạo, trao đổi comment, quản lý log giờ làm việc (time entries), quản lý user story, quản lý board và theo dõi tiến độ dự án trên OpenProject.

---

## 🔑 Hướng Dẫn Cách Lấy API Access Token Trên OpenProject

Để kết nối MCP Server với máy chủ OpenProject của bạn, bạn cần lấy **API Access Token** theo các bước sau:

1. **Đăng nhập vào OpenProject**:
   - Đăng nhập vào trang OpenProject của bạn (ví dụ: `https://your-openproject-domain.com`).

2. **Truy cập Cài Đặt Tài Khoản (My Account)**:
   - Click vào **Avatar / Tên người dùng** ở góc trên bên phải màn hình.
   - Chọn **My Account** (Tài khoản của tôi) hoặc truy cập đường dẫn: `https://<your-domain>/my/account`.

3. **Mở Mục Access Tokens**:
   - Ở menu bên trái, chọn mục **Access tokens** (Mã truy cập) hoặc truy cập trực tiếp: `https://<your-domain>/my/access_tokens`.

4. **Tạo API Token Mới**:
   - Tại dòng **API**, nhấn nút **Generate** (Tạo) hoặc **+ Access token**.
   - Đặt tên gợi nhớ cho Token (ví dụ: `AI Agent Token`).

5. **Sao Chép & Lưu Trữ Token**:
   - Chuỗi API Token sẽ hiển thị có định dạng bắt đầu bằng `opapi-` (ví dụ: `opapi-xxxx...`).
   - > [!IMPORTANT]
   - > Copy và lưu lại mã Token ngay lập tức vì OpenProject chỉ hiển thị mã này **một lần duy nhất**.

---

## ⚙️ Cấu Hình MCP JSON (MCP JSON Configuration Guide)

Dưới đây là mã cấu hình JSON để nạp MCP Server vào các ứng dụng AI khác nhau. Thay thế `/path/to/openproject-mcp-and-skills` và thông tin OpenProject của bạn vào file tương ứng.

### 1. Cấu hình Workspace Local (`mcp.json` hoặc `.vscode/mcp.json`)
Thêm đoạn JSON sau vào file `mcp.json` tại thư mục dự án của bạn:

```json
{
  "mcpServers": {
    "openproject": {
      "command": "node",
      "args": [
        "/path/to/openproject-mcp-and-skills/dist/index.js"
      ],
      "env": {
        "OPENPROJECT_HOST": "https://your-openproject-domain.com",
        "OPENPROJECT_API_KEY": "opapi-your-api-token-here"
      }
    }
  }
}
```

### 2. Cấu hình Toàn Cục Antigravity / Gemini CLI (`~/.gemini/antigravity/mcp_config.json`)
Thêm vào file cấu hình toàn cục hệ thống:

```json
{
  "mcpServers": {
    "openproject": {
      "$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
      "command": "/usr/bin/node",
      "args": [
        "/path/to/openproject-mcp-and-skills/dist/index.js"
      ],
      "env": {
        "OPENPROJECT_HOST": "https://your-openproject-domain.com",
        "OPENPROJECT_API_KEY": "opapi-your-api-token-here"
      }
    }
  }
}
```

### 3. Cấu hình Claude Desktop (`claude_desktop_config.json`)
Dành cho Claude Desktop App (File nằm tại `~/.config/Claude/claude_desktop_config.json` trên Linux/macOS hoặc `%APPDATA%\Claude\claude_desktop_config.json` trên Windows):

```json
{
  "mcpServers": {
    "openproject": {
      "command": "node",
      "args": [
        "C:/path/to/openproject-mcp-and-skills/dist/index.js"
      ],
      "env": {
        "OPENPROJECT_HOST": "https://your-openproject-domain.com",
        "OPENPROJECT_API_KEY": "opapi-your-api-token-here"
      }
    }
  }
}
```

---

## ⚡ Cài Đặt Tự Động 1-Click (Automated Installer Script)

Nếu bạn không muốn tạo file cấu hình JSON thủ công, chỉ cần chạy kịch bản cài đặt tự động:

```bash
cd openproject-mcp-and-skills
./install.sh --host "https://your-openproject-domain.com" --api-key "opapi-xxxx"
```

Script sẽ tự động:
1. Cài đặt dependencies & biên dịch TypeScript ra `dist/index.js`.
2. Tự động ghi cấu hình JSON vào cả file local `mcp.json` và file toàn cục `~/.gemini/antigravity/mcp_config.json`.
3. Tự động sao chép Skill `.agents/skills/openproject/SKILL.md` và Rule `.agents/rules/openproject.md` vào dự án.

---

## 🌟 Tính Năng Chính (Full 22 MCP Tools)

### 1. 📋 Quản lý Task & User Story
- `openproject_create_work_package`: Tạo mới Task, Feature, Bug, Epic, Milestone.
- `openproject_create_user_story`: Tạo mới User Story chuẩn Agile với Acceptance Criteria & Story Points.
- `openproject_list_work_packages`: Tìm kiếm, lọc danh sách công việc theo dự án, trạng thái, người được giao, từ khóa.
- `openproject_get_work_package`: Xem chi tiết 1 work package (% hoàn thành, mô tả markdown, người tạo, ngày cập nhật).
- `openproject_update_progress`: Cập nhật trạng thái (New, In Progress, Closed...), % tiến độ (0-100%), người thực hiện, story points.
- `openproject_delete_work_package`: Xóa work package.

### 2. 📁 Quản lý Dự Án (Projects), Version & Categories
- `openproject_list_projects`: Danh sách tất cả các dự án.
- `openproject_get_project`: Đọc chi tiết thông tin dự án.
- `openproject_create_project`: Tạo mới một dự án trên OpenProject.
- `openproject_list_versions`: Liệt kê các phiên bản / milestone dự án.
- `openproject_list_categories`: Liệt kê danh mục công việc dự án.

### 3. 💬 Trao Đổi Bình Luận, Log Giờ Làm Việc & File Đính Kèm
- `openproject_list_comments`: Xem danh sách thảo luận/bình luận trong task.
- `openproject_add_comment`: Đăng bình luận hoặc cập nhật tiến độ công việc vào task.
- `openproject_list_attachments`: Danh sách file đính kèm trong task.
- `openproject_list_time_entries`: Danh sách các log giờ làm việc.
- `openproject_log_time`: Ghi nhận số giờ làm việc (time entry) cho công việc.
- `openproject_delete_time_entry`: Xóa log giờ làm việc.

### 4. 📊 Quản lý Board & Di chuyển Card
- `openproject_list_boards`: Liệt kê các danh sách Agile Boards & Grids trong dự án.
- `openproject_get_board_details`: Xem chi tiết các cột và cấu hình thẻ trên board.
- `openproject_move_board_card`: Di chuyển thẻ trên board sang trạng thái cột mới.

### 5. 🤖 User & AI Agent Dashboard
- `openproject_list_users`: Danh sách tất cả người dùng trong hệ thống.
- `openproject_get_user`: Xem chi tiết thông tin người dùng.
- `openproject_get_current_user`: Xem tài khoản API đang kết nối.
- `openproject_get_metadata`: Lấy danh sách Work Package Types, Statuses, Priorities.
- `openproject_get_agent_dashboard`: Báo cáo tổng quan tiến độ (tỷ lệ hoàn thành %, tổng số task, backlog, công việc đang làm) thiết kế tối ưu cho AI reasoning.

---

## 📜 Giấy phép
MIT