@denisixnpm/planka-mcp 2.4.0 → 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,37 +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`.
 
-```json
-{
-  "mcp": {
-    "planka": {
-      "type": "local",
-      "command": ["npx", "-y", "@denisixnpm/planka-mcp"],
-      "environment": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_API_KEY": "your-api-key" }
-    }
-  }
-}
-```
+## Attachments & files
 
-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`.
+`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`).
 
-## Attachments
+- **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? } }`.
 
-`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`.
+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).
 
-- **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? } }`.
+## 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
+{ "action": "set", "data": { "boardId": "..." } }
+```
 
-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).
+`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
 
@@ -135,23 +119,9 @@ and 2.0.3).
 | `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)
 
@@ -159,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"],
@@ -103,9 +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") {
+        // 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);

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,11 +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 (attachment download needs cookie-auth + binary
-        // handling that the generic JSON engine cannot express).
+        // 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;
@@ -210,30 +233,48 @@ async function executeGroupedApiCall(groupedDef, input, overridePath, retryAttem
             // 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 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");
-            fd.append("name", name);
             if (isLink) {
+                fd.append("name", typeof d.name === "string" && d.name !== "" ? d.name : "link");
                 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 !== "") {
+                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 (typeof d.mimeType !== "string")
+                    if (!mimeType)
                         mimeType = "text/plain";
                 }
                 else {
-                    return { success: false, error: "Provide data.contentBase64, data.text, or data.url for the attachment content" };
+                    return { success: false, error: "Provide data.filePath, data.contentBase64, data.text, or data.url for the attachment content" };
                 }
-                fd.append("file", new Blob([bytes], { type: mimeType }), name);
+                fd.append("name", name !== "" ? name : "attachment");
+                fd.append("file", new Blob([bytes], { type: mimeType !== "" ? mimeType : "application/octet-stream" }), name !== "" ? name : "attachment");
             }
             body = fd;
         }
@@ -326,6 +367,8 @@ function normalizeAttachment(raw) {
     }
     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)
@@ -347,7 +390,50 @@ function normalizeAttachmentsIn(data) {
  * 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;
+/**
+ * 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" };
@@ -392,16 +478,32 @@ async function downloadAttachment(input, scope) {
     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"),
-        },
+    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:
@@ -524,7 +626,7 @@ if (!process.argv.includes("--healthcheck")) {
 function createMcpServer() {
     const server = new McpServer({
         name: "planka-mcp",
-        version: "2.4.0",
+        version: "2.5.0",
     }, {
         capabilities: {
             tools: {},
@@ -548,15 +650,22 @@ function createMcpServer() {
                 isError: true,
             };
         }
-        // cards.create accepts data.attachments — strip them from the API payload
-        // and upload after the card exists.
+        // 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 ?? {});
-        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;
+        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)
@@ -570,6 +679,18 @@ 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 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/tools.d.ts

@@ -22,7 +22,6 @@ 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.

package/dist/tools/core/tools.js

@@ -241,7 +241,13 @@ export const cardsTool = {
         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",
@@ -254,30 +260,32 @@ export const cardsTool = {
             description: "Delete a card permanently",
         },
     },
-    inputSchema: buildGroupedSchema(["list", "get", "getActions", "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, getActions, update, delete) or List ID (for list, create)",
-            requiredFor: ["list", "get", "getActions", "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, attachments?: [{ name, contentBase64 | text | url, mimeType? }] }",
-            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, contentBase64 (base64 of file bytes) | text (plain text content) | url (link, Planka v2), mimeType? }] (Planka v1 ignores type)" },
+                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: {
@@ -290,7 +298,6 @@ 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.

package/dist/tools/types.d.ts

@@ -16,8 +16,8 @@ export interface ToolOperation {
     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";
+    /** 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.4.0",
+  "version": "2.5.0",
   "description": "MCP server for Planka - Real-Time Collaborative Kanban Board",
   "main": "dist/server.js",
   "type": "module",