@filcuk/planka-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 filcuk
+
+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,180 @@
+# PLANKA MCP Server
+
+A Model Context Protocol (MCP) server for [PLANKA](https://planka.app) kanban boards, purpose-built for Claude and other AI agents.
+
+Forked from [gogogadgetbytes/planka-mcp](https://github.com/gogogadgetbytes/planka-mcp).
+
+## Features
+
+- Full PLANKA 2.0 API support
+- Type-safe with Zod validation
+- Optimized for agent workflows (combined operations, sensible defaults)
+- 13 tools covering cards, tasks, labels, comments, and lists
+
+## Installation
+
+```bash
+npm install @filcuk/planka-mcp
+```
+
+Or run directly:
+
+```bash
+npx @filcuk/planka-mcp
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PLANKA_BASE_URL` | Yes | Your PLANKA server URL |
+| `PLANKA_AGENT_EMAIL` | Yes | Agent user email |
+| `PLANKA_AGENT_PASSWORD` | Yes | Agent user password |
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "planka": {
+      "command": "npx",
+      "args": ["@filcuk/planka-mcp"],
+      "env": {
+        "PLANKA_BASE_URL": "https://planka.example.com",
+        "PLANKA_AGENT_EMAIL": "agent@example.com",
+        "PLANKA_AGENT_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "planka": {
+      "command": "npx",
+      "args": ["@filcuk/planka-mcp"],
+      "env": {
+        "PLANKA_BASE_URL": "https://planka.example.com",
+        "PLANKA_AGENT_EMAIL": "agent@example.com",
+        "PLANKA_AGENT_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Navigation
+
+| Tool | Description |
+|------|-------------|
+| `planka_get_structure` | Get projects, boards, and lists hierarchy |
+| `planka_get_board` | Get a board with all cards, lists, and labels |
+
+### Cards
+
+| Tool | Description |
+|------|-------------|
+| `planka_create_card` | Create a card (optionally with tasks) |
+| `planka_update_card` | Update card properties |
+| `planka_move_card` | Move card to different list/position |
+| `planka_get_card` | Get card details with tasks/comments |
+| `planka_delete_card` | Delete a card |
+
+### Tasks
+
+| Tool | Description |
+|------|-------------|
+| `planka_create_tasks` | Add tasks (checklist items) to a card |
+| `planka_update_task` | Update task name or completion |
+| `planka_delete_task` | Delete a task |
+
+### Labels
+
+| Tool | Description |
+|------|-------------|
+| `planka_manage_labels` | Create/update/delete board labels |
+| `planka_set_card_labels` | Add/remove labels from a card |
+
+### Comments
+
+| Tool | Description |
+|------|-------------|
+| `planka_add_comment` | Add a comment to a card |
+| `planka_get_comments` | Get all comments on a card |
+
+### Lists
+
+| Tool | Description |
+|------|-------------|
+| `planka_manage_lists` | Create/update/delete lists |
+
+## Usage Examples
+
+### Get board structure
+
+```
+Use planka_get_structure to see all projects and boards
+```
+
+### Create a card with tasks
+
+```
+Use planka_create_card with:
+- listId: "abc123"
+- name: "Implement feature X"
+- tasks: ["Research", "Design", "Implement", "Test"]
+```
+
+### Move card through workflow
+
+```
+Use planka_move_card to move card from "To Do" to "In Progress"
+```
+
+## PLANKA 2.0 Compatibility
+
+This server is designed for PLANKA 2.0 and handles the API differences from 1.x:
+
+- Card creation includes required `type` field
+- Label endpoints use `/card-labels` path
+- Optional fields handled gracefully
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/filcuk/planka-mcp.git
+cd planka-mcp
+
+# Install
+npm install
+
+# Build
+npm run build
+
+# Test
+npm test
+```
+
+## License
+
+MIT
+
+## Links
+
+- [PLANKA](https://planka.app) - The kanban board
+- [PLANKA Swagger](https://plankanban.github.io/planka/swagger-ui/swagger.json) - The kanban board
+- [MCP SDK](https://github.com/modelcontextprotocol/sdk) - Model Context Protocol
+- [Design Document](./DESIGN.md) - Technical design details

package/dist/client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * PLANKA API client with automatic JWT token management.
+ */
+declare class PlankaClient {
+    private config;
+    private token;
+    private tokenExpiresAt;
+    /**
+     * Gets or initializes the configuration.
+     */
+    private getConfig;
+    /** Request timeout in milliseconds */
+    private static readonly REQUEST_TIMEOUT_MS;
+    /**
+     * Creates an AbortSignal with timeout.
+     * Uses AbortSignal.timeout() which automatically cleans up when the request completes.
+     */
+    private createTimeoutSignal;
+    /**
+     * Authenticates and retrieves a new JWT token.
+     */
+    private authenticate;
+    /**
+     * Gets a valid token, refreshing if necessary.
+     */
+    private getToken;
+    /**
+     * Safely parses JSON from a response, returning null on failure.
+     */
+    private safeParseJson;
+    /**
+     * Makes an authenticated request to the PLANKA API.
+     * @param isRetry - Internal flag to prevent infinite retry loops on 401
+     */
+    private request;
+    /**
+     * GET request.
+     */
+    get<T>(path: string): Promise<T>;
+    /**
+     * POST request.
+     */
+    post<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * PATCH request.
+     */
+    patch<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * DELETE request.
+     */
+    delete(path: string): Promise<void>;
+}
+export declare const plankaClient: PlankaClient;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAmDA;;GAEG;AACH,cAAM,YAAY;IAChB,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,cAAc,CAAa;IAEnC;;OAEG;IACH,OAAO,CAAC,SAAS;IAOjB,sCAAsC;IACtC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAEnD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;YACW,YAAY;IAiD1B;;OAEG;YACW,QAAQ;IAOtB;;OAEG;YACW,aAAa;IAQ3B;;;OAGG;YACW,OAAO;IAqDrB;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAItC;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAItD;;OAEG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvD;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C;AAGD,eAAO,MAAM,YAAY,cAAqB,CAAC"}

package/dist/client.js

@@ -0,0 +1,193 @@
+/**
+ * HTTP client for PLANKA API with automatic authentication.
+ */
+import { PlankaAuthError, PlankaConfigError, PlankaNetworkError, createPlankaError, } from "./errors.js";
+import { AuthResponse } from "./schemas/responses.js";
+/**
+ * Validates and returns the configuration from environment variables.
+ */
+function getConfig() {
+    const baseUrl = process.env.PLANKA_BASE_URL;
+    const email = process.env.PLANKA_AGENT_EMAIL;
+    const password = process.env.PLANKA_AGENT_PASSWORD;
+    const missing = [];
+    if (!baseUrl)
+        missing.push("PLANKA_BASE_URL");
+    if (!email)
+        missing.push("PLANKA_AGENT_EMAIL");
+    if (!password)
+        missing.push("PLANKA_AGENT_PASSWORD");
+    if (missing.length > 0) {
+        throw new PlankaConfigError(`Missing required environment variables: ${missing.join(", ")}`);
+    }
+    // Validate URL format
+    try {
+        new URL(baseUrl);
+    }
+    catch {
+        throw new PlankaConfigError(`Invalid PLANKA_BASE_URL: ${baseUrl}`);
+    }
+    // TypeScript narrowing: after the check above, these are guaranteed to be defined
+    return {
+        baseUrl: baseUrl.replace(/\/$/, ""), // Remove trailing slash
+        email: email,
+        password: password,
+    };
+}
+/**
+ * PLANKA API client with automatic JWT token management.
+ */
+class PlankaClient {
+    config = null;
+    token = null;
+    tokenExpiresAt = 0;
+    /**
+     * Gets or initializes the configuration.
+     */
+    getConfig() {
+        if (!this.config) {
+            this.config = getConfig();
+        }
+        return this.config;
+    }
+    /** Request timeout in milliseconds */
+    static REQUEST_TIMEOUT_MS = 30000;
+    /**
+     * Creates an AbortSignal with timeout.
+     * Uses AbortSignal.timeout() which automatically cleans up when the request completes.
+     */
+    createTimeoutSignal() {
+        return AbortSignal.timeout(PlankaClient.REQUEST_TIMEOUT_MS);
+    }
+    /**
+     * Authenticates and retrieves a new JWT token.
+     */
+    async authenticate() {
+        const config = this.getConfig();
+        const url = `${config.baseUrl}/api/access-tokens`;
+        let response;
+        try {
+            response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    emailOrUsername: config.email,
+                    password: config.password,
+                }),
+                signal: this.createTimeoutSignal(),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new PlankaNetworkError(`Request timeout connecting to PLANKA at ${config.baseUrl}`, error);
+            }
+            throw new PlankaNetworkError(`Failed to connect to PLANKA at ${config.baseUrl}`, error);
+        }
+        if (!response.ok) {
+            const body = await this.safeParseJson(response);
+            throw new PlankaAuthError(`Authentication failed: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        const parsed = AuthResponse.parse(data);
+        // PLANKA tokens are valid for 30 minutes by default.
+        // We refresh after 25 minutes to avoid edge cases.
+        // If PLANKA's token lifetime changes, adjust this value.
+        this.tokenExpiresAt = Date.now() + 25 * 60 * 1000;
+        this.token = parsed.item;
+        return this.token;
+    }
+    /**
+     * Gets a valid token, refreshing if necessary.
+     */
+    async getToken() {
+        if (!this.token || Date.now() >= this.tokenExpiresAt) {
+            return this.authenticate();
+        }
+        return this.token;
+    }
+    /**
+     * Safely parses JSON from a response, returning null on failure.
+     */
+    async safeParseJson(response) {
+        try {
+            return await response.json();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Makes an authenticated request to the PLANKA API.
+     * @param isRetry - Internal flag to prevent infinite retry loops on 401
+     */
+    async request(method, path, body, isRetry = false) {
+        const config = this.getConfig();
+        const token = await this.getToken();
+        const url = `${config.baseUrl}${path}`;
+        const headers = {
+            Authorization: `Bearer ${token}`,
+        };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: this.createTimeoutSignal(),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new PlankaNetworkError(`Request timeout: ${method} ${path}`, error);
+            }
+            throw new PlankaNetworkError(`Network error: ${method} ${path}`, error);
+        }
+        // Handle 204 No Content
+        if (response.status === 204) {
+            return undefined;
+        }
+        const data = await this.safeParseJson(response);
+        if (!response.ok) {
+            // If token expired and this is not already a retry, get fresh token and retry once
+            if (response.status === 401 && this.token && !isRetry) {
+                this.token = null;
+                this.tokenExpiresAt = 0;
+                return this.request(method, path, body, true);
+            }
+            throw createPlankaError(response.status, data, `${method} ${path}`);
+        }
+        return data;
+    }
+    /**
+     * GET request.
+     */
+    async get(path) {
+        return this.request("GET", path);
+    }
+    /**
+     * POST request.
+     */
+    async post(path, body) {
+        return this.request("POST", path, body);
+    }
+    /**
+     * PATCH request.
+     */
+    async patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    /**
+     * DELETE request.
+     */
+    async delete(path) {
+        return this.request("DELETE", path);
+    }
+}
+// Singleton client instance
+export const plankaClient = new PlankaClient();
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Typed error classes for PLANKA API operations.
+ */
+export declare class PlankaError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, status: number, details?: unknown | undefined);
+}
+export declare class PlankaAuthError extends PlankaError {
+    constructor(message?: string);
+}
+export declare class PlankaNotFoundError extends PlankaError {
+    constructor(resource: string, id: string);
+}
+export declare class PlankaValidationError extends PlankaError {
+    constructor(message: string, details?: unknown);
+}
+export declare class PlankaPermissionError extends PlankaError {
+    constructor(message?: string);
+}
+export declare class PlankaConfigError extends PlankaError {
+    constructor(message: string);
+}
+export declare class PlankaNetworkError extends PlankaError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Factory function to create typed errors from API responses.
+ * @param status HTTP status code
+ * @param body Response body (parsed JSON or null)
+ * @param context Optional context (e.g., "GET /api/cards/123")
+ */
+export declare function createPlankaError(status: number, body: unknown, context?: string): PlankaError;
+/**
+ * Type guard for PlankaError instances.
+ */
+export declare function isPlankaError(error: unknown): error is PlankaError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,WAAY,SAAQ,KAAK;aAGlB,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;aACd,OAAO,CAAC,EAAE,OAAO;gBAHjC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,SAA0B;CAI9C;AAED,qBAAa,mBAAoB,SAAQ,WAAW;gBACtC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM;CAIzC;AAED,qBAAa,qBAAsB,SAAQ,WAAW;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED,qBAAa,qBAAsB,SAAQ,WAAW;gBACxC,OAAO,SAA6B;CAIjD;AAED,qBAAa,iBAAkB,SAAQ,WAAW;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,MAAM,GACf,WAAW,CAoBb;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE"}

package/dist/errors.js

@@ -0,0 +1,82 @@
+/**
+ * Typed error classes for PLANKA API operations.
+ */
+export class PlankaError extends Error {
+    code;
+    status;
+    details;
+    constructor(message, code, status, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = "PlankaError";
+    }
+}
+export class PlankaAuthError extends PlankaError {
+    constructor(message = "Authentication failed") {
+        super(message, "AUTH_FAILED", 401);
+        this.name = "PlankaAuthError";
+    }
+}
+export class PlankaNotFoundError extends PlankaError {
+    constructor(resource, id) {
+        super(`${resource} not found: ${id}`, "NOT_FOUND", 404);
+        this.name = "PlankaNotFoundError";
+    }
+}
+export class PlankaValidationError extends PlankaError {
+    constructor(message, details) {
+        super(message, "VALIDATION_ERROR", 422, details);
+        this.name = "PlankaValidationError";
+    }
+}
+export class PlankaPermissionError extends PlankaError {
+    constructor(message = "Insufficient permissions") {
+        super(message, "PERMISSION_DENIED", 403);
+        this.name = "PlankaPermissionError";
+    }
+}
+export class PlankaConfigError extends PlankaError {
+    constructor(message) {
+        super(message, "CONFIG_ERROR", 0);
+        this.name = "PlankaConfigError";
+    }
+}
+export class PlankaNetworkError extends PlankaError {
+    constructor(message, details) {
+        super(message, "NETWORK_ERROR", 0, details);
+        this.name = "PlankaNetworkError";
+    }
+}
+/**
+ * Factory function to create typed errors from API responses.
+ * @param status HTTP status code
+ * @param body Response body (parsed JSON or null)
+ * @param context Optional context (e.g., "GET /api/cards/123")
+ */
+export function createPlankaError(status, body, context) {
+    const message = typeof body === "object" && body !== null && "message" in body
+        ? String(body.message)
+        : "Unknown error";
+    const contextSuffix = context ? ` (${context})` : "";
+    switch (status) {
+        case 401:
+            return new PlankaAuthError(message + contextSuffix);
+        case 403:
+            return new PlankaPermissionError(message + contextSuffix);
+        case 404:
+            return new PlankaNotFoundError("Resource", context || "unknown");
+        case 422:
+            return new PlankaValidationError(message + contextSuffix, body);
+        default:
+            return new PlankaError(message + contextSuffix, "API_ERROR", status, body);
+    }
+}
+/**
+ * Type guard for PlankaError instances.
+ */
+export function isPlankaError(error) {
+    return error instanceof PlankaError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}