create_task

Instructions

Implementation Reference

• src/tools/tasks.ts:154-180 (handler)

  The MCP server.tool registration for 'create_task' — contains the Zod schema (input validation) and the async handler that resolves IDs, calls SpClient.createTask, and returns the result.

  // ── Create task ─────────────────────────────────────────────────────────
  server.tool(
    "create_task",
    "Creates a new task in Super Productivity. Extra fields are passed through to the local API if supported by your app version.",
    {
      title: nonEmptyString.describe("Task title"),
      notes: z.string().optional().describe("Additional notes / description"),
      projectId: nonEmptyString.optional().describe("Project ID to assign the task to"),
      projectName: nonEmptyString.optional().describe("Project name to assign the task to"),
      tagIds: z.array(nonEmptyString).optional().describe("List of tag IDs"),
      tagNames: z.array(nonEmptyString).optional().describe("List of tag names"),
      timeEstimateMins: z.number().optional().describe("Estimated duration in minutes"),
      dueDateISO: nonEmptyString.optional().describe("Due date in ISO 8601 format (e.g. 2026-04-23)"),
    },
    async ({ title, notes, projectId, projectName, tagIds, tagNames, timeEstimateMins, dueDateISO }) => {
      const resolved = await resolveTaskWriteIds({ projectId, projectName, tagIds, tagNames });
      const task = await SpClient.createTask({
        title,
        notes,
        projectId: resolved.projectId,
        tagIds: resolved.tagIds,
        timeEstimate: timeEstimateMins ? timeEstimateMins * 60_000 : undefined,
        dueDate: parseIsoDateToTimestamp(dueDateISO),
      });
      return ok(task);
    }
  );

• src/sp-client.ts:162-169 (schema)

  The CreateTaskPayload interface that defines the shape of the payload sent to the Super Productivity API (the backend HTTP call).

  export interface CreateTaskPayload {
    title: string;
    notes?: string;
    projectId?: string;
    tagIds?: string[];
    timeEstimate?: number;
    dueDate?: number;
  }

• src/sp-client.ts:224-229 (helper)

  The SpClient.createTask method — the actual HTTP POST request to /tasks that creates the task via the REST API.

  createTask(payload: CreateTaskPayload): Promise<Task> {
    return request("/tasks", TaskSchema, {
      method: "POST",
      body: JSON.stringify(payload),
    });
  },

• src/tool-helpers.ts:79-90 (helper)

  The parseIsoDateToTimestamp helper used by the create_task handler to convert dueDateISO to a millisecond timestamp.

  export function parseIsoDateToTimestamp(dateString?: string): number | undefined {
    if (!dateString) {
      return undefined;
    }
  
    const timestamp = Date.parse(dateString);
    if (Number.isNaN(timestamp)) {
      throw new Error(`Invalid dueDateISO "${dateString}". Use a valid ISO date like 2026-04-23 or 2026-04-23T09:00:00Z.`);
    }
  
    return timestamp;
  }

• src/index.ts:5-17 (registration)

  The top-level entry point where registerTaskTools is called, which includes the 'create_task' tool registration.

  import { registerTaskTools } from "./tools/tasks.js";
  import { registerProjectTools } from "./tools/projects.js";
  import { registerResources } from "./resources.js";
  import { registerPrompts } from "./prompts.js";
  
  const server = new McpServer({
    name: "super-productivity-mcp",
    version: "1.0.0",
  });
  
  // Register everything
  registerTaskTools(server);
  registerProjectTools(server);