# MCPaeroedu — AeroEdu MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A5%2018-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-8b5cf6)](https://modelcontextprotocol.io)

**MCP server cho [inphysic.com](https://inphysic.com)** — kết nối Claude · DeepSeek · GPT · Codex · Gemini với
nền tảng AeroEduVision. Sinh đề, quản lý khoá học, query Knowledge Graph, chấm bài —
tất cả qua prompt tự nhiên trong client AI bạn yêu thích.

> Hỗ trợ chính thức: **Claude Desktop · Cursor · Cherry Studio · Cline · 5ire**

---

## 🚀 Cài đặt nhanh (3 phút)

### Cách A — Tải bản đóng gói (KHUYẾN NGHỊ — không cần git/npm)

Tải zip 5.3 MB cho hệ điều hành của bạn:

- 🍎 **[macOS / Linux](https://storage.googleapis.com/aeroedu-media-extreme-lattice-491123-p2/mcp/aeroedu-mcp-v0.5.0-mac.zip)** (5.3 MB)
- 🪟 **[Windows](https://storage.googleapis.com/aeroedu-media-extreme-lattice-491123-p2/mcp/aeroedu-mcp-v0.5.0-win.zip)** (5.3 MB)

Yêu cầu: **Node.js ≥ 18** (tải [nodejs.org](https://nodejs.org)).

### Cách B — Build từ source (cho dev)

```bash
git clone https://github.com/aerovfx/MCPaeroedu.git
cd MCPaeroedu
npm install
npm run build
```

---

## 🔑 Setup API Key

1. Đăng nhập [inphysic.com/teacher/api-keys](https://inphysic.com/teacher/api-keys)
2. Bấm **"+ Tạo API Key mới"** → đặt tên (vd "Claude MacBook")
3. ⚠️ **Copy ngay** chuỗi `AERO-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` (chỉ hiện 1 lần)

---

## ⚙️ Cấu hình client AI

### Claude Desktop

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "aeroedu": {
      "command": "/path/to/aeroedu-mcp/bin/aeroedu-mcp",
      "env": {
        "AEROEDU_API_KEY": "AERO-your-key-here"
      }
    }
  }
}
```

### Cursor (`~/.cursor/mcp.json`)

Cùng format JSON như Claude Desktop. Sau đó vào **Settings → Models → Custom OpenAI Endpoint**:
- Base URL: `https://api.deepseek.com/v1`
- Model: `deepseek-chat` hoặc `deepseek-reasoner`

### Cherry Studio (GUI desktop)

**Settings → MCP Servers → + Add**:
- Name: `aeroedu`
- Type: `STDIO`
- Command: `/path/to/aeroedu-mcp/bin/aeroedu-mcp`
- Env: `AEROEDU_API_KEY = AERO-...`

### Cline (VS Code extension)

Cline panel → **MCP Servers** → **Configure MCP Servers** → cùng JSON format.

### Windows path

Thay `/path/to/aeroedu-mcp/bin/aeroedu-mcp` bằng `C:\\path\\to\\aeroedu-mcp\\bin\\aeroedu-mcp.cmd`.

---

## 🛠 24 MCP Tools

### Course (5)
- `aeroedu_course_list` — list khoá học
- `aeroedu_course_create` — tạo khoá mới
- `aeroedu_course_detail` — chi tiết khoá
- `aeroedu_course_update` — cập nhật
- `aeroedu_course_delete` — xoá

### Knowledge Graph (5)
- `aeroedu_kg_search` — tìm node theo query
- `aeroedu_kg_node` — chi tiết node
- `aeroedu_kg_path` — tìm đường giữa 2 node
- `aeroedu_kg_visit` — log visit + mastery
- `aeroedu_kg_extract` — trích xuất concept từ text

### Block (4)
- `aeroedu_block_create_video` — tạo video block
- `aeroedu_block_create_pdf` — tạo PDF block
- `aeroedu_block_create_quiz` — tạo quiz block
- `aeroedu_block_create_lab` — tạo lab block

### Exam & Question (5)
- `aeroedu_exam_publish` — publish đề
- `aeroedu_question_add` — thêm câu hỏi vào bank
- `aeroedu_student_list` — list HS
- `aeroedu_report_xp` — báo cáo XP
- `aeroedu_report_progress` — tiến độ HS

### DaVinci Resolve (5)
- `aeroedu_davinci_*` — video timeline ops (cần DaVinci Resolve cài local)

---

## 🧪 Ví dụ prompt

```
"Tạo cho tôi 1 đề thi Vật lí 11 chương Dao động cơ —
 10 câu MCQ, độ khó trung bình, có lời giải"
```
→ AI gọi `aeroedu_exam_publish` → Đề xuất hiện trong `/teacher/exams` ✓

```
"Liệt kê 5 khoá học gần nhất của tôi"
```
→ `aeroedu_course_list` → bảng 5 khoá + ID + status

```
"Tìm node 'Định luật bảo toàn năng lượng' trong KG Vật lí"
```
→ `aeroedu_kg_search` → metadata + path tới node

---

## 🔐 Bảo mật

- **API Key** hash bcrypt, chỉ stored prefix trên client. Server không bao giờ thấy raw key.
- **JWT** mint sau validate-key, expire 90d (`ignoreExpiration` enabled trên server).
- **Audit log** mỗi tool call vào `~/.aeroedu-mcp/audit-YYYY-MM-DD.jsonl`.
- **Revoke** key bất kỳ lúc nào ở `/teacher/api-keys`.

---

## 📦 Build & Release

```bash
npm install              # cài deps
npm run build            # tsc → dist/
npm run dev              # watch mode (tsx)
npm run pack:release     # build zip cho Mac + Win → releases/
```

Output: `releases/aeroedu-mcp-vX.Y.Z-{mac,win}.zip` (mỗi 5.3 MB)

Upload public:
```bash
gsutil cp releases/aeroedu-mcp-v*-{mac,win}.zip \
  gs://aeroedu-media-extreme-lattice-491123-p2/mcp/
```

---

## 🌐 Tài nguyên

- **Website**: [inphysic.com](https://inphysic.com)
- **Hướng dẫn cài đặt full**: [inphysic.com/teacher/api-keys](https://inphysic.com/teacher/api-keys)
- **API Key Dashboard**: [inphysic.com/teacher/api-keys](https://inphysic.com/teacher/api-keys)
- **MCP Spec**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **Source main monorepo**: [aerovfx/aeroeduvision](https://github.com/aerovfx/aeroeduvision)

---

## 📜 License

MIT — Copyright (c) 2026 AeroEduVision

---

## 🐛 Issues

Báo lỗi hoặc đề xuất tại: [GitHub Issues](https://github.com/aerovfx/MCPaeroedu/issues)

Hoặc email: support@inphysic.com