student-export-mcp

English

MCP server chạy local trên máy bạn (qua stdio), dùng để export danh sách học viên của một web ra file Excel.

Bạn chỉ cần cung cấp username, password và URL API trả danh sách học viên. Phần còn lại server tự dò:

• Đăng nhập: mở Chrome chạy ẩn và đăng nhập như người thật. Bạn không cần biết endpoint login hay token được lưu ở đâu.
• Xác thực: lần lượt thử cookie phiên, header Authorization mà web gửi đi, và token trong localStorage/sessionStorage.
• Phân trang: đi theo link next, đọc total_records/total/last_page, rồi tăng page_index/page/offset. Nếu API không có metadata, server lấy tiếp trang sau cho tới khi hết dữ liệu.
• Cột Excel: mỗi field thành một cột. Object lồng được làm phẳng 1 cấp, ví dụ class.name.

Thông tin đăng nhập luôn nằm trên máy bạn: không đi qua chat và không là tham số của tool.

Yêu cầu

• Node.js 20 trở lên
• Google Chrome, hoặc chạy npx playwright-core install chromium

Cài nhanh

1. Tạo file cấu hình. Tự điền bằng editor, không dán nội dung vào chat.

   mkdir -p ~/.config/student-export-mcp
   nano ~/.config/student-export-mcp/.env
   chmod 600 ~/.config/student-export-mcp/.env

   [email protected]
   SITE_PASSWORD=mat-khau
   # Request API trả danh sách (copy trong DevTools → Network), có thể kèm filter
   STUDENTS_API_URL=https://app.example.com/api/students?page_index=1&page_size=100
   # Tuỳ chọn: chỉ cần khi server không tự tìm được trang đăng nhập
   # LOGIN_URL=https://app.example.com/auth/login

2. Đăng ký với MCP client.

   Claude Code:

   claude mcp add -s user student-export -- npx -y student-export-mcp

   Claude Desktop, hoặc client đọc cấu hình JSON:

   {
     "mcpServers": {
       "student-export": { "command": "npx", "args": ["-y", "student-export-mcp"] }
     }
   }

3. Khởi động lại client rồi nói: "kiểm tra kết nối web học viên", sau đó "export danh sách học viên ra Excel". File được lưu vào ~/Exports/hoc-vien-<thời gian>.xlsx.

Muốn để file cấu hình ở chỗ khác thì đặt biến STUDENT_MCP_ENV_PATH=/duong/dan/.env trong môi trường chạy server.

Tools

| Tool | Chức năng | Trả về | |---|---|---| | test_connection | Đăng nhập và gọi thử trang đầu | Kiểu xác thực tìm được, số dòng trang đầu, tổng theo API | | export_students_xlsx | Đăng nhập, lấy toàn bộ các trang và ghi file .xlsx | { filePath, rowCount, pages, expectedTotal, complete, warning? } |

Dữ liệu học viên chỉ nằm trong file Excel, không bao giờ được trả vào chat.

Ví dụ phân trang

STUDENTS_API_URL=https://app.example.com/api/students?page_index=1&page_size=50

{ "data": [ "...50 học viên" ], "metadata": { "total_records": 173, "page_index": 1 } }

page_index=1 -> 50   (đã lấy 50)
page_index=2 -> 50   (đã lấy 100)
page_index=3 -> 50   (đã lấy 150)
page_index=4 -> 23   (đủ 173 = total_records, dừng)

• API đánh số trang từ 0: ghi page_index=0 trong URL. Server tăng dần từ giá trị bạn ghi.
• Các trang sau trả metadata: null: không sao, vì tổng được đọc từ trang đầu.
• Thiếu dữ liệu: nếu API hết dữ liệu hoặc trả trang trùng trước khi đủ tổng, server dừng. Kết quả sẽ có "complete": false kèm warning.

Cách tìm trang đăng nhập

Server thử lần lượt các URL sau, và dừng ở trang HTML đầu tiên có ô mật khẩu hiển thị, cùng tên miền với API:

1. LOGIN_URL
2. Origin của API
3. Host frontend đoán từ host API, ví dụ app-be.example.com → app.example.com, api.example.com → example.com

Chưa hỗ trợ: captcha, OTP/2FA, đăng nhập 2 bước (username và password ở 2 màn hình khác nhau), SSO qua domain khác.

Bảo mật

• Nơi lưu cấu hình: ~/.config/student-export-mcp/.env, ngoài project và chỉ bạn đọc được. Server cảnh báo nếu quyền file lỏng hơn 600.
• Cấu hình không nằm ở đâu: không ghi vào biến môi trường của process, không là tham số của tool, không ghi vào cấu hình MCP client.
• Mật khẩu được điền vào đâu: chỉ vào trang đăng nhập cùng tên miền với API.
• Kết nối mạng: bắt buộc HTTPS. Request không ra ngoài origin của API và không đi theo redirect sang host khác.
• Token/cookie: chỉ giữ trong RAM. Trình duyệt được đóng sau mỗi lần gọi.
• Thông báo lỗi: chỉ 1 dòng, không kèm body response. Username, password và token đều được che.
• Khuyến nghị cho Claude Code: chặn AI đọc file cấu hình bằng cách thêm "deny": ["Read(~/.config/student-export-mcp/**)", "Edit(~/.config/student-export-mcp/**)"] vào mục permissions trong ~/.claude/settings.json.

Chỉ dùng với hệ thống và dữ liệu bạn có quyền truy cập, và tuân thủ quy định bảo vệ dữ liệu cá nhân áp dụng cho bạn.

Xử lý lỗi

| Lỗi | Cách xử lý | |---|---| | Không đọc được file cấu hình | Tạo ~/.config/student-export-mcp/.env, hoặc đặt STUDENT_MCP_ENV_PATH | | Không tìm thấy trang đăng nhập | Thêm LOGIN_URL=<url trang đăng nhập> | | Đăng nhập thất bại | Kiểm tra tài khoản. Captcha, OTP và SSO chưa được hỗ trợ. | | thất bại (HTTP 401/403) | Tài khoản không có quyền gọi API, hoặc web dùng kiểu xác thực chưa dò được | | Timeout trong MCP Inspector | Tăng Request Timeout (đăng nhập và lấy nhiều trang có thể mất hơn 10 giây) |

Phát triển

npm install
npm run build
npm test          # test end-to-end với các web giả chạy local (cần Chrome)
npm run inspect   # MCP Inspector

License

MIT