Planka MCP Server

Instructions

Implementation Reference

• index.ts:735-788 (handler)

  Core execution logic for the mcp_kanban_membership_manager tool. Handles different actions (get_all, create, get_one, update, delete) by calling corresponding functions from boardMemberships module and returns JSON stringified result.

  async (args) => {
    let result;
  
    switch (args.action) {
      case "get_all":
        if (!args.boardId)
          throw new Error("boardId is required for get_all action");
        result = await boardMemberships.getBoardMemberships(args.boardId);
        break;
  
      case "create":
        if (!args.boardId || !args.userId || !args.role)
          throw new Error(
            "boardId, userId, and role are required for create action"
          );
        result = await boardMemberships.createBoardMembership({
          boardId: args.boardId,
          userId: args.userId,
          role: args.role,
        });
        break;
  
      case "get_one":
        if (!args.id) throw new Error("id is required for get_one action");
        result = await boardMemberships.getBoardMembership(args.id);
        break;
  
      case "update":
        if (!args.id) throw new Error("id is required for update action");
        const membershipUpdateOptions = {} as any;
  
        if (args.role !== undefined) membershipUpdateOptions.role = args.role;
        if (args.canComment !== undefined)
          membershipUpdateOptions.canComment = args.canComment;
  
        result = await boardMemberships.updateBoardMembership(
          args.id,
          membershipUpdateOptions
        );
        break;
  
      case "delete":
        if (!args.id) throw new Error("id is required for delete action");
        result = await boardMemberships.deleteBoardMembership(args.id);
        break;
  
      default:
        throw new Error(`Unknown action: ${args.action}`);
    }
  
    return {
      content: [{ type: "text", text: JSON.stringify(result) }],
    };
  }

• index.ts:719-734 (schema)

  Input schema validation using Zod for the tool parameters including action, ids, role, and permissions.

  {
    action: z
      .enum(["get_all", "create", "get_one", "update", "delete"])
      .describe("The action to perform"),
    id: z.string().optional().describe("The ID of the membership"),
    boardId: z.string().optional().describe("The ID of the board"),
    userId: z.string().optional().describe("The ID of the user"),
    role: z
      .enum(["editor", "viewer"])
      .optional()
      .describe("The role of the user in the board"),
    canComment: z
      .boolean()
      .optional()
      .describe("Whether the user can comment on the board"),
  },

• index.ts:716-718 (registration)

  Tool registration call to the MCP server, specifying the tool name and description.

  server.tool(
    "mcp_kanban_membership_manager",
    "Manage board memberships with various operations",

• operations/boardMemberships.ts:115-138 (helper)

  Helper function to create a new board membership via Planka API POST request.

  export async function createBoardMembership(
      options: CreateBoardMembershipOptions,
  ) {
      try {
          const response = await plankaRequest(
              `/api/boards/${options.boardId}/memberships`,
              {
                  method: "POST",
                  body: {
                      userId: options.userId,
                      role: options.role,
                  },
              },
          );
          const parsedResponse = BoardMembershipResponseSchema.parse(response);
          return parsedResponse.item;
      } catch (error) {
          throw new Error(
              `Failed to create board membership: ${
                  error instanceof Error ? error.message : String(error)
              }`,
          );
      }
  }

• operations/boardMemberships.ts:147-176 (helper)

  Helper function to retrieve all board memberships for a given board ID via Planka API.

  export async function getBoardMemberships(boardId: string) {
      try {
          const response = await plankaRequest(
              `/api/boards/${boardId}/memberships`,
          );
  
          try {
              // Try to parse as a BoardMembershipsResponseSchema first
              const parsedResponse = BoardMembershipsResponseSchema.parse(
                  response,
              );
              return parsedResponse.items;
          } catch (parseError) {
              // If that fails, try to parse as an array directly
              if (Array.isArray(response)) {
                  return z.array(BoardMembershipSchema).parse(response);
              }
  
              // If we get here, we couldn't parse the response in any expected format
              throw new Error(
                  `Could not parse board memberships response: ${
                      JSON.stringify(response)
                  }`,
              );
          }
      } catch (error) {
          // If all else fails, return an empty array
          return [];
      }
  }