@denisixnpm/planka-mcp 2.5.1 → 2.6.0

package/README.md

@@ -135,9 +135,20 @@ Every tool takes `action`, optional `id`/`data`/`query`, and optional `raw: true
 
 Actions per tool are enumerated in the MCP `tools/list` response. Live-verified semantics worth
 knowing: project managers exist only on `shared` projects; notification services are self-only;
-v1.26.2 lacks REST task-lists/custom-fields/webhooks (clean 404s); renamed v1 membership/label
-routes are retried automatically; link attachments to some URLs (e.g. `example.com`) HTTP 500
-inside Planka 2.0.3 itself.
+v1.26.2 lacks REST task-lists/custom-fields/webhooks (clean 404s); renamed v1 membership/label/
+comment routes are retried automatically; `labels.list` and `cards.find` derive from `boards.get`
+(Planka has no labels GET route on either major); link attachments to some URLs (e.g.
+`example.com`) HTTP 500 inside Planka 2.0.3 itself.
+
+### If a tool reports "returned an HTML page"
+
+Planka serves its web UI from the same origin as the API, so a route the server does not have may
+answer `200 text/html` (the SPA's `index.html`) instead of `404`. The server refuses to pass that
+off as data and tells you which call hit it. Usually it means the route is newer than your Planka:
+on 1.26.x the server transparently retries the v1 route, or derives the answer from `boards.get` /
+the card activity log and marks the result with a `_compat` note. If it names a route with no v1
+equivalent (task lists), the error also names what to use instead. A page returned for *every*
+call, including login, means `PLANKA_BASE_URL` points at a proxy or portal rather than at Planka.
 
 ## Multi-client SSE mode (optional)
 
@@ -164,12 +175,12 @@ Compiled Bun binary on distroless (no shell, no node_modules).
 
 ```bash
 bun install
-bun test                                    # hermetic suite
-E2E_PLANKA_URL=… E2E_PLANKA_V1_URL=… bun test  # + live Planka e2e (154 tests)
+npm test          # build + hermetic suite (222 tests)
+npm run e2e       # + live Planka 2.0.3 and 1.26.2: up, test, tear down
+npm run check     # lockfile + version-trio guards, then the suite (run before tagging)
 ```
 
-E2E stacks: `docker compose --profile e2e up -d`. Details in [CONTRIBUTING.md](CONTRIBUTING.md)
-and [CLAUDE.md](CLAUDE.md).
+Details in [CONTRIBUTING.md](CONTRIBUTING.md) and [CLAUDE.md](CLAUDE.md).
 
 ## Credits
 

package/dist/compat.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Planka version compatibility: everything the engine needs to decide *which*
+ * route to use, with no network and no engine state. Kept separate from
+ * `server.ts` so the tables and the fingerprint logic can be unit-tested
+ * directly — driving them through the stdio transport would otherwise leave
+ * most branches unreachable.
+ *
+ * Every route table is keyed by `` `METHOD path` `` using the canonical
+ * (un-substituted) path from `src/tools/*​/tools.ts`. `test/compat.test.ts`
+ * asserts each key still resolves to a real operation, so renaming a path in
+ * a tool definition cannot silently orphan an entry here.
+ */
+/** The Planka API generation: 1 = <= 1.26.x, 2 = 2.x, null = undetermined. */
+export type PlankaMajor = 1 | 2 | null;
+/**
+ * Planka serves its SPA from the same origin as the API, and a reverse-proxied
+ * deployment answers an unknown /api/* route with 200 + index.html instead of
+ * 404 (verified against a live 1.26.x host). Two things go wrong if this is not
+ * detected: the engine reports success and hands the agent a web page, and the
+ * 404-driven legacy-route fallback never fires. An HTML body always means
+ * "this route does not exist here".
+ *
+ * The body test is deliberately anchored: a JSON payload that merely *contains*
+ * markup somewhere (a card description, say) is data, not a catch-all page.
+ */
+export declare function looksLikeHtml(contentType: string, body: string): boolean;
+/**
+ * Decide the Planka generation from a `GET /api/config` response.
+ *
+ * v1's `show-config` returns exactly `{oidc, allowAllToCreateProjects}` to
+ * anyone; v2's `config/show` presents the whole Config model and is gated
+ * behind admin — so an auth failure is itself a v2 signal. Anything we cannot
+ * read (an HTML catch-all, a non-JSON body, a missing envelope) stays `null`
+ * rather than guessing: callers treat `null` as "unknown", not as "v1".
+ */
+export declare function fingerprintConfig(status: number, contentType: string, body: string): PlankaMajor;
+export declare function describePlankaMajor(major: PlankaMajor): string;
+/**
+ * Planka <= 1.26.x routes that v2 renamed, verified against a live 1.26.2
+ * instance and its `server/config/routes.js`. When the v2 route is missing
+ * (a clean 404, or the SPA catch-all's 200 + index.html), the call is retried
+ * once with the legacy route so a single server build serves both API
+ * generations.
+ *
+ * The method is part of the key because `/cards/{cardId}/comments` needs a
+ * rename for POST but an emulator for GET.
+ *
+ * No custom-field-value entry: v1.26.x has no custom-field routes at all, so
+ * there is nothing to fall back to. (An entry here once mapped to a path
+ * containing a literal `$` — a template-literal typo that matched no real
+ * route; `test/compat.test.ts` now guards against that class of mistake.)
+ */
+export declare const LEGACY_PATH_FALLBACKS: Record<string, string>;
+/**
+ * Routes v1 does not have but whose answer can be derived from one it does.
+ * The emulator functions live in `server.ts` (they need the request engine);
+ * this list is the single definition of *which* routes get one, so the keys
+ * cannot drift apart from the implementations.
+ */
+export declare const V1_EMULATED_ROUTES: readonly ["GET /cards/{cardId}/comments", "GET /lists/{id}", "GET /lists/{listId}/cards", "GET /bootstrap", "POST /task-lists/{taskListId}/tasks"];
+export type V1EmulatedRoute = (typeof V1_EMULATED_ROUTES)[number];
+/**
+ * v2-only routes with no v1 rename and no derivable source, and what an agent
+ * should reach for instead. Consulted only once a route is known to be missing,
+ * to turn a bare 404 or a masked HTML page into an actionable error.
+ */
+export declare const V1_ALTERNATIVES: Record<string, string>;

