Academic Advisor MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
HNUE AI Academic Advisor — V1
Web app local bằng FastAPI và React với một giao diện chính: chat cùng cố vấn AI và bảng điểm ở cạnh bên. Dán trực tiếp bảng TSV sao chép từ trang trường; Python giữ cả dòng chưa có điểm và điểm 0, rồi hiển thị mã môn, tên môn, tín chỉ, điểm hệ 10, hệ 4 và điểm chữ.
Các phép tính học vụ và thay đổi dữ liệu nằm trong Python tool. Gemini chỉ chọn tool và diễn giải kết quả theo schema AdvisorResponse. Hành động ghi dữ liệu luôn dừng ở một nút xác nhận cho đúng tham số đã chuẩn bị phía server. Inspector LOCAL DEBUG cho thấy catalog và tool call thật; đây không phải vai trò quản trị hay ranh giới bảo mật.
Phạm vi tin cậy: dữ liệu HNUE đi kèm là dữ liệu một phần do người dùng cung cấp, chưa đủ để xác nhận tốt nghiệp chính thức. Màn hình và API luôn giữ trạng thái
UNKNOWN/NEEDS_REVIEWcho phần chưa xác minh. V1 là ứng dụng local một người dùng, chưa có authentication để public.
Chạy nhanh
Yêu cầu: Python 3.11+, Node.js 20+ và pnpm/npm.
cd outputs/hnue-ai-academic-advisor
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
alembic upgrade head
python -m app.data.seed_cli
uvicorn app.main:app --reloadỞ terminal khác:
cd outputs/hnue-ai-academic-advisor/frontend
pnpm install
pnpm devMở http://localhost:5173, dán bảng điểm vào panel bên phải rồi đặt câu hỏi. OpenAPI ở http://localhost:8000/docs.
Lần đầu mở app không tự chèn hồ sơ demo. Có thể yêu cầu cố vấn nạp dữ liệu demo qua chat; đây là hành động ghi dữ liệu nên ứng dụng luôn yêu cầu xác nhận.
Nếu không muốn dùng migration khi thử nhanh, FastAPI tự tạo bảng còn thiếu lúc khởi động; migration vẫn là cách được khuyến nghị.
Related MCP server: induslms-academics
Chạy một địa chỉ bằng Docker
Docker build React trước, chép frontend/dist vào image Python rồi để FastAPI phục vụ cả giao diện và API:
docker compose up --buildSau khi build:
Giao diện:
http://localhost:8000/API:
http://localhost:8000/api/...OpenAPI:
http://localhost:8000/docs
Đặt API key Gemini trong .env trước khi build:
GOOGLE_API_KEY=<api-key-tu-google-ai-studio>
GEMINI_MODEL=gemini-3.6-flashcompose.yaml truyền key vào backend để gọi Gemini Developer API. Database SQLite được giữ trong volume advisor-data.
Dừng ứng dụng:
docker compose downDữ liệu mẫu và import
POST /api/seed tạo curriculum HNUE một phần, hồ sơ DEMO-001, transcript minh họa và career mapping có nhãn. Lệnh seed có tính idempotent.
Mẫu CSV:
app/data/transcript_template.csvDữ liệu minh họa:
app/data/demo_transcript.csv
Luồng import qua chat/tool: preview CSV → xem warning/lỗi từng dòng → xác nhận commit. Unique key (student, course, semester, attempt_number) ngăn import lặp. Điểm và điểm chữ mâu thuẫn được giữ nguyên và báo warning.
Gemini và tool calling
LLM chỉ nhìn thấy 8 tool nghiệp vụ: get_academic_status, lookup_academic_rules,
check_graduation_progress, calculate_gpa_goal, simulate_grades,
recommend_grade_improvements, recommend_study_plan và explore_careers.
Mỗi tool có Pydantic input/output schema; catalog và inspector hiển thị cả hai schema.
Ví dụ, mục tiêu GPA số dùng {"target":{"type":"GPA","gpa":3.2}}, còn yêu cầu
"bằng Khá" dùng {"target":{"type":"CLASSIFICATION","classification":"KHA"}}.
Nếu chưa có ngưỡng xếp loại đã xác minh, tool trả UNKNOWN thay vì tự gán một GPA.
Cài phần AI:
pip install -r requirements-ai.txtSửa .env:
GOOGLE_API_KEY=<api-key-tu-google-ai-studio>
GEMINI_MODEL=gemini-3.6-flashVòng điều phối là Gemini → tool Python → Gemini, tối đa 6 lượt tool. Finalizer dùng function calling và bắt buộc tạo AdvisorResponse theo schema Pydantic. Nếu Gemini không phản hồi hoặc cấu hình thiếu, API trả AI_UNAVAILABLE thay vì tạo câu trả lời giả.
MCP
Cài requirements-ai.txt, seed database rồi chạy:
python -m app.mcp.serverServer FastMCP qua stdio expose:
get_student_profile, get_student_transcript, get_curriculum, check_graduation_requirements, check_requirement_groups, calculate_current_gpa, calculate_gpa_plan, recommend_retakes, match_career_to_specialization, recommend_courses, create_study_plan.
Kiểm tra discovery thật qua MultiServerMCPClient:
python -m app.mcp.clientKiểm thử
pip install -r requirements-dev.txt
python -m pytest tests/test_advisor_tools.py tests/test_advisor_integration.py -q
pytest
cd frontend
pnpm install
pnpm buildTest bao phủ biên thang điểm, xung đột điểm, F rồi học lại đạt, các repeat policy, môn không tính GPA, GPA mục tiêu động/bất khả thi, requirement lồng nhau, retake exact search, credit limit động, API persistence, graceful degradation và MCP deterministic entry points.
API chính
POST /api/profiles,GET /api/profilesGET /api/students/{id}/transcript,POST /api/students/{id}/attemptsPOST /api/students/{id}/import/preview,POST /api/students/{id}/import/commitGET /api/students/{id}/graduation,GET /api/students/{id}/gpaPOST /api/gpa/plan,POST /api/retakes/planGET /api/students/{id}/recommendations,GET /api/careers/matchPOST /api/scenarios,GET /api/scenariosPOST /api/scenarios/{id}/recalculateGET /api/students/{id}/export,DELETE /api/students/{id}POST /api/advisor/sessions,GET /api/advisor/sessions/{id}POST /api/advisor/transcript/paste,POST /api/advisor/chatGET /api/advisor/tools,GET /api/advisor/sessions/{id}/tracesPOST /api/advisor/actions/confirm
Thiết kế và giới hạn
Chưa có portal HNUE, OCR, email, lịch mở lớp và kiểm tra trùng giờ.
Planner dùng backtracking hữu hạn để tìm packing theo tín chỉ và tự tăng số kỳ khi horizon không cố định; chưa xét lịch mở lớp nên không tuyên bố tối ưu lịch học thực tế.
Các planning mode có objective riêng.
CAREER_FOCUSEDcần career mapping;GPA_FOCUSEDcần target vàexpected_grade_points. Nếu thiếu, API trảUNSUPPORTED.Study scenario chỉ packing tập môn được chọn từ phần requirement còn thiếu. Output lưu contribution, alternatives và unknown groups; catalog elective không được đưa toàn bộ vào kế hoạch.
GPA_FOCUSEDtrả required average, feasibility, projected GPA và nguồn dữ liệu (TRANSCRIPT_POLICYhoặcEXPLICIT_ASSUMPTION).Retake duyệt toàn bộ tổ hợp trong tối đa 20 candidate, tôn trọng hard cap kể cả môn bắt buộc và chỉ là exact trong tập candidate đã cho. Kết quả vẫn phụ thuộc policy/điểm giả định.
Career mapping là biên tập tham khảo, không phải chuyên ngành chính thức. Curriculum tham chiếu trang FIT HNUE ngày 29/07/2023 nhưng cohort áp dụng và các mã xung đột vẫn để
UNKNOWN.Session và bảng điểm dán chỉ ở bộ nhớ tiến trình. Scenario bấm lưu nằm trong database và mang provenance; kết quả từ snapshot cũ được đánh dấu stale khi đọc lại.
Frontend package dùng
latestđể scaffold thuận tiện; với triển khai dài hạn nên commit lockfile sinh bởipnpm install.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
AI-callable calculators and engineering models with real formulas. No hallucinated math.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
Deterministic AEO/GEO checks and a source-cited rulebook for AI search, for your agent.
Deterministic AI agent microtools, no accounts/API keys. fetch_extract: 98% token cut. 47 tools.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI clients to read a student's own UGent Ufora (D2L Brightspace) data, including courses, announcements, deadlines, grades, course materials, and PDF text, over stdio or local Streamable HTTP. All operations are read-only and run locally against the student's authenticated session.192MIT
- AlicenseCqualityBmaintenanceProvides read-only access to Indus LMS academic data, letting agents browse courses, announcements, assignments, shared resources, notifications, attendance records, and school email inboxes. It exposes these capabilities as MCP tools over stdio, with no login, mark-read, or submission operations.22GPL 3.0
- AlicenseAqualityCmaintenanceEnables a tutor or assistant to read a student's Brightspace courses, deadlines, announcements, assignment instructions, course outlines, quiz metadata and released grades, plus search explicitly imported school notes and read course documents. Runs locally over stdio with read-only access and configurable tenant settings.181MIT
- AlicenseNot gradedqualityBmaintenanceExposes 22 typed, read-only MCP tools that let an agent answer questions about a student's own Ed discussion threads, Moodle deadlines and course materials, Gmail inbox, and OnTrack task feedback. Runs locally over stdio with credentials captured once by a CLI login, so the agent never handles passwords and never writes to any service.88 npm1MIT