Sunsama MCP Server

Instructions

Implementation Reference

• src/tools/task-tools.ts:43-53 (handler)

  Defines the main handler for the 'get-tasks-backlog' tool using withTransportClient wrapper. Fetches tasks from the client's backlog method, trims them, and formats as TSV response.
  export const getTasksBacklogTool = withTransportClient({ name: "get-tasks-backlog", description: "Get tasks from the backlog", parameters: getTasksBacklogSchema, execute: async (_args: GetTasksBacklogInput, context: ToolContext) => { const tasks = await context.client.getTasksBacklog(); const trimmedTasks = trimTasksForResponse(tasks); return formatTsvResponse(trimmedTasks); }, });
• src/schemas.ts:29-30 (schema)

  Defines the Zod input schema for the tool, which accepts no parameters (empty object).
  export const getTasksBacklogSchema = z.object({});
• src/main.ts:32-44 (registration)

  Registers all tools, including 'get-tasks-backlog', with the MCP server by iterating over allTools and calling server.registerTool for each.
  // Register all tools allTools.forEach((tool) => { server.registerTool( tool.name, { description: tool.description, inputSchema: "shape" in tool.parameters ? tool.parameters.shape : tool.parameters, }, tool.execute, ); });
• src/tools/index.ts:5-9 (registration)

  Assembles allTools array by combining userTools, taskTools (which includes getTasksBacklogTool), and streamTools for registration in main.ts.
  export const allTools = [ ...userTools, ...taskTools, ...streamTools, ];
