clokio-mcp 0.16.0 → 0.17.0

package/README.md

@@ -76,7 +76,7 @@ are marked mutating (deletes are `destructive`).
 
 | Area | Tools |
 |------|-------|
-| **Tasks** | list (with `compact` / `sort` / `updated_since`), get (with `comments_limit`), create, update, delete, bulk update, set assignees, list/add/edit comments, list attachments (with `is_latest` + `latest_only`), upload, download one (save to disk, or read PDF text / ZIP entries / images / text inline), download all to a folder, activity, list/add/remove dependencies, set custom field |
+| **Tasks** | list (with `compact` / `sort` / `updated_since` / `recurring`), get (with `comments_limit`), create, update (incl. recurring series: set a rule, pause/resume, stop), delete, bulk update, set assignees, list/add/edit comments, list attachments (with `is_latest` + `latest_only`), upload, download one (save to disk, or read PDF text / ZIP entries / images / text inline), download all to a folder, activity, list/add/remove dependencies, set custom field |
 | **Projects & clients** | list projects, project statuses, project custom fields, project contacts, get client, add client contact |
 | **Reference** | task statuses, task labels, locations, list webhooks (read-only), whoami |
 | **Employees** | list (name search), lookup by PIN, task-stats, inbox (mentions, new assignments, others' status changes), create, set status |
@@ -96,6 +96,15 @@ are marked mutating (deletes are `destructive`).
   Clokio stores. Text that already starts with an HTML tag is passed through untouched.
 - **Status slugs** come from `clokio_list_task_statuses` /
   `clokio_get_project_statuses`.
+- **Recurring tasks are templates.** Pass `recurrence` on create/update
+  (`{frequency, every?, days_of_week?, day_of_month?, anchor?}`) and the task
+  becomes the series template; **moving it to a done status starts the
+  schedule**. A fresh copy (same content, assignees, labels, estimate) is
+  created early on each matching day, due that day, independent of earlier
+  copies. Pause/resume with `recurrence_active`, stop with `recurrence: null`;
+  `recurrence.armed` on a task says whether the series is live, a copy names
+  its template as `recurrence.spawned_from`, and `series_of` on the list tool
+  returns every occurrence of one series.
 - An API key sees **public custom fields only**.
 
 ## Security

package/dist/tools/tasks.js

@@ -7,6 +7,122 @@ import { asAttachmentArray, downloadAttachment, safeAttachmentName, stampIsLates
 const employeeCode = z
     .string()
     .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code must be 1-50 chars of letters, digits, _ or -');
+/**
+ * Recurrence, as a structured object the agent fills, serialized here into
+ * the rule string the Clokio scheduler executes (`daily`, `weekly:sun,wed`,
+ * `monthly:15`, `quarterly:MM-DD`, `custom:N:unit[:detail]`, ...).
+ *
+ * The server model is a TEMPLATE: the task itself is the series. Once the
+ * template sits in a done status (completing it ARMS the series), the
+ * scheduler creates a fresh copy - same title, description, assignees,
+ * labels, priority, estimate - early on each matching day, due that day,
+ * regardless of whether earlier copies were closed. The template stays done
+ * forever; the copies are the actual work items.
+ */
+const recurrenceInput = z.object({
+    frequency: z.enum(['daily', 'weekly', 'monthly', 'quarterly', 'semiannual', 'yearly']),
+    every: z
+        .number()
+        .int()
+        .min(1)
+        .max(999)
+        .optional()
+        .describe('Every N periods (default 1). "Every 2 weeks" = frequency weekly + every 2.'),
+    days_of_week: z
+        .array(z.enum(['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']))
+        .min(1)
+        .optional()
+        .describe('weekly: which weekday(s). REQUIRED for weekly.'),
+    day_of_month: z
+        .number()
+        .int()
+        .min(1)
+        .max(31)
+        .optional()
+        .describe('monthly: which day of the month. REQUIRED for monthly.'),
+    anchor: z
+        .string()
+        .regex(/^\d{2}-\d{2}$/, 'anchor must be MM-DD')
+        .optional()
+        .describe('quarterly / semiannual / yearly: the MM-DD date the cycle starts from. REQUIRED for those.'),
+});
+/** Canonical weekday order for serialized rules - see recurrenceToRule(). */
+const WEEKDAY_ORDER = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+/**
+ * A field that names a day the chosen frequency does not use is REFUSED, not
+ * ignored: {frequency: 'daily', days_of_week: ['mon']} reads like "every
+ * Monday", and silently dropping the days spawns SEVEN copies a week.
+ */
+function refuseIrrelevant(r, allowed) {
+    for (const field of ['days_of_week', 'day_of_month', 'anchor']) {
+        if (r[field] !== undefined && !allowed.includes(field)) {
+            throw new Error(`${field} does not apply to frequency "${r.frequency}" and would be silently ignored - remove it, or pick the frequency it belongs to.`);
+        }
+    }
+}
+/** Serialize the structured object into the scheduler's rule grammar. */
+export function recurrenceToRule(r) {
+    const every = r.every ?? 1;
+    switch (r.frequency) {
+        case 'daily':
+            refuseIrrelevant(r, []);
+            return every === 1 ? 'daily' : `custom:${every}:day`;
+        case 'weekly': {
+            refuseIrrelevant(r, ['days_of_week']);
+            if (!r.days_of_week?.length) {
+                // A day-less weekly is the exact rule shape behind a production
+                // outage - the server refuses it too, but failing here names the fix.
+                throw new Error('weekly recurrence requires days_of_week (e.g. ["sun"]).');
+            }
+            // Canonical: dedupe + fixed weekday order, so the same intent always
+            // stores the same rule string ("did the rule change?" comparisons and
+            // health reports read these back).
+            const unique = [...new Set(r.days_of_week)];
+            const days = WEEKDAY_ORDER.filter((d) => unique.includes(d)).join(',');
+            if (every > 1 && unique.length > 1) {
+                // The scheduler's custom:N:week rule spawns ONE occurrence per cycle
+                // (the day list only seeds which day), so "every 2 weeks on Mon and
+                // Thu" would silently become "every 2 weeks on Mon". Refuse rather
+                // than surprise - weekly (every: 1) does cover multiple days. The
+                // server refuses the same shape (ValidRecurrenceRule).
+                throw new Error('every > 1 with multiple days_of_week is not supported by the scheduler (it would spawn only on the earliest day). Use one day, or every: 1 for all of them.');
+            }
+            return every === 1 ? `weekly:${days}` : `custom:${every}:week:${days}`;
+        }
+        case 'monthly': {
+            refuseIrrelevant(r, ['day_of_month']);
+            if (!r.day_of_month) {
+                throw new Error('monthly recurrence requires day_of_month (1-31).');
+            }
+            return every === 1 ? `monthly:${r.day_of_month}` : `custom:${every}:month:${r.day_of_month}`;
+        }
+        case 'quarterly':
+        case 'semiannual':
+        case 'yearly': {
+            refuseIrrelevant(r, ['anchor']);
+            if (!r.anchor) {
+                throw new Error(`${r.frequency} recurrence requires anchor (MM-DD, the cycle's first date).`);
+            }
+            // The MM-DD shape is schema-checked; the RANGE is checked here so
+            // "13-45" fails fast with the field named, not as a generic server 422.
+            const [mo, dy] = r.anchor.split('-').map(Number);
+            if (mo < 1 || mo > 12 || dy < 1 || dy > 31) {
+                throw new Error(`anchor "${r.anchor}" is not a real date - MM must be 01-12 and DD 01-31.`);
+            }
+            if (every !== 1) {
+                throw new Error(`${r.frequency} does not take "every" - its cadence is fixed. For other cadences use frequency monthly/weekly with every.`);
+            }
+            return `${r.frequency}:${r.anchor}`;
+        }
+    }
+}
+/** The one description of the template model, shared by both task tools. */
+const RECURRENCE_MODEL_NOTE = 'RECURRING TASKS: pass `recurrence` to make this task a repeating series. The task becomes the series ' +
+    'TEMPLATE - move it to a done status to START the schedule (an open template is configured but not ' +
+    'spawning; the resource reports this as recurrence.armed). The scheduler then creates a fresh copy of ' +
+    'the template (title, description, assignees, labels, priority, estimate) early on each matching day, ' +
+    'due that day, independent of whether earlier copies were closed. A multi-period cadence ' +
+    '(every: N > 1) counts whole periods from the task\'s DUE DATE, so set one.';
 /** Task-management tools: the core of the Clokio API surface. */
 export function registerTaskTools(server, config) {
     registerTool(server, config, {
@@ -24,6 +140,17 @@ export function registerTaskTools(server, config) {
             label: z.string().optional(),
             search: z.string().optional().describe('Free text over title and description'),
             open: z.boolean().optional().describe('true = only tasks whose status is not a "done" one'),
+            recurring: z
+                .boolean()
+                .optional()
+                .describe('true = only the recurring SERIES TEMPLATES (tasks carrying a recurrence rule); false = only ' +
+                'ordinary tasks, which includes the copies a template spawns. Omit for no filter.'),
+            series_of: z
+                .number()
+                .int()
+                .optional()
+                .describe('A series template\'s task id: returns every occurrence that template spawned ("did the Sunday ' +
+                'check actually happen every week?"). A copy also names its template as recurrence.spawned_from.'),
             parent_task_id: z
                 .number()
                 .int()
@@ -79,6 +206,8 @@ export function registerTaskTools(server, config) {
                 label: args.label,
                 search: args.search,
                 open: args.open === undefined ? undefined : args.open ? 1 : 0,
+                recurring: args.recurring === undefined ? undefined : args.recurring ? 1 : 0,
+                series_of: args.series_of,
                 parent_task_id: args.parent_task_id === null ? '' : args.parent_task_id,
                 created_before: args.created_before,
                 created_after: args.created_after,
@@ -118,7 +247,8 @@ export function registerTaskTools(server, config) {
             'You do NOT normally need created_by_employee_code: an unnamed task is attributed to the key\'s issuer ' +
             'automatically (whoami shows who that is). Set it only to credit someone OTHER than the key owner. ' +
             'Pass parent_task_id to create it as a SUBTASK of that task ' +
-            '(same project, and the parent must not itself be a subtask - one level deep only).',
+            '(same project, and the parent must not itself be a subtask - one level deep only).\n\n' +
+            RECURRENCE_MODEL_NOTE,
         schema: {
             project_id: z.number().int(),
             title: z.string().max(255),
@@ -136,31 +266,61 @@ export function registerTaskTools(server, config) {
                 .optional()
                 .describe('Label names. A name that does not exist yet is CREATED - check clokio_list_task_labels first'),
             created_by_employee_code: employeeCode.optional().describe('Credit someone OTHER than the key owner; omit to use the key issuer / CLOKIO_DEFAULT_ACTOR'),
+            recurrence: recurrenceInput
+                .optional()
+                .describe('Make this task a recurring series (see the tool description for how the template model works)'),
+        },
+        handler: async (args, cfg) => {
+            const result = (await request(cfg, '/tasks', {
+                method: 'POST',
+                body: {
+                    project_id: args.project_id,
+                    title: args.title,
+                    description: args.description === undefined ? undefined : markdownToHtml(args.description),
+                    priority: args.priority,
+                    status: args.status,
+                    due_date: args.due_date,
+                    start_date: args.start_date,
+                    estimated_hours: args.estimated_hours,
+                    parent_task_id: args.parent_task_id,
+                    assignee_employee_codes: args.assignee_employee_codes,
+                    label_names: args.label_names,
+                    created_by_employee_code: args.created_by_employee_code ?? cfg.defaultActor,
+                    ...(args.recurrence
+                        ? { is_recurring: true, recurrence_rule: recurrenceToRule(args.recurrence) }
+                        : {}),
+                },
+            }));
+            // A Clokio older than the recurrence fields IGNORES unknown body keys
+            // on create (Laravel validate() drops what it has no rule for), so the
+            // task would be born NON-recurring with a 201 - and the agent would
+            // report a weekly series that never spawns. The echoed resource is the
+            // truth: if we asked for recurrence and it is not reflected, say so
+            // loudly instead of letting the silence stand.
+            if (args.recurrence && result && typeof result === 'object') {
+                const data = result.data;
+                const echoed = data?.recurrence;
+                if (echoed?.is_recurring !== true) {
+                    result.warning =
+                        'The task WAS created, but the server IGNORED the recurrence fields - this Clokio version ' +
+                            'predates recurring-series support on the API. The task will NOT repeat. Update the server, ' +
+                            'then set the recurrence again with clokio_update_task.';
+                }
+            }
+            return result;
         },
-        handler: (args, cfg) => request(cfg, '/tasks', {
-            method: 'POST',
-            body: {
-                project_id: args.project_id,
-                title: args.title,
-                description: args.description === undefined ? undefined : markdownToHtml(args.description),
-                priority: args.priority,
-                status: args.status,
-                due_date: args.due_date,
-                start_date: args.start_date,
-                estimated_hours: args.estimated_hours,
-                parent_task_id: args.parent_task_id,
-                assignee_employee_codes: args.assignee_employee_codes,
-                label_names: args.label_names,
-                created_by_employee_code: args.created_by_employee_code ?? cfg.defaultActor,
-            },
-        }),
     });
     registerTool(server, config, {
         name: 'clokio_update_task',
         mutates: true,
         description: 'Update a task. ONLY the fields you pass are changed; omitted fields are left alone. Pass null to ' +
             'due_date / start_date / estimated_hours / description to CLEAR them. Set actor_employee_code so the ' +
-            'activity log names the person rather than the API key.',
+            'activity log names the person rather than the API key.\n\n' +
+            RECURRENCE_MODEL_NOTE +
+            '\n\nManage an existing series here: `recurrence` (an object) sets or retunes the rule and switches ' +
+            'the series ON; `recurrence: null` STOPS it (future copies stop; already-spawned copies are ordinary ' +
+            'tasks and stay). To PAUSE while keeping the rule stored, pass `recurrence_active: false`, and ' +
+            '`recurrence_active: true` to resume.',
         schema: {
             id: z.number().int(),
             title: z.string().max(255).optional(),
@@ -172,6 +332,14 @@ export function registerTaskTools(server, config) {
             estimated_hours: z.number().min(0).max(9999.99).nullable().optional(),
             project_id: z.number().int().optional().describe('Move the task to another project'),
             actor_employee_code: employeeCode.optional().describe('Who to credit in the activity log; omit to use the key issuer / CLOKIO_DEFAULT_ACTOR'),
+            recurrence: recurrenceInput
+                .nullable()
+                .optional()
+                .describe('Set/retune the series rule (and switch it on), or null to STOP the series'),
+            recurrence_active: z
+                .boolean()
+                .optional()
+                .describe('Pause (false) / resume (true) the series without touching its stored rule'),
         },
         handler: (args, cfg) => {
             // Only keys the caller actually supplied may go in the body: PATCH
@@ -194,6 +362,24 @@ export function registerTaskTools(server, config) {
             }
             if (typeof body.description === 'string')
                 body.description = markdownToHtml(body.description);
+            // Series management maps onto the API's two columns. `recurrence`
+            // carries the whole intent (rule + on/off), so combining it with the
+            // bare pause/resume switch is ambiguous and refused rather than
+            // silently picking a winner.
+            if (args.recurrence !== undefined && args.recurrence_active !== undefined) {
+                throw new Error('Pass either recurrence or recurrence_active, not both.');
+            }
+            if (args.recurrence === null) {
+                body.is_recurring = false;
+                body.recurrence_rule = null;
+            }
+            else if (args.recurrence !== undefined) {
+                body.is_recurring = true;
+                body.recurrence_rule = recurrenceToRule(args.recurrence);
+            }
+            else if (args.recurrence_active !== undefined) {
+                body.is_recurring = args.recurrence_active;
+            }
             // Credit the update to CLOKIO_DEFAULT_ACTOR when the caller named no
             // actor. The API otherwise falls back to the key's issuer on its own,
             // so this only overrides for a shared/service key. An explicit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clokio-mcp",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Model Context Protocol (MCP) server for Clokio — manage tasks, projects, clients, employees and attendance from Claude and any MCP client.",
   "type": "module",
   "bin": {