Skip to content
Back to search

v-work

MCP server + CLI cho VNFITE Work (tiến độ dự án, ticket, thông báo)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/enles004--v-work/badge.svg)](/listings/enles004--v-work)

HTML

<a href="/listings/enles004--v-work"><img src="/api/listings/enles004--v-work/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 222 lines
  1. # v-work
  2. MCP server (Node.js + TypeScript) cho **VNFITE Work** — cho phép AI đọc tiến độ dự án,
  3. ticket, thông báo và gọi các API khác của vWork bằng tài khoản của bạn.
  4. Chạy local qua **stdio**, không mở port, không gửi dữ liệu đi đâu ngoài `vWork.vnfite.com.vn`.
  5. ## Vì sao bọc API thay vì crawl HTML
  6. Trang `/workplace/tien-do-du-an` là SPA React (Vite). Dữ liệu đi qua REST API:
  7. ```
  8. Base: https://vWork.vnfite.com.vn
  9. Auth: POST /auth/login {username,password} → accessToken + refreshToken (xoay vòng)
  10. Data: GET /project-tracker/eoffice/docs
  11. GET /project-tracker/eoffice/me
  12. PATCH /project-tracker/eoffice/docs/{collection}/{docId}
  13. POST /project-tracker/eoffice/import
  14. ```
  15. Bản đồ đầy đủ: **157 endpoint / 10 nhóm** (project-tracker, tickets, notification, customer,
  16. customer-care, customer-call, user/department, workplace files, permissions, ai-assistant).
  17. Tool `vwork_api` phủ các endpoint còn lại mà không cần viết từng tool.
  18. ## Cài đặt
  19. ### Cài global — gõ `vwork` trực tiếp (không cần npx)
  20. ```bash
  21. npm i -g https://github.com/enles004/v-work/archive/refs/heads/master.tar.gz
  22. vwork auth
  23. vwork tasks --mine
  24. ```
  25. Cài xong có cả hai lệnh: `vwork` và `v-work`. Cập nhật phiên bản mới: chạy lại
  26. lệnh `npm i -g` ở trên. (npx chỉ chạy tạm, không tạo lệnh cố định.)
  27. Config MCP client có thể dùng binary global:
  28. ```json
  29. { "mcpServers": { "vwork": { "command": "vwork" } } }
  30. ```
  31. ### Qua npx (sau khi publish)
  32. ```bash
  33. npx -y v-work auth # đăng nhập một lần
  34. npx -y v-work auth status
  35. ```
  36. Config MCP client:
  37. ```json
  38. {
  39. "mcpServers": {
  40. "vwork": {
  41. "command": "npx",
  42. "args": ["-y", "v-work"]
  43. }
  44. }
  45. }
  46. ```
  47. Nếu chưa publish lên npm, có thể chạy trực tiếp từ GitHub:
  48. ```bash
  49. npx -y github:enles004/v-work auth
  50. ```
  51. ### Từ source
  52. ```bash
  53. npm install
  54. npm run build
  55. node dist/cli.js auth # hỏi username/password một lần
  56. node dist/cli.js auth status
  57. ```
  58. **Không cần file `.env`.** Mặc định đã có sẵn:
  59. - base URL: `https://vWork.vnfite.com.vn` (prod)
  60. - project: `eoffice`
  61. - chỉ đọc, cache 30s, timeout 20s
  62. Chỉ khi cần đổi mặc định (ví dụ UAT) mới dùng biến môi trường `VWORK_BASE_URL`,
  63. `VWORK_PROJECT`, `VWORK_ALLOW_WRITE` trong config của MCP client.
  64. `login` hỏi username/password (password ẩn), lưu token vào
  65. `~/.config/v-work/tokens.json` (chmod 600). Server dùng token này và tự refresh;
  66. khi hết hạn hoàn toàn thì chạy `login` lại.
  67. Cách khác (không khuyến nghị): đặt `VWORK_USERNAME`/`VWORK_PASSWORD` trong env của
  68. MCP client — server tự đăng nhập. Password sẽ nằm trong config client.
  69. `npm run auth:check` vẫn dùng để xem tài khoản + cấu trúc doc thật.
  70. ## Cấu hình client
  71. **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`
  72. hoặc `%APPDATA%\Claude\claude_desktop_config.json`):
  73. ```json
  74. {
  75. "mcpServers": {
  76. "vwork": {
  77. "command": "node",
  78. "args": ["/home/faris/code/My_Workspace/v-work/dist/cli.js"]
  79. }
  80. }
  81. }
  82. ```
  83. **Cursor / VS Code** (`.cursor/mcp.json` hoặc `.vscode/mcp.json`): cùng cấu trúc trên.
  84. **Claude Code**:
  85. ```bash
  86. claude mcp add vwork -- node /home/faris/code/My_Workspace/v-work/dist/cli.js
  87. /mcp # xem server đã kết nối + danh sách tool
  88. ```
  89. Lưu ý: `/mcp` trong Claude và `opencode mcp auth` chỉ có flow OAuth cho server **remote
  90. HTTP**. Server stdio (như server này) không có flow đó — auth nằm ở CLI `login` + token file.
  91. Debug bằng MCP Inspector:
  92. ```bash
  93. npm run inspect
  94. ```
  95. ## Tools
  96. | Tool | Việc |
  97. |---|---|
  98. | `vwork_me` | tài khoản + quyền hiện tại |
  99. | `vwork_my_tasks` | **task được giao cho chính bạn** (tự resolve danh tính) |
  100. | `vwork_project_overview` | ảnh chụp nhanh: tài khoản, tổng hợp tiến độ, ticket, thông báo chưa đọc |
  101. | `vwork_tracker_docs` | danh sách doc trong bảng tiến độ |
  102. | `vwork_tracker_search` | tìm theo từ khoá / trạng thái / người phụ trách / collection / quá hạn |
  103. | `vwork_tracker_summary` | đếm theo collection, trạng thái, người phụ trách, quá hạn, sắp đến hạn |
  104. | `vwork_tickets` | danh sách ticket hỗ trợ |
  105. | `vwork_ticket` | chi tiết ticket |
  106. | `vwork_notifications` | thông báo chưa đọc + mới nhất |
  107. | `vwork_update_task` | cập nhật status/note của task (cần `VWORK_ALLOW_WRITE=true`) |
  108. | `vwork_file_departments` | phòng ban có ổ file nội bộ (Tài liệu phòng ban) |
  109. | `vwork_dept_files` | thư mục + file trong một phòng ban, tìm theo tên |
  110. | `vwork_dept_tree` | cây thư mục đầy đủ của phòng ban |
  111. | `vwork_file_download` | tải file về `~/Downloads/vwork` (giới hạn 50MB) |
  112. | `vwork_api` | gọi API bất kỳ trong allowlist (GET luôn được; ghi phải bật) |
  113. Câu hỏi mẫu:
  114. - "Tuần này tôi có task nào quá hạn?"
  115. - "Tổng hợp tiến độ dự án eoffice, ai đang nhiều việc nhất?"
  116. - "Tài liệu phòng ban Công Nghệ có gì mới?"
  117. - "Tải file báo cáo tuần mới nhất về máy"
  118. - "Ticket nào đang mở cho khách hàng X?"
  119. - "Có thông báo chưa đọc nào không?"
  120. ## Cập nhật
  121. ```bash
  122. vwork upgrade # git pull + npm install + build (hoặc npm i -g nếu bản global)
  123. ```
  124. Sau đó **reconnect MCP** trong Claude (`/mcp`) là dùng bản mới. Không cần xoá cache, không cần sửa config.
  125. Repo có pre-commit hook tự build + stage `dist/`, và CI kiểm tra `dist` đồng bộ với `src` (bật hook: `git config core.hooksPath .githooks`).
  126. ## Nền tảng
  127. Chạy trên Linux, macOS, Windows (Node ≥ 20). Token lưu theo chuẩn từng OS:
  128. | OS | Đường dẫn |
  129. |---|---|
  130. | Linux | `~/.config/vwork-mcp/tokens.json` |
  131. | macOS | `~/Library/Application Support/vwork-mcp/tokens.json` |
  132. | Windows | `%APPDATA%\vwork-mcp\tokens.json` |
  133. CI GitHub Actions chạy test + typecheck trên cả 3 OS với Node 20 và 22.
  134. ## An toàn
  135. - Mặc định **chỉ đọc**: `VWORK_ALLOW_WRITE=false`. Bật `true` mới cho PATCH/POST/PUT/DELETE.
  136. - Ghi chỉ mở cho `/project-tracker`, `/tickets`, `/notification`; `/auth/*` và `/permissions/*` luôn bị chặn.
  137. - Token lưu tại `~/.config/v-work/tokens.json` (chmod 600), tự refresh và xoay vòng.
  138. - Password chỉ nằm trong env của MCP client — không commit, không log.
  139. - Cache GET 30s để tránh spam API khi AI hỏi liên tiếp.
  140. ## Phát triển
  141. ```bash
  142. npm test # mock toàn bộ HTTP, không gọi mạng
  143. npm run build
  144. npm run dev # tsx, dùng khi debug
  145. ```
  146. CLI:
  147. ```bash
  148. node dist/cli.js # chạy server (mặc định)
  149. node dist/cli.js login # đăng nhập, lưu token
  150. node dist/cli.js status # kiểm tra token
  151. node dist/cli.js whoami # in tài khoản hiện tại
  152. node dist/cli.js logout # xoá token
  153. ```
  154. Cấu trúc:
  155. ```
  156. src/
  157. config.ts # env → Config (zod)
  158. auth.ts # login / refresh / token store
  159. client.ts # HTTP client: auth, retry 401, cache, timeout
  160. format.ts # helper đọc JSON không phụ thuộc schema
  161. tools/
  162. api.ts # allowlist cho tool generic
  163. tracker.ts # search / summarize / format doc
  164. register.ts # đăng ký 11 tool
  165. server.ts # entrypoint stdio
  166. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.