Skip to main content
Glama

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/import

Bả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 --mine

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 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 status

Config 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 auth

Từ source

npm install
npm run build

node dist/cli.js auth      # hỏi username/password một lần
node dist/cli.js auth status

Không cần file .env. Mặc định đã có sẵn:

  • base URL: https://vWork.vnfite.com.vn (prod)

  • project: eoffice

  • chỉ đọ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 tool

Lư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 inspect

Tools

Tool

Việc

vwork_me

tài khoản + quyền hiện tại

vwork_my_tasks

task được giao cho chính bạn (tự resolve danh tính)

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

vwork_tracker_docs

danh sách doc trong bảng tiến độ

vwork_tracker_search

tìm theo từ khoá / trạng thái / người phụ trách / collection / quá hạn

vwork_tracker_summary

đếm theo collection, trạng thái, người phụ trách, quá hạn, sắp đến hạn

vwork_tickets

danh sách ticket hỗ trợ

vwork_ticket

chi tiết ticket

vwork_notifications

thông báo chưa đọc + mới nhất

vwork_update_task

cập nhật status/note của task (cần VWORK_ALLOW_WRITE=true)

vwork_api

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

~/.config/vwork-mcp/tokens.json

macOS

~/Library/Application Support/vwork-mcp/tokens.json

Windows

%APPDATA%\vwork-mcp\tokens.json

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ật true mớ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 debug

CLI:

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á token

Cấ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 stdio

Available Tools

11 tools
vwork_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_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

    B3.4/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Local 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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
    • A
      license
      A
      quality
      B
      maintenance
      Lets 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.
      3
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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