Planka MCP Server

Instructions

Implementation Reference

• index.ts:386-423 (registration)

  Registers the mcp_kanban_stopwatch tool, defines input schema (action: start/stop/get/reset, id: card ID), and provides dispatcher handler that calls specific stopwatch functions from the cards module.

  server.tool(
    "mcp_kanban_stopwatch",
    "Manage card stopwatches for time tracking",
    {
      action: z
        .enum(["start", "stop", "get", "reset"])
        .describe("The action to perform"),
      id: z.string().describe("The ID of the card"),
    },
    async (args) => {
      let result;
  
      switch (args.action) {
        case "start":
          result = await cards.startCardStopwatch(args.id);
          break;
  
        case "stop":
          result = await cards.stopCardStopwatch(args.id);
          break;
  
        case "get":
          result = await cards.getCardStopwatch(args.id);
          break;
  
        case "reset":
          result = await cards.resetCardStopwatch(args.id);
          break;
  
        default:
          throw new Error(`Unknown action: ${args.action}`);
      }
  
      return {
        content: [{ type: "text", text: JSON.stringify(result) }],
      };
    }
  );

• operations/cards.ts:382-413 (handler)

  Handler for starting the card stopwatch: sets startedAt to current time, preserves existing total, updates card via PATCH /api/cards/{id} with stopwatch object

  export async function startCardStopwatch(id: string) {
      try {
          // Get the current card to check if a stopwatch is already running
          const card = await getCard(id);
  
          // Calculate the stopwatch object
          let stopwatch = {
              startedAt: new Date().toISOString(),
              total: 0,
          };
  
          // If there's an existing stopwatch, preserve the total time
          if (card.stopwatch && card.stopwatch.total) {
              stopwatch.total = card.stopwatch.total;
          }
  
          // Update the card with the new stopwatch
          const response = await plankaRequest(`/api/cards/${id}`, {
              method: "PATCH",
              body: { stopwatch },
          });
  
          const parsedResponse = CardResponseSchema.parse(response);
          return parsedResponse.item;
      } catch (error) {
          throw new Error(
              `Failed to start card stopwatch: ${
                  error instanceof Error ? error.message : String(error)
              }`,
          );
      }
  }

• operations/cards.ts:421-461 (handler)

  Handler for stopping the card stopwatch: calculates elapsed time, adds to total, sets startedAt to null, updates via PATCH

  export async function stopCardStopwatch(id: string) {
      try {
          // Get the current card to calculate elapsed time
          const card = await getCard(id);
  
          // If there's no stopwatch or it's not running, return the card as is
          if (!card.stopwatch || !card.stopwatch.startedAt) {
              return card;
          }
  
          // Calculate elapsed time
          const startedAt = new Date(card.stopwatch.startedAt);
          const now = new Date();
          const elapsedSeconds = Math.floor(
              (now.getTime() - startedAt.getTime()) / 1000,
          );
  
          // Calculate the new total time
          const totalSeconds = (card.stopwatch.total || 0) + elapsedSeconds;
  
          // Update the card with the stopped stopwatch (null startedAt but preserved total)
          const stopwatch = {
              startedAt: null,
              total: totalSeconds,
          };
  
          const response = await plankaRequest(`/api/cards/${id}`, {
              method: "PATCH",
              body: { stopwatch },
          });
  
          const parsedResponse = CardResponseSchema.parse(response);
          return parsedResponse.item;
      } catch (error) {
          throw new Error(
              `Failed to stop card stopwatch: ${
                  error instanceof Error ? error.message : String(error)
              }`,
          );
      }
  }

• operations/cards.ts:469-511 (handler)

  Handler for getting card stopwatch status: returns isRunning, total time, current elapsed if running, formatted durations using internal formatDuration helper

  export async function getCardStopwatch(id: string) {
      try {
          const card = await getCard(id);
  
          // If there's no stopwatch, return default values
          if (!card.stopwatch) {
              return {
                  isRunning: false,
                  total: 0,
                  current: 0,
                  formattedTotal: formatDuration(0),
                  formattedCurrent: formatDuration(0),
              };
          }
  
          // Calculate current elapsed time if stopwatch is running
          let currentElapsed = 0;
          const isRunning = !!card.stopwatch.startedAt;
  
          if (isRunning && card.stopwatch.startedAt) {
              const startedAt = new Date(card.stopwatch.startedAt);
              const now = new Date();
              currentElapsed = Math.floor(
                  (now.getTime() - startedAt.getTime()) / 1000,
              );
          }
  
          return {
              isRunning,
              total: card.stopwatch.total || 0,
              current: currentElapsed,
              startedAt: card.stopwatch.startedAt,
              formattedTotal: formatDuration(card.stopwatch.total || 0),
              formattedCurrent: formatDuration(currentElapsed),
          };
      } catch (error) {
          throw new Error(
              `Failed to get card stopwatch: ${
                  error instanceof Error ? error.message : String(error)
              }`,
          );
      }
  }

• operations/cards.ts:519-536 (handler)

  Handler for resetting the card stopwatch: patches the card with stopwatch: null to clear it

  export async function resetCardStopwatch(id: string) {
      try {
          // Set stopwatch to null to clear it
          const response = await plankaRequest(`/api/cards/${id}`, {
              method: "PATCH",
              body: { stopwatch: null },
          });
  
          const parsedResponse = CardResponseSchema.parse(response);
          return parsedResponse.item;
      } catch (error) {
          throw new Error(
              `Failed to reset card stopwatch: ${
                  error instanceof Error ? error.message : String(error)
              }`,
          );
      }
  }