@omnicoreos/planka-mcp 0.2.0 → 0.3.0

package/docs/planka-2x-gotchas.md

@@ -87,13 +87,112 @@ card of the previous page:
 GET /api/lists/<LIST_ID>/cards?before[id]=<LAST_CARD_ID>&before[listChangedAt]=<LAST_CARD_listChangedAt>
 ```
 
-This fork follows that cursor until a page comes back short, capped at 20 pages.
-When it stops early, or when the last card has no `listChangedAt` and no cursor
-can be built, `planka_list_cards` returns `truncated: true` with a note. It says
-it did not see everything rather than pretending it did.
+This fork follows that cursor until a page comes back short, capped at 20 pages,
+and the page size is **derived from the first response, never assumed**: an
+instance answering 20 per page would otherwise stop on page one and report a
+third of the column as the whole of it. When pagination stops early, or when the
+last card has no `listChangedAt` and no cursor can be built, the result carries
+`truncated: true` with a note. It says it did not see everything rather than
+pretending it did.
+
+`planka_find_cards` with a `listId` avoids the cursor entirely: `GET
+/api/lists/:id` returns **every card of the column in one response**, so the
+answer is `truncated: false` by construction and `total` is the real size of the
+column. Verified on Planka 2.2.1 against a column of 159 cards — one request
+where the cursor needed four.
 
 Why it matters: an incomplete list looks exactly like a complete one.
 
+## 6. The `item` a write returns is not the state of the entity
+
+**Planka 2.x behavior:** a write answers `200` with the item it *thinks* it
+wrote, and that echo can disagree with the database.
+
+Measured against Planka 2.2.1:
+
+| Write | What it answers | What is true afterwards |
+|---|---|---|
+| `PATCH /api/cards/:id {isSubscribed:true}` | `200`, `item.isSubscribed: **null**` | re-reading the card says `true` |
+| `POST /api/lists/:id/cards` | `200` with `{item}` and **no `included`** | the card exists, but its tasks/labels are not in the answer |
+| `DELETE /api/cards/:id` | `200` with `{item}` of the deleted card | a later `GET` answers `404` JSON — that 404 is the proof |
+| `PATCH` with an empty body | `200` with the untouched item | nothing changed |
+
+So a `success: true` built out of the write's own response proves only that the
+request was accepted. The empty PATCH is the sharpest case: the tool reported a
+change that never happened.
+
+This fork writes and then **re-reads**, and reports `verified: true|false`
+(`src/operations/verify.ts`). The DELETE body is kept rather than discarded,
+because the deleted item carries the parent id (`cardId`, `boardId`) the
+confirmation read needs. Deletes are confirmed either by a 404 on the entity or
+by its absence from the parent.
+
+Corollary for tasks: there is no `GET /api/tasks/:id` in 2.x, so a task can only
+be verified through its card — which is why `planka_update_task` and
+`planka_delete_task` take an optional `cardId` and say
+`verificationUnavailable` when it is missing, instead of claiming success.
+
+## 7. Deleting a list deletes its cards
+
+**Planka 2.x behavior:** `DELETE /api/lists/:id` removes the column **and every
+card in it**, with no warning and no undo.
+
+The tool description and the docs now say so out loud, and `planka_delete_list`
+confirms the deletion by re-reading the board. There is no server-side guard:
+move the cards out first.
+
+## 8. Comments come 50 at a time, and only `beforeId` walks them
+
+Measured against Planka 2.2.1 on 2026-09-03:
+
+```text
+GET /api/cards/:cardId/comments             -> 50 items, newest first (id DESC)
+GET /api/cards/:cardId/comments?beforeId=X  -> the 50 older than X
+```
+
+`?limit=` and `?page=` are **ignored** — the page size is fixed at 50 in the
+server. A card with 120 comments therefore answers 50 and looks complete. Any
+"comment count" derived from one response is the size of that page, never the
+card's total.
+
+What planka-mcp does:
+
+- `planka_get_comments` returns `limit` comments (default 20) plus `hasMore` and
+  `nextBeforeId`, and `all: true` walks the pages up to a ceiling of 10, after
+  which it says `truncated: true`. Its `commentCount` is documented as what the
+  response carries.
+- the card's **real** total is `commentsTotal` on the card row itself, which is
+  what `planka_get_card` reports.
+
+The same `?beforeId=` cursor and the same 50-item page apply to
+`GET /api/cards/:id/actions` and `GET /api/boards/:id/actions`.
+
+## 9. `GET /api/cards/:id` names nothing
+
+The card response's `included` carries `cardMemberships`, `cardLabels`,
+`taskLists`, `tasks`, `customFieldGroups`, `customFields`, `customFieldValues`,
+`users` and `attachments`. It does **not** carry `comments`, and it does **not**
+carry `labels` or `lists`.
+
+So a card read on its own gives `listId` and a set of `labelId`s and no way to
+say which column it is in or what its labels are called. The names live only in
+the board payload (`GET /api/boards/:boardId`). `planka_get_card` resolves them
+with one board read cached for a minute, and treats a failure there as "no
+names", never as a failed read.
+
+## 10. Planka answers 404 where it means 403
+
+A 404 from Planka means one of three things, and the body does not distinguish
+them:
+
+1. the entity really does not exist;
+2. the ID is of the wrong kind (all IDs are strings of digits: a `labelId`
+   passed as a `listId` produces exactly this);
+3. **the agent user has no permission on it** — a 403 wearing a 404's clothes.
+
+Every 404 this server raises now names the kind of ID the path expected, keeps
+Planka's own message, and states the permission possibility.
+
 ## Related Planka 2.x traps
 
 ### Board-level card and label endpoints do not exist
@@ -124,11 +223,28 @@ accepts:
 Both are per list, not per board. Since enumerating a board's columns, or
 resolving a label name to its ID, needs a `GET /api/boards/:boardId` anyway, and
 that single call already carries every card with its description and label
-links, this fork filters board-level searches locally over that one request.
+links, planka-mcp filters board-level searches locally over that one request.
 Issuing one search per list would be N extra round-trips for data already in
 hand. What stays small in `planka_find_cards` and `planka_board_summary` is the
 **output**, which is what a model pays for.
 
+### The board read has no archive and no trash
+
+`GET /api/boards/:id` carries every card of the FINITE lists — the ones typed
+`active` or `closed`. The `archive` and `trash` lists come back with
+`name: null`, `position: null` and **without a single card**. There is no
+parameter to include them, and no `GET /api/boards/:id/cards` to ask again.
+
+So every read built on the board show — `planka_board_summary`,
+`planka_find_cards` without a `listId`, `planka_get_board`, `planka_list_lists` —
+describes the **visible** board, not everything Planka stores. A card someone
+archived is not "gone": it is outside what these tools can see. They all say so
+with `excludesArchived: true` rather than letting a zero pass for a fact.
+
+Verified on Planka 2.2.1: a board whose show reports 185 cards across 8 named
+columns also carries two nameless lists (`archive`, `trash`) with no cards
+attached to them anywhere in the payload.
+
 ### A projectId where a boardId goes returns a bare 404
 
 Project IDs and board IDs are both strings of digits. Nothing in either one says