• src/tools/task-tools.ts:53-406 (helper)

  Includes getTasksBacklogTool in the taskTools array, which is then spread into allTools for server registration.
  }); export const getTasksByDayTool = withTransportClient({ name: "get-tasks-by-day", description: "Get tasks for a specific day with optional filtering by completion status", parameters: getTasksByDaySchema, execute: async ( { day, timezone, completionFilter = "all" }: GetTasksByDayInput, context: ToolContext, ) => { // If no timezone provided, get the user's default timezone let resolvedTimezone = timezone; if (!resolvedTimezone) { resolvedTimezone = await context.client.getUserTimezone(); } const tasks = await context.client.getTasksByDay(day, resolvedTimezone); const filteredTasks = filterTasksByCompletion(tasks, completionFilter); const trimmedTasks = trimTasksForResponse(filteredTasks); return formatTsvResponse(trimmedTasks); }, }); export const getArchivedTasksTool = withTransportClient({ name: "get-archived-tasks", description: "Get archived tasks with optional pagination", parameters: getArchivedTasksSchema, execute: async ( { offset = 0, limit = 100 }: GetArchivedTasksInput, context: ToolContext, ) => { const requestedLimit = limit; const fetchLimit = requestedLimit + 1; const allTasks = await context.client.getArchivedTasks(offset, fetchLimit); const hasMore = allTasks.length > requestedLimit; const tasks = hasMore ? allTasks.slice(0, requestedLimit) : allTasks; const trimmedTasks = trimTasksForResponse(tasks); const paginationInfo = { offset, limit: requestedLimit, count: tasks.length, hasMore, nextOffset: hasMore ? offset + requestedLimit : null, }; return formatPaginatedTsvResponse(trimmedTasks, paginationInfo); }, }); export const getTaskByIdTool = withTransportClient({ name: "get-task-by-id", description: "Get a specific task by its ID", parameters: getTaskByIdSchema, execute: async ({ taskId }: GetTaskByIdInput, context: ToolContext) => { const task = await context.client.getTaskById(taskId) || null; return formatJsonResponse(task); }, }); // Task Lifecycle Tools export const createTaskTool = withTransportClient({ name: "create-task", description: "Create a new task with optional properties", parameters: createTaskSchema, execute: async ( { text, notes, streamIds, timeEstimate, dueDate, snoozeUntil, private: isPrivate, taskId, integration, }: CreateTaskInput, context: ToolContext, ) => { const options: CreateTaskOptions = {}; if (notes) options.notes = notes; if (streamIds) options.streamIds = streamIds; if (timeEstimate) options.timeEstimate = timeEstimate; if (dueDate) options.dueDate = dueDate; if (snoozeUntil) options.snoozeUntil = snoozeUntil; if (isPrivate !== undefined) options.private = isPrivate; if (taskId) options.taskId = taskId; if (integration) options.integration = integration; const result = await context.client.createTask(text, options); return formatJsonResponse({ success: result.success, taskId: result.updatedFields?._id, title: text, created: true, updatedFields: result.updatedFields, }); }, }); export const deleteTaskTool = withTransportClient({ name: "delete-task", description: "Delete a task permanently", parameters: deleteTaskSchema, execute: async ( { taskId, limitResponsePayload, wasTaskMerged }: DeleteTaskInput, context: ToolContext, ) => { const result = await context.client.deleteTask( taskId, limitResponsePayload, wasTaskMerged, ); return formatJsonResponse({ success: result.success, taskId, deleted: true, updatedFields: result.updatedFields, }); }, }); // Task Update Tools export const updateTaskCompleteTool = withTransportClient({ name: "update-task-complete", description: "Mark a task as complete with optional completion timestamp", parameters: updateTaskCompleteSchema, execute: async ( { taskId, completeOn, limitResponsePayload }: UpdateTaskCompleteInput, context: ToolContext, ) => { const result = await context.client.updateTaskComplete( taskId, completeOn, limitResponsePayload, ); return formatJsonResponse({ success: result.success, taskId, completed: true, updatedFields: result.updatedFields, }); }, }); export const updateTaskSnoozeDateTool = withTransportClient({ name: "update-task-snooze-date", description: "Update task snooze date to reschedule tasks or move them to backlog", parameters: updateTaskSnoozeDateSchema, execute: async ( { taskId, newDay, timezone, limitResponsePayload }: UpdateTaskSnoozeDateInput, context: ToolContext, ) => { const options: { timezone?: string; limitResponsePayload?: boolean } = {}; if (timezone) options.timezone = timezone; if (limitResponsePayload !== undefined) { options.limitResponsePayload = limitResponsePayload; } const result = await context.client.updateTaskSnoozeDate( taskId, newDay, options, ); return formatJsonResponse({ success: result.success, taskId, newDay, updatedFields: result.updatedFields, }); }, }); export const updateTaskBacklogTool = withTransportClient({ name: "update-task-backlog", description: "Move a task to the backlog", parameters: updateTaskBacklogSchema, execute: async ( { taskId, timezone, limitResponsePayload }: UpdateTaskBacklogInput, context: ToolContext, ) => { const options: { timezone?: string; limitResponsePayload?: boolean } = {}; if (timezone) options.timezone = timezone; if (limitResponsePayload !== undefined) { options.limitResponsePayload = limitResponsePayload; } const result = await context.client.updateTaskSnoozeDate( taskId, null, options, ); return formatJsonResponse({ success: result.success, taskId, movedToBacklog: true, updatedFields: result.updatedFields, }); }, }); export const updateTaskPlannedTimeTool = withTransportClient({ name: "update-task-planned-time", description: "Update the planned time (time estimate) for a task", parameters: updateTaskPlannedTimeSchema, execute: async ( { taskId, timeEstimateMinutes, limitResponsePayload }: UpdateTaskPlannedTimeInput, context: ToolContext, ) => { const result = await context.client.updateTaskPlannedTime( taskId, timeEstimateMinutes, limitResponsePayload, ); return formatJsonResponse({ success: result.success, taskId, timeEstimateMinutes, updatedFields: result.updatedFields, }); }, }); 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, }); }, }); export const updateTaskDueDateTool = withTransportClient({ name: "update-task-due-date", description: "Update the due date for a task", parameters: updateTaskDueDateSchema, execute: async ( { taskId, dueDate, limitResponsePayload }: UpdateTaskDueDateInput, context: ToolContext, ) => { const result = await context.client.updateTaskDueDate( taskId, dueDate, limitResponsePayload, ); return formatJsonResponse({ success: result.success, taskId, dueDate, dueDateUpdated: true, updatedFields: result.updatedFields, }); }, }); export const updateTaskTextTool = withTransportClient({ name: "update-task-text", description: "Update the text/title of a task", parameters: updateTaskTextSchema, execute: async ( { taskId, text, recommendedStreamId, limitResponsePayload }: UpdateTaskTextInput, context: ToolContext, ) => { const options: { recommendedStreamId?: string | null; limitResponsePayload?: boolean; } = {}; if (recommendedStreamId !== undefined) { options.recommendedStreamId = recommendedStreamId; } if (limitResponsePayload !== undefined) { options.limitResponsePayload = limitResponsePayload; } const result = await context.client.updateTaskText(taskId, text, options); return formatJsonResponse({ success: result.success, taskId, text, textUpdated: true, updatedFields: result.updatedFields, }); }, }); export const updateTaskStreamTool = withTransportClient({ name: "update-task-stream", description: "Update the stream/channel assignment for a task", parameters: updateTaskStreamSchema, execute: async ( { taskId, streamId, limitResponsePayload }: UpdateTaskStreamInput, context: ToolContext, ) => { const result = await context.client.updateTaskStream( taskId, streamId, limitResponsePayload !== undefined ? limitResponsePayload : true, ); return formatJsonResponse({ success: result.success, taskId, streamId, streamUpdated: true, updatedFields: result.updatedFields, }); }, }); // Export all task tools export const taskTools = [