viot-tasktisk

MCP server for qlda-viot task tracking. Exposes 4 high-level skills to Claude — no raw API fiddling needed.

Ngoài 4 tool trên còn các tool dự án / cấu trúc / họp / timesheet (list_projects, get_project, add_block, add_meeting, log_time, comment…).

Tool PMS (v1.5.0) — src/pms.ts

add_meeting từ v1.5.0 không bắt buộc project_id (bỏ trống = họp tổng thể) và nhận thêm giờ, thời lượng, hình thức, địa điểm. E2E: npx tsx tests/pms-e2e.ts (chạy trên qlda-viot local, tự dọn dữ liệu test).

Install

Requires Node.js ≥ 20.

macOS / Linux

Run the installer. It asks a few questions upfront — global vs. user install, then your QLDA credentials — so the rest (npm install + setup wizard) runs unattended:

curl -fsSL https://raw.githubusercontent.com/Iot-Viet-Solution/viot-tasktisk/main/install.sh | bash

Upfront prompts:

• Global or User install

• QLDA API URL (default http://localhost:3100)

• Username

• Password (hidden input)

Config is saved to ~/.config/viot-tasktisk/config.json (mode 0600). The wizard prints the exact snippet to paste into Claude Desktop when done.

Install options explained

Windows

npm install -g https://github.com/Iot-Viet-Solution/viot-tasktisk/releases/latest/download/viot-tasktisk-1.10.0.tgz
viot-tasktisk setup

Manual install (without the script)

# Global
npm install -g https://github.com/Iot-Viet-Solution/viot-tasktisk/releases/latest/download/viot-tasktisk-1.10.0.tgz
viot-tasktisk setup

# User-local
npm install -g --prefix ~/.npm-global https://github.com/Iot-Viet-Solution/viot-tasktisk/releases/latest/download/viot-tasktisk-1.10.0.tgz
export PATH="$HOME/.npm-global/bin:$PATH"   # add to ~/.zshrc or ~/.bashrc
viot-tasktisk setup

Related MCP server: mcp-todo

Claude integration

viot-tasktisk setup offers to auto-configure both Claude products at the end of the wizard. To re-run just the config step (without re-entering credentials):

viot-tasktisk configure

This registers viot-tasks as a stdio MCP server for each product:

Claude Code is the one exception: its CLI doesn't read MCP servers from ~/.claude/settings.json (despite that file existing and looking plausible) — the only supported way to register one is the claude mcp subcommand, which stores it in ~/.claude.json. configure shells out to claude mcp remove (ignoring "not found") then claude mcp add, so re-running it updates the command instead of erroring on a duplicate. This requires the claude CLI to be on PATH. Command Code works the same way: configure shells out to cmdc mcp remove / cmdc mcp add -s user (user scope, stored in ~/.commandcode/mcp.json), which requires the cmdc CLI to be on PATH.

Restart Claude Desktop / reload Claude Code / Command Code after configuring.

User-local install: every target here launches the server as its own subprocess rather than through your interactive shell, so none of them see a PATH change that only lives in ~/.bashrc / ~/.zshrc. configure therefore always uses the full binary path (~/.npm-global/bin/viot-tasktisk) for a user-local install, for every target — not just Claude Desktop.

Usage

From Claude

Once configured (see above), just ask in plain language — Claude picks the right tool:

• "What's on my dashboard today?"

• "Mark task 482 as Done"

• "Show me item 120 with all its tasks"

• "Add a task to item 120: write API tests, due 2026-07-10, priority Cao"

Direct CLI (no Claude needed)

Every tool is also a standalone terminal command — handy for scripts or a quick check:

viot-tasktisk dashboard                       # your tasks + weekly priorities
viot-tasktisk my-tasks                        # alias for dashboard
viot-tasktisk get-item <item_id>               # full item detail + child tasks
viot-tasktisk add-task <item_id> <title> [options]
  --due YYYY-MM-DD          # due date
  --priority TB|Cao|Thấp    # priority
  --assignee <user_id>      # assign to user
  --descr <text>            # description
viot-tasktisk update-task <task_id> <status>   # Plan · Todo · Doing · Done · Close · "Need help"
viot-tasktisk update-item <item_id> <status>   # Todo · Doing · Review · Done · Cancelled
viot-tasktisk week-goals [list|add|update|delete] ...
  --week YYYY-Wnn|current|next|prev|all   # which ISO week (default: current)
  --mine / --project <id> / --user <id>   # list filters
  --pct N                                 # % progress (add/update)
viot-tasktisk week-priorities [list|add|update|delete] ...
  --week YYYY-Wnn|current|next|prev       # which ISO week (default: current)
  --rank N                                # 1 = highest
  --project <id> | --lead <id>            # scope; omit both = chung (all projects)
viot-tasktisk --help                           # full command reference

Examples:

viot-tasktisk get-item 120
viot-tasktisk add-task 120 "Write API tests" --due 2026-07-10 --priority Cao
viot-tasktisk update-task 482 Done
viot-tasktisk week-goals --week next                       # team goals for next week
viot-tasktisk week-goals add 10 "Xong API đăng nhập"        # goal for me, current week
viot-tasktisk week-goals update 42 --pct 80                 # bump progress
viot-tasktisk week-priorities                               # this week's priority list
viot-tasktisk week-priorities add "Chốt nghiệm thu GĐ1" --rank 1
viot-tasktisk week-priorities add "Fix P1" --rank 2 --project 10

Troubleshooting

If the server runs but tools don't work in Claude (or you're helping someone else debug this remotely), start with:

