Đồ á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)

npm install
npx @modelcontextprotocol/inspector node server/server.js

2. HTTP server (local, rồi deploy public)

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)

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)