# System Task — MCP plugin for Claude Code

Run your projects and your team from a conversation: see how each project is doing, who is
overloaded, **who has nothing assigned**, and register work in a shape people can actually execute
and verify.

**[System Task](https://system-task.defaltm.com)** is a task and project app for small teams —
web, Android and Windows. This plugin connects it to Claude Code.

---

## Install

In Claude Code:

```
/plugin marketplace add luis1amaral/system-task-mcp
```

```
/plugin install system-task
```

```
/plugin configure system-task
```

The third command asks for one thing — your **access token**. Generate it in the System Task app
under **Settings → Agent access**, tap *Connect Claude Code*, and paste it. (`install` prompts too
when the token is missing; `configure` always does, and is also how you replace it later.) It goes
into the client's own credential store — never into a project file, never into your shell history.

Don't have an account yet? Create one at **[system-task.defaltm.com](https://system-task.defaltm.com)**.

---

## Where the token lives (and why you only paste it once)

Each MCP client keeps its own copy of the plugin config, so a second app — or the same one after a
reinstall — used to start disconnected and ask for the token again. It looks like the token vanished;
it never did.

So the server reads it from two places, in this order:

| Order | Source | Who fills it |
|---|---|---|
| 1 | `SYSTEM_TASK_TOKEN` | the plugin, from the client's config |
| 2 | `~/.config/system-task/token` (`%APPDATA%\system-task\token` on Windows) | written automatically the first time a token arrives through the environment |

The file is created with mode `0600` inside a `0700` directory, holds one line, and is what makes
every *new* client start already connected. The environment always wins — it is what the client was
told to use right now — and a new token there replaces the stored one.

- `SYSTEM_TASK_TOKEN_FILE=/other/path` — use a different file.
- `SYSTEM_TASK_TOKEN_PERSIST=0` — never write it to disk (you then supply the variable every time).

The startup line on `stderr` says which source was used, e.g. `system-task: pronto (…) [token:
ambiente]`. The token itself never appears in a log or an error message — only the path.

---

## What the token can and cannot do

The agent token is **not a second login**. The server only accepts it on a closed list of routes:
read reports, search, create and edit tasks, comment, move. It **deletes nothing**, cannot touch
your account, cannot see billing and cannot mint another token.

If it ever leaks, you revoke it in two taps on the same screen — and the "last used" column tells
you whether it is still plugged into some machine.

---

## Commands

The plugin ships two slash commands:

| Command | Does |
|---|---|
| `/daily` | Your day in one call: due today, overdue, estimated time |
| `/system-task #project` | Tasks, optionally for one project. Also takes `atrasadas`, `sem dono`, `de ana` |

## Tools

**Read**

| Tool | Answers |
|---|---|
| `systemtask_day_brief` | What is yours today, what is late, how much time that adds up to |
| `systemtask_projects_list` | Every project, with progress, overdue and unassigned counts |
| `systemtask_project_report` | One project: totals, board columns, created vs. completed |
| `systemtask_project_risks` | Overdue, undated, unassigned — oldest first |
| `systemtask_team_load` | Workload per person and **who has nothing assigned** |
| `systemtask_team_list` | Who is on the project |
| `systemtask_tasks_search` | Search by project, assignee, status, period |
| `systemtask_task_get` | One task in full — the escape hatch when a title is truncated |
| `systemtask_whoami` | Which account the token opens |
| `systemtask_list_trash` | What is in the lists trash, ready to restore or purge |

**Write**

| Tool | Does |
|---|---|
| `systemtask_demand_create` | Registers a **demand** (objective + deliverable + done-when) |
| `systemtask_task_create` | Creates a simple task of your own |
| `systemtask_task_update` | Complete, reschedule, reprioritise, estimate |
| `systemtask_task_assign` | Set or clear the assignee (one, or nobody) |
| `systemtask_task_move` | Move between projects (a recurring task moves its whole series) |
| `systemtask_task_comment` | Comment on a task (an `@user` notifies that person) |
| `systemtask_list_create` | Creates a list (the app's "project") |
| `systemtask_list_rename` | Renames a list, and/or changes its color/icon |
| `systemtask_list_delete` | Sends a list to the trash — reversible, tasks go with it |
| `systemtask_list_restore` | Restores a list from the trash, tasks included |
| `systemtask_list_purge` | Deletes a list **for good** — only when the user explicitly asks for that |

---

## The demand format

`systemtask_demand_create` requires three things, and that is the point of the plugin:

- **objective** — what needs to exist (becomes the title);
- **deliverable** — what is concretely handed over;
- **doneWhen** — a criterion **another person can verify without asking anyone**.

The *how* is never prescribed: the method belongs to whoever does the work. Subtasks only when the
demand has genuinely independent deliverables — the default is not to split.

That discipline is what stops a task from sitting open for two months because nobody can assert it
is finished.

---

## Example prompts

> "How are my projects doing?"
> "In The City, who has nothing assigned?"
> "Create a demand for João: ship the pricing page, done when /pricing returns 200 with the 3 plans, due Friday"
> "What do I have today?"
> "Show me what's overdue in the Vendas project"

---

## Self-hosting

Pointing the plugin at your own System Task API is an environment variable, not a plugin option:
set `SYSTEM_TASK_API_URL`. It is deliberately not in the configure panel — the plugin should ask
for one thing only.

## Development

```bash
npm install
npm run build
node scripts/smoke.mjs                              # protocol only (no token)
SYSTEM_TASK_TOKEN=stk_... node scripts/smoke.mjs    # + read tools against the API
node scripts/token-file.mjs                         # the token cascade (env → file), no real token
npm run check                                       # tsc + build + both of the above
```

`scripts/smoke.mjs` speaks JSON-RPC to the built binary over stdin/stdout, exactly like an MCP
client — including a check that **nothing but the protocol** is written to `stdout` (the number one
failure in stdio servers: one `console.log` corrupts the channel).

`dist/` is committed on purpose: installing a plugin copies the folder and does not run
`npm install`. When releasing, run `npm run build` and bump `version` in
`.claude-plugin/plugin.json` — without the bump, nobody receives the update.

## License

MIT.