package/dist/compat.js

@@ -0,0 +1,109 @@
+/**
+ * Planka version compatibility: everything the engine needs to decide *which*
+ * route to use, with no network and no engine state. Kept separate from
+ * `server.ts` so the tables and the fingerprint logic can be unit-tested
+ * directly — driving them through the stdio transport would otherwise leave
+ * most branches unreachable.
+ *
+ * Every route table is keyed by `` `METHOD path` `` using the canonical
+ * (un-substituted) path from `src/tools/*​/tools.ts`. `test/compat.test.ts`
+ * asserts each key still resolves to a real operation, so renaming a path in
+ * a tool definition cannot silently orphan an entry here.
+ */
+/**
+ * Planka serves its SPA from the same origin as the API, and a reverse-proxied
+ * deployment answers an unknown /api/* route with 200 + index.html instead of
+ * 404 (verified against a live 1.26.x host). Two things go wrong if this is not
+ * detected: the engine reports success and hands the agent a web page, and the
+ * 404-driven legacy-route fallback never fires. An HTML body always means
+ * "this route does not exist here".
+ *
+ * The body test is deliberately anchored: a JSON payload that merely *contains*
+ * markup somewhere (a card description, say) is data, not a catch-all page.
+ */
+export function looksLikeHtml(contentType, body) {
+    return contentType.includes("text/html") || /^\s*<(!doctype|html)\b/i.test(body);
+}
+/**
+ * Decide the Planka generation from a `GET /api/config` response.
+ *
+ * v1's `show-config` returns exactly `{oidc, allowAllToCreateProjects}` to
+ * anyone; v2's `config/show` presents the whole Config model and is gated
+ * behind admin — so an auth failure is itself a v2 signal. Anything we cannot
+ * read (an HTML catch-all, a non-JSON body, a missing envelope) stays `null`
+ * rather than guessing: callers treat `null` as "unknown", not as "v1".
+ */
+export function fingerprintConfig(status, contentType, body) {
+    if (status === 401 || status === 403)
+        return 2;
+    if (looksLikeHtml(contentType, body))
+        return null;
+    let item;
+    try {
+        item = JSON.parse(body)?.item;
+    }
+    catch {
+        return null;
+    }
+    if (!item || typeof item !== "object" || Array.isArray(item))
+        return null;
+    const keys = Object.keys(item);
+    const isV1 = keys.length <= 2 && keys.every(k => k === "oidc" || k === "allowAllToCreateProjects");
+    return isV1 ? 1 : 2;
+}
+export function describePlankaMajor(major) {
+    return major === null ? "Planka version could not be determined" : `detected Planka ${major}.x`;
+}
+/**
+ * Planka <= 1.26.x routes that v2 renamed, verified against a live 1.26.2
+ * instance and its `server/config/routes.js`. When the v2 route is missing
+ * (a clean 404, or the SPA catch-all's 200 + index.html), the call is retried
+ * once with the legacy route so a single server build serves both API
+ * generations.
+ *
+ * The method is part of the key because `/cards/{cardId}/comments` needs a
+ * rename for POST but an emulator for GET.
+ *
+ * No custom-field-value entry: v1.26.x has no custom-field routes at all, so
+ * there is nothing to fall back to. (An entry here once mapped to a path
+ * containing a literal `$` — a template-literal typo that matched no real
+ * route; `test/compat.test.ts` now guards against that class of mistake.)
+ */
+export const LEGACY_PATH_FALLBACKS = {
+    "POST /boards/{boardId}/board-memberships": "/boards/{boardId}/memberships",
+    "POST /projects/{projectId}/project-managers": "/projects/{projectId}/managers",
+    "POST /cards/{cardId}/card-labels": "/cards/{cardId}/labels",
+    "DELETE /cards/{cardId}/card-labels/labelId:{labelId}": "/cards/{cardId}/labels/{labelId}",
+    "POST /cards/{cardId}/card-memberships": "/cards/{cardId}/memberships",
+    "DELETE /cards/{cardId}/card-memberships/userId:{userId}": "/cards/{cardId}/memberships?userId={userId}",
+    // v1 keeps comments in the activity log as `comment-actions`.
+    "POST /cards/{cardId}/comments": "/cards/{cardId}/comment-actions",
+    "PATCH /comments/{id}": "/comment-actions/{id}",
+    "DELETE /comments/{id}": "/comment-actions/{id}",
+};
+/**
+ * Routes v1 does not have but whose answer can be derived from one it does.
+ * The emulator functions live in `server.ts` (they need the request engine);
+ * this list is the single definition of *which* routes get one, so the keys
+ * cannot drift apart from the implementations.
+ */
+export const V1_EMULATED_ROUTES = [
+    "GET /cards/{cardId}/comments",
+    "GET /lists/{id}",
+    "GET /lists/{listId}/cards",
+    "GET /bootstrap",
+    "POST /task-lists/{taskListId}/tasks",
+];
+/**
+ * v2-only routes with no v1 rename and no derivable source, and what an agent
+ * should reach for instead. Consulted only once a route is known to be missing,
+ * to turn a bare 404 or a masked HTML page into an actionable error.
+ */
+export const V1_ALTERNATIVES = {
+    "GET /task-lists/{id}": "Planka 1.x has no task-list entity — cards.get already returns the card's tasks",
+    "PATCH /task-lists/{id}": "Planka 1.x has no task-list entity — update the individual tasks instead",
+    "DELETE /task-lists/{id}": "Planka 1.x has no task-list entity — delete the individual tasks instead",
+    "POST /cards/{cardId}/task-lists": "Planka 1.x has no task-list entity — create tasks directly with tasks.create",
+    "POST /lists/{id}/clear": "Planka 1.x has no list-clear route — delete the cards individually",
+    "POST /lists/{id}/move-cards": "Planka 1.x has no bulk move route — move cards individually with cards.update",
+};

