list_tasks

Instructions

Implementation Reference

• src/tools/tasks.ts:26-37 (handler)

  The handler function for list_tasks. Makes a GET request to Capsule's /tasks endpoint with optional filters (status, ownerId, page, perPage) and returns paginated results.

  export async function listTasks(input: z.infer<typeof listTasksSchema>) {
    const { data, nextPage } = await capsuleGet<{ tasks: unknown[] }>("/tasks", {
      // Default 'OPEN' applied here (not via zod .default()) so that
      // z.infer keeps `status` optional for callers that omit it.
      status: input.status ?? "OPEN",
      // Capsule's owner filter is the bare query param `owner`, not `ownerId`/`assignedToUserId`.
      owner: input.ownerId,
      page: input.page,
      perPage: input.perPage,
    });
    return { ...data, nextPage };
  }

• src/tools/tasks.ts:8-24 (schema)

  Zod schema for list_tasks input. Defines optional status (OPEN/COMPLETED), ownerId, page, and perPage parameters.

  export const listTasksSchema = z.object({
    // Note: Capsule has a third internal status `PENDING` (a task that's
    // part of an active track but not yet "open"), but it can only be
    // reached via track machinery — it is NOT directly settable by
    // /tasks PUT, and a list filter for it returns the same as OPEN
    // anyway. We expose only the two values that are actually filterable
    // by the v2 API.
    status: z
      .enum(["OPEN", "COMPLETED"])
      .optional()
      .describe(
        "Defaults to OPEN when omitted. Pass COMPLETED to filter to completed tasks, or 'OPEN' explicitly.",
      ),
    ownerId: z.number().int().positive().optional().describe("Filter to tasks owned by this user ID"),
    page: z.number().int().positive().optional().default(1),
    perPage: z.number().int().min(1).max(100).optional().default(25),
  });

• src/server.ts:596-602 (registration)

  Registration of the list_tasks tool on the MCP server, wiring schema and handler together with a descriptive string.

  registerTool(
    server,
    "list_tasks",
    "List tasks in Capsule CRM. Defaults to OPEN tasks; pass status to broaden. Optionally filter to a specific owner via ownerId. Capsule does not expose a due-date filter on this endpoint — for that use filter_* tools elsewhere or iterate.",
    listTasksSchema,
    listTasks,
  );

• src/server/register-tool.ts:39-59 (helper)

  Generic tool registration helper that wraps handler return values into MCP text content responses. Used to register list_tasks.

  export function registerTool<Schema extends z.ZodObject<ZodRawShape>>(
    server: McpServer,
    name: string,
    description: string,
    schema: Schema,
    handler: (input: z.infer<Schema>) => Promise<unknown>,
  ): void {
    // Use the SDK config-form registerTool with the full Zod schema. The
    // deprecated shape overload rebuilds z.object(schema.shape), which drops
    // object-level refinements such as superRefine.
    const registerWithSchema = server.registerTool.bind(server) as (
      toolName: string,
      config: { description: string; inputSchema: Schema },
      callback: (input: z.infer<Schema>) => Promise<CallToolResult>,
    ) => void;
  
    registerWithSchema(name, { description, inputSchema: schema }, async (input) => {
      const result = await handler(input);
      return wrapAsText(result);
    });
  }