Sunsama MCP Server

Instructions

Implementation Reference

• src/tools/task-tools.ts:290-323 (handler)

  The core handler implementation for the 'update-task-notes' tool. Handles input validation (via schema), constructs notes content from HTML or Markdown, calls the Sunsama client API to update notes, and returns a formatted JSON response.

  export const updateTaskNotesTool = withTransportClient({
    name: "update-task-notes",
    description: "Update the notes content for a task",
    parameters: updateTaskNotesSchema,
    execute: async (
      { taskId, html, markdown, limitResponsePayload }: UpdateTaskNotesInput,
      context: ToolContext,
    ) => {
      const content = html
        ? { type: "html" as const, value: html }
        : { type: "markdown" as const, value: markdown! };
  
      const options: { limitResponsePayload?: boolean } = {};
      if (limitResponsePayload !== undefined) {
        options.limitResponsePayload = limitResponsePayload;
      }
  
      const apiContent = content.type === "html"
        ? { html: content.value }
        : { markdown: content.value };
      const result = await context.client.updateTaskNotes(
        taskId,
        apiContent,
        options,
      );
  
      return formatJsonResponse({
        success: result.success,
        taskId,
        notesUpdated: true,
        updatedFields: result.updatedFields,
      });
    },
  });

• src/schemas.ts:204-228 (schema)

  Zod schema for input validation of the update-task-notes tool, ensuring taskId is provided and exactly one of html or markdown is specified.

  export const updateTaskNotesSchema = z.object({
    taskId: z.string().min(1, "Task ID is required").describe(
      "The ID of the task to update notes for",
    ),
    html: z.string().optional().describe(
      "HTML content for the task notes (mutually exclusive with markdown)",
    ),
    markdown: z.string().optional().describe(
      "Markdown content for the task notes (mutually exclusive with html)",
    ),
    limitResponsePayload: z.boolean().optional().describe(
      "Whether to limit the response payload size (defaults to true)",
    ),
  }).refine(
    (data) => {
      // Exactly one of html or markdown must be provided
      const hasHtml = data.html !== undefined;
      const hasMarkdown = data.markdown !== undefined;
      return hasHtml !== hasMarkdown; // XOR: exactly one must be true
    },
    {
      message: "Exactly one of 'html' or 'markdown' must be provided",
      path: [], // This will show the error at the root level
    },
  );

• src/tools/index.ts:1-9 (registration)

  Top-level registration exporting allTools array which spreads taskTools containing the update-task-notes tool.

  import { userTools } from "./user-tools.js";
  import { taskTools } from "./task-tools.js";
  import { streamTools } from "./stream-tools.js";
  
  export const allTools = [
    ...userTools,
    ...taskTools,
    ...streamTools,
  ];

• src/tools/task-tools.ts:406-426 (registration)

  Registration of updateTaskNotesTool within the taskTools array exported from task-tools.ts.

  export const taskTools = [
    // Query tools
    getTasksBacklogTool,
    getTasksByDayTool,
    getArchivedTasksTool,
    getTaskByIdTool,
  
    // Lifecycle tools
    createTaskTool,
    deleteTaskTool,
  
    // Update tools
    updateTaskCompleteTool,
    updateTaskSnoozeDateTool,
    updateTaskBacklogTool,
    updateTaskPlannedTimeTool,
    updateTaskNotesTool,
    updateTaskDueDateTool,
    updateTaskTextTool,
    updateTaskStreamTool,
  ];