package/dist/condense.d.ts

@@ -14,5 +14,9 @@
  *  - strings           -> truncated to TEXT_LIMIT characters
  *  - auth/context      -> verbatim (tokens and local state must not be mangled)
  */
-/** Reduce one tool result (envelope, list, or raw value). */
-export declare function condenseResult(toolName: string, data: unknown): unknown;
+/**
+ * Reduce one tool result (envelope, list, or raw value). `action` is optional
+ * and only consulted through ACTION_ENTITY_OVERRIDE, for actions that return
+ * something other than the tool's own entity.
+ */
+export declare function condenseResult(toolName: string, data: unknown, action?: string): unknown;

package/dist/condense.js

@@ -46,6 +46,17 @@ const ENTITY_FIELDS = {
     notifications: ["id", "type", "isRead", "cardId"],
     actions: ["id", "type", "cardId", "boardId", "userId", "createdAt", "data"],
 };
+/**
+ * Actions whose payload is not the tool's own entity. Without this,
+ * `cards.getActions` is reduced with the `cards` whitelist — action records
+ * share only `id` with a card, so every action collapsed to `{id}` and the
+ * comment text, type and timestamp were dropped silently.
+ */
+const ACTION_ENTITY_OVERRIDE = {
+    "cards.getActions": "actions",
+    "actions.boardActions": "actions",
+    "actions.cardActions": "actions",
+};
 /** `included` keys that do not match their tool name verbatim. */
 const INCLUDED_KEY_TO_TOOL = {
     boardMemberships: "boardMembers",
@@ -64,9 +75,33 @@ const GENERIC_FIELDS = [
 ];
 /** Tools whose payloads are returned verbatim (tokens, local state). */
 const PASSTHROUGH_TOOLS = { auth: true, context: true };
+/**
+ * `bootstrap.get` returns a bag of entity collections rather than one entity —
+ * `{user, projects, boards, notifications, …}` on v2, and the emulated shape on
+ * v1. No whitelist matches those keys, so `condenseEntity` would find nothing
+ * and fall back to returning the item verbatim, leaking the full user record.
+ * Treat the item like an `included` sidecar instead: arrays are condensed per
+ * entity, and `user` gets the `users` whitelist.
+ */
+const BOOTSTRAP_SINGLE_ENTITY = { user: "users", config: "config" };
 function truncateText(value) {
     return value.length > TEXT_LIMIT ? value.slice(0, TEXT_LIMIT) + "…" : value;
 }
+/**
+ * An action's payload lives in its `data` object (a comment's body is
+ * `data.text`). Keep the object but truncate its strings, so long comments do
+ * not slip past TEXT_LIMIT just because they are one level down.
+ */
+function condenseActionData(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return value;
+    }
+    const out = {};
+    for (const [key, inner] of Object.entries(value)) {
+        out[key] = typeof inner === "string" ? truncateText(inner) : inner;
+    }
+    return out;
+}
 function condenseEntity(toolName, entity) {
     if (typeof entity !== "object" || entity === null || Array.isArray(entity)) {
         return entity;
@@ -77,11 +112,42 @@ function condenseEntity(toolName, entity) {
     for (const field of whitelist) {
         const value = source[field];
         if (value !== null && value !== undefined) {
-            out[field] = typeof value === "string" ? truncateText(value) : value;
+            if (field === "data") {
+                out[field] = condenseActionData(value);
+            }
+            else {
+                out[field] = typeof value === "string" ? truncateText(value) : value;
+            }
         }
     }
+    // Deliberately NOT widened to "only `id` survived -> pass the entity
+    // through": whitelists are the only thing keeping fields like passwordHash
+    // out of an agent's context. A mismatched whitelist is fixed by mapping the
+    // action to the right entity (ACTION_ENTITY_OVERRIDE), not by leaking.
     return Object.keys(out).length > 0 ? out : entity;
 }
+/** Reduce the entity bag `bootstrap.get` returns as its `item`. */
+function condenseBootstrapItem(item) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        return item;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(item)) {
+        if (Array.isArray(value)) {
+            out[key] = value.map(entity => condenseEntity(INCLUDED_KEY_TO_TOOL[key] ?? key, entity));
+        }
+        else if (key === "included" && value && typeof value === "object") {
+            out[key] = condenseIncluded(value);
+        }
+        else if (value !== null && value !== undefined && typeof value === "object") {
+            out[key] = condenseEntity(BOOTSTRAP_SINGLE_ENTITY[key] ?? key, value);
+        }
+        else if (value !== null && value !== undefined) {
+            out[key] = typeof value === "string" ? truncateText(value) : value;
+        }
+    }
+    return out;
+}
 /** Reduce every entity array inside an `included` sidecar object. */
 function condenseIncluded(included) {
     const out = {};
@@ -93,13 +159,18 @@ function condenseIncluded(included) {
     }
     return out;
 }
-/** Reduce one tool result (envelope, list, or raw value). */
-export function condenseResult(toolName, data) {
+/**
+ * Reduce one tool result (envelope, list, or raw value). `action` is optional
+ * and only consulted through ACTION_ENTITY_OVERRIDE, for actions that return
+ * something other than the tool's own entity.
+ */
+export function condenseResult(toolName, data, action) {
     if (PASSTHROUGH_TOOLS[toolName]) {
         return data;
     }
+    const entityName = (action && ACTION_ENTITY_OVERRIDE[`${toolName}.${action}`]) || toolName;
     if (Array.isArray(data)) {
-        return data.map(item => condenseEntity(toolName, item));
+        return data.map(item => condenseEntity(entityName, item));
     }
     if (typeof data === "object" && data !== null) {
         const source = data;
@@ -115,10 +186,17 @@ export function condenseResult(toolName, data) {
         if (hasItems || hasItem) {
             const out = {};
             if (hasItems) {
-                out.items = source.items.map(item => condenseEntity(toolName, item));
+                out.items = source.items.map(item => condenseEntity(entityName, item));
             }
             if (hasItem) {
-                out.item = condenseEntity(toolName, source.item);
+                out.item = entityName === "bootstrap"
+                    ? condenseBootstrapItem(source.item)
+                    : condenseEntity(entityName, source.item);
+            }
+            // Compatibility notes from the Planka 1.x emulators must survive the
+            // envelope rebuild — they tell the agent where the data came from.
+            if (typeof source._compat === "string") {
+                out._compat = source._compat;
             }
             if (source.included && typeof source.included === "object") {
                 const included = condenseIncluded(source.included);
@@ -128,7 +206,7 @@ export function condenseResult(toolName, data) {
             }
             return out;
         }
-        return condenseEntity(toolName, data);
+        return condenseEntity(entityName, data);
     }
     return data;
 }

package/dist/server.js

@@ -10,6 +10,7 @@ import { basename, extname } from "node:path";
 // Import tool definitions
 import { getEnabledTools, toolCounts } from "./tools/index.js";
 import { condenseResult } from "./condense.js";
+import { LEGACY_PATH_FALLBACKS, V1_ALTERNATIVES, V1_EMULATED_ROUTES, looksLikeHtml, fingerprintConfig, describePlankaMajor, } from "./compat.js";
 /** Common file extensions -> MIME type (uploads via data.filePath). */
 const MIME_BY_EXT = {
     ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".gif": "image/gif",
@@ -83,7 +84,17 @@ async function login() {
     if (!res.ok) {
         throw new Error(`Authentication failed: ${res.status} - ${text}`);
     }
-    const data = JSON.parse(text);
+    if (looksLikeHtml(res.headers.get("content-type") ?? "", text)) {
+        throw new Error(`Authentication failed: ${loginUrl} returned an HTML page instead of JSON. ` +
+            `Check PLANKA_BASE_URL — it must point at the Planka origin itself, not at a proxy or login portal.`);
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Authentication failed: login response was not JSON - ${truncate(text, 200)}`);
+    }
     if (typeof data.item !== "string" || data.item.length === 0) {
         throw new Error(`Authentication failed: unexpected login response - ${truncate(text, 200)}`);
     }
@@ -105,6 +116,39 @@ function sleep(ms) {
 function shouldRetryStatus(statusCode) {
     return statusCode === 408 || statusCode === 429 || statusCode >= 500;
 }
+// ----- Planka generation detection -----
+/**
+ * Resolved lazily and only where it changes behaviour (error wording, forked
+ * routes); the happy path never probes. The decision itself lives in
+ * `compat.fingerprintConfig` — this only owns the fetch and the cache.
+ */
+let plankaMajor = null;
+let inflightVersionProbe = null;
+async function probePlankaMajor() {
+    try {
+        const res = await fetch(`${PLANKA_BASE_URL}/api/config`, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(PLANKA_HTTP_TIMEOUT_MS),
+        });
+        // 401/403 needs no body: v2 gates GET /config behind admin, v1 does not.
+        const body = res.status === 401 || res.status === 403 ? "" : await res.text();
+        const major = fingerprintConfig(res.status, res.headers.get("content-type") ?? "", body);
+        if (major !== null)
+            plankaMajor = major;
+        return major;
+    }
+    catch {
+        return null;
+    }
+}
+async function detectPlankaMajor() {
+    if (plankaMajor !== null)
+        return plankaMajor;
+    inflightVersionProbe ??= probePlankaMajor().finally(() => {
+        inflightVersionProbe = null;
+    });
+    return inflightVersionProbe;
+}
 function formatAttempt(attempt) {
     return `${attempt + 1}/${MAX_HTTP_RETRIES + 1}`;
 }
@@ -133,20 +177,6 @@ function buildTools() {
     }));
 }
 // ----- Execute API call for grouped tools -----
-/**
- * Planka <= 1.26.x routes that v2 renamed, verified against a live 1.26.2
- * instance. When the v2 route answers 404, the call is retried once with the
- * legacy route so a single server build serves both API generations.
- */
-const LEGACY_PATH_FALLBACKS = {
-    "/boards/{boardId}/board-memberships": "/boards/{boardId}/memberships",
-    "/projects/{projectId}/project-managers": "/projects/{projectId}/managers",
-    "/cards/{cardId}/card-labels": "/cards/{cardId}/labels",
-    "/cards/{cardId}/card-labels/labelId:{labelId}": "/cards/{cardId}/labels/{labelId}",
-    "/cards/{cardId}/card-memberships": "/cards/{cardId}/memberships",
-    "/cards/{cardId}/card-memberships/userId:{userId}": "/cards/{cardId}/memberships?userId={userId}",
-    "/cards/{cardId}/custom-field-values/customFieldGroupId:{customFieldGroupId}:customFieldId:{customFieldId}": "/cards/{cardId}/custom-field-values/customFieldGroupId:{customFieldGroupId}:customFieldId:${customFieldId}",
-};
 async function executeGroupedApiCall(groupedDef, input, overridePath, retryAttempt = 0, unauthorizedRetried = false, allowLegacyPathFallback = true, scope) {
     try {
         const action = input?.action;
@@ -166,6 +196,9 @@ async function executeGroupedApiCall(groupedDef, input, overridePath, retryAttem
         if (operation.custom === "findCards") {
             return findCards(input, scope);
         }
+        if (operation.custom === "listLabels") {
+            return listLabels(input, scope);
+        }
         // Construct URL with path parameters
         const canonicalPath = overridePath ?? operation.path;
         let actualPath = canonicalPath;
@@ -306,7 +339,12 @@ async function executeGroupedApiCall(groupedDef, input, overridePath, retryAttem
                 // Keep as text if JSON parsing fails
             }
         }
-        if (res.ok) {
+        // An HTML body on a JSON route is the SPA catch-all, never a result. Treat
+        // it as the 404 the server should have sent so the fallbacks below engage.
+        const routeMissing = res.ok && looksLikeHtml(contentType, text);
+        const effectiveStatus = routeMissing ? 404 : res.status;
+        const routeKey = `${methodUpper} ${canonicalPath}`;
+        if (res.ok && !routeMissing) {
             return { success: true, data };
         }
         else {
@@ -318,15 +356,36 @@ async function executeGroupedApiCall(groupedDef, input, overridePath, retryAttem
                 console.error(`[auth] received 401 for ${groupedDef.name}.${action} (${methodUpper} ${actualPath}); clearing cached token and retrying once`);
                 return executeGroupedApiCall(groupedDef, input, overridePath, retryAttempt, true, allowLegacyPathFallback, scope);
             }
-            // Legacy-version fallback: when a v2 route 404s, retry once with the
-            // older Planka (<= 1.26.x) route it replaced. All variants below are
-            // verified against a live Planka 1.26.2 instance.
-            if (res.status === 404 && allowLegacyPathFallback) {
-                const legacyPath = LEGACY_PATH_FALLBACKS[canonicalPath];
+            // Legacy-version fallback: when a v2 route is missing, retry once with
+            // the older Planka (<= 1.26.x) route it replaced, or derive the answer
+            // from a route v1 does have. All variants are verified against a live
+            // Planka 1.26.2 instance and its routes.js.
+            if (effectiveStatus === 404 && allowLegacyPathFallback) {
+                const legacyPath = LEGACY_PATH_FALLBACKS[routeKey];
                 if (legacyPath && legacyPath !== canonicalPath) {
-                    console.error(`[compat] 404 for ${groupedDef.name}.${action} (${methodUpper} ${actualPath}); retrying with legacy route ${legacyPath}`);
+                    console.error(`[compat] route missing for ${groupedDef.name}.${action} (${methodUpper} ${actualPath}); retrying with legacy route ${legacyPath}`);
                     return executeGroupedApiCall(groupedDef, input, legacyPath, retryAttempt, unauthorizedRetried, false, scope);
                 }
+                // Emulators reshape the request, so unlike a plain rename a misfire on
+                // v2 would mask a genuine 404 (a bad taskListId, say). Only derive when
+                // the host is not known to be v2.
+                const emulate = emulatorFor(routeKey);
+                if (emulate && (await detectPlankaMajor()) !== 2) {
+                    console.error(`[compat] route missing for ${groupedDef.name}.${action} (${methodUpper} ${actualPath}); deriving the result from Planka 1.x routes`);
+                    return emulate(input, scope);
+                }
+            }
+            if (routeMissing) {
+                // Never hand the SPA page back to the agent: report the call instead.
+                const major = await detectPlankaMajor();
+                const hint = V1_ALTERNATIVES[routeKey];
+                return {
+                    success: false,
+                    error: `Planka answered ${methodUpper} /api${actualPath} with HTTP ${res.status} and an HTML page ` +
+                        `(content-type: ${contentType || "none"}, ${text.length} bytes) instead of JSON. ` +
+                        `That route does not exist on this server (${describePlankaMajor(major)}); its SPA catch-all served index.html.` +
+                        (hint ? ` ${hint}.` : ""),
+                };
             }
             if (shouldRetryStatus(res.status) && retryAttempt < MAX_HTTP_RETRIES) {
                 const delayMs = retryDelayMs(retryAttempt);
@@ -335,9 +394,13 @@ async function executeGroupedApiCall(groupedDef, input, overridePath, retryAttem
                 return executeGroupedApiCall(groupedDef, input, overridePath, retryAttempt + 1, unauthorizedRetried, allowLegacyPathFallback, scope);
             }
             console.error(`[error] API call failed for ${groupedDef.name}.${action} (${methodUpper} ${actualPath}) with HTTP ${res.status}`);
+            // A clean 404 on a v2-only route deserves the same pointer the HTML
+            // branch gives, so agents on Planka 1.x learn what to use instead.
+            const missingHint = res.status === 404 ? V1_ALTERNATIVES[routeKey] : undefined;
             return {
                 success: false,
-                error: `HTTP ${res.status}: ${truncate(typeof data === 'string' ? data : JSON.stringify(data), 2000)}`,
+                error: `HTTP ${res.status}: ${truncate(typeof data === 'string' ? data : JSON.stringify(data), 2000)}` +
+                    (missingHint ? ` — ${missingHint}.` : ""),
             };
         }
     }
@@ -434,6 +497,155 @@ async function findCards(input, scope) {
         },
     };
 }
+/**
+ * List a board's labels. Neither Planka major exposes GET /labels, so the
+ * labels tool would otherwise be write-only and agents had to know to reach
+ * for boards.get; one board GET supplies them on both majors.
+ */
+async function listLabels(input, scope) {
+    const boardId = String(input?.data?.boardId ?? input?.id ?? scope?.boardId ?? "");
+    if (!boardId) {
+        return { success: false, error: "Provide data.boardId (or id), or select a board via the context tool" };
+    }
+    const boardsTool = toolMap.get("boards");
+    if (!boardsTool) {
+        return { success: false, error: "boards tool unavailable; cannot list labels" };
+    }
+    const boardRes = await executeGroupedApiCall(boardsTool.groupedDef, { action: "get", id: boardId }, undefined, 0, false, true, scope);
+    if (!boardRes.success) {
+        return boardRes;
+    }
+    const included = (boardRes.data?.included ?? {});
+    return {
+        success: true,
+        data: {
+            items: included.labels ?? [],
+            _compat: `derived from GET /boards/${boardId} (Planka has no labels GET route on either major)`,
+        },
+    };
+}
+/** Run one action of another grouped tool, without any fallback recursion. */
+async function callTool(toolName, input, scope) {
+    const tool = toolMap.get(toolName);
+    if (!tool) {
+        return { success: false, error: `${toolName} tool unavailable; cannot derive the result` };
+    }
+    return executeGroupedApiCall(tool.groupedDef, input, undefined, 0, false, false, scope);
+}
+/** Fetch a board once and hand back its `included` sidecar. */
+async function includedOfBoard(boardId, scope) {
+    const res = await callTool("boards", { action: "get", id: boardId }, scope);
+    if (!res.success)
+        return { error: res.error };
+    return { included: (res.data?.included ?? {}) };
+}
+/**
+ * v1 has no GET /cards/{id}/comments: comments live in the activity log as
+ * `commentCard` actions with the body under `data.text`.
+ */
+const emulateCommentsList = async (input, scope) => {
+    const cardId = String(input?.data?.cardId ?? input?.id ?? scope?.cardId ?? "");
+    if (!cardId) {
+        return { success: false, error: "Provide id (card ID), or select the card via the context tool" };
+    }
+    const res = await callTool("cards", { action: "getActions", id: cardId }, scope);
+    if (!res.success)
+        return res;
+    const items = (res.data?.items ?? [])
+        .filter(a => a.type === "commentCard")
+        .map(a => ({
+        id: a.id,
+        text: a.data?.text ?? "",
+        cardId: a.cardId ?? cardId,
+        userId: a.userId,
+        createdAt: a.createdAt,
+        updatedAt: a.updatedAt,
+    }));
+    return { success: true, data: { items, _compat: "derived from GET /cards/{id}/actions (Planka 1.x stores comments as commentCard actions)" } };
+};
+/** v1 has no GET /lists/{id}; the board payload carries every list. */
+const emulateListGet = async (input, scope) => {
+    const listId = String(input?.data?.listId ?? input?.id ?? scope?.listId ?? "");
+    const boardId = String(input?.data?.boardId ?? scope?.boardId ?? "");
+    if (!listId) {
+        return { success: false, error: "Provide id (list ID), or select the list via the context tool" };
+    }
+    if (!boardId) {
+        return { success: false, error: "Planka 1.x has no GET /lists/{id}. Provide data.boardId (or select a board via the context tool) so the list can be read from boards.get." };
+    }
+    const { included, error } = await includedOfBoard(boardId, scope);
+    if (error)
+        return { success: false, error };
+    const item = (included.lists ?? []).find(l => String(l.id) === listId);
+    if (!item) {
+        return { success: false, error: `List ${listId} not found on board ${boardId}` };
+    }
+    return { success: true, data: { item, _compat: `derived from GET /boards/${boardId} (Planka 1.x has no list route)` } };
+};
+/** v1 has no GET /lists/{id}/cards; filter the board's cards by list. */
+const emulateListCards = async (input, scope) => {
+    const listId = String(input?.data?.listId ?? input?.id ?? scope?.listId ?? "");
+    const boardId = String(input?.data?.boardId ?? scope?.boardId ?? "");
+    if (!listId) {
+        return { success: false, error: "Provide id (list ID), or select the list via the context tool" };
+    }
+    if (!boardId) {
+        return { success: false, error: "Planka 1.x has no GET /lists/{id}/cards. Provide data.boardId (or select a board via the context tool) so the cards can be read from boards.get." };
+    }
+    const { included, error } = await includedOfBoard(boardId, scope);
+    if (error)
+        return { success: false, error };
+    const items = (included.cards ?? []).filter(c => String(c.listId) === listId);
+    return { success: true, data: { items, _compat: `derived from GET /boards/${boardId} (Planka 1.x has no per-list card route)` } };
+};
+/** v1 has no /bootstrap; compose the same working set from /projects + /config. */
+const emulateBootstrap = async (_input, scope) => {
+    const projects = await callTool("projects", { action: "list" }, scope);
+    if (!projects.success)
+        return projects;
+    const item = {
+        projects: projects.data?.items ?? [],
+        included: projects.data?.included ?? {},
+    };
+    const config = await callTool("config", { action: "get" }, scope);
+    if (config.success)
+        item.config = config.data?.item;
+    return { success: true, data: { item, _compat: "derived from GET /projects (+ /config) — Planka 1.x has no /bootstrap route" } };
+};
+/**
+ * v1 hangs tasks off the card (POST /cards/{cardId}/tasks) instead of off a
+ * task list, so this is a re-parent rather than a rename and cannot live in
+ * LEGACY_PATH_FALLBACKS.
+ */
+const emulateTaskCreate = async (input, scope) => {
+    const cardId = String(input?.data?.cardId ?? scope?.cardId ?? "");
+    if (!cardId) {
+        return { success: false, error: "Planka 1.x creates tasks on the card, not on a task list. Provide data.cardId (or select the card via the context tool)." };
+    }
+    const tasksTool = toolMap.get("tasks");
+    if (!tasksTool) {
+        return { success: false, error: "tasks tool unavailable; cannot create the task" };
+    }
+    const { taskListId: _omit, ...data } = (input?.data ?? {});
+    return executeGroupedApiCall(tasksTool.groupedDef, { action: "create", id: cardId, data: { ...data, cardId } }, "/cards/{cardId}/tasks", 0, false, false, scope);
+};
+/**
+ * Keyed like LEGACY_PATH_FALLBACKS: `METHOD canonicalPath`. The key set is
+ * `V1_EMULATED_ROUTES` in compat.ts — typing the record by it means adding a
+ * route there without an implementation (or vice versa) is a compile error.
+ */
+const V1_EMULATORS = {
+    "GET /cards/{cardId}/comments": emulateCommentsList,
+    "GET /lists/{id}": emulateListGet,
+    "GET /lists/{listId}/cards": emulateListCards,
+    "GET /bootstrap": emulateBootstrap,
+    "POST /task-lists/{taskListId}/tasks": emulateTaskCreate,
+};
+function emulatorFor(routeKey) {
+    return V1_EMULATED_ROUTES.includes(routeKey)
+        ? V1_EMULATORS[routeKey]
+        : undefined;
+}
 async function downloadAttachment(input, scope) {
     if (PLANKA_API_KEY) {
         return { success: false, error: "Attachment downloads require PLANKA_USERNAME/PLANKA_PASSWORD auth: Planka serves files from a cookie-authenticated route that rejects API keys" };
@@ -474,6 +686,11 @@ async function downloadAttachment(input, scope) {
     if (!res.ok) {
         return { success: false, error: `Attachment download failed: HTTP ${res.status}` };
     }
+    const servedType = res.headers.get("content-type") ?? "";
+    if (servedType.includes("text/html") && !String(record.mimeType ?? "").startsWith("text/html")) {
+        // The SPA catch-all again: index.html must never be handed back as file bytes.
+        return { success: false, error: `Attachment download returned an HTML page for ${target} — the file route is unavailable on this Planka` };
+    }
     const bytes = new Uint8Array(await res.arrayBuffer());
     if (bytes.byteLength > MAX_ATTACHMENT_BYTES) {
         return { success: false, error: `Attachment too large to inline (${bytes.byteLength} bytes > ${MAX_ATTACHMENT_BYTES}); fetch it directly: ${target}` };
@@ -528,6 +745,24 @@ async function enrichCardResult(action, data, pendingAttachments, cardId, scope)
         catch (actionsError) {
             console.error(`[cards.get] actions fetch failed for card ${cardId}: ${actionsError instanceof Error ? actionsError.message : String(actionsError)}`);
         }
+        // v2 keeps comments on their own route, so the activity log above does not
+        // carry them; v1 answers this from the same log. Folding them in here means
+        // one cards.get returns the whole working context on both majors instead of
+        // forcing a second comments.list round trip. Best-effort, like actions.
+        const commentsTool = toolMap.get("comments");
+        if (commentsTool) {
+            try {
+                const comments = await executeGroupedApiCall(commentsTool.groupedDef, { action: "list", id: cardId }, undefined, 0, false, true, scope);
+                if (comments.success && Array.isArray(comments.data?.items)) {
+                    if (!data.included || typeof data.included !== "object")
+                        data.included = {};
+                    data.included.comments = comments.data.items;
+                }
+            }
+            catch (commentsError) {
+                console.error(`[cards.get] comments fetch failed for card ${cardId}: ${commentsError instanceof Error ? commentsError.message : String(commentsError)}`);
+            }
+        }
     }
     if (action === "create" && pendingAttachments && pendingAttachments.length > 0) {
         const createdCardId = String(data?.item?.id ?? cardId ?? "");
@@ -626,7 +861,7 @@ if (!process.argv.includes("--healthcheck")) {
 function createMcpServer() {
     const server = new McpServer({
         name: "planka-mcp",
-        version: "2.5.1",
+        version: "2.6.0",
     }, {
         capabilities: {
             tools: {},
@@ -678,7 +913,9 @@ function createMcpServer() {
         }
         if (result.success) {
             const wantsRaw = !PLANKA_CONDENSED_OUTPUT || args?.raw === true;
-            const payload = wantsRaw ? result.data : condenseResult(toolDef.groupedDef.name, result.data);
+            const payload = wantsRaw
+                ? result.data
+                : condenseResult(toolDef.groupedDef.name, result.data, typeof args?.action === "string" ? args.action : undefined);
             const asRecord = (typeof payload === "object" && payload !== null ? payload : undefined);
             // Image downloads additionally ship an MCP image content block so
             // clients render the picture directly instead of showing base64.

package/dist/tools/core/tools.js

@@ -402,7 +402,9 @@ export const commentsTool = {
  */
 export const tasksTool = {
     name: "tasks",
-    description: "Manage task lists and tasks on Planka cards. Tasks are checklist items within a card.",
+    description: "Manage task lists and tasks on Planka cards. Tasks are checklist items within a card. " +
+        "There is no 'list' action — a card's tasks already come back with cards.get; " +
+        "getList reads one task list by ID (Planka 2.x only).",
     operations: {
         getList: {
             method: "GET",
@@ -456,6 +458,14 @@ export const labelsTool = {
     name: "labels",
     description: "Manage labels on Planka boards and cards. Labels help categorize and filter cards.",
     operations: {
+        list: {
+            // No Planka major exposes a labels GET route; the board payload carries
+            // them, so the engine derives this from boards.get.
+            method: "GET",
+            path: "/boards/{id}",
+            description: "List a board's labels",
+            custom: "listLabels",
+        },
         create: {
             method: "POST",
             path: "/boards/{boardId}/labels",
@@ -482,7 +492,8 @@ export const labelsTool = {
             description: "Remove a label from a card",
         },
     },
-    inputSchema: buildGroupedSchema(["create", "update", "delete", "addToCard", "removeFromCard"], {
+    inputSchema: buildGroupedSchema(["list", "create", "update", "delete", "addToCard", "removeFromCard"], {
+        list: "List the labels defined on a board",
         create: "Create a label on a board",
         update: "Update a label's name, color, or position",
         delete: "Delete a label from a board",
@@ -490,8 +501,8 @@ export const labelsTool = {
         removeFromCard: "Remove a label from a card",
     }, {
         id: {
-            description: "Board ID (for create), Label ID (for update, delete), or Card ID (for addToCard, removeFromCard)",
-            requiredFor: ["create", "update", "delete", "addToCard", "removeFromCard"],
+            description: "Board ID (for list, create), Label ID (for update, delete), or Card ID (for addToCard, removeFromCard)",
+            requiredFor: ["list", "create", "update", "delete", "addToCard", "removeFromCard"],
         },
         data: {
             description: "Label data: { name?: string, color: string (required), position: number (required) } for create/update, { labelId: string } for addToCard/removeFromCard. Colors: muddy-grey, autumn-leafs, morning-sky, antique-blue, egg-yellow, desert-sand, dark-granite, fresh-salad, lagoon-blue, midnight-blue, light-orange, pumpkin-orange, light-concrete, sunny-grass, navy-blue, lilac-eyes, apricot-red, orange-peel, silver-glint, bright-moss, deep-ocean, summer-sky, berry-red, light-cocoa, grey-stone, tank-green, coral-green, sugar-plum, pink-tulip, shady-rust, wet-rock, wet-moss, turquoise-sea, lavender-fields, piggy-red, light-mud, gun-metal, modern-green, french-coast, sweet-lilac, red-burgundy, pirate-gold",

package/dist/tools/types.d.ts

@@ -16,8 +16,12 @@ export interface ToolOperation {
     description?: string;
     /** Send data as multipart/form-data instead of JSON (file uploads). */
     requestType?: "multipart";
-    /** Fully custom handling in the engine (attachment download, card search). */
-    custom?: "downloadAttachment" | "findCards";
+    /**
+     * Fully custom handling in the engine: attachment download (cookie auth),
+     * board-wide card search, and label listing (no Planka major has a labels
+     * GET route — the board payload carries them).
+     */
+    custom?: "downloadAttachment" | "findCards" | "listLabels";
 }
 /**
  * Grouped tool definition - multiple operations under one tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denisixnpm/planka-mcp",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "MCP server for Planka - Real-Time Collaborative Kanban Board",
   "main": "dist/server.js",
   "type": "module",
@@ -18,10 +18,16 @@
     "dev:sse": "MCP_TRANSPORT=sse bun src/server.ts",
     "prepublishOnly": "npm run build",
     "test": "bun run build && bun test",
-    "test:tools": "bun test test/tools.test.ts",
+    "test:tools": "bun run build && bun test test/tools.test.ts",
     "test:build": "bun run build && bun test test/build.test.ts",
-    "test:server": "bun test test/server.test.ts",
-    "test:ci": "bun run build && bun test"
+    "test:server": "bun run build && bun test test/server.test.ts",
+    "check": "npm run guard:lockfiles && npm run guard:version && npm test",
+    "guard:version": "node scripts/version-sync.mjs",
+    "guard:lockfiles": "node scripts/guard-lockfiles.mjs",
+    "version:set": "node scripts/version-sync.mjs --set",
+    "e2e": "node scripts/e2e.mjs",
+    "e2e:up": "docker compose --profile e2e up -d",
+    "e2e:down": "docker compose --profile e2e down -v"
   },
   "keywords": [
     "mcp",