@omnicoreos/planka-mcp 0.2.0

package/dist/tools/tasks.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Tool: planka_create_tasks
+ * Add one or more tasks (checklist items) to a card.
+ */
+export declare const createTasksTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            cardId: {
+                type: string;
+                description: string;
+            };
+            tasks: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                minItems: number;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (params: {
+        cardId: string;
+        tasks: string[];
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+/**
+ * Tool: planka_update_task
+ * Update a task's name or completion status.
+ */
+export declare const updateTaskTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            taskId: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+            isCompleted: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (params: {
+        taskId: string;
+        name?: string;
+        isCompleted?: boolean;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+/**
+ * Tool: planka_delete_task
+ * Delete a task from a card.
+ */
+export declare const deleteTaskTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            taskId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (params: {
+        taskId: string;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+export declare const taskTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            cardId: {
+                type: string;
+                description: string;
+            };
+            tasks: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                minItems: number;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (params: {
+        cardId: string;
+        tasks: string[];
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            taskId: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+            isCompleted: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (params: {
+        taskId: string;
+        name?: string;
+        isCompleted?: boolean;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            taskId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (params: {
+        taskId: string;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+})[];
+//# sourceMappingURL=tasks.d.ts.map

package/dist/tools/tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/tools/tasks.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;sBAmBF;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE;;;;;;;;;;;;;CAqC5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;sBAqBD;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB;;;;;;;;;;;;;CAyCF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;sBAaD;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;;;;;;;;;;;;;CA6B3C,CAAC;AAEF,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;sBA/JI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAgEnC;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB;;;;;;;;;;;;;;;;;;;;;;;;;;sBA4DuB;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;;;;;;;;;;;;;IA+B8B,CAAC"}

package/dist/tools/tasks.js

@@ -0,0 +1,169 @@
+/**
+ * Task tools for PLANKA MCP server.
+ */
+import { createTasks, updateTask, deleteTask } from "../operations/tasks.js";
+import { PlankaError } from "../errors.js";
+/**
+ * Tool: planka_create_tasks
+ * Add one or more tasks (checklist items) to a card.
+ */
+export const createTasksTool = {
+    name: "planka_create_tasks",
+    description: "Add one or more tasks (checklist items) to a card.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            cardId: {
+                type: "string",
+                description: "The card ID",
+            },
+            tasks: {
+                type: "array",
+                items: { type: "string" },
+                minItems: 1,
+                description: "Task names to create",
+            },
+        },
+        required: ["cardId", "tasks"],
+    },
+    handler: async (params) => {
+        try {
+            const tasks = await createTasks({
+                cardId: params.cardId,
+                tasks: params.tasks.map((name) => ({ name })),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            tasksCreated: tasks.length,
+                            tasks: tasks.map((t) => ({
+                                id: t.id,
+                                name: t.name,
+                                isCompleted: t.isCompleted,
+                            })),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof PlankaError) {
+                return {
+                    content: [{ type: "text", text: `Error: ${error.message}` }],
+                    isError: true,
+                };
+            }
+            throw error;
+        }
+    },
+};
+/**
+ * Tool: planka_update_task
+ * Update a task's name or completion status.
+ */
+export const updateTaskTool = {
+    name: "planka_update_task",
+    description: "Update a task's name or completion status.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "The task ID",
+            },
+            name: {
+                type: "string",
+                description: "New task name",
+            },
+            isCompleted: {
+                type: "boolean",
+                description: "Mark as complete/incomplete",
+            },
+        },
+        required: ["taskId"],
+    },
+    handler: async (params) => {
+        try {
+            const { taskId, ...updates } = params;
+            // Only include defined fields
+            const patch = { taskId };
+            if (updates.name !== undefined)
+                patch.name = updates.name;
+            if (updates.isCompleted !== undefined)
+                patch.isCompleted = updates.isCompleted;
+            const task = await updateTask(patch);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            task: {
+                                id: task.id,
+                                name: task.name,
+                                isCompleted: task.isCompleted,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof PlankaError) {
+                return {
+                    content: [{ type: "text", text: `Error: ${error.message}` }],
+                    isError: true,
+                };
+            }
+            throw error;
+        }
+    },
+};
+/**
+ * Tool: planka_delete_task
+ * Delete a task from a card.
+ */
+export const deleteTaskTool = {
+    name: "planka_delete_task",
+    description: "Delete a task from a card.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            taskId: {
+                type: "string",
+                description: "The task ID to delete",
+            },
+        },
+        required: ["taskId"],
+    },
+    handler: async (params) => {
+        try {
+            await deleteTask({ taskId: params.taskId });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            message: `Task ${params.taskId} deleted`,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof PlankaError) {
+                return {
+                    content: [{ type: "text", text: `Error: ${error.message}` }],
+                    isError: true,
+                };
+            }
+            throw error;
+        }
+    },
+};
+export const taskTools = [createTasksTool, updateTaskTool, deleteTaskTool];
+//# sourceMappingURL=tasks.js.map

package/dist/tools/tasks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../../src/tools/tasks.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,192 @@
+# Planka 2.x compatibility gotchas
+
+The older published package can fail without throwing. That is worse than a loud
+error because an agent may make a workflow decision from false state.
+
+This fork fixes five known incompatibilities and verifies the dangerous writes.
+
+## 1. Comments appear empty
+
+**Old behavior:** read `included.comments` from `GET /api/cards/:cardId`.
+
+**Planka 2.x behavior:** comments live at:
+
+```text
+GET /api/cards/:cardId/comments
+```
+
+The old request returns HTTP 200, but the comments array is absent or empty. The MCP
+then reports zero comments without an error. This fork calls the dedicated endpoint
+for both `planka_get_comments` and the comments included by `planka_get_card`.
+
+Why it matters: comments often contain the newest decision or closing evidence.
+
+Upstream fix proposed in [PR #5](https://github.com/gogogadgetbytes/planka-mcp/pull/5).
+
+## 2. `labelIds` is silently discarded
+
+**Old schema:** only declared `addLabelIds`.
+
+MCP clients commonly send this natural payload:
+
+```json
+{
+  "cardId": "<CARD_ID>",
+  "labelIds": ["<LABEL_ID>"]
+}
+```
+
+Unknown properties were discarded during validation. The handler then counted an
+empty request and could return a successful result without touching the card.
+
+This fork:
+
+- accepts `labelIds` and `addLabelIds`;
+- merges and deduplicates them;
+- rejects an empty label operation;
+- re-reads the card after the operation;
+- returns `added`, `removed`, `alreadyPresent`, `notPresent`, `failed`, and
+  `finalLabelIds` from observed state.
+
+## 3. Removing a label uses criteria syntax
+
+The junction record returned by Planka has its own ID, but Planka 2.x deletion is
+addressed by label criteria:
+
+```text
+DELETE /api/cards/:cardId/card-labels/labelId:<labelId>
+```
+
+Deleting by the junction-record ID returns 404 and leaves the label attached. This
+fork uses the criteria URL and then verifies the final card state.
+
+## 4. Label colors are an open read contract
+
+Planka adds colors over time. A closed Zod enum on responses means one unfamiliar
+color rejects the entire `planka_get_board` response.
+
+This fork uses `z.string()` for label colors returned by Planka. Write paths remain
+validated against the currently documented Planka 2.x colors.
+
+Upstream fix proposed in [PR #1](https://github.com/gogogadgetbytes/planka-mcp/pull/1).
+
+## 5. A long column truncates in silence
+
+**Planka 2.x behavior:** `GET /api/lists/:listId/cards` returns at most 50 cards
+per page and **ignores `?limit=`**. There is no `total` in the response and no
+flag saying more exist.
+
+A column holding 77 cards answers with 50 of them, HTTP 200, and nothing else.
+Read as-is, that is a board with 27 cards fewer than it has, and an agent will
+happily conclude a card does not exist.
+
+The cursor is **composite**. Both parts are required, and they come from the last
+card of the previous page:
+
+```text
+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.
+
+Why it matters: an incomplete list looks exactly like a complete one.
+
+## Related Planka 2.x traps
+
+### Board-level card and label endpoints do not exist
+
+These two routes look like they should exist, and they do not:
+
+```text
+GET /api/boards/:boardId/cards
+GET /api/boards/:boardId/labels
+```
+
+Planka does not 404 them. The web server answers with the single-page app's HTML
+and **status 200**, so a client that only checks `response.ok` sees a success and
+then fails while parsing, or worse, treats the result as an empty collection.
+
+Cards and labels are reachable per list (`GET /api/lists/:listId/cards`) or in
+the board payload itself (`GET /api/boards/:boardId`, whose `included` carries
+every card, label, and card-label link).
+
+### Per-list `search` and `labelIds` really do filter server-side
+
+Verified against Planka 2.x on 2026-08-24, `GET /api/lists/:listId/cards`
+accepts:
+
+- `?search=<text>` — matches the card **name and description**, case-insensitive;
+- `?labelIds=<labelId>` — restricts to cards carrying that label.
+
+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.
+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.
+
+### 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
+which it is. Passing a project ID to a board tool produces
+`GET /api/boards/<projectId>` and a naked `404`, which does not hint that the ID
+belongs to a different kind of entity.
+
+This fork diagnoses that 404 before reporting it:
+
+- if the ID is a project with exactly one board, it resolves to that board and
+  the call proceeds;
+- if it is a project with several boards, the error says so and lists them with
+  their IDs and names;
+- if it is a project with no boards, the error says that instead;
+- if it is neither a project nor a board, the error says so and lists the boards
+  the account can actually see.
+
+### Creating lists requires `type`
+
+Planka 2.x requires all three fields:
+
+```json
+{
+  "name": "Pending",
+  "position": 65536,
+  "type": "active"
+}
+```
+
+Valid write types are `active` and `closed`. Board responses can also contain
+internal `archive` and `trash` lists; read schemas must tolerate them.
+
+### Creating cards requires a card type
+
+The server sends `type: "project"` by default when creating a card. Callers do not
+need to know this Planka-specific requirement.
+
+### Authentication redirects can turn into HTML
+
+Use the final HTTPS origin. An HTTP URL may redirect the authentication POST, lose
+its body, and return an HTML page. `setup.sh` uses `redirect: manual` and reports this
+case explicitly before writing configuration.
+
+## Why the smoke test uses the raw API
+
+A valid JSON-RPC result proves only that the MCP handler returned. It does not prove
+Planka persisted the change.
+
+`npm run test:smoke` builds the server, starts it over stdio, and drives all 24
+tools through real MCP calls — 64 named checks. Every write is then cross-checked
+against the raw Planka HTTP API: a tool that reports success on something that
+never landed fails here. It creates a uniquely prefixed card, list, labels, tasks,
+comments, and an attachment, exercises the scoped reads against the sizes the raw
+board actually returns, feeds a project ID to a board tool to confirm the 404 gets
+explained, and deletes everything it made in a `finally` — over raw HTTP, so
+cleanup does not depend on the component under test.
+
+`PLANKA_SMOKE_FAIL_AFTER=<n>` injects a failure after check `n`, which is how the
+cleanup path itself is verified.
+
+This is the regression defense for silent failures.