@denisixnpm/planka-mcp 2.2.0

package/dist/tools/core/tools.js

@@ -0,0 +1,535 @@
+import { buildGroupedSchema } from "../types.js";
+/**
+ * Auth tool - authentication operations
+ */
+export const authTool = {
+    name: "auth",
+    description: "Authentication operations for login flows, token management, and terms acceptance.",
+    operations: {
+        login: {
+            method: "POST",
+            path: "/access-tokens",
+            requiresAuth: false,
+            description: "Authenticate with email/username and password",
+        },
+        logout: {
+            method: "DELETE",
+            path: "/access-tokens/me",
+            description: "Logout current user",
+        },
+        acceptTerms: {
+            method: "POST",
+            path: "/access-tokens/accept-terms",
+            requiresAuth: false,
+            description: "Accept terms during authentication flow",
+        },
+        oidcExchange: {
+            method: "POST",
+            path: "/access-tokens/exchange-with-oidc",
+            requiresAuth: false,
+            description: "Exchange OIDC code for access token",
+        },
+        revokePending: {
+            method: "POST",
+            path: "/access-tokens/revoke-pending-token",
+            requiresAuth: false,
+            description: "Revoke pending authentication token",
+        },
+        getTerms: {
+            method: "GET",
+            path: "/terms",
+            requiresAuth: false,
+            description: "Get terms and conditions",
+        },
+    },
+    inputSchema: buildGroupedSchema(["login", "logout", "acceptTerms", "oidcExchange", "revokePending", "getTerms"], {
+        login: "Login with credentials",
+        logout: "Logout current session",
+        acceptTerms: "Accept terms during auth",
+        oidcExchange: "Exchange OIDC code",
+        revokePending: "Revoke pending token",
+        getTerms: "Get terms document",
+    }, {
+        data: {
+            description: "Auth data: { emailOrUsername?: string, password?: string, token?: string, code?: string }",
+            requiredFor: ["login", "acceptTerms", "oidcExchange", "revokePending"],
+        },
+        query: {
+            language: { type: "string", description: "Language code for terms" },
+        },
+    }),
+};
+/**
+ * Projects tool - manages Planka projects
+ */
+export const projectsTool = {
+    name: "projects",
+    description: "Manage Planka projects. Projects are top-level containers for boards.",
+    operations: {
+        list: {
+            method: "GET",
+            path: "/projects",
+            description: "List all projects accessible to the current user",
+        },
+        get: {
+            method: "GET",
+            path: "/projects/{id}",
+            description: "Get detailed project information including boards and memberships",
+        },
+        create: {
+            method: "POST",
+            path: "/projects",
+            description: "Create a new project (you become the project manager)",
+        },
+        update: {
+            method: "PATCH",
+            path: "/projects/{id}",
+            description: "Update project settings",
+        },
+        delete: {
+            method: "DELETE",
+            path: "/projects/{id}",
+            description: "Delete a project and all its data",
+        },
+    },
+    inputSchema: buildGroupedSchema(["list", "get", "create", "update", "delete"], {
+        list: "List all accessible projects",
+        get: "Get project details by ID",
+        create: "Create a new project",
+        update: "Update project settings",
+        delete: "Delete a project",
+    }, {
+        id: {
+            description: "Project ID",
+            requiredFor: ["get", "update", "delete"],
+        },
+        data: {
+            description: "Project data: { name: string, type: 'private'|'shared' (required for create), description?: string, backgroundType?: 'gradient'|'image', backgroundGradient?: string }",
+            requiredFor: ["create", "update"],
+            properties: {
+                name: { type: "string", description: "Project name", required: true },
+                type: { type: "string", enum: ["private", "shared"], description: "Project visibility type", required: true },
+                description: { type: "string", description: "Project description" },
+                backgroundType: { type: "string", enum: ["gradient", "image"], description: "Background type" },
+                backgroundGradient: { type: "string", description: "Background gradient value" },
+            },
+        },
+    }),
+};
+/**
+ * Boards tool - manages boards within projects
+ */
+export const boardsTool = {
+    name: "boards",
+    description: "Manage Planka boards. Boards contain lists and cards for organizing work.",
+    operations: {
+        get: {
+            method: "GET",
+            path: "/boards/{id}",
+            description: "Get board with lists, cards, labels, and memberships",
+        },
+        create: {
+            method: "POST",
+            path: "/projects/{projectId}/boards",
+            description: "Create a new board in a project",
+        },
+        update: {
+            method: "PATCH",
+            path: "/boards/{id}",
+            description: "Update board settings",
+        },
+        delete: {
+            method: "DELETE",
+            path: "/boards/{id}",
+            description: "Delete a board and all its data",
+        },
+    },
+    inputSchema: buildGroupedSchema(["get", "create", "update", "delete"], {
+        get: "Get board details by ID",
+        create: "Create a new board in a project",
+        update: "Update board settings",
+        delete: "Delete a board",
+    }, {
+        id: {
+            description: "Board ID (for get, update, delete) or Project ID (for create, use projectId in data)",
+            requiredFor: ["get", "update", "delete"],
+        },
+        data: {
+            description: "Board data: { name: string, position: number (required for create), projectId?: string (for create), defaultView?: 'kanban'|'grid'|'list' }",
+            requiredFor: ["create", "update"],
+            properties: {
+                name: { type: "string", description: "Board name", required: true },
+                position: { type: "number", description: "Board position (Planka requires this on create)", required: true },
+                projectId: { type: "string", description: "Project ID (for create)" },
+                defaultView: { type: "string", enum: ["kanban", "grid", "list"], description: "Default board view" },
+            },
+        },
+    }),
+};
+/**
+ * Lists tool - manages lists within boards
+ */
+export const listsTool = {
+    name: "lists",
+    description: "Manage Planka lists. Lists are columns on a board that contain cards.",
+    operations: {
+        get: {
+            method: "GET",
+            path: "/lists/{id}",
+            description: "Get a list with its cards",
+        },
+        create: {
+            method: "POST",
+            path: "/boards/{boardId}/lists",
+            description: "Create a new list on a board",
+        },
+        update: {
+            method: "PATCH",
+            path: "/lists/{id}",
+            description: "Update list name, position, or type",
+        },
+        delete: {
+            method: "DELETE",
+            path: "/lists/{id}",
+            description: "Delete a list (cards move to trash)",
+        },
+    },
+    inputSchema: buildGroupedSchema(["get", "create", "update", "delete"], {
+        get: "Get list details and cards",
+        create: "Create a new list on a board",
+        update: "Update list settings",
+        delete: "Delete a list",
+    }, {
+        id: {
+            description: "List ID (for get, update, delete) or Board ID (for create, use boardId in data)",
+            requiredFor: ["get", "update", "delete"],
+        },
+        data: {
+            description: "List data: { name: string, type: 'active'|'closed' (required), position: number (required), boardId?: string (for create) }",
+            requiredFor: ["create", "update"],
+            properties: {
+                name: { type: "string", description: "List name", required: true },
+                type: { type: "string", enum: ["active", "closed"], description: "List type", required: true },
+                position: { type: "number", description: "List position", required: true },
+                boardId: { type: "string", description: "Board ID (for create)" },
+            },
+        },
+    }),
+};
+/**
+ * Cards tool - manages cards within lists
+ */
+export const cardsTool = {
+    name: "cards",
+    description: "Manage Planka cards. Cards are individual work items on a board.",
+    operations: {
+        list: {
+            method: "GET",
+            path: "/lists/{listId}/cards",
+            description: "Get cards from a list with filtering, search, and pagination",
+        },
+        get: {
+            method: "GET",
+            path: "/cards/{id}",
+            description: "Get card with task lists, attachments, and custom fields",
+        },
+        create: {
+            method: "POST",
+            path: "/lists/{listId}/cards",
+            description: "Create a new card in a list",
+        },
+        update: {
+            method: "PATCH",
+            path: "/cards/{id}",
+            description: "Update card properties (can move between lists)",
+        },
+        delete: {
+            method: "DELETE",
+            path: "/cards/{id}",
+            description: "Delete a card permanently",
+        },
+    },
+    inputSchema: buildGroupedSchema(["list", "get", "create", "update", "delete"], {
+        list: "Get cards from a list (requires listId)",
+        get: "Get card details by ID",
+        create: "Create a new card",
+        update: "Update card properties",
+        delete: "Delete a card",
+    }, {
+        id: {
+            description: "Card ID (for get, update, delete) or List ID (for list, create)",
+            requiredFor: ["list", "get", "update", "delete"],
+        },
+        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"],
+            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 },
+                listId: { type: "string", description: "List ID (for create/move)" },
+                description: { type: "string", description: "Card description" },
+                dueDate: { type: "string", description: "Due date (ISO 8601)" },
+                isDueCompleted: { type: "boolean", description: "Whether the due date is completed" },
+            },
+        },
+        query: {
+            search: { type: "string", description: "Search term to filter cards" },
+            userIds: { type: "string", description: "Comma-separated user IDs to filter by" },
+            labelIds: { type: "string", description: "Comma-separated label IDs to filter by" },
+        },
+    }),
+};
+/**
+ * Comments tool - manages comments on cards
+ */
+export const commentsTool = {
+    name: "comments",
+    description: "Manage comments on Planka cards.",
+    operations: {
+        list: {
+            method: "GET",
+            path: "/cards/{cardId}/comments",
+            description: "Get comments for a card with pagination",
+        },
+        create: {
+            method: "POST",
+            path: "/cards/{cardId}/comments",
+            description: "Add a comment to a card",
+        },
+    },
+    inputSchema: buildGroupedSchema(["list", "create"], {
+        list: "Get comments for a card",
+        create: "Add a comment to a card",
+    }, {
+        id: {
+            description: "Card ID to get/add comments",
+            requiredFor: ["list", "create"],
+        },
+        data: {
+            description: "Comment data: { text: string }",
+            requiredFor: ["create"],
+            properties: {
+                text: { type: "string", description: "Comment text", required: true },
+            },
+        },
+        query: {
+            beforeId: { type: "string", description: "Get comments before this ID (pagination)" },
+        },
+    }),
+};
+/**
+ * Tasks tool - manages task lists and tasks on cards
+ */
+export const tasksTool = {
+    name: "tasks",
+    description: "Manage task lists and tasks on Planka cards. Tasks are checklist items within a card.",
+    operations: {
+        getList: {
+            method: "GET",
+            path: "/task-lists/{id}",
+            description: "Get a task list with all its tasks",
+        },
+        createList: {
+            method: "POST",
+            path: "/cards/{cardId}/task-lists",
+            description: "Create a new task list on a card",
+        },
+        create: {
+            method: "POST",
+            path: "/task-lists/{taskListId}/tasks",
+            description: "Create a new task in a task list",
+        },
+        update: {
+            method: "PATCH",
+            path: "/tasks/{id}",
+            description: "Update task (name, completion status, assignee)",
+        },
+    },
+    inputSchema: buildGroupedSchema(["getList", "createList", "create", "update"], {
+        getList: "Get a task list by ID",
+        createList: "Create a task list on a card",
+        create: "Create a task in a task list",
+        update: "Update a task",
+    }, {
+        id: {
+            description: "Task List ID (for getList), Card ID (for createList), Task List ID (for create, use taskListId in data), or Task ID (for update)",
+            requiredFor: ["getList", "createList", "create", "update"],
+        },
+        data: {
+            description: "Data: { name: string, position: number (required for createList/create), cardId?: string (for createList), taskListId?: string (for create), isCompleted?: boolean (for update), assigneeUserId?: string }",
+            requiredFor: ["createList", "create", "update"],
+            properties: {
+                name: { type: "string", description: "Task list/task name", required: true },
+                position: { type: "number", description: "Position (required for createList and create)", required: true },
+                cardId: { type: "string", description: "Card ID (for createList)" },
+                taskListId: { type: "string", description: "Task list ID (for create)" },
+                isCompleted: { type: "boolean", description: "Task completion status (for update)" },
+                assigneeUserId: { type: "string", description: "Assigned user ID" },
+            },
+        },
+    }),
+};
+/**
+ * Labels tool - manages labels on boards and cards
+ */
+export const labelsTool = {
+    name: "labels",
+    description: "Manage labels on Planka boards and cards. Labels help categorize and filter cards.",
+    operations: {
+        create: {
+            method: "POST",
+            path: "/boards/{boardId}/labels",
+            description: "Create a new label on a board",
+        },
+        update: {
+            method: "PATCH",
+            path: "/labels/{id}",
+            description: "Update a label",
+        },
+        delete: {
+            method: "DELETE",
+            path: "/labels/{id}",
+            description: "Delete a label",
+        },
+        addToCard: {
+            method: "POST",
+            path: "/cards/{cardId}/card-labels",
+            description: "Add a label to a card",
+        },
+        removeFromCard: {
+            method: "DELETE",
+            path: "/cards/{cardId}/card-labels/labelId:{labelId}",
+            description: "Remove a label from a card",
+        },
+    },
+    inputSchema: buildGroupedSchema(["create", "update", "delete", "addToCard", "removeFromCard"], {
+        create: "Create a label on a board",
+        update: "Update a label's name, color, or position",
+        delete: "Delete a label from a board",
+        addToCard: "Add a label to a card",
+        removeFromCard: "Remove a label from a card",
+    }, {
+        id: {
+            description: "Board ID (for create), Label ID (for update, delete), or Card ID (for addToCard, removeFromCard)",
+            requiredFor: ["create", "update", "delete", "addToCard", "removeFromCard"],
+        },
+        data: {
+            description: "Label data: { name?: string, color: string (required), position: number (required) } for create/update, { labelId: string } for addToCard/removeFromCard. Colors: muddy-grey, autumn-leafs, morning-sky, antique-blue, egg-yellow, desert-sand, dark-granite, fresh-salad, lagoon-blue, midnight-blue, light-orange, pumpkin-orange, light-concrete, sunny-grass, navy-blue, lilac-eyes, apricot-red, orange-peel, silver-glint, bright-moss, deep-ocean, summer-sky, berry-red, light-cocoa, grey-stone, tank-green, coral-green, sugar-plum, pink-tulip, shady-rust, wet-rock, wet-moss, turquoise-sea, lavender-fields, piggy-red, light-mud, gun-metal, modern-green, french-coast, sweet-lilac, red-burgundy, pirate-gold",
+            requiredFor: ["create", "update", "addToCard", "removeFromCard"],
+            properties: {
+                name: { type: "string", description: "Label name" },
+                color: { type: "string", description: "Label color (one of the listed colors)", required: true },
+                position: { type: "number", description: "Label position", required: true },
+                labelId: { type: "string", description: "Label ID (for addToCard/removeFromCard)" },
+            },
+        },
+    }),
+};
+/**
+ * Card Members tool - manages card memberships
+ */
+export const cardMembersTool = {
+    name: "cardMembers",
+    description: "Manage user assignments on Planka cards.",
+    operations: {
+        add: {
+            method: "POST",
+            path: "/cards/{cardId}/card-memberships",
+            description: "Assign a user to a card",
+        },
+        remove: {
+            method: "DELETE",
+            path: "/cards/{cardId}/card-memberships/userId:{userId}",
+            description: "Remove a user from a card",
+        },
+    },
+    inputSchema: buildGroupedSchema(["add", "remove"], {
+        add: "Assign a user to a card",
+        remove: "Remove a user from a card",
+    }, {
+        id: {
+            description: "Card ID",
+            requiredFor: ["add", "remove"],
+        },
+        data: {
+            description: "Membership data: { userId: string }",
+            requiredFor: ["add", "remove"],
+            properties: {
+                userId: { type: "string", description: "User ID to assign/remove", required: true },
+            },
+        },
+    }),
+};
+/**
+ * Bootstrap tool - retrieves application initialization data
+ */
+export const bootstrapTool = {
+    name: "bootstrap",
+    description: "Get Planka application bootstrap data including current user, projects, boards, and notifications.",
+    operations: {
+        get: {
+            method: "GET",
+            path: "/bootstrap",
+            description: "Get application bootstrap data",
+        },
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["get"],
+                description: "Action: 'get' - Retrieve bootstrap data",
+            },
+        },
+        required: ["action"],
+    },
+};
+/**
+ * Context tool - selects the working scope (project/board/list/card) so
+ * scoped tools default to it instead of repeating ids on every call.
+ */
+export const contextTool = {
+    name: "context",
+    description: "Select the project/board/list/card to work inside. Once set, other tools " +
+        "use the scoped ids as defaults when their id/data arguments are omitted, " +
+        "so a session can stay inside one board without repeating ids. " +
+        "Setting a higher level clears the deeper ones (a new board resets the list).",
+    operations: {
+        set: {
+            method: "POST",
+            path: "/context/set",
+            requiresAuth: false,
+            description: "Set the working scope; returns the scope plus an overview of its contents",
+        },
+        get: {
+            method: "GET",
+            path: "/context/get",
+            requiresAuth: false,
+            description: "Read the current working scope",
+        },
+        clear: {
+            method: "POST",
+            path: "/context/clear",
+            requiresAuth: false,
+            description: "Reset the working scope",
+        },
+    },
+    inputSchema: buildGroupedSchema(["set", "get", "clear"], {
+        set: "Set the scope (any subset of projectId, boardId, listId, cardId)",
+        get: "Read the current scope",
+        clear: "Reset the scope",
+    }, {
+        data: {
+            description: "Scope fields to set: { projectId?, boardId?, listId?, cardId? }",
+            requiredFor: ["set"],
+            properties: {
+                projectId: { type: "string", description: "Project to work inside" },
+                boardId: { type: "string", description: "Board to work inside (within the project)" },
+                listId: { type: "string", description: "List to create cards in" },
+                cardId: { type: "string", description: "Card to operate on (comments, tasks)" },
+            },
+        },
+    }),
+};