viot-tasktisk doctor

It checks Node version, config validity, URL reachability, login, and whether each client (Claude Desktop, Claude Code, Command Code, VS Code, Antigravity, Codex) has a working — not just present — viot-tasks registration, then prints the tail of the local log. Every server run (and every direct-CLI command) also appends to that log regardless of what the MCP client does with its own logs, at ~/.config/viot-tasktisk/logs/latest.log (%USERPROFILE%\.config\viot-tasktisk\logs\latest.log on Windows) — useful when a client only shows a generic "failed to connect" with no detail. Paste the doctor output (or the log file) when asking for help.

Override via env vars

Env vars take priority over the config file — useful for CI or Docker:

QLDA_URL=http://your-server:3100 \
QLDA_USERNAME=thanh \
QLDA_PASSWORD=secret \
viot-tasktisk

Requests that fail with a network error or a gateway/rate-limit status (408, 429, 502, 503, 504, 524 — e.g. Cloudflare's "524 A Timeout Occurred") are retried automatically with exponential backoff, up to 3 times by default. Override with QLDA_MAX_RETRIES=<n>, or by adding "maxRetries": <n> to ~/.config/viot-tasktisk/config.json.

Update

viot-tasktisk update

Pulls the latest version from GitHub and reinstalls using the same prefix (global or user-local) that was used when you first installed. Prints a reminder to restart Claude Desktop.

Re-configure

viot-tasktisk setup

Development

git clone https://github.com/Iot-Viet-Solution/viot-tasktisk
cd viot-tasktisk
npm install
npm run dev          # run directly with tsx (no build needed)
npm run build        # rebuild dist/index.js
npm run typecheck    # type check only

The prebuilt dist/index.js is committed so the GitHub install needs no build step. When you change source, run npm run build and commit dist/index.js.

Seed accounts (for testing against local qlda-viot)

Default URL: http://localhost:3100

Claude Code plugin (skills + MCP)

Adds four skills (weekly review, task triage, meeting minutes, setup help) that load only when relevant, and registers the MCP server with credentials stored via the plugin's settings prompt. Requires the viot-tasktisk binary on PATH (see install above).

/plugin marketplace add Iot-Viet-Solution/viot-tasktisk
/plugin install viot-tasktisk@viot-tools