@denisixnpm/planka-mcp 2.3.1 → 2.5.0

package/README.md

@@ -9,17 +9,16 @@ MCP server for [Planka](https://planka.app/) (real-time Kanban), tuned for AI co
 **Claude Code, Codex, opencode** and any MCP client. Works with Planka v2 and v1 (≤ 1.26.x).
 No build step, no Docker required — `npx` runs the prebuilt package over stdio.
 
-## Install
+**Auth:** `PLANKA_USERNAME`/`PLANKA_PASSWORD` works on **every** Planka version (login, token
+cache, and silent re-login are automatic). `PLANKA_API_KEY` is **v2 only** — generate one in
+Planka user settings → *API keys* (v1.26.x has none; `X-Api-Key` returns 401 there, verified).
+All examples below use username/password; on v2 you may swap the two auth envs for
+`PLANKA_API_KEY=your-api-key`.
 
-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).
+## Install
 
 ### Claude Code
 
-**Planka v1 (≤ 1.26.x) — username/password:**
-
 ```bash
 claude mcp add planka \
   --env PLANKA_BASE_URL=http://localhost:3000 \
@@ -28,16 +27,7 @@ claude mcp add planka \
   -- 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 \
-  --env PLANKA_API_KEY=your-api-key \
-  -- npx -y @denisixnpm/planka-mcp
-```
-
-Or in `claude_desktop_config.json` / `.mcp.json` (username/password form — works on both versions):
+Or in `claude_desktop_config.json` / `.mcp.json`:
 
 ```json
 {
@@ -53,8 +43,6 @@ Or in `claude_desktop_config.json` / `.mcp.json` (username/password form — wor
 
 ### Codex (`~/.codex/config.toml`)
 
-**Planka v1 (≤ 1.26.x):**
-
 ```toml
 [mcp_servers.planka]
 command = "npx"
@@ -62,19 +50,8 @@ 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"
-args = ["-y", "@denisixnpm/planka-mcp"]
-env = { PLANKA_BASE_URL = "http://localhost:3000", PLANKA_API_KEY = "your-api-key" }
-```
-
 ### opencode (`opencode.json`)
 
-**Planka v1 (≤ 1.26.x):**
-
 ```json
 {
   "mcp": {
@@ -87,21 +64,44 @@ env = { PLANKA_BASE_URL = "http://localhost:3000", PLANKA_API_KEY = "your-api-ke
 }
 ```
 
-**Planka v2 (API key):**
+Requires Node.js ≥ 22.19 (or Bun ≥ 1.3). Debug: `npx -y @denisixnpm/planka-mcp 2>&1 | tee debug.log`.
+
+## Attachments & files
+
+`cards.get` returns the full working context in one call — description, tasks, task lists,
+attachments, and the activity log (`actions`). Attachment records are normalized across versions
+(v2's nested `data.url` flattened to `url`/`size`/`mimeType`).
+
+- **Create with files**: `cards { action: "create", data: { name, attachments: [{ name?, filePath | text | contentBase64, mimeType? }] } }` — uploads happen in the same tool call. With `filePath` the server reads the local file itself and auto-detects name + MIME from the extension (.png, .jpg, .webp, .gif, .pdf, .doc(x), .xls(x), .ppt(x), .txt, .md, .csv, .json, and more).
+- **Upload later**: `attachments { action: "upload", id: <cardId>, data: { name?, filePath | text | contentBase64 | url, mimeType? } }` — `url` creates a link attachment (v2 only).
+- **Download**: `attachments { action: "download", id: <attachmentId>, data: { cardId } }` — images (`image/*`) come back as a rendered MCP image block, text files as decoded `text`, other binary as `contentBase64` (≤ 10 MB inline).
+- **Rename / delete**: `attachments { action: "rename" | "delete", id, data: { name? } }`.
+
+Downloads need username/password auth: Planka's file route authenticates via cookie only
+(Bearer/API keys get 401 — verified on 1.26.2 and 2.0.3).
+
+## Agent workflow
+
+**Minimal card creation** — `cards { action: "create", data: { name: "Fix login" } }` is enough:
+`type` and `position` (append at end) are defaulted; add `description`, `dueDate`, `listId`
+(move), and inline `attachments` as needed.
+
+**Find without walking lists** — `cards { action: "find", data: { boardId?, name: "login" } }`
+searches every card on the board case-insensitively and returns matches with their list names
+(`boardId` can come from the `context` tool).
+
+**Scoped context** — select a project/board/list/card once, then omit ids:
 
 ```json
-{
-  "mcp": {
-    "planka": {
-      "type": "local",
-      "command": ["npx", "-y", "@denisixnpm/planka-mcp"],
-      "environment": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_API_KEY": "your-api-key" }
-    }
-  }
-}
+{ "action": "set", "data": { "boardId": "..." } }
 ```
 
-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`.
+`context.set` returns an overview of what you opened; setting a higher level resets deeper ones.
+Scope is per SSE session, process-wide for stdio.
+
+**Condensed output** — responses keep only agent-relevant fields (ids, names, positions, states);
+timestamps, password hashes, and audit metadata are stripped, long text truncated, `included`
+sidecars reduced per entity. Escape hatches: per-call `raw: true` or `PLANKA_CONDENSED_OUTPUT=false`.
 
 ## Configuration
 
@@ -114,28 +114,14 @@ Requires Node.js ≥ 22.19 (or run the same command with Bun ≥ 1.3). Debug: `n
 | `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 |
 | `MCP_AUTH_TOKEN` | — | If set, SSE endpoints require `Authorization: Bearer <token>` |
-| `MCP_CORS_ORIGIN` | — | If set, emitted as `Access-Control-Allow-Origin` (no CORS by default) |
 | `MCP_HEARTBEAT_INTERVAL_MS` | `30000` | SSE keep-alive interval for strict proxies |
 
-Note: Bun auto-loads `.env` from the working directory (real env vars win); the Node/npx path does not.
-
-## Agent workflow
-
-**Scoped context** — select a project/board/list/card once, then omit ids:
-
-```json
-{"name": "context", "arguments": {"action": "set", "data": {"boardId": "..."}}}
-{"name": "cards",  "arguments": {"action": "create", "data": {"name": "Ship it", "type": "project", "position": 1}}}
-```
-
-`context.set` returns an overview of what you opened (boards of the project, lists/cards of the board). Setting a higher level resets deeper ones. Scope is per SSE session; process-wide for stdio.
-
-**Condensed output** — responses keep only agent-relevant fields (ids, names, positions, states); timestamps, password hashes and audit metadata are stripped, long text truncated, `included` sidecars reduced per entity. Escape hatches: per-call `raw: true` or `PLANKA_CONDENSED_OUTPUT=false`.
+Bun auto-loads `.env` from the working directory (real env vars win); the Node/npx path does not.
 
 ## Tools (28)
 
@@ -143,60 +129,58 @@ Every tool takes `action`, optional `id`/`data`/`query`, and optional `raw: true
 
 | Category | Tools |
 |----------|-------|
-| **Core** (11, always on) | `auth`, `bootstrap`, `context`, `projects`, `boards`, `lists`, `cards`, `comments`, `tasks`, `labels`, `cardMembers` |
-| **Admin** (4) | `config`, `users`, `webhooks`, `projectManagers` |
-| **Optional** (13) | `attachments`, `backgroundImages`, `boardMembers`, `cardExtras`, `cardMemberExtras`, `commentExtras`, `customFields`, `labelExtras`, `listExtras`, `notifications`, `taskExtras`, `userInfo`, `actions` |
+| Core (12, always on) | `auth`, `bootstrap`, `context`, `projects`, `boards`, `lists`, `cards`, `attachments`, `comments`, `tasks`, `labels`, `cardMembers` |
+| Admin (4) | `users`, `projectManagers`, `webhooks`, `notificationServices` |
+| Optional (12) | `actions`, `boardMembers`, `customFields`, `notifications`, `backgroundImages`, `cardExtras`, `commentExtras`, `listExtras`, `taskExtras`, `labelExtras`, `cardMemberExtras`, `userInfo` |
 
-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; Planka v2 JSON link attachments HTTP 500 (multipart required); v1.26.2 has no REST comments/task-lists/custom-fields/webhooks (clean 404s), and renamed v1 membership/label routes are retried automatically.
+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.
 
 ## Multi-client SSE mode (optional)
 
-To serve several clients over HTTP instead of stdio, run the same package in SSE mode:
-
 ```bash
-MCP_TRANSPORT=sse MCP_HOST=127.0.0.1 MCP_PORT=3001 MCP_AUTH_TOKEN=change-me \
-PLANKA_BASE_URL=http://localhost:3000 PLANKA_API_KEY=your-api-key \
-npx -y @denisixnpm/planka-mcp
+MCP_TRANSPORT=sse npx -y @denisixnpm/planka-mcp
 ```
 
 Connect MCP clients to `http://127.0.0.1:3001/sse`. Set `MCP_AUTH_TOKEN` whenever binding beyond
-loopback (`MCP_HOST=0.0.0.0`) — without it, anyone who can reach the port has full tool access.
-A `--healthcheck` mode is built in for orchestrators.
-
-Prefer a container? The image is published on Docker Hub:
-[`hub.docker.com/r/denisix/planka-mcp`](https://hub.docker.com/r/denisix/planka-mcp)
+loopback — without it, anyone who can reach the port has full tool access. A `--healthcheck`
+mode is built in for orchestrators.
 
+Prefer a container? [`hub.docker.com/r/denisix/planka-mcp`](https://hub.docker.com/r/denisix/planka-mcp):
 
 ```bash
-docker run -d -p 3001:3001 \
-  -e MCP_TRANSPORT=sse -e MCP_HOST=0.0.0.0 -e MCP_AUTH_TOKEN=change-me \
+docker run -d --name planka-mcp -p 3001:3001 \
   -e PLANKA_BASE_URL=http://host.docker.internal:3000 \
-  -e PLANKA_API_KEY=your-api-key \
-  denisix/planka-mcp:latest
+  -e PLANKA_USERNAME -e PLANKA_PASSWORD \
+  denisix/planka-mcp
 ```
 
-Compiled Bun binary on distroless (171 MB, no shell, no node_modules).
+Compiled Bun binary on distroless (no shell, no node_modules).
 
 ## Development
 
 ```bash
-bun install && bun test          # build + full hermetic suite
-bun run dev                      # run from source (stdio)
+bun install
+bun test                                    # hermetic suite
+E2E_PLANKA_URL=… E2E_PLANKA_V1_URL=… bun test  # + live Planka e2e (154 tests)
 ```
 
-End-to-end tests run against real Planka stacks (`docker compose --profile e2e up -d`, then `E2E_PLANKA_URL=... bun test`). See [CONTRIBUTING.md](CONTRIBUTING.md).
+E2E stacks: `docker compose --profile e2e up -d`. Details in [CONTRIBUTING.md](CONTRIBUTING.md)
+and [CLAUDE.md](CLAUDE.md).
 
 ## Credits
 
 Fork of [planka-mcp](https://github.com/chmald/planka-mcp) by [Christopher Maldonado](https://github.com/chmald) — credit for the original server goes to him. Maintained by [denisix](https://github.com/denisix), published as [`@denisixnpm/planka-mcp`](https://www.npmjs.com/package/@denisixnpm/planka-mcp).
 
-**What this fork improves**
-
-- **Security**: 0 `npm audit` findings; loopback-only SSE by default, timing-safe bearer auth, no wildcard CORS, validated login responses (no `Bearer undefined`), single-flight login, per-request timeouts.
-- **Planka v1 compatibility**: renamed v1 routes retried transparently on 404 — one build serves v2 and v1.
-- **Agent-optimized**: condensed output + `context` tool for scoped, id-free workflows.
-- **Lean**: one production dependency (MCP SDK), built-in `fetch`, compiled distroless image.
-- **Verified**: 117 tests incl. live E2E against real Planka 2.0.3 and 1.26.2, SSE protocol round-trips, engine edge cases.
+**What this fork improves**: security hardening (0 `npm audit` findings, loopback-only SSE,
+timing-safe auth, single-flight login, per-request timeouts); Planka v1 compatibility with
+automatic legacy-route fallbacks; condensed agent output and scoped working context; full
+attachment support (upload/download/create-with-files, both Planka majors); agent-first card
+workflows (minimal create, board-wide find); npm + Docker Hub release pipelines with provenance
+and SBOM.
 
 ## License
 

package/dist/condense.js

@@ -21,7 +21,7 @@ const ENTITY_FIELDS = {
     boards: ["id", "name", "position"],
     lists: ["id", "name", "type", "position"],
     listExtras: ["id", "name", "type", "position"],
-    cards: ["id", "name", "description", "position", "listId", "isArchived"],
+    cards: ["id", "name", "description", "position", "listId", "listName", "isArchived"],
     cardExtras: ["id", "name", "description", "position", "listId", "isArchived"],
     tasks: ["id", "name", "isCompleted", "taskListId"],
     taskExtras: ["id", "name", "isCompleted", "taskListId"],
@@ -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,13 @@ export function condenseResult(toolName, data) {
     }
     if (typeof data === "object" && data !== null) {
         const source = data;
+        // Attachment download payloads carry base64 / decoded text — whitelists
+        // and text truncation must not touch them (size is capped by the engine).
+        if (typeof source.contentBase64 === "string" ||
+            typeof source.imageBase64 === "string" ||
+            (toolName === "attachments" && typeof source.text === "string" && source.size !== undefined)) {
+            return data;
+        }
         const hasItems = Array.isArray(source.items);
         const hasItem = "item" in source;
         if (hasItems || hasItem) {

package/dist/server.js

@@ -5,10 +5,30 @@ import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { createServer } from "node:http";
 import { createHash, timingSafeEqual } from "node:crypto";
+import { readFile, stat as statFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
 // Import tool definitions
 import { getEnabledTools, toolCounts } from "./tools/index.js";
 import { condenseResult } from "./condense.js";
-// ----- Configuration -----
+/** 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",
+    ".webp": "image/webp", ".svg": "image/svg+xml", ".avif": "image/avif", ".bmp": "image/bmp", ".ico": "image/x-icon",
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xls": "application/vnd.ms-excel",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".odt": "application/vnd.oasis.opendocument.text",
+    ".txt": "text/plain", ".md": "text/markdown", ".csv": "text/csv", ".html": "text/html", ".xml": "text/xml",
+    ".json": "application/json", ".yaml": "application/yaml", ".yml": "application/yaml",
+    ".zip": "application/zip", ".gz": "application/gzip", ".tar": "application/x-tar",
+    ".mp3": "audio/mpeg", ".wav": "audio/wav", ".mp4": "video/mp4", ".webm": "video/webm", ".mov": "video/quicktime",
+};
+/** Hard cap for attachment bytes moved through the server (upload and download). */
+const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
 const PLANKA_BASE_URL = process.env.PLANKA_BASE_URL || "http://localhost:3000";
 const PLANKA_USERNAME = process.env.PLANKA_USERNAME;
 const PLANKA_PASSWORD = process.env.PLANKA_PASSWORD;
@@ -138,6 +158,14 @@ 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 (binary/cookie auth and board-wide search that
+        // the generic JSON engine cannot express).
+        if (operation.custom === "downloadAttachment") {
+            return downloadAttachment(input, scope);
+        }
+        if (operation.custom === "findCards") {
+            return findCards(input, scope);
+        }
         // Construct URL with path parameters
         const canonicalPath = overridePath ?? operation.path;
         let actualPath = canonicalPath;
@@ -201,7 +229,56 @@ 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 isLink = typeof d.url === "string" && d.url !== "" && d.contentBase64 === undefined && d.text === undefined && d.filePath === undefined;
+            const fd = new FormData();
+            fd.append("type", isLink ? "link" : "file");
+            if (isLink) {
+                fd.append("name", typeof d.name === "string" && d.name !== "" ? d.name : "link");
+                fd.append("url", String(d.url));
+            }
+            else {
+                let bytes;
+                let name = typeof d.name === "string" && d.name !== "" ? d.name : "";
+                let mimeType = typeof d.mimeType === "string" ? d.mimeType : "";
+                if (typeof d.filePath === "string" && d.filePath !== "") {
+                    // Agents hand over a local file path; the server reads and encodes it.
+                    if (!name)
+                        name = basename(d.filePath);
+                    try {
+                        const fileInfo = await statFile(d.filePath);
+                        if (fileInfo.size > MAX_ATTACHMENT_BYTES) {
+                            return { success: false, error: `File too large (${fileInfo.size} bytes > ${MAX_ATTACHMENT_BYTES}): ${d.filePath}` };
+                        }
+                        bytes = new Uint8Array(await readFile(d.filePath));
+                    }
+                    catch (readError) {
+                        return { success: false, error: `Cannot read data.filePath (${d.filePath}): ${readError instanceof Error ? readError.message : String(readError)}` };
+                    }
+                    if (!mimeType)
+                        mimeType = MIME_BY_EXT[extname(d.filePath).toLowerCase()] ?? "";
+                }
+                else 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 (!mimeType)
+                        mimeType = "text/plain";
+                }
+                else {
+                    return { success: false, error: "Provide data.filePath, data.contentBase64, data.text, or data.url for the attachment content" };
+                }
+                fd.append("name", name !== "" ? name : "attachment");
+                fd.append("file", new Blob([bytes], { type: mimeType !== "" ? mimeType : "application/octet-stream" }), name !== "" ? name : "attachment");
+            }
+            body = fd;
+        }
+        else if (["POST", "PUT", "PATCH"].includes(methodUpper) && input?.data !== undefined) {
             headers["Content-Type"] = "application/json";
             body = JSON.stringify(input.data);
         }
@@ -272,6 +349,213 @@ 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;
+}
+/** Inline decoded text for downloads up to this size; larger stays base64-only. */
+const MAX_INLINE_TEXT_BYTES = 64 * 1024;
+/** 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}.
+ */
+/**
+ * Board-wide card search: agents say "find the card called X" without
+ * walking lists. One board GET supplies cards + lists on both Planka majors;
+ * results are matched case-insensitively on a name substring and annotated
+ * with the containing list's name.
+ */
+async function findCards(input, scope) {
+    const boardId = String(input?.data?.boardId ?? input?.id ?? scope?.boardId ?? "");
+    const needle = String(input?.data?.name ?? input?.query?.search ?? "").toLowerCase();
+    if (!boardId) {
+        return { success: false, error: "Provide data.boardId (or id), or select a board via the context tool" };
+    }
+    if (!needle) {
+        return { success: false, error: "Provide data.name (case-insensitive substring) to search for" };
+    }
+    const boardsTool = toolMap.get("boards");
+    if (!boardsTool) {
+        return { success: false, error: "boards tool unavailable; cannot search" };
+    }
+    const boardRes = await executeGroupedApiCall(boardsTool.groupedDef, { action: "get", id: boardId });
+    if (!boardRes.success) {
+        return boardRes;
+    }
+    const included = (boardRes.data?.included ?? {});
+    const listNames = new Map((included.lists ?? []).map(l => [String(l.id), String(l.name ?? "")]));
+    const matches = (included.cards ?? [])
+        .filter(card => String(card.name ?? "").toLowerCase().includes(needle))
+        .map(card => ({
+        id: card.id,
+        name: card.name,
+        listId: card.listId,
+        listName: listNames.get(String(card.listId)) ?? "",
+        position: card.position,
+        isArchived: card.isArchived,
+    }));
+    return {
+        success: true,
+        data: {
+            items: matches,
+            query: { boardId, name: needle },
+            count: matches.length,
+        },
+    };
+}
+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}` };
+    }
+    const mimeType = res.headers.get("content-type")?.split(";")[0] ?? record.mimeType ?? "application/octet-stream";
+    const base64 = Buffer.from(bytes).toString("base64");
+    const payload = {
+        id: attachmentId,
+        name: record.name,
+        size: bytes.byteLength,
+        mimeType,
+    };
+    if (mimeType.startsWith("image/")) {
+        // Rendered directly by MCP clients as an image content block; the raw
+        // base64 stays available for agents that need the bytes.
+        payload.imageBase64 = base64;
+    }
+    else if (mimeType.startsWith("text/") || mimeType === "application/json" || mimeType === "application/yaml") {
+        const decoded = Buffer.from(bytes).toString("utf8");
+        if (bytes.byteLength <= MAX_INLINE_TEXT_BYTES && !decoded.includes("\u0000")) {
+            payload.text = decoded;
+        }
+        else {
+            payload.contentBase64 = base64;
+        }
+    }
+    else {
+        payload.contentBase64 = base64;
+    }
+    return { success: true, data: payload };
+}
+/**
+ * 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 +626,7 @@ if (!process.argv.includes("--healthcheck")) {
 function createMcpServer() {
     const server = new McpServer({
         name: "planka-mcp",
-        version: "2.3.1",
+        version: "2.5.0",
     }, {
         capabilities: {
             tools: {},
@@ -366,12 +650,47 @@ function createMcpServer() {
                 isError: true,
             };
         }
+        // cards.create convenience: Planka v2 requires type + position — default
+        // them instead of failing (v1 ignores both extras). data.attachments is
+        // stripped from the API payload and uploaded after the card exists.
+        let pendingAttachments = null;
+        const reqArgs = (args ?? {});
+        if (toolDef.groupedDef.name === "cards" && reqArgs.action === "create") {
+            const data = (reqArgs.data ?? {});
+            if (data.type === undefined)
+                data.type = "story";
+            if (data.position === undefined)
+                data.position = 65535;
+            if (Array.isArray(data.attachments)) {
+                pendingAttachments = data.attachments;
+                const { attachments: _omit, ...dataWithout } = data;
+                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);
+            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.
+            if (asRecord && typeof asRecord.imageBase64 === "string" && reqArgs.action === "download") {
+                const { imageBase64, ...meta } = asRecord;
+                return {
+                    content: [
+                        { type: "image", data: imageBase64, mimeType: String(asRecord.mimeType ?? "image/png") },
+                        { type: "text", text: JSON.stringify(meta, null, 2) },
+                    ],
+                };
+            }
             return {
                 content: [
                     {

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,19 @@ 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.
+ *
+ *  - 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,12 +231,23 @@ 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",
             path: "/lists/{listId}/cards",
-            description: "Create a new card in a list",
+            description: "Create a new card in a list (type/position default automatically; accepts inline attachments)",
+        },
+        find: {
+            method: "GET",
+            path: "/cards/{id}",
+            custom: "findCards",
+            description: "Find cards by name across a whole board (no need to walk lists)",
         },
         update: {
             method: "PATCH",
@@ -249,28 +260,32 @@ export const cardsTool = {
             description: "Delete a card permanently",
         },
     },
-    inputSchema: buildGroupedSchema(["list", "get", "create", "update", "delete"], {
+    inputSchema: buildGroupedSchema(["list", "get", "getActions", "create", "find", "update", "delete"], {
         list: "Get cards from a list (requires listId)",
-        get: "Get card details by ID",
+        get: "Get card details by ID (full context: description, tasks, attachments, actions)",
+        getActions: "Get card activity log",
         create: "Create a new card",
+        find: "Find cards by name across a board",
         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 (get/getActions/update/delete), List ID (list/create), or Board ID (find)",
+            requiredFor: ["list", "get", "getActions", "create", "find", "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 }",
-            requiredFor: ["create", "update"],
+            description: "Card data: create needs { name } only — type ('story') and position (append at end) are defaulted; optional: description, dueDate, isDueCompleted, listId (move), attachments: [{ name, text | contentBase64 | filePath, mimeType? }]. find: { name: substring, boardId? }. update: any of the above except attachments.",
+            requiredFor: ["create", "find", "update"],
             properties: {
-                name: { type: "string", description: "Card name", required: true },
-                type: { type: "string", enum: ["project", "story"], description: "Card type", required: true },
-                position: { type: "number", description: "Card position (Planka requires this on create)", required: true },
+                name: { type: "string", description: "Card name (create) or case-insensitive substring to find (find)", required: true },
+                type: { type: "string", enum: ["project", "story"], description: "Card type (v2; defaults to 'story')" },
+                position: { type: "number", description: "Card position; defaults to append at the end of the list" },
                 listId: { type: "string", description: "List ID (for create/move)" },
-                description: { type: "string", description: "Card description" },
+                boardId: { type: "string", description: "Board to search (find; or set via context)" },
+                description: { type: "string", description: "Card description (markdown)" },
                 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, filePath (server reads + encodes it) | contentBase64 | text, mimeType? }] (mimeType auto-detected from extension for filePath)" },
             },
         },
         query: {
@@ -280,6 +295,69 @@ export const cardsTool = {
         },
     }),
 };
+/**
+ * Attachments tool - upload, download, and manage card file attachments.
+ *
+ *  - 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 (attachment download, card search). */
+    custom?: "downloadAttachment" | "findCards";
 }
 /**
  * Grouped tool definition - multiple operations under one tool

package/package.json

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