@denisixnpm/planka-mcp 2.3.0 → 2.4.0

package/README.md

@@ -11,8 +11,25 @@ No build step, no Docker required — `npx` runs the prebuilt package over stdio
 
 ## Install
 
+Two auth modes: **username/password** works on every Planka version (the server logs in
+automatically, caches the token, and silently re-logins on expiry); **API key** is Planka **v2
+only** — generate one in your Planka user settings → *API keys* (v1.26.x has no API keys; verified:
+`X-Api-Key` returns 401 there).
+
 ### Claude Code
 
+**Planka v1 (≤ 1.26.x) — username/password:**
+
+```bash
+claude mcp add planka \
+  --env PLANKA_BASE_URL=http://localhost:3000 \
+  --env PLANKA_USERNAME=your-email-or-username \
+  --env PLANKA_PASSWORD=your-password \
+  -- npx -y @denisixnpm/planka-mcp
+```
+
+**Planka v2 — API key (username/password above works too):**
+
 ```bash
 claude mcp add planka \
   --env PLANKA_BASE_URL=http://localhost:3000 \
@@ -20,7 +37,7 @@ claude mcp add planka \
   -- npx -y @denisixnpm/planka-mcp
 ```
 
-Or in `claude_desktop_config.json` / `.mcp.json`:
+Or in `claude_desktop_config.json` / `.mcp.json` (username/password form — works on both versions):
 
 ```json
 {
@@ -28,7 +45,7 @@ Or in `claude_desktop_config.json` / `.mcp.json`:
     "planka": {
       "command": "npx",
       "args": ["-y", "@denisixnpm/planka-mcp"],
-      "env": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_API_KEY": "your-api-key" }
+      "env": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_USERNAME": "your-email-or-username", "PLANKA_PASSWORD": "your-password" }
     }
   }
 }
@@ -36,6 +53,17 @@ Or in `claude_desktop_config.json` / `.mcp.json`:
 
 ### Codex (`~/.codex/config.toml`)
 
+**Planka v1 (≤ 1.26.x):**
+
+```toml
+[mcp_servers.planka]
+command = "npx"
+args = ["-y", "@denisixnpm/planka-mcp"]
+env = { PLANKA_BASE_URL = "http://localhost:3000", PLANKA_USERNAME = "your-email-or-username", PLANKA_PASSWORD = "your-password" }
+```
+
+**Planka v2 (API key):**
+
 ```toml
 [mcp_servers.planka]
 command = "npx"