package/dist/tools/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Planka MCP Server - Grouped Tool Definitions
+ *
+ * This module exports all tool definitions organized by category:
+ * - Core: Essential Kanban operations (always enabled) - 10 tools
+ * - Admin: Administrative functions requiring admin privileges - 4 tools
+ * - Optional: Extended functionality for advanced use cases - 13 tools
+ *
+ * Total: 27 grouped tools covering 104 API operations
+ */
+export type { GroupedToolDefinition, ToolOperation } from "./types.js";
+export { buildGroupedSchema } from "./types.js";
+export { coreTools } from "./core/index.js";
+export { adminTools } from "./admin/index.js";
+export { optionalTools } from "./optional/index.js";
+import { GroupedToolDefinition } from "./types.js";
+/**
+ * All tools combined (for reference/documentation)
+ */
+export declare const allTools: GroupedToolDefinition[];
+/**
+ * Configuration for tool categories
+ */
+export interface ToolConfig {
+    enableAllTools?: boolean;
+    enableAdminTools?: boolean;
+    enableOptionalTools?: boolean;
+}
+/**
+ * Gets enabled tools based on configuration
+ */
+export declare function getEnabledTools(config: ToolConfig): GroupedToolDefinition[];
+/**
+ * Tool counts by category
+ */
+export declare const toolCounts: {
+    core: number;
+    coreOperations: number;
+    admin: number;
+    adminOperations: number;
+    optional: number;
+    optionalOperations: number;
+    total: number;
+    totalOperations: number;
+};

