vwork
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vwork Tuần này tôi có task nào quá hạn?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
v-work
MCP server (Node.js + TypeScript) cho VNFITE Work — cho phép AI đọc tiến độ dự án, 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.
Chạy local qua stdio, không mở port, không gửi dữ liệu đi đâu ngoài vWork.vnfite.com.vn.
Vì sao bọc API thay vì crawl HTML
Trang /workplace/tien-do-du-an là SPA React (Vite). Dữ liệu đi qua REST API:
Base: https://vWork.vnfite.com.vn
Auth: POST /auth/login {username,password} → accessToken + refreshToken (xoay vòng)
Data: GET /project-tracker/eoffice/docs
GET /project-tracker/eoffice/me
PATCH /project-tracker/eoffice/docs/{collection}/{docId}
POST /project-tracker/eoffice/importBản đồ đầy đủ: 157 endpoint / 10 nhóm (project-tracker, tickets, notification, customer,
customer-care, customer-call, user/department, workplace files, permissions, ai-assistant).
Tool vwork_api phủ các endpoint còn lại mà không cần viết từng tool.
Related MCP server: TodoServer
Cài đặt
Cài global — gõ vwork trực tiếp (không cần npx)
npm i -g https://github.com/enles004/v-work/archive/refs/heads/master.tar.gz
vwork auth
vwork tasks --mineCà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
lệnh npm i -g ở trên. (npx chỉ chạy tạm, không tạo lệnh cố định.)
Config MCP client có thể dùng binary global:
{ "mcpServers": { "vwork": { "command": "vwork" } } }Qua npx (sau khi publish)
npx -y v-work auth # đăng nhập một lần
npx -y v-work auth statusConfig MCP client:
{
"mcpServers": {
"vwork": {
"command": "npx",
"args": ["-y", "v-work"]
}
}
}Nếu chưa publish lên npm, có thể chạy trực tiếp từ GitHub:
npx -y github:enles004/v-work authTừ source
npm install
npm run build
node dist/cli.js auth # hỏi username/password một lần
node dist/cli.js auth statusKhông cần file .env. Mặc định đã có sẵn:
base URL:
https://vWork.vnfite.com.vn(prod)project:
eofficechỉ đọc, cache 30s, timeout 20s
Chỉ khi cần đổi mặc định (ví dụ UAT) mới dùng biến môi trường VWORK_BASE_URL,
VWORK_PROJECT, VWORK_ALLOW_WRITE trong config của MCP client.
login hỏi username/password (password ẩn), lưu token vào
~/.config/v-work/tokens.json (chmod 600). Server dùng token này và tự refresh;
khi hết hạn hoàn toàn thì chạy login lại.
Cách khác (không khuyến nghị): đặt VWORK_USERNAME/VWORK_PASSWORD trong env của
MCP client — server tự đăng nhập. Password sẽ nằm trong config client.
npm run auth:check vẫn dùng để xem tài khoản + cấu trúc doc thật.
Cấu hình client
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json
hoặc %APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"vwork": {
"command": "node",
"args": ["/home/faris/code/My_Workspace/v-work/dist/cli.js"]
}
}
}Cursor / VS Code (.cursor/mcp.json hoặc .vscode/mcp.json): cùng cấu trúc trên.
Claude Code:
claude mcp add vwork -- node /home/faris/code/My_Workspace/v-work/dist/cli.js
/mcp # xem server đã kết nối + danh sách toolLưu ý: /mcp trong Claude và opencode mcp auth chỉ có flow OAuth cho server remote
HTTP. Server stdio (như server này) không có flow đó — auth nằm ở CLI login + token file.
Debug bằng MCP Inspector:
npm run inspectTools
Tool | Việc |
| tài khoản + quyền hiện tại |
| task được giao cho chính bạn (tự resolve danh tính) |
| ảnh chụp nhanh: tài khoản, tổng hợp tiến độ, ticket, thông báo chưa đọc |
| danh sách doc trong bảng tiến độ |
| tìm theo từ khoá / trạng thái / người phụ trách / collection / quá hạn |
| đếm theo collection, trạng thái, người phụ trách, quá hạn, sắp đến hạn |
| danh sách ticket hỗ trợ |
| chi tiết ticket |
| thông báo chưa đọc + mới nhất |
| cập nhật status/note của task (cần |
| gọi API bất kỳ trong allowlist (GET luôn được; ghi phải bật) |
Câu hỏi mẫu:
"Tuần này tôi có task nào quá hạn?"
"Tổng hợp tiến độ dự án eoffice, ai đang nhiều việc nhất?"
"Ticket nào đang mở cho khách hàng X?"
"Có thông báo chưa đọc nào không?"
Nền tảng
Chạy trên Linux, macOS, Windows (Node ≥ 20). Token lưu theo chuẩn từng OS:
OS | Đường dẫn |
Linux |
|
macOS |
|
Windows |
|
CI GitHub Actions chạy test + typecheck trên cả 3 OS với Node 20 và 22.
An toàn
Mặc định chỉ đọc:
VWORK_ALLOW_WRITE=false. Bậttruemới cho PATCH/POST/PUT/DELETE.Ghi chỉ mở cho
/project-tracker,/tickets,/notification;/auth/*và/permissions/*luôn bị chặn.Token lưu tại
~/.config/v-work/tokens.json(chmod 600), tự refresh và xoay vòng.Password chỉ nằm trong env của MCP client — không commit, không log.
Cache GET 30s để tránh spam API khi AI hỏi liên tiếp.
Phát triển
npm test # mock toàn bộ HTTP, không gọi mạng
npm run build
npm run dev # tsx, dùng khi debugCLI:
node dist/cli.js # chạy server (mặc định)
node dist/cli.js login # đăng nhập, lưu token
node dist/cli.js status # kiểm tra token
node dist/cli.js whoami # in tài khoản hiện tại
node dist/cli.js logout # xoá tokenCấu trúc:
src/
config.ts # env → Config (zod)
auth.ts # login / refresh / token store
client.ts # HTTP client: auth, retry 401, cache, timeout
format.ts # helper đọc JSON không phụ thuộc schema
tools/
api.ts # allowlist cho tool generic
tracker.ts # search / summarize / format doc
register.ts # đăng ký 11 tool
server.ts # entrypoint stdioAvailable Tools
11 toolsvwork_apiB
Gọi API VWork tuỳ ý (đã có sẵn auth). GET luôn được phép trong danh sách nhóm API; PATCH/POST/PUT/DELETE chỉ khi VWORK_ALLOW_WRITE=true và thuộc nhóm an toàn.
Inputs: path (required), body, query, method.
vwork_meA
Xem hồ sơ tài khoản VWork đang đăng nhập (họ tên, username, phòng ban) và danh sách quyền.
Inputs: no named parameters.
vwork_my_tasksA
Task/doc được giao cho CHÍNH tài khoản đang đăng nhập. Tự lấy danh tính từ /user/getUserInfo rồi khớp theo tên/username/email/id. Dùng khi người dùng hỏi 'tôi đang có task gì'.
Inputs: limit, status, project, includeDone, +1 more.
vwork_notificationsC
Xem thông báo chưa đọc và thông báo mới nhất của tài khoản.
Inputs: limit.
vwork_project_overviewB
Ảnh chụp nhanh: tài khoản hiện tại + tổng hợp tiến độ + ticket đang mở + thông báo chưa đọc.
Inputs: project.
vwork_ticketC
Xem chi tiết một ticket theo id.
Inputs: id (required).
vwork_ticketsB
Liệt kê ticket hỗ trợ nội bộ, lọc theo trạng thái và từ khoá.
Inputs: page, limit, query, status.
vwork_tracker_docsB
Lấy danh sách doc trong bảng tiến độ dự án (project tracker). Trả về tối đa limit doc kèm tổng số.
Inputs: limit, project.
vwork_tracker_searchB
Tìm task/doc trong bảng tiến độ theo từ khoá, trạng thái, người phụ trách, collection hoặc chỉ task quá hạn.
Inputs: limit, query, status, project, +3 more.
vwork_tracker_summaryA
Tổng hợp bảng tiến độ: số lượng theo collection, trạng thái, người phụ trách; đếm task quá hạn và sắp đến hạn (3 ngày).
Inputs: project.
vwork_update_taskA
Cập nhật một task/doc trong bảng tiến độ (theo code A01/E02 hoặc collection/doc_id). Chỉ gửi field cần đổi. Yêu cầu VWORK_ALLOW_WRITE=true.
Inputs: reference (required), note, status, project.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have a clearly distinct target: profile, tracker list/search/summary, a single task update, ticket list/detail, notifications, and a generic API escape hatch. The main overlap is vwork_my_tasks vs vwork_tracker_search (which also filters by assignee) and vwork_project_overview, which re-composes data from vwork_me, vwork_tracker_summary, vwork_tickets, and vwork_notifications. Descriptions do flag when to prefer each, keeping confusion limited.
All names share the vwork_ prefix and snake_case, with a mostly resource-oriented convention (vwork_me, vwork_tickets, vwork_ticket, vwork_notifications) plus a vwork_tracker_* namespace for the tracker family. The singular/plural pair (ticket/tickets) and the lone verb-style vwork_update_task are minor, readable deviations. No mixed camelCase or chaotic verb styles.
Eleven tools is squarely in the sweet spot for a workspace assistant covering identity, tracker, tickets, and notifications. Each tool corresponds to a recognizable user intent, and no redundant variations (e.g. process/run/execute) inflate the surface.
Read coverage is solid (list, search, aggregate, detail) and vwork_update_task covers the tracker write path, but there is no create/delete for tracker docs, no ticket create/update/comment, and no notification mark-as-read. The generic vwork_api tool is an escape hatch that partly compensates, though it requires the agent to know raw API paths and write-flag configuration.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Official Fibery MCP server: query and update your workspace from any AI client via OAuth.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceLocal stdio MCP server for working on Intern-hosted sites through guarded Git checkouts. It enables authentication, site preparation, testing, validation, and publishing via coding harnesses like Codex and Claude Code.37 npmMIT
- AlicenseNot gradedqualityBmaintenanceA host-local stdio MCP server that lets AI agents read and create tasks, comment, and run a full claim/heartbeat/release/complete lifecycle with automatic process identification, all through local-first actions that sync to a task workspace without exposing a GitHub token.MIT
- AlicenseAqualityBmaintenanceLets ChatGPT, Claude Desktop, Claude Code, and other MCP clients run an allowlisted set of local commands and read files from a chosen directory, so an assistant can analyse a codebase or trigger local generators (images, sprites, assets) without metered API tokens. The server is read-only and deny-by-default by default, with no shell, path containment, opt-in writes, and required auth when exposed over HTTP.33MIT
- AlicenseNot gradedqualityBmaintenanceA stdio MCP server that lets any MCP client dispatch tasks to the local WorkBuddy desktop agent, wait until a run reaches a terminal state, and independently verify evidence such as session transcripts, tool-call counts, and archived copies. It also exposes read-only tools for locating WorkBuddy projects and sessions, publishing runs into the desktop app's workspace, and inspecting scheduled automation tasks, their run history, and overall scheduler health.MIT