# Đồ án MCP — Deadline / Lịch học tracker

Bài tập lớn môn MCP (FIT-HCMUS, GV Kha Do) — dựa trên slide
`MCP — Plug Your Agent Into Everything`.

## Cấu trúc

```
mcp-homework/
├── server/
│   ├── core.js     ← logic MCP thật: 3 tools + 1 resource + 1 prompt
│   ├── server.js   ← chạy core qua stdio
│   └── http.js      ← chạy core qua Streamable HTTP + API key guard + /health
├── agent/
│   ├── host.js     ← agent = MCP HOST (load config, merge tools, dispatch, use_skill)
│   └── config.json ← khai báo model + các MCP server cần nối + nơi chứa skills
├── skills/
│   └── deadline-review/SKILL.md ← 1 skill orchestrate tool của server
└── README.md
```

## Đề tài server: Deadline / lịch học tracker

- **Tools**
  - `add_deadline({ title, subject, due })` — thêm deadline
  - `list_deadlines({ subject?, onlyPending? })` — liệt kê, có lọc
  - `complete_deadline({ id })` — đánh dấu hoàn thành, trả `isError: true` nếu id sai
- **Resource**: `deadline://list` — toàn bộ danh sách, chỉ đọc
- **Prompt**: `plan_my_week` — yêu cầu model lên kế hoạch tuần từ deadline hiện có

## Chạy từng phần

### 1. stdio server (test bằng Inspector)
```bash
npm install
npx @modelcontextprotocol/inspector node server/server.js
```

### 2. HTTP server (local, rồi deploy public)
```bash
MCP_KEY=$(openssl rand -hex 32) node server/http.js
# test:
npx @modelcontextprotocol/inspector   # chọn Streamable HTTP, URL http://localhost:3000/mcp,
                                       # header Authorization: Bearer <MCP_KEY>
```
Deploy (Render/Fly/Railway...): set biến môi trường `MCP_KEY`, expose cổng `PORT`,
`/health` dùng cho health check của nền tảng.

### 3. Agent host (dùng cả 2 server + skill)
```bash
cd agent && npm install
# cần Ollama chạy sẵn model qwen3.5:4b (hoặc đổi model/baseURL trong config.json)
node host.js "deadline tuần này của tôi thế nào?"
```
`host.js` sẽ: nối server stdio + server HTTP → gộp tool list → build index skill từ
`skills/` → chạy vòng lặp think/decide/act/observe, tự gọi `use_skill` khi câu hỏi
khớp mô tả skill, rồi gọi tool MCP tương ứng.

## Đã tự kiểm thử

- Smoke test stdio server: gọi cả 3 tool, đọc resource, lấy prompt, kiểm tra
  `isError` khi complete id không tồn tại — tất cả đúng như kỳ vọng.
- HTTP server: request thiếu key → 401; có key đúng → handshake `initialize`
  thành công; `/health` trả `ok`.

## Còn cần làm trước khi nộp

- [ ] Deploy bản HTTP lên nền tảng public (Render/Fly/Railway/Cloudflare Workers…),
      set `MCP_KEY`, ghi lại URL + key cho người chấm
- [ ] Cài Ollama + pull `qwen3.5:4b`, chạy thử `agent/host.js` với model thật
      (bản test ở trên chỉ kiểm thử tầng MCP, chưa gọi LLM)
- [ ] Quay video demo ngắn (xem mục "Nộp bài" bên dưới)