package/dist/tools/index.js

@@ -0,0 +1,61 @@
+/**
+ * Planka MCP Server - Grouped Tool Definitions
+ *
+ * This module exports all tool definitions organized by category:
+ * - Core: Essential Kanban operations (always enabled) - 10 tools
+ * - Admin: Administrative functions requiring admin privileges - 4 tools
+ * - Optional: Extended functionality for advanced use cases - 13 tools
+ *
+ * Total: 27 grouped tools covering 104 API operations
+ */
+export { buildGroupedSchema } from "./types.js";
+export { coreTools } from "./core/index.js";
+export { adminTools } from "./admin/index.js";
+export { optionalTools } from "./optional/index.js";
+import { coreTools } from "./core/index.js";
+import { adminTools } from "./admin/index.js";
+import { optionalTools } from "./optional/index.js";
+/**
+ * All tools combined (for reference/documentation)
+ */
+export const allTools = [
+    ...coreTools,
+    ...adminTools,
+    ...optionalTools,
+];
+/**
+ * Gets enabled tools based on configuration
+ */
+export function getEnabledTools(config) {
+    const { enableAllTools, enableAdminTools, enableOptionalTools } = config;
+    if (enableAllTools) {
+        return allTools;
+    }
+    const tools = [...coreTools];
+    if (enableAdminTools) {
+        tools.push(...adminTools);
+    }
+    if (enableOptionalTools) {
+        tools.push(...optionalTools);
+    }
+    return tools;
+}
+/**
+ * Count operations in a tool
+ */
+function countOperations(tools) {
+    return tools.reduce((sum, tool) => sum + Object.keys(tool.operations).length, 0);
+}
+/**
+ * Tool counts by category
+ */
+export const toolCounts = {
+    core: coreTools.length,
+    coreOperations: countOperations(coreTools),
+    admin: adminTools.length,
+    adminOperations: countOperations(adminTools),
+    optional: optionalTools.length,
+    optionalOperations: countOperations(optionalTools),
+    total: allTools.length,
+    totalOperations: countOperations(allTools),
+};

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

@@ -0,0 +1,10 @@
+/**
+ * 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, };
+/**
+ * All optional tools combined
+ */
+export declare const optionalTools: GroupedToolDefinition[];

package/dist/tools/optional/index.js

@@ -0,0 +1,20 @@
+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, };
+/**
+ * All optional tools combined
+ */
+export const optionalTools = [
+    actionsTool,
+    attachmentsTool,
+    boardMembersTool,
+    customFieldsTool,
+    notificationsTool,
+    backgroundImagesTool,
+    cardExtrasTool,
+    commentExtrasTool,
+    listExtrasTool,
+    taskExtrasTool,
+    labelExtrasTool,
+    cardMemberExtrasTool,
+    userInfoTool,
+];