laver-mcp

# @laver/mcp

An MCP server for [Laver](https://laver.app). Gives an agent tools to read and
drive kanban boards, tickets and the workspace wiki.

Every tool is a thin call to the same public REST API the web app uses. There is
no local state, no cache, and no second implementation of anything — if Laver
refuses a write, the refusal comes back verbatim, because an agent can act on
"409, re-read and retry" and cannot act on "something went wrong".

## Setup

Create a workspace-scoped API key in Laver under **Admin → API keys**. It acts
as the person who created it, so it can do exactly what they can do and nothing
more, and it can be revoked without touching their account.

```json
{
  "mcpServers": {
    "laver": {
      "command": "npx",
      "args": ["-y", "@laver/mcp"],
      "env": { "LAVER_API_KEY": "your key here" }
    }
  }
}
```

`LAVER_API_URL` overrides the API host; it defaults to `https://api.laver.app`.
`LAVER_API_KEY_FILE` is an alternative to `LAVER_API_KEY`: a path to either a
file containing nothing but the key, or a `.env`-style file with a
`LAVER_API_KEY=…` line among others (an assignment line wins; quotes and an
`export` prefix are both fine). That is how the `.mcp.json` in this repo
registers the server without a secret in a tracked file.

A file with neither — no assignment line, and more than one token in it — yields
**no key at all**, and you get the "key is not set" error. It used to send the
whole file as the token, which is fine for a file holding one secret and is a
leak for anything else.

`LAVER_API_URL` must be `https`, except for `localhost`.

### Working in this repo

`.mcp.json` at the repo root registers this server for anyone who opens the
project, reading the key from the gitignored `.env`. Nothing to export.

It runs the **published** package, `npx -y @laver/mcp`, rather than the
`mcp/server.js` beside it. That is deliberate: pointing it at the local file
meant everyone here ran the one code path no user takes, and that is precisely
how 0.1.0 shipped with an entry point that never connected its transport when
started through `bin` — which is the only way a real client starts it. Running
what we publish means we meet what users meet.

**If you are editing this server**, that same choice will fool you: your changes
do nothing until they are published. Point the client at the working copy while
you work on it —

```json
{ "command": "node", "args": ["mcp/server.js"] }
```

— and put it back before you commit. `npm run check` and
`frontend/tests/check-mcp-bin-entrypoint.mjs` both run against the working copy
regardless, so the tests never depend on a publish.

**A client only connects to MCP servers at startup.** `claude mcp add` while a
session is already running does not retrofit the tools into that session — the
tool list was built before the server existed. Start a new session (or
reconnect from the client's MCP panel) and the tools appear.

## Tools

**Reading**

| Tool                     | What it gives you                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------- |
| `list_workspaces`        | Where to start when you have no uuids                                                 |
| `list_boards`            | The boards in a workspace                                                             |
| `get_board`              | A board with its status columns, labels, members and tickets                          |
| `list_tickets`           | Tickets on a board, filterable, paged — `updated_since` is how you follow a board     |
| `list_workspace_tickets` | Triage across every board at once — `overdue`, `unassigned`, or free text             |
| `get_ticket`             | One ticket in full, its subtasks, **including its `version`**                         |
| `get_ticket_comments`    | Comments and activity history                                                         |
| `get_ticket_flow`        | How long the ticket has spent in each column                                          |
| `list_custom_fields`     | A board's custom field definitions — the uuids `update_ticket` writes against         |
| `list_labels`            | Every label in the workspace, not only the ones already used on one board             |
| `search`                 | Boards, tickets, wiki pages and comments across a whole workspace at once             |

`list_workspace_tickets` is the stand-up read: it needs no `board_uuid`, and it
is the only thing here that answers "what is late" and "what does nobody own"
without walking every board. It is deliberately the small sibling of
`list_tickets` — one page, 50 by default and 200 at most, no cursor — so narrow
it rather than paging it.

`get_ticket_flow` derives its numbers from the moves already in a ticket's
history. Read `visits` rather than the `by_status` totals if you are adding
several tickets up: tickets worked in one batch overlap, and their totals do not.
`gaps` says when the history and the ticket's current column disagree, which
makes the totals a floor rather than a measurement.

To follow a board, call `list_tickets` again with `updated_since` set to the
`server_time` the previous call returned; you get back the tickets that changed
and nothing else. There is no tool for the server-sent event stream at
`GET /boards/:uuid/events` — a tool call is one request and one answer, and a
stream that never ends is neither.

**Asking for less.** A tool result is charged against the model's context, and
three of these calls are the ones you cannot route around: a `status_uuid` or a
`label_uuid` comes from `get_board`, and a `page_uuid` comes from
`get_wiki_tree`. On a busy board they were 154 kB, 119 kB and 180 kB. Each now
takes a parameter that narrows the reply, and every one of them is opt-in — a
call that passes none of them is unchanged.

| Call                                        | Gives you                                      | Measured        |
| ------------------------------------------- | ---------------------------------------------- | --------------- |
| `get_board(include_tasks: false)`           | the structure alone — statuses, labels, fields | 155 kB → 17 kB  |
| `get_wiki_tree(depth: 1)`                   | the top level, nothing nested under it         | 119 kB → 1.8 kB |
| `get_wiki_tree(parent_page_uuid: …)`        | one page and everything beneath it             | 119 kB → 9.8 kB |
| `list_tickets(include_descriptions: false)` | titles and uuids without the bodies            | 167 kB → 45 kB  |

Reach for `get_board(include_tasks: false)` whenever you called it for a uuid
rather than for the tickets, and `list_tickets` when you want the tickets —
that one takes `status` and `limit` as well.

**Writing**

| Tool                | Notes                                                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `create_ticket`     | `status` takes the column name, or pass `status_uuid`; markdown in `description` is parsed                                     |
| `update_ticket`     | Needs `version`; markdown in `description` is parsed; `custom_fields` is keyed by field uuid and **replaces** the whole object |
| `move_ticket`       | Needs `version`, and a column — neither column is a 400                                                                        |
| `comment_on_ticket` | Markdown in `body` is parsed; no `version`, so it cannot 409                                                                   |
| `update_comment`    | Your own comments only; replaces the whole body and is marked as edited                                                       |
| `delete_comment`    | Your own comments only; to the trash, and nothing here restores one                                                           |
| `mark_comments_read`| Clears this ticket's unread badge for the user the key acts as                                                                |
| `add_subtask`       | One checklist item, appended — plain text, not markdown                                                                       |
| `update_subtask`    | Tick it off (`is_done`), rename it, or move it up the list                                                                    |
| `delete_subtask`    | **Not** recoverable — a checklist item has no trash                                                                            |
| `archive_ticket`    | To the trash — **recoverable** for 30 days                                                                                     |
| `delete_ticket`     | Destroys one already in the trash — **permanent**                                                                              |
| `create_board`      | Optionally from a template — `crm` or `sales-leads`                                                                            |
| `link_tickets`      | "this before that" — direction is `blocks` or `blocked_by`                                                                     |
| `unlink_tickets`    | From either end, and removes **every** kind of link on the pair                                                                |

Comments are not versioned, so none of the three comment writes takes a
`version` and none of them can 409 — the last edit wins. Only the author may
edit or delete one, and somebody else's is a 404 indistinguishable from a
comment that does not exist, so these never report who wrote what.
`get_ticket_comments` deliberately marks nothing read; `mark_comments_read` is
the only call that does, and it marks up to the newest comment that exists at
that moment rather than subscribing.

Subtasks are the checklist on a ticket — a progress count on the car