@@ -45,6 +73,22 @@ env = { PLANKA_BASE_URL = "http://localhost:3000", PLANKA_API_KEY = "your-api-ke
 
 ### opencode (`opencode.json`)
 
+**Planka v1 (≤ 1.26.x):**
+
+```json
+{
+  "mcp": {
+    "planka": {
+      "type": "local",
+      "command": ["npx", "-y", "@denisixnpm/planka-mcp"],
+      "environment": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_USERNAME": "your-email-or-username", "PLANKA_PASSWORD": "your-password" }
+    }
+  }
+}
+```
+
+**Planka v2 (API key):**
+
 ```json
 {
   "mcp": {
@@ -59,18 +103,34 @@ env = { PLANKA_BASE_URL = "http://localhost:3000", PLANKA_API_KEY = "your-api-ke
 
 Requires Node.js ≥ 22.19 (or run the same command with Bun ≥ 1.3). Debug: `npx -y @denisixnpm/planka-mcp 2>&1 | tee debug.log`.
 
+## Attachments
+
+`cards.get` returns the full working context in one call: description, tasks, task lists,
+attachments, and the activity log (`actions`). Attachment metadata is normalized across Planka
+versions (v2's nested `data.url` is flattened), so every record carries `id`, `name`, `url`,
+`type`, `size`, `mimeType`.
+
+- **Create with files**: `cards { action: "create", ..., data: { attachments: [{ name, text | contentBase64, mimeType? }] } }` — uploads happen in the same tool call.
+- **Upload later**: `attachments { action: "upload", id: <cardId>, data: { name, text | contentBase64 | url, mimeType? } }` — `url` creates a link attachment (Planka v2 only).
+- **Download**: `attachments { action: "download", id: <attachmentId>, data: { cardId } }` — returns `{ name, mimeType, size, contentBase64 }` (≤ 10 MB inline).
+- **Rename / delete**: `attachments { action: "rename" | "delete", id, data: { name? } }`.
+
+Downloads require `PLANKA_USERNAME`/`PLANKA_PASSWORD` auth: Planka serves files from a
+cookie-authenticated route that rejects `Authorization` headers and API keys (verified on 1.26.2
+and 2.0.3).
+
 ## Configuration
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PLANKA_BASE_URL` | `http://localhost:3000` | Planka instance URL |
-| `PLANKA_API_KEY` | — | API key auth (recommended; wins if both are set) |
-| `PLANKA_USERNAME` / `PLANKA_PASSWORD` | — | Login auth (alternative to API key) |
+| `PLANKA_USERNAME` / `PLANKA_PASSWORD` | — | Login auth — **all Planka versions**; token is fetched, cached, and refreshed automatically |
+| `PLANKA_API_KEY` | — | API key auth — **Planka v2 only** (user settings → API keys); wins if both are set |
 | `PLANKA_HTTP_TIMEOUT_MS` | `30000` | Per-request timeout (aborts, then retries) |
 | `PLANKA_HTTP_MAX_RETRIES` | `2` | Retries for `408`/`429`/`5xx` and network errors |
 | `PLANKA_HTTP_RETRY_BASE_DELAY_MS` | `250` | Exponential backoff base (`base * 2^attempt`) |
 | `PLANKA_CONDENSED_OUTPUT` | `true` | Condensed agent output; `false` = raw payloads |
-| `ENABLE_ALL_TOOLS` | `false` | Enable all 28 tools (otherwise 11 core) |
+| `ENABLE_ALL_TOOLS` | `false` | Enable all 28 tools (otherwise 12 core) |
 | `ENABLE_ADMIN_TOOLS` / `ENABLE_OPTIONAL_TOOLS` | `false` | Enable one extra category |
 | `MCP_TRANSPORT` | `stdio` | `stdio` (single client) or `sse` (multi-client) |
 | `MCP_PORT` / `MCP_HOST` | `3001` / `127.0.0.1` | SSE mode bind; `0.0.0.0` in Docker |

package/dist/condense.js

@@ -30,7 +30,7 @@ const ENTITY_FIELDS = {
     labelExtras: ["id", "cardId", "labelId"],
     comments: ["id", "text", "cardId"],
     commentExtras: ["id", "text", "cardId"],
-    attachments: ["id", "name", "url", "type", "cardId"],
+    attachments: ["id", "name", "url", "type", "size", "mimeType", "cardId"],
     users: ["id", "email", "name", "username", "role"],
     userInfo: ["id", "email", "name", "username", "role"],
     boardMembers: ["id", "userId", "boardId", "role"],
@@ -44,7 +44,7 @@ const ENTITY_FIELDS = {
     webhooks: ["id", "name", "url"],
     backgroundImages: ["id", "name", "boardId"],
     notifications: ["id", "type", "isRead", "cardId"],
-    actions: ["id", "type", "cardId", "userId"],
+    actions: ["id", "type", "cardId", "boardId", "userId", "createdAt", "data"],
 };
 /** `included` keys that do not match their tool name verbatim. */
 const INCLUDED_KEY_TO_TOOL = {
@@ -103,6 +103,11 @@ export function condenseResult(toolName, data) {
     }
     if (typeof data === "object" && data !== null) {
         const source = data;
+        // Attachment downloads carry base64 payload — whitelists and text
+        // truncation must not touch them (size is already capped by the engine).
+        if (typeof source.contentBase64 === "string") {
+            return data;
+        }
         const hasItems = Array.isArray(source.items);
         const hasItem = "item" in source;
         if (hasItems || hasItem) {

package/dist/server.js

@@ -138,6 +138,11 @@ async function executeGroupedApiCall(groupedDef, input, overridePath, retryAttem
             const validActions = Object.keys(groupedDef.operations).join(", ");
             return { success: false, error: `Invalid action '${action}'. Valid actions: ${validActions}` };
         }
+        // Fully custom operations (attachment download needs cookie-auth + binary
+        // handling that the generic JSON engine cannot express).
+        if (operation.custom === "downloadAttachment") {
+            return downloadAttachment(input, scope);
+        }
         // Construct URL with path parameters
         const canonicalPath = overridePath ?? operation.path;
         let actualPath = canonicalPath;
@@ -201,7 +206,38 @@ async function executeGroupedApiCall(groupedDef, input, overridePath, retryAttem
         }
         // Handle request body
         let body = undefined;
-        if (["POST", "PUT", "PATCH"].includes(methodUpper) && input?.data !== undefined) {
+        if (operation.requestType === "multipart") {
+            // Planka file upload: v2 requires form fields `type` + `name`; v1
+            // ignores extra fields, so one v2-shaped request serves both majors.
+            const d = (input?.data ?? {});
+            const name = typeof d.name === "string" && d.name !== "" ? d.name : "attachment";
+            const isLink = typeof d.url === "string" && d.url !== "" && d.contentBase64 === undefined && d.text === undefined;
+            const fd = new FormData();
+            fd.append("type", isLink ? "link" : "file");
+            fd.append("name", name);
+            if (isLink) {
+                fd.append("url", String(d.url));
+            }
+            else {
+                let bytes;
+                let mimeType = typeof d.mimeType === "string" ? d.mimeType : "application/octet-stream";
+                if (typeof d.contentBase64 === "string" && d.contentBase64 !== "") {
+                    const binary = atob(d.contentBase64);
+                    bytes = Uint8Array.from(binary, ch => ch.charCodeAt(0));
+                }
+                else if (typeof d.text === "string") {
+                    bytes = new TextEncoder().encode(d.text);
+                    if (typeof d.mimeType !== "string")
+                        mimeType = "text/plain";
+                }
+                else {
+                    return { success: false, error: "Provide data.contentBase64, data.text, or data.url for the attachment content" };
+                }
+                fd.append("file", new Blob([bytes], { type: mimeType }), name);
+            }
+            body = fd;
+        }
+        else if (["POST", "PUT", "PATCH"].includes(methodUpper) && input?.data !== undefined) {
             headers["Content-Type"] = "application/json";
             body = JSON.stringify(input.data);
         }
@@ -272,6 +308,152 @@ async function executeGroupedApiCall(groupedDef, input, overridePath, retryAttem
         };
     }
 }
+/**
+ * Planka v2 nests attachment metadata under `data` ({url, size, mimeType});
+ * v1 keeps `url` top-level. Flatten to one shape for agents and the condenser.
+ */
+function normalizeAttachment(raw) {
+    const item = (raw ?? {});
+    const nested = item.data;
+    if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+        return {
+            ...item,
+            url: item.url ?? nested.url,
+            size: nested.size,
+            mimeType: nested.mimeType,
+            data: undefined,
+        };
+    }
+    return item;
+}
+/** Normalize every attachment record inside a `{item|items, included}` envelope. */
+function normalizeAttachmentsIn(data) {
+    if (typeof data !== "object" || data === null)
+        return;
+    const envelope = data;
+    const item = envelope.item;
+    if (item && item.type !== undefined && (item.cardId !== undefined || item.data !== undefined)) {
+        envelope.item = normalizeAttachment(item);
+    }
+    const list = envelope.included?.attachments;
+    if (Array.isArray(list)) {
+        envelope.included.attachments = list.map(normalizeAttachment);
+    }
+}
+/**
+ * Download an attachment's bytes. Planka serves files from
+ * /attachments/{id}/download/{name}, which authenticates via the
+ * `accessToken` cookie only — Bearer and X-Api-Key headers get 401 (verified
+ * against live 1.26.2 and 2.0.3). The attachment record must be located on
+ * its owning card first, since there is no GET /attachments/{id}.
+ */
+const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+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" };
+    }
+    const attachmentId = String(input?.id ?? "");
+    const cardId = String(input?.data?.cardId ?? scope?.cardId ?? "");
+    if (!attachmentId || !cardId) {
+        return { success: false, error: "Provide id (attachment ID) and data.cardId (owning card), or select the card via the context tool" };
+    }
+    const cardsTool = toolMap.get("cards");
+    if (!cardsTool) {
+        return { success: false, error: "cards tool unavailable; cannot resolve attachment" };
+    }
+    const cardRes = await executeGroupedApiCall(cardsTool.groupedDef, { action: "get", id: cardId });
+    if (!cardRes.success) {
+        return cardRes;
+    }
+    const found = (cardRes.data?.included?.attachments ?? []).find(a => String(a.id) === attachmentId);
+    if (!found) {
+        return { success: false, error: `Attachment ${attachmentId} not found on card ${cardId}` };
+    }
+    const record = normalizeAttachment(found);
+    if (record.type === "link" || typeof record.url !== "string" || record.url === "") {
+        return { success: true, data: { ...record, note: "link attachment — follow data.url" } };
+    }
+    const target = new URL(String(record.url), PLANKA_BASE_URL);
+    const token = await getAccessToken();
+    let res;
+    try {
+        res = await fetch(target, {
+            headers: { Authorization: `Bearer ${token}`, cookie: `accessToken=${token}` },
+            signal: AbortSignal.timeout(PLANKA_HTTP_TIMEOUT_MS),
+        });
+    }
+    catch (downloadError) {
+        return { success: false, error: `Attachment download failed: ${downloadError instanceof Error ? downloadError.message : String(downloadError)}` };
+    }
+    if (!res.ok) {
+        return { success: false, error: `Attachment download failed: HTTP ${res.status}` };
+    }
+    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}` };
+    }
+    return {
+        success: true,
+        data: {
+            id: attachmentId,
+            name: record.name,
+            size: bytes.byteLength,
+            mimeType: res.headers.get("content-type")?.split(";")[0] ?? record.mimeType ?? "application/octet-stream",
+            contentBase64: Buffer.from(bytes).toString("base64"),
+        },
+    };
+}
+/**
+ * Post-processing for card calls:
+ *  - `get`: fold the activity log (`actions`) into `included` so one call
+ *    returns the full working context — description, tasks, attachments,
+ *    actions. Best-effort: an actions failure never fails the card get.
+ *  - `create`: upload any `data.attachments` entries and fold them into
+ *    `included.attachments`.
+ */
+async function enrichCardResult(action, data, pendingAttachments, cardId, scope) {
+    normalizeAttachmentsIn(data);
+    const cardsTool = toolMap.get("cards");
+    if (action === "get" && cardsTool && cardId) {
+        try {
+            const acts = await executeGroupedApiCall(cardsTool.groupedDef, { action: "getActions", id: cardId }, undefined, 0, false, false, scope);
+            if (acts.success && Array.isArray(acts.data?.items)) {
+                if (!data.included || typeof data.included !== "object")
+                    data.included = {};
+                data.included.actions = acts.data.items;
+            }
+        }
+        catch (actionsError) {
+            console.error(`[cards.get] actions fetch failed for card ${cardId}: ${actionsError instanceof Error ? actionsError.message : String(actionsError)}`);
+        }
+    }
+    if (action === "create" && pendingAttachments && pendingAttachments.length > 0) {
+        const createdCardId = String(data?.item?.id ?? cardId ?? "");
+        const attachmentsTool = toolMap.get("attachments");
+        if (createdCardId && attachmentsTool) {
+            const uploaded = [];
+            const errors = [];
+            for (const att of pendingAttachments) {
+                const up = await executeGroupedApiCall(attachmentsTool.groupedDef, { action: "upload", id: createdCardId, data: att });
+                if (up.success) {
+                    uploaded.push(normalizeAttachment(up.data?.item));
+                }
+                else {
+                    errors.push({ name: String(att?.name ?? "attachment"), error: up.error ?? "upload failed" });
+                }
+            }
+            if (uploaded.length > 0) {
+                if (!data.included || typeof data.included !== "object")
+                    data.included = {};
+                data.included.attachments = [...(data.included.attachments ?? []), ...uploaded];
+            }
+            if (errors.length > 0) {
+                data.attachmentUploadErrors = errors;
+            }
+        }
+    }
+    return data;
+}
 /**
  * Local handler for the `context` tool: maintains the working scope of this
  * server instance (per SSE session, process-wide for stdio). Enriches `set`
@@ -342,7 +524,7 @@ if (!process.argv.includes("--healthcheck")) {
 function createMcpServer() {
     const server = new McpServer({
         name: "planka-mcp",
-        version: "2.3.0",
+        version: "2.4.0",
     }, {
         capabilities: {
             tools: {},
@@ -366,9 +548,25 @@ function createMcpServer() {
                 isError: true,
             };
         }
+        // cards.create accepts data.attachments — strip them from the API payload
+        // and upload after the card exists.
+        let pendingAttachments = null;
+        const reqArgs = (args ?? {});
+        const reqData = reqArgs.data;
+        if (toolDef.groupedDef.name === "cards" && reqArgs.action === "create" && Array.isArray(reqData?.attachments)) {
+            pendingAttachments = reqData.attachments;
+            const { attachments: _omit, ...dataWithout } = reqData;
+            reqArgs.data = dataWithout;
+        }
         const result = toolDef.groupedDef.name === "context"
             ? await handleContextCall(args, scope)
             : await executeGroupedApiCall(toolDef.groupedDef, args, undefined, 0, false, true, scope);
+        if (result.success && toolDef.groupedDef.name === "attachments") {
+            normalizeAttachmentsIn(result.data);
+        }
+        if (result.success && toolDef.groupedDef.name === "cards") {
+            result.data = await enrichCardResult(String(args?.action ?? ""), result.data, pendingAttachments, typeof args?.id === "string" ? args.id : undefined, scope);
+        }
         if (result.success) {
             const wantsRaw = !PLANKA_CONDENSED_OUTPUT || args?.raw === true;
             const payload = wantsRaw ? result.data : condenseResult(toolDef.groupedDef.name, result.data);

package/dist/tools/core/index.d.ts

@@ -2,8 +2,8 @@
  * Core tools - Essential for basic Kanban operations (always enabled)
  */
 import { GroupedToolDefinition } from "../types.js";
-import { authTool, projectsTool, boardsTool, listsTool, cardsTool, commentsTool, tasksTool, labelsTool, cardMembersTool, bootstrapTool, contextTool } from "./tools.js";
-export { authTool, projectsTool, boardsTool, listsTool, cardsTool, commentsTool, tasksTool, labelsTool, cardMembersTool, bootstrapTool, contextTool, };
+import { authTool, projectsTool, boardsTool, listsTool, cardsTool, attachmentsTool, commentsTool, tasksTool, labelsTool, cardMembersTool, bootstrapTool, contextTool } from "./tools.js";
+export { authTool, projectsTool, boardsTool, listsTool, cardsTool, attachmentsTool, commentsTool, tasksTool, labelsTool, cardMembersTool, bootstrapTool, contextTool, };
 /**
  * All core tools combined
  */

package/dist/tools/core/index.js

@@ -1,5 +1,5 @@
-import { authTool, projectsTool, boardsTool, listsTool, cardsTool, commentsTool, tasksTool, labelsTool, cardMembersTool, bootstrapTool, contextTool, } from "./tools.js";
-export { authTool, projectsTool, boardsTool, listsTool, cardsTool, commentsTool, tasksTool, labelsTool, cardMembersTool, bootstrapTool, contextTool, };
+import { authTool, projectsTool, boardsTool, listsTool, cardsTool, attachmentsTool, commentsTool, tasksTool, labelsTool, cardMembersTool, bootstrapTool, contextTool, } from "./tools.js";
+export { authTool, projectsTool, boardsTool, listsTool, cardsTool, attachmentsTool, commentsTool, tasksTool, labelsTool, cardMembersTool, bootstrapTool, contextTool, };
 /**
  * All core tools combined
  */
@@ -11,6 +11,7 @@ export const coreTools = [
     boardsTool,
     listsTool,
     cardsTool,
+    attachmentsTool,
     commentsTool,
     tasksTool,
     labelsTool,

package/dist/tools/core/tools.d.ts

@@ -19,6 +19,20 @@ export declare const listsTool: GroupedToolDefinition;
  * Cards tool - manages cards within lists
  */
 export declare const cardsTool: GroupedToolDefinition;
+/**
+ * Attachments tool - upload, download, and manage card file attachments.
+ *
+ * Verified against live Planka 1.26.2 and 2.0.3:
+ *  - upload: POST /cards/{cardId}/attachments, multipart. v2 requires form
+ *    fields `type` ("file"|"link") and `name`; v1 ignores extra fields, so a
+ *    single v2-shaped request works on both.
+ *  - download: no JSON API — the attachment record carries an `url`
+ *    (/attachments/{id}/download/{name}) that Planka authenticates via the
+ *    `accessToken` cookie only (Bearer/X-Api-Key get 401). The engine fetches
+ *    it and returns base64.
+ *  - link attachments (url instead of file content) are Planka v2 only.
+ */
+export declare const attachmentsTool: GroupedToolDefinition;
 /**
  * Comments tool - manages comments on cards
  */

package/dist/tools/core/tools.js

@@ -231,7 +231,12 @@ export const cardsTool = {
         get: {
             method: "GET",
             path: "/cards/{id}",
-            description: "Get card with task lists, attachments, and custom fields",
+            description: "Get card with description, task lists, tasks, attachments, and custom fields",
+        },
+        getActions: {
+            method: "GET",
+            path: "/cards/{cardId}/actions",
+            description: "Get the card's activity log (actions: created, moved, commented, ...)",
         },
         create: {
             method: "POST",
@@ -249,19 +254,20 @@ export const cardsTool = {
             description: "Delete a card permanently",
         },
     },
-    inputSchema: buildGroupedSchema(["list", "get", "create", "update", "delete"], {
+    inputSchema: buildGroupedSchema(["list", "get", "getActions", "create", "update", "delete"], {
         list: "Get cards from a list (requires listId)",
         get: "Get card details by ID",
+        getActions: "Get card activity log",
         create: "Create a new card",
         update: "Update card properties",
         delete: "Delete a card",
     }, {
         id: {
-            description: "Card ID (for get, update, delete) or List ID (for list, create)",
-            requiredFor: ["list", "get", "update", "delete"],
+            description: "Card ID (for get, getActions, update, delete) or List ID (for list, create)",
+            requiredFor: ["list", "get", "getActions", "update", "delete"],
         },
         data: {
-            description: "Card data: { name: string, type: 'project'|'story' (required), position: number (required for create), listId?: string (for create/move), description?: string, dueDate?: string, isDueCompleted?: boolean }",
+            description: "Card data: { name: string, type: 'project'|'story' (required), position: number (required for create), listId?: string (for create/move), description?: string, dueDate?: string, isDueCompleted?: boolean, attachments?: [{ name, contentBase64 | text | url, mimeType? }] }",
             requiredFor: ["create", "update"],
             properties: {
                 name: { type: "string", description: "Card name", required: true },
@@ -271,6 +277,7 @@ export const cardsTool = {
                 description: { type: "string", description: "Card description" },
                 dueDate: { type: "string", description: "Due date (ISO 8601)" },
                 isDueCompleted: { type: "boolean", description: "Whether the due date is completed" },
+                attachments: { type: "array", description: "Files to attach on create: [{ name, contentBase64 (base64 of file bytes) | text (plain text content) | url (link, Planka v2), mimeType? }] (Planka v1 ignores type)" },
             },
         },
         query: {
@@ -280,6 +287,70 @@ export const cardsTool = {
         },
     }),
 };
+/**
+ * Attachments tool - upload, download, and manage card file attachments.
+ *
+ * Verified against live Planka 1.26.2 and 2.0.3:
+ *  - upload: POST /cards/{cardId}/attachments, multipart. v2 requires form
+ *    fields `type` ("file"|"link") and `name`; v1 ignores extra fields, so a
+ *    single v2-shaped request works on both.
+ *  - download: no JSON API — the attachment record carries an `url`
+ *    (/attachments/{id}/download/{name}) that Planka authenticates via the
+ *    `accessToken` cookie only (Bearer/X-Api-Key get 401). The engine fetches
+ *    it and returns base64.
+ *  - link attachments (url instead of file content) are Planka v2 only.
+ */
+export const attachmentsTool = {
+    name: "attachments",
+    description: "Upload, download, and manage file attachments on Planka cards. Content moves as base64 (data.contentBase64 for upload, result.contentBase64 for download).",
+    operations: {
+        upload: {
+            method: "POST",
+            path: "/cards/{cardId}/attachments",
+            requestType: "multipart",
+            description: "Upload a file (contentBase64 or text) or attach a link (url, Planka v2) to a card",
+        },
+        download: {
+            method: "GET",
+            path: "/attachments/{id}",
+            custom: "downloadAttachment",
+            description: "Download an attachment's content as base64 (requires the owning card ID)",
+        },
+        rename: {
+            method: "PATCH",
+            path: "/attachments/{id}",
+            description: "Rename an attachment",
+        },
+        delete: {
+            method: "DELETE",
+            path: "/attachments/{id}",
+            description: "Delete an attachment permanently",
+        },
+    },
+    inputSchema: buildGroupedSchema(["upload", "download", "rename", "delete"], {
+        upload: "Upload a file or link to a card (id = card ID)",
+        download: "Download attachment content as base64 (id = attachment ID)",
+        rename: "Rename an attachment",
+        delete: "Delete an attachment",
+    }, {
+        id: {
+            description: "Card ID (for upload) or Attachment ID (for download, rename, delete)",
+            requiredFor: ["upload", "download", "rename", "delete"],
+        },
+        data: {
+            description: "Attachment data: upload = { name (required), contentBase64 | text | url, mimeType? }; download = { cardId? (owning card, or set via context) }; rename = { name }",
+            requiredFor: ["upload", "rename"],
+            properties: {
+                name: { type: "string", description: "File/attachment name (e.g. report.pdf)", required: true },
+                contentBase64: { type: "string", description: "Base64-encoded file content (preferred for binary)" },
+                text: { type: "string", description: "Plain-text content (alternative to contentBase64)" },
+                mimeType: { type: "string", description: "MIME type (e.g. application/pdf); default application/octet-stream, text/plain for text" },
+                url: { type: "string", description: "Link attachments (Planka v2): attach an external URL instead of file content" },
+                cardId: { type: "string", description: "Owning card ID for download (or set cardId via the context tool)" },
+            },
+        },
+    }),
+};
 /**
  * Comments tool - manages comments on cards
  */

package/dist/tools/optional/index.d.ts

@@ -2,8 +2,8 @@
  * Optional tools - Extended functionality (not essential for basic operations)
  */
 import { GroupedToolDefinition } from "../types.js";
-import { actionsTool, attachmentsTool, boardMembersTool, customFieldsTool, notificationsTool, backgroundImagesTool, cardExtrasTool, commentExtrasTool, listExtrasTool, taskExtrasTool, labelExtrasTool, cardMemberExtrasTool, userInfoTool } from "./tools.js";
-export { actionsTool, attachmentsTool, boardMembersTool, customFieldsTool, notificationsTool, backgroundImagesTool, cardExtrasTool, commentExtrasTool, listExtrasTool, taskExtrasTool, labelExtrasTool, cardMemberExtrasTool, userInfoTool, };
+import { actionsTool, boardMembersTool, customFieldsTool, notificationsTool, backgroundImagesTool, cardExtrasTool, commentExtrasTool, listExtrasTool, taskExtrasTool, labelExtrasTool, cardMemberExtrasTool, userInfoTool } from "./tools.js";
+export { actionsTool, boardMembersTool, customFieldsTool, notificationsTool, backgroundImagesTool, cardExtrasTool, commentExtrasTool, listExtrasTool, taskExtrasTool, labelExtrasTool, cardMemberExtrasTool, userInfoTool, };
 /**
  * All optional tools combined
  */

package/dist/tools/optional/index.js

@@ -1,11 +1,10 @@
-import { actionsTool, attachmentsTool, boardMembersTool, customFieldsTool, notificationsTool, backgroundImagesTool, cardExtrasTool, commentExtrasTool, listExtrasTool, taskExtrasTool, labelExtrasTool, cardMemberExtrasTool, userInfoTool, } from "./tools.js";
-export { actionsTool, attachmentsTool, boardMembersTool, customFieldsTool, notificationsTool, backgroundImagesTool, cardExtrasTool, commentExtrasTool, listExtrasTool, taskExtrasTool, labelExtrasTool, cardMemberExtrasTool, userInfoTool, };
+import { actionsTool, boardMembersTool, customFieldsTool, notificationsTool, backgroundImagesTool, cardExtrasTool, commentExtrasTool, listExtrasTool, taskExtrasTool, labelExtrasTool, cardMemberExtrasTool, userInfoTool, } from "./tools.js";
+export { actionsTool, boardMembersTool, customFieldsTool, notificationsTool, backgroundImagesTool, cardExtrasTool, commentExtrasTool, listExtrasTool, taskExtrasTool, labelExtrasTool, cardMemberExtrasTool, userInfoTool, };
 /**
  * All optional tools combined
  */
 export const optionalTools = [
     actionsTool,
-    attachmentsTool,
     boardMembersTool,
     customFieldsTool,
     notificationsTool,

package/dist/tools/optional/tools.d.ts

@@ -3,10 +3,6 @@ import { GroupedToolDefinition } from "../types.js";
  * Actions tool - action history
  */
 export declare const actionsTool: GroupedToolDefinition;
-/**
- * Attachments tool - manages card attachments
- */
-export declare const attachmentsTool: GroupedToolDefinition;
 /**
  * Board Members tool - manages board memberships
  */

package/dist/tools/optional/tools.js

@@ -30,49 +30,6 @@ export const actionsTool = {
         },
     }),
 };
-/**
- * Attachments tool - manages card attachments
- */
-export const attachmentsTool = {
-    name: "attachments",
-    description: "Manage attachments on Planka cards.",
-    operations: {
-        create: {
-            method: "POST",
-            path: "/cards/{cardId}/attachments",
-            description: "Add an attachment to a card",
-        },
-        update: {
-            method: "PATCH",
-            path: "/attachments/{id}",
-            description: "Update attachment properties",
-        },
-        delete: {
-            method: "DELETE",
-            path: "/attachments/{id}",
-            description: "Delete an attachment",
-        },
-    },
-    inputSchema: buildGroupedSchema(["create", "update", "delete"], {
-        create: "Add attachment to card",
-        update: "Update attachment",
-        delete: "Delete attachment",
-    }, {
-        id: {
-            description: "Card ID (for create) or Attachment ID (for update, delete)",
-            requiredFor: ["create", "update", "delete"],
-        },
-        data: {
-            description: "Attachment data: { type: 'file'|'link', name?: string, url?: string (for link) }. Binary file uploads are not supported by this MCP server; use type 'link'.",
-            requiredFor: ["create", "update"],
-            properties: {
-                type: { type: "string", enum: ["file", "link"], description: "Attachment type", required: true },
-                name: { type: "string", description: "Attachment name" },
-                url: { type: "string", description: "URL (for link attachments)" },
-            },
-        },
-    }),
-};
 /**
  * Board Members tool - manages board memberships
  */

package/dist/tools/types.d.ts

@@ -14,6 +14,10 @@ export interface ToolOperation {
     requiresAuth?: boolean;
     /** Description of this specific operation */
     description?: string;
+    /** Send data as multipart/form-data instead of JSON (file uploads). */
+    requestType?: "multipart";
+    /** Fully custom handling in the engine (attachments download). */
+    custom?: "downloadAttachment";
 }
 /**
  * Grouped tool definition - multiple operations under one tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denisixnpm/planka-mcp",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "MCP server for Planka - Real-Time Collaborative Kanban Board",
   "main": "dist/server.js",
   "type": "module",