@denisixnpm/planka-mcp 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# Planka MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@denisixnpm/planka-mcp)](https://www.npmjs.com/package/@denisixnpm/planka-mcp)
+[![GitHub release](https://img.shields.io/github/v/release/denisix/planka-mcp)](https://github.com/denisix/planka-mcp/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MCP server for [Planka](https://planka.app/) (real-time Kanban), tuned for AI coding agents:
+**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
+
+### Claude Code
+
+```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`:
+
+```json
+{
+  "mcpServers": {
+    "planka": {
+      "command": "npx",
+      "args": ["-y", "@denisixnpm/planka-mcp"],
+      "env": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+### Codex (`~/.codex/config.toml`)
+
+```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`)
+
+```json
+{
+  "mcp": {
+    "planka": {
+      "type": "local",
+      "command": ["npx", "-y", "@denisixnpm/planka-mcp"],
+      "environment": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+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`.
+
+## 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_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_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`.
+
+## Tools (28)
+
+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` |
+
+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.
+
+## 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
+```
+
+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:
+
+
+```bash
+docker run -d -p 3001:3001 \
+  -e MCP_TRANSPORT=sse -e MCP_HOST=0.0.0.0 -e MCP_AUTH_TOKEN=change-me \
+  -e PLANKA_BASE_URL=http://host.docker.internal:3000 \
+  -e PLANKA_API_KEY=your-api-key \
+  denisix/planka-mcp:latest
+```
+
+Compiled Bun binary on distroless (171 MB, no shell, no node_modules).
+
+## Development
+
+```bash
+bun install && bun test          # build + full hermetic suite
+bun run dev                      # run from source (stdio)
+```
+
+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).
+
+## 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.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Issues: [github.com/denisix/planka-mcp/issues](https://github.com/denisix/planka-mcp/issues).

package/dist/condense.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Response condenser: shrinks Planka API payloads to the fields an AI agent
+ * (Claude Code, Codex, opencode) actually needs, protecting the client's
+ * context window. Planka envelopes every response as {item|items, included}
+ * with full audit metadata on each entity; the condenser keeps the structure
+ * but reduces every entity to its whitelist and truncates long text.
+ *
+ * Semantics:
+ *  - {items, included} -> {items: [...reduced], included: {...reduced}}
+ *  - {item,  included} -> {item: reduced,       included: {...reduced}}
+ *  - bare arrays       -> each entity reduced (defensive; mocks, older shapes)
+ *  - whitelists        -> per-tool field lists; unknown tools fall back to a
+ *                         generic id/name/... pick of primitive values
+ *  - strings           -> truncated to TEXT_LIMIT characters
+ *  - auth/context      -> verbatim (tokens and local state must not be mangled)
+ */
+/** Reduce one tool result (envelope, list, or raw value). */
+export declare function condenseResult(toolName: string, data: unknown): unknown;

package/dist/condense.js

@@ -0,0 +1,127 @@
+/**
+ * Response condenser: shrinks Planka API payloads to the fields an AI agent
+ * (Claude Code, Codex, opencode) actually needs, protecting the client's
+ * context window. Planka envelopes every response as {item|items, included}
+ * with full audit metadata on each entity; the condenser keeps the structure
+ * but reduces every entity to its whitelist and truncates long text.
+ *
+ * Semantics:
+ *  - {items, included} -> {items: [...reduced], included: {...reduced}}
+ *  - {item,  included} -> {item: reduced,       included: {...reduced}}
+ *  - bare arrays       -> each entity reduced (defensive; mocks, older shapes)
+ *  - whitelists        -> per-tool field lists; unknown tools fall back to a
+ *                         generic id/name/... pick of primitive values
+ *  - strings           -> truncated to TEXT_LIMIT characters
+ *  - auth/context      -> verbatim (tokens and local state must not be mangled)
+ */
+const TEXT_LIMIT = 300;
+/** Entity-specific field whitelists, keyed by tool name. */
+const ENTITY_FIELDS = {
+    projects: ["id", "name", "type"],
+    boards: ["id", "name", "position"],
+    lists: ["id", "name", "type", "position"],
+    listExtras: ["id", "name", "type", "position"],
+    cards: ["id", "name", "description", "position", "listId", "isArchived"],
+    cardExtras: ["id", "name", "description", "position", "listId", "isArchived"],
+    tasks: ["id", "name", "isCompleted", "taskListId"],
+    taskExtras: ["id", "name", "isCompleted", "taskListId"],
+    taskLists: ["id", "name", "position", "cardId"],
+    labels: ["id", "name", "color", "position"],
+    labelExtras: ["id", "cardId", "labelId"],
+    comments: ["id", "text", "cardId"],
+    commentExtras: ["id", "text", "cardId"],
+    attachments: ["id", "name", "url", "type", "cardId"],
+    users: ["id", "email", "name", "username", "role"],
+    userInfo: ["id", "email", "name", "username", "role"],
+    boardMembers: ["id", "userId", "boardId", "role"],
+    cardMembers: ["id", "userId", "cardId"],
+    cardMemberExtras: ["id", "userId", "cardId"],
+    projectManagers: ["id", "userId", "projectId"],
+    customFields: ["id", "name", "position", "content", "value"],
+    customFieldGroups: ["id", "name", "position"],
+    customFieldValues: ["id", "cardId", "customFieldId", "content"],
+    baseCustomFieldGroups: ["id", "name", "position"],
+    webhooks: ["id", "name", "url"],
+    backgroundImages: ["id", "name", "boardId"],
+    notifications: ["id", "type", "isRead", "cardId"],
+    actions: ["id", "type", "cardId", "userId"],
+};
+/** `included` keys that do not match their tool name verbatim. */
+const INCLUDED_KEY_TO_TOOL = {
+    boardMemberships: "boardMembers",
+    cardMemberships: "cardMembers",
+    cardLabels: "labelExtras",
+    taskLists: "taskLists",
+    customFieldGroups: "customFieldGroups",
+    customFieldValues: "customFieldValues",
+    baseCustomFieldGroups: "baseCustomFieldGroups",
+};
+/** Generic whitelist used when a tool has no specific mapping. */
+const GENERIC_FIELDS = [
+    "id", "name", "email", "username", "url", "text", "type", "position",
+    "color", "role", "isCompleted", "isRead", "cardId", "listId", "boardId",
+    "projectId", "userId",
+];
+/** Tools whose payloads are returned verbatim (tokens, local state). */
+const PASSTHROUGH_TOOLS = { auth: true, context: true };
+function truncateText(value) {
+    return value.length > TEXT_LIMIT ? value.slice(0, TEXT_LIMIT) + "…" : value;
+}
+function condenseEntity(toolName, entity) {
+    if (typeof entity !== "object" || entity === null || Array.isArray(entity)) {
+        return entity;
+    }
+    const source = entity;
+    const whitelist = ENTITY_FIELDS[toolName] ?? GENERIC_FIELDS;
+    const out = {};
+    for (const field of whitelist) {
+        const value = source[field];
+        if (value !== null && value !== undefined) {
+            out[field] = typeof value === "string" ? truncateText(value) : value;
+        }
+    }
+    return Object.keys(out).length > 0 ? out : entity;
+}
+/** Reduce every entity array inside an `included` sidecar object. */
+function condenseIncluded(included) {
+    const out = {};
+    for (const [key, value] of Object.entries(included)) {
+        if (Array.isArray(value)) {
+            const toolName = INCLUDED_KEY_TO_TOOL[key] ?? key;
+            out[key] = value.map(entity => condenseEntity(toolName, entity));
+        }
+    }
+    return out;
+}
+/** Reduce one tool result (envelope, list, or raw value). */
+export function condenseResult(toolName, data) {
+    if (PASSTHROUGH_TOOLS[toolName]) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return data.map(item => condenseEntity(toolName, item));
+    }
+    if (typeof data === "object" && data !== null) {
+        const source = data;
+        const hasItems = Array.isArray(source.items);
+        const hasItem = "item" in source;
+        if (hasItems || hasItem) {
+            const out = {};
+            if (hasItems) {
+                out.items = source.items.map(item => condenseEntity(toolName, item));
+            }
+            if (hasItem) {
+                out.item = condenseEntity(toolName, source.item);
+            }
+            if (source.included && typeof source.included === "object") {
+                const included = condenseIncluded(source.included);
+                if (Object.keys(included).length > 0) {
+                    out.included = included;
+                }
+            }
+            return out;
+        }
+        return condenseEntity(toolName, data);
+    }
+    return data;
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};