ziptask

MCP task tracker for AI agents — pure state layer (statuses, deps, leases, versioning) over SQLite.

Install

One-liner — installs the published binary via the deploy/ framework (see deploy/app.env for every knob), seeds a default settings.json and provisions the service:

# latest release
curl -fsSL https://raw.githubusercontent.com/zumik3-del/ziptask/main/deploy/install.sh | bash

# from a checkout, or pinned to a version
sudo bash deploy/install.sh --version v0.4.0

Canonical layout: binary in /opt/ziptask, database and settings.json in /var/lib/ziptask/, deploy state (helpers, hooks, app.env) in ~/.ziptask/. Override with --dir, --port, --version and --no-service; bash deploy/install.sh --help lists them all. updater.sh and uninstall.sh are installed into ~/.ziptask/scripts/.

The layout, the unit policy and the per-app app.env keys are shared with synaptomind and subagentix and documented once, in zumik3-del/synaptomind docs/DEPLOY-LAYOUT.md.

Prebuilt release binaries target Linux x86_64 only. On other platforms (macOS, arm64 Linux) build from source with bun run build:bin.

Service mode

When systemd is detected and running, the installer renders /etc/systemd/system/ziptask.service from the framework's unit template (Restart=always, a bounded TimeoutStopSec, and the usual hardening) and starts it. The unit runs as the user that invoked the installer — even under sudo, SUDO_USER is honoured. Manage it with:

sudo systemctl start ziptask
sudo systemctl stop ziptask
sudo systemctl enable ziptask     # auto-start on boot
journalctl -u ziptask -f         # live logs

Remove with bash ~/.ziptask/scripts/uninstall.sh. It keeps the binary, the database and the state directory by default; add --purge to delete them.

MCP client config (stdio)

// Claude Desktop / Cursor / opencode — see your client's MCP config (key "mcpServers" in most)
{
  "mcpServers": {
    "ziptask": {
      "command": "/opt/ziptask/ziptask",
      "args": ["--stdio", "--settings", "/var/lib/ziptask/settings.json"]
    }
  }
}

Pass --settings so the DB path and options come from settings.json regardless of the client's working directory — otherwise the DB defaults to ./data/ziptask.db under the client's cwd. Clients do not expand ~ in command/args; substitute the absolute path (the installer prints a ready-to-paste block).

MCP client config (remote HTTP)

When the service is running on the same host, point the client at the HTTP endpoint instead:

{
  "mcp": {
    "ziptask": { "type": "remote", "url": "http://127.0.0.1:3005/mcp" }
  }
}

The endpoint has no authentication, so keep it bound to 127.0.0.1 (ZIPTASK_HOST/settings.json). Use a reverse proxy with auth if it must be reachable from other hosts.

Related MCP server: tasqr-mcp

Quick start (from source)

Requires Bun ≥ 1.4.

bun install
bun run start          # HTTP server on an ephemeral port (MCP endpoint + /health + experimental /api/tasks and /api/task/:id)
bun run start:stdio    # run over stdio

Build a binary

bun run build:bin        # produces dist/ziptask
dist/ziptask --version   # prints ziptask and the package.json version
dist/ziptask --stdio     # runs as stdio MCP server

Architecture

Layered by carrier, no framework beyond the MCP SDK:

The public task API is MCP, exposed at POST/GET/DELETE /mcp, alongside GET /health and two experimental REST-style read endpoints, GET /api/tasks and GET /api/task/:id (the latter kept as an integration endpoint for the subagentix client). No endpoint authenticates. Enumeration is scoped: the enumerating tools require a project slug, while by-id calls stay unscoped — see Projects. See HTTP endpoints.

Development

bun test               # unit tests (per-test temp DBs)
bunx tsc --noEmit      # type check
bun run lint           # biome check src/ scripts/
bun run src/smoke.ts   # MCP end-to-end over HTTP (ephemeral port + temp DB)
bun run changelog      # rebuild CHANGELOG.md from git tags (maintainers; clean tree required; prints next steps to commit/push manually)

The changelog script only regenerates CHANGELOG.md; it does not commit or push. After running it, commit and push manually:

git add CHANGELOG.md
git commit -m "docs: update CHANGELOG.md"
git push

Documentation

• Configuration — settings.json, environment variables, the upgrade path, and backups.

• HTTP endpoints — /mcp, /health, and the two experimental read endpoints GET /api/tasks and GET /api/task/:id.

• MCP tools — the 14-tool reference, projects and scope, task statuses, lease-reap semantics, and lease recovery paths.

• Projects — what a project is, the slug, the fail-closed scope rule, and the four project tools.

• Epic → sub-task workflow — declaring epics, attaching sub-tasks, roll-up, closure, and the cross-project constraints.

• Subagent setup — install and configure the example orchestrator + subagent agents.

License

MIT

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.