things-api 0.18.0 → 0.19.1

package/dist/mcp/server.js

@@ -16,7 +16,64 @@
  */
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ALL_DESC, AREA_FILTER_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, blockedCode, capabilitiesTable, DATE_FORMAT, DEFAULT_LIST_LIMIT, diagnose, FILTER_CONTRACT, FULL_DESC, hasTagPresence, isLooseRef, isValidTimeZone, LIMIT_DESC, looseShadowNotice, MCP_WHEN_LABELS, mutationWireData, noUuidMatch, omitEmpty, OMIT_EMPTY_NOTE, OP_ID_RE, opResult, OPERATION_KINDS, openThings, PKG_VERSION, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, REF_FORMAT, REF_RULE_NOTE, ReferenceResolutionError, REMINDER_FORMAT, RESOLUTION_DATE_FORMAT, schemaWarnings, shapeReadPayload, withTodayBucketTotals, withAreaBucketTotals, withSectionTotals, withUpcomingBlockTotals, splitWhenSugar, tagFilterFields, tagFlagConflict, validateViewArgs, verifyFailedCode, WHEN_VALUES, } from "../index.js";
+import { ALL_DESC, AREA_FILTER_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, blockedCode, buildUpdatePatch, capabilitiesTable, DATE_FORMAT, DEFAULT_LIST_LIMIT, diagnose, FILTER_CONTRACT, FULL_DESC, hasTagPresence, isLooseRef, isValidTimeZone, LIMIT_DESC, looseShadowNotice, MCP_UPDATE_LABELS, MCP_WHEN_LABELS, mutationWireData, NOTES_FORMAT, noUuidMatch, omitEmpty, OMIT_EMPTY_NOTE, OP_ID_RE, opResult, OPERATION_KINDS, openThings, readAllowed, readCapability, uiAllowed, uiCapability, writeAllowed, writeCapability, PKG_VERSION, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, REF_FORMAT, REF_RULE_NOTE, ReferenceResolutionError, REMINDER_FORMAT, RESOLUTION_DATE_FORMAT, schemaWarnings, shapeReadPayload, withTodayBucketTotals, withAreaBucketTotals, withSectionTotals, withUpcomingBlockTotals, splitWhenSugar, tagFilterFields, tagFlagConflict, validateViewArgs, verifyFailedCode, WHEN_VALUES, } from "../index.js";
+/** Tools that mutate through the app. Everything unlisted is a plain read. */
+const WRITE_TOOLS = new Set([
+    "add_todo",
+    "update",
+    "set_status",
+    "move_todo",
+    "set_tags",
+    "edit_checklist",
+    "delete",
+    "restore_item",
+    "heading",
+    "clear_reminder",
+    "duplicate_item",
+    "clone_item",
+    "add_project",
+    "move_project",
+    "add_area",
+    "add_tag",
+    "log_now",
+    "run_operation",
+    "batch",
+    "reorder",
+    "undo",
+]);
+/**
+ * Tools with NO headless spelling at all — every path through them drives the
+ * Things window. A tool that merely *can* reach a GUI op (`heading`'s promote,
+ * `reorder`'s areas) is NOT listed: those have working headless branches, and
+ * the pipeline's own Article IV gate refuses the GUI ones per call.
+ */
+const UI_TOOLS = new Set(["repeat", "convert_to_project"]);
+/** The always-available diagnostics. */
+const DIAGNOSTIC_TOOLS = new Set(["doctor", "capabilities", "op_result"]);
+function toolClass(name) {
+    if (DIAGNOSTIC_TOOLS.has(name))
+        return "none";
+    if (UI_TOOLS.has(name))
+        return "ui";
+    if (WRITE_TOOLS.has(name))
+        return "write";
+    return "read";
+}
+/** The one remediation every baked refusal ends with. */
+const RESTART_REMEDIATION = "this server surveyed its permissions once at startup and does not re-check them, because a " +
+    "grant made now would attach to whoever launched it: stop this server, run the setup command " +
+    "above at the machine, then start it again.";
+/** The vector classes this server can actually serve, for the instructions. */
+function availableClasses(capability) {
+    const available = [];
+    if (readAllowed(capability.read))
+        available.push("read");
+    if (writeAllowed(capability.write))
+        available.push("write");
+    if (uiAllowed(capability.ui))
+        available.push("gui-driving");
+    return available;
+}
 function jsonResult(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
@@ -341,9 +398,11 @@ const preserveModifiedShape = {
 /**
  * The per-call idempotency key for a single write tool — the analogue of a batch
  * line's op_id. A resubmission carrying the same key is recognized as already
- * applied (a prior verified change with that key) and is not re-run. Spread into
- * the single-mutation write tools (not the variadic move/reorder tools, whose
- * idempotency is the batch-shaped per-line op_id).
+ * applied (a prior change recorded under that key) and is not re-run. Spread
+ * into every write tool whose call records ONE result — the single mutations,
+ * and the multi-step verbs that record one summary (the repeating-series tool,
+ * the template-target status/exception writes) — but not the variadic
+ * move/reorder tools, whose idempotency is the batch-shaped per-line op_id.
  */
 const opIdShape = {
     op_id: z
@@ -402,7 +461,7 @@ const tagLabel = (t) => t.parent === null ? t.title : `${t.parent} > ${t.title}`
  * names without a discovery round-trip. Degrades to conventions-only when
  * the database is not readable.
  */
-function buildInstructions(getClient) {
+function buildInstructions(getClient, capability) {
     const lines = [
         "This server reads and modifies the user's Things 3 data: to-dos, projects, areas, and tags.",
         "",
@@ -418,6 +477,8 @@ function buildInstructions(getClient) {
         `- Scheduling vocabulary: when = ${WHEN_VALUES}; deadlines are ${DATE_FORMAT}; reminders ` +
             `are ${REMINDER_FORMAT}. Resolve relative calendar phrases against the Calendar context ` +
             `below (or a date-sensitive read result's meta.clock.today), then pass the explicit date.`,
+        `- Notes vocabulary: the notes field is ${NOTES_FORMAT}. Newlines are kept as written, so ` +
+            `pass a multi-line body directly rather than flattening it into one line.`,
         "- Every write tool accepts dry_run: true to preview the change without applying it. " +
             "A preview creates no state, so later calls cannot reference an item that only appeared in " +
             "a dry-run result. Operations with cascading or permanent effects require the explicit " +
@@ -430,6 +491,27 @@ function buildInstructions(getClient) {
         "- For capped reads, pass limit to cap rows or all: true for everything; if both are set, all wins.",
         `- Read results are compact: ${OMIT_EMPTY_NOTE}`,
     ];
+    // What this server may do, decided once at startup and true for its whole
+    // life (permissions doctrine, Article II). Stated up front so an agent plans
+    // around the real surface instead of discovering it one refusal at a time.
+    const available = availableClasses(capability);
+    const missing = [];
+    if (!readAllowed(capability.read))
+        missing.push(`reads — ${capability.read.detail}`);
+    if (!writeAllowed(capability.write))
+        missing.push(`changes — ${capability.write.detail}`);
+    if (!uiAllowed(capability.ui))
+        missing.push(`GUI-driven operations — ${capability.ui.detail}`);
+    lines.push("", "Permissions (checked once at server start, fixed for this server's lifetime):", `- Available here: ${available.length > 0 ? available.join(", ") : "nothing — every tool below refuses"}.`, ...(missing.length > 0
+        ? [
+            `- Unavailable here: ${missing.join("; ")}.`,
+            "- Tools needing an unavailable capability refuse immediately rather than trying and " +
+                "raising a macOS permission dialog nobody is present to answer. Remediation for each " +
+                "is in its refusal. These grants attach to whichever process launched this server, so " +
+                "they cannot change while it runs: the fix is always stop the server, run the named " +
+                "setup command at the machine, start it again.",
+        ]
+        : ["- Nothing is missing; no tool will refuse for want of a permission."]));
     try {
         const c = getClient();
         // Under a container scope the inventory below is already limited to in-scope
@@ -499,7 +581,86 @@ export function createThingsMcpServer(options = {}) {
         });
         return client;
     };
-    const server = new McpServer({ name: "things-api", version: PKG_VERSION }, { instructions: buildInstructions(getClient) });
+    // THE STARTUP BAKE (permissions doctrine, Article II). One prompt-free survey
+    // before the transport is connected; the verdict then shapes the instructions
+    // and gates the tools, and is never re-taken.
+    const capability = options.capability ?? {
+        read: readCapability(options.dbPath !== undefined ? { dbPath: options.dbPath } : {}),
+        // SURVEY: starting a server must never start the user's app as a side
+        // effect. A closed Things reads as the liveness state; the write gate wakes
+        // it when a change is actually dispatched (#617).
+        write: writeCapability(),
+        ui: uiCapability(),
+    };
+    const warn = options.onStartupWarning ?? ((line) => process.stderr.write(`${line}\n`));
+    const unavailable = [
+        ...(readAllowed(capability.read) ? [] : ["reads"]),
+        ...(writeAllowed(capability.write) ? [] : ["changes"]),
+        ...(uiAllowed(capability.ui) ? [] : ["GUI-driven operations"]),
+    ];
+    if (unavailable.length > 0) {
+        warn(`things-api MCP: ${unavailable.join(", ")} unavailable on this machine — ` +
+            `${capability.read.detail}; ${capability.write.detail}; ${capability.ui.detail}. ` +
+            "Tools needing them refuse; restart this server after running setup.");
+    }
+    const server = new McpServer({ name: "things-api", version: PKG_VERSION }, { instructions: buildInstructions(getClient, capability) });
+    /**
+     * The baked refusal for one tool class, or null when the class is served.
+     * Article II in one function: the answer is the STARTUP verdict, quoted, with
+     * the setup command and the restart rule — never a fresh probe, and never a
+     * dispatch that could put a dialog on screen.
+     */
+    const bakedRefusal = (name) => {
+        switch (toolClass(name)) {
+            case "none":
+                return null;
+            case "read":
+                return readAllowed(capability.read)
+                    ? null
+                    : errorResult({
+                        code: "environment",
+                        message: `this tool reads the Things database, and ${capability.read.detail}`,
+                        remediation: [...capability.read.remediation, RESTART_REMEDIATION].join("; "),
+                    });
+            case "write":
+                // A write read-verifies, so it needs both classes; name the one that
+                // is actually missing rather than a generic "cannot write".
+                if (!readAllowed(capability.read)) {
+                    return errorResult({
+                        code: "environment",
+                        message: `this tool changes Things data and verifies the result by reading it back, and ${capability.read.detail}`,
+                        remediation: [...capability.read.remediation, RESTART_REMEDIATION].join("; "),
+                    });
+                }
+                return writeAllowed(capability.write)
+                    ? null
+                    : errorResult({
+                        code: "environment",
+                        message: `this tool changes Things data by driving the app, and ${capability.write.detail}`,
+                        remediation: [...capability.write.remediation, RESTART_REMEDIATION].join("; "),
+                    });
+            case "ui":
+                return uiAllowed(capability.ui)
+                    ? null
+                    : errorResult({
+                        code: "environment",
+                        message: `this tool is delivered by driving the Things window, and ${capability.ui.detail}`,
+                        remediation: [...capability.ui.remediation, RESTART_REMEDIATION].join("; "),
+                    });
+        }
+    };
+    /**
+     * `server.registerTool` with the baked gate in front of every callback. Every
+     * registration below goes through this, so a tool cannot be added without a
+     * class — {@link toolClass} defaults an unlisted name to `read`, the weakest
+     * useful assumption, rather than to ungated.
+     */
+    const registerTool = ((name, config, cb) => server.registerTool(name, config, ((...args) => {
+        const refusal = bakedRefusal(name);
+        if (refusal !== null)
+            return refusal;
+        return cb(...args);
+    })));
     // The audit author for every write on this connection, derived once from the
     // client's handshake identity (clientInfo.name). Read per call: clientInfo is
     // populated when the initialize handshake completes, before any tool can run.
@@ -608,14 +769,18 @@ export function createThingsMcpServer(options = {}) {
         return item.type;
     };
     // ------------------------------------------------------------------ reads
-    server.registerTool("read_view", {
+    registerTool("read_view", {
         description: "Read a Things list as the app presents it: today (two children buckets — " +
             "children.today and children.evening, evening expires daily; the whole-view " +
             "count due/overdue vs. other rides the result's second block), inbox, anytime, " +
             "upcoming, someday, logbook, trash, or deadlines (a flat items list of everything " +
             "carrying a deadline — to-dos and projects — in deadline order, most-overdue first; " +
             "repeating items appear at their next occurrence's projected deadline; scope with " +
-            "today/overdue/project/area/tag). For upcoming, " +
+            "today/overdue/project/area/tag), or repeaters (every repeating series in the " +
+            "library — to-dos and projects — each carrying its decoded rule under " +
+            "repeating.rule; series appear in no other view, which show the occurrences a " +
+            "series spawns instead; paused and ended series are included; ordered by next " +
+            "occurrence, the ones with none last). For upcoming, " +
             "horizon > 1 also includes future occurrences of repeating items (up to 10 each). " +
             "anytime/someday return sections in canonical order (area + items; null area = the " +
             "top-level block); children of someday/future-scheduled projects are excluded " +
@@ -639,6 +804,7 @@ export function createThingsMcpServer(options = {}) {
                 "logbook",
                 "trash",
                 "deadlines",
+                "repeaters",
             ]),
             ...tagFilterShape,
             ...tzShape,
@@ -854,10 +1020,14 @@ export function createThingsMcpServer(options = {}) {
                     });
                     return truncatedResult(shapeReadPayload("deadlines", items, full, c.refPromoter()), truncation);
                 }
+                case "repeaters": {
+                    const { items, truncation } = c.read.repeaters({ ...filter, ...zone, limit });
+                    return truncatedResult(shapeReadPayload("repeaters", items, full, c.refPromoter()), truncation);
+                }
             }
         }, args.tz, () => (filterMeta !== undefined ? { filter: filterMeta } : undefined), () => looseAreaWarnings(getClient(), args.area));
     });
-    server.registerTool("search", {
+    registerTool("search", {
         description: "Find items by title/notes substring. Returns open, untrashed items by default; " +
             "include more with logged/trashed/all. Scope with project/area/tag — scope " +
             "references must name existing items. " +
@@ -920,7 +1090,7 @@ export function createThingsMcpServer(options = {}) {
         });
         return truncatedResult(shapeReadPayload("search", items, args.full === true, getClient().refPromoter()), truncation);
     }, args.tz, undefined, () => looseAreaWarnings(getClient(), args.area)));
-    server.registerTool("changes_since", {
+    registerTool("changes_since", {
         description: "List items created or modified since a moment — including trashed, logged, and " +
             "repeating items (inspect each item's fields to tell them apart). Edits to tags, " +
             "areas, and checklist items do not mark the containing item as modified. " +
@@ -950,7 +1120,7 @@ export function createThingsMcpServer(options = {}) {
         });
         return truncatedResult(shapeReadPayload("changes", items, args.full === true, getClient().refPromoter()), truncation);
     }, args.tz));
-    server.registerTool("get_item", {
+    registerTool("get_item", {
         description: "Full detail for one item by uuid: notes, schedule, reminder, deadline, tags " +
             "(direct and inherited), checklist with per-item state, repeat schedule, and its " +
             "project/area/heading. " +
@@ -965,7 +1135,7 @@ export function createThingsMcpServer(options = {}) {
             ? errorResult({ code: "not-found", message: noUuidMatch("item", args.uuid) })
             : readResult(shapeReadPayload("detail", item, false, getClient().refPromoter()));
     }));
-    server.registerTool("get_project", {
+    registerTool("get_project", {
         description: "One project's full contents: metadata plus its to-dos grouped under their headings. " +
             "Open headings (and archived ones not yet swept to the logbook) stay live, carrying " +
             "archived once archived; a swept archived heading moves into the logged region as a " +
@@ -997,7 +1167,7 @@ export function createThingsMcpServer(options = {}) {
             ...(args.tz !== undefined && { zone: args.tz }),
         }), args.full === true, getClient().refPromoter()));
     }, args.tz));
-    server.registerTool("get_area", {
+    registerTool("get_area", {
         description: "One area's contents: metadata plus its direct to-dos (active first), its " +
             "projects in canonical order, and later (scheduled/repeating/someday). The area " +
             "logbook is not returned here — read it with read_view logbook + area; trashed " +
@@ -1061,7 +1231,7 @@ export function createThingsMcpServer(options = {}) {
             return groupedResult(withAreaBucketTotals(shapeReadPayload("area-view", view, args.full === true, getClient().refPromoter()), totals), truncation);
         }, args.tz, undefined, () => (areaNotice !== undefined ? [areaNotice] : undefined));
     });
-    server.registerTool("list_collections", {
+    registerTool("list_collections", {
         description: "List every project, area, or tag (tags include their parent-tag nesting). Use to " +
             "refresh the inventory summarized in the server instructions. The tag filters scope " +
             "the projects list by each project's own tags (areas/tags reject them). " +
@@ -1116,7 +1286,7 @@ export function createThingsMcpServer(options = {}) {
     }, args.tz));
     // ---------------------------------------------------------------- to-dos
     const whenSchema = z.string().optional().describe(WHEN_VALUES);
-    server.registerTool("add_todo", {
+    registerTool("add_todo", {
         description: "Create a to-do and return its uuid. Optionally schedule it, set a reminder or " +
             "deadline, tag it, give it a checklist, and place it in a project or area " +
             "(optionally under a heading within that project). A reminder " +
@@ -1124,7 +1294,7 @@ export function createThingsMcpServer(options = {}) {
             "project reopens that project — pass acknowledge_project_reopen to confirm.",
         inputSchema: {
             title: z.string(),
-            notes: z.string().optional(),
+            notes: z.string().optional().describe(`Notes body — ${NOTES_FORMAT}`),
             when: whenSchema,
             reminder: z.string().optional().describe(REMINDER_FORMAT),
             deadline: z.string().optional().describe(DATE_FORMAT),
@@ -1177,7 +1347,7 @@ export function createThingsMcpServer(options = {}) {
             ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
         }, writeOptions(args)));
     }));
-    server.registerTool("update", {
+    registerTool("update", {
         description: "Edit an existing to-do, project, area, or tag — kind selects which. " +
             "kind todo/project: title, notes (or append_notes/prepend_notes to add a line to the " +
             "existing body, exclusive with notes), schedule (when), reminder/clear_reminder, and " +
@@ -1198,7 +1368,10 @@ export function createThingsMcpServer(options = {}) {
                 .describe("The item to update — a to-do by uuid; a project, area, or tag also accepts a " +
                 "unique name"),
             title: z.string().optional().describe("New title (any kind)"),
-            notes: z.string().optional().describe("todo/project: replaces the whole notes body"),
+            notes: z
+                .string()
+                .optional()
+                .describe(`todo/project: replaces the whole notes body — ${NOTES_FORMAT}`),
             append_notes: z.string().optional().describe("todo/project: add a line after the notes"),
             prepend_notes: z.string().optional().describe("todo/project: add a line before the notes"),
             when: whenSchema,
@@ -1220,6 +1393,17 @@ export function createThingsMcpServer(options = {}) {
                 .array(z.string())
                 .optional()
                 .describe(`area: replace the tag set (full) — ${TAG_REF_FORMAT}`),
+            exception: z
+                .boolean()
+                .optional()
+                .describe("todo, repeating only: change just the NEXT occurrence and leave the series alone " +
+                "(the occurrence is created if it has not appeared yet). Refused when the series " +
+                "already lands on the requested day, and when the series names no next date at " +
+                "all (a paused one — resume it first). The result's occurrence field names both the occurrence " +
+                "and the series. Each call takes another occurrence out of the series, so pass " +
+                "op_id when retrying: a resubmission with the same key replays the first result " +
+                "instead of creating a second occurrence. Undo restores the occurrence's own " +
+                "change but cannot remove the occurrence or rewind the series"),
             parent: z.string().optional().describe("tag: existing tag to nest under"),
             unnest: z.boolean().optional().describe("tag: move the tag to the top level"),
             shortcut: z.string().optional().describe("tag: keyboard shortcut character"),
@@ -1238,49 +1422,23 @@ export function createThingsMcpServer(options = {}) {
         const opts = writeOptions(args);
         const c = getClient();
         if (args.kind === "todo" || args.kind === "project") {
-            const notesModes = [args.notes, args.append_notes, args.prepend_notes].filter((v) => v !== undefined);
-            if (notesModes.length > 1) {
-                return usage("notes, append_notes, prepend_notes are exclusive");
-            }
-            if (args.reminder !== undefined && args.clear_reminder === true) {
-                return usage("pass at most one of reminder / clear_reminder");
-            }
-            if (args.deadline !== undefined && args.clear_deadline === true) {
-                return usage("pass at most one of deadline / clear_deadline");
-            }
-            if (args.kind === "todo") {
-                const sugar = splitWhenSugar(args.when, args.reminder !== undefined, MCP_WHEN_LABELS);
-                if (sugar.kind === "error")
-                    return usage(sugar.message);
-                const when = sugar.kind === "split" ? sugar.when : args.when;
-                const reminder = sugar.kind === "split" ? sugar.reminder : args.reminder;
-                return mutationResult(await c.write.updateTodo(args.uuid, {
-                    ...(args.title !== undefined && { title: args.title }),
-                    ...(args.notes !== undefined && { notes: args.notes }),
-                    ...(args.append_notes !== undefined && { appendNotes: args.append_notes }),
-                    ...(args.prepend_notes !== undefined && { prependNotes: args.prepend_notes }),
-                    ...(when !== undefined && { when: when }),
-                    ...(reminder !== undefined && { reminder }),
-                    ...(args.clear_reminder === true && { reminder: null }),
-                    ...(args.deadline !== undefined && { deadline: args.deadline }),
-                    ...(args.clear_deadline === true && { deadline: null }),
-                    ...(args.created_at !== undefined && { createdAt: args.created_at }),
-                    ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
-                }, opts));
+            // The patch — and every exclusive pair in the vocabulary, the `@time`
+            // sugar included — comes from the ONE builder the CLI shares, so the two
+            // surfaces cannot drift on which flags they accept (#491 doctrine).
+            const built = buildUpdatePatch(args, MCP_UPDATE_LABELS);
+            if (built.kind === "error")
+                return usage(built.message);
+            if (args.exception === true) {
+                if (args.kind !== "todo")
+                    return usage("exception applies to kind todo");
+                if (args.created_at !== undefined || args.completed_at !== undefined) {
+                    return usage("exception cannot be combined with created_at/completed_at");
+                }
+                return mutationResult(await c.write.updateTodoOccurrence(args.uuid, built.patch, opts));
             }
-            return mutationResult(await c.write.updateProject(args.uuid, {
-                ...(args.title !== undefined && { title: args.title }),
-                ...(args.notes !== undefined && { notes: args.notes }),
-                ...(args.append_notes !== undefined && { appendNotes: args.append_notes }),
-                ...(args.prepend_notes !== undefined && { prependNotes: args.prepend_notes }),
-                ...(args.when !== undefined && { when: args.when }),
-                ...(args.reminder !== undefined && { reminder: args.reminder }),
-                ...(args.clear_reminder === true && { reminder: null }),
-                ...(args.deadline !== undefined && { deadline: args.deadline }),
-                ...(args.clear_deadline === true && { deadline: null }),
-                ...(args.created_at !== undefined && { createdAt: args.created_at }),
-                ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
-            }, opts));
+            return mutationResult(args.kind === "todo"
+                ? await c.write.updateTodo(args.uuid, built.patch, opts)
+                : await c.write.updateProject(args.uuid, built.patch, opts));
         }
         if (args.kind === "area") {
             if (args.title === undefined && args.tags === undefined) {
@@ -1313,9 +1471,15 @@ export function createThingsMcpServer(options = {}) {
             ...(args.clear_shortcut === true && { clearShortcut: true }),
         }, opts));
     }));
-    server.registerTool("set_status", {
+    registerTool("set_status", {
         description: "Set a to-do's or project's status (scope selects which): completed, canceled, or open " +
-            "(reopening a completed/canceled item). Not available for repeating to-dos. " +
+            "(reopening a completed/canceled item). scope todo, a REPEATING to-do: completed/canceled " +
+            "resolves the series' CURRENT occurrence — the unfinished one if there is one, otherwise " +
+            "the next one, created for the purpose — and leaves the series running; the result's " +
+            "occurrence field names both uuids and says which of the two was created. Each call is a " +
+            "new resolution that takes the FOLLOWING occurrence, so pass op_id when retrying: a " +
+            "resubmission with the same key replays the first result instead of creating a second " +
+            "occurrence. Reopening a repeating to-do is not available. " +
             "scope project, completing or canceling requires a children policy: 'require-resolved' " +
             "errors if open to-dos remain; 'auto-complete'/'auto-cancel' resolves them together with " +
             "the project (canceling never alters already-completed children). scope project, status " +
@@ -1401,7 +1565,7 @@ export function createThingsMcpServer(options = {}) {
             ? jsonResult(outcome)
             : mutationResult(outcome.project);
     }));
-    server.registerTool("move_todo", {
+    registerTool("move_todo", {
         description: "Move one or more to-dos as an ordered block (spec §4). MOVE changes WHAT a to-do " +
             "belongs to (membership somewhere); to REARRANGE to-dos that already share a container " +
             "without changing membership, call this with a position (first/last/before/after) and " +
@@ -1474,7 +1638,7 @@ export function createThingsMcpServer(options = {}) {
         };
         return moveResult(await getClient().write.moveTodos(request, writeOptions(args)));
     }));
-    server.registerTool("set_tags", {
+    registerTool("set_tags", {
         description: "Replace or extend a to-do's or project's tags. mode 'replace' (default) sets exactly " +
             "the given list — an empty list removes all tags; mode 'add' merges with the current " +
             "tags. Tags must exist unless create_tags is set (or create them first with add_tag).",
@@ -1501,7 +1665,7 @@ export function createThingsMcpServer(options = {}) {
             ? await c.write.setProjectTags(args.uuid, args.tags, opts)
             : await c.write.setTags(args.uuid, args.tags, opts));
     }));
-    server.registerTool("edit_checklist", {
+    registerTool("edit_checklist", {
         description: "Edit a to-do's checklist. The single-item actions add / remove / check / uncheck " +
             "/ rename / move change one item — targeted by title or 1-based index — and leave " +
             "every other item and its checked state untouched (duplicate titles resolve " +
@@ -1591,11 +1755,16 @@ export function createThingsMcpServer(options = {}) {
         return mutationResult(await c.write.editChecklist(args.uuid, edit, writeOptions(args)));
     }));
     // ------------------------------------------------- to-dos AND projects
-    server.registerTool("delete", {
+    registerTool("delete", {
         description: "Delete a to-do/project (kind item), an area, or a tag — kind selects which. " +
             "kind item: moves a to-do or project to the Trash (recoverable via restore_item until " +
-            "the Trash is emptied; a deleted project takes its to-dos with it; not available for " +
-            "repeating to-dos). kind area: PERMANENT — areas do not go to the Trash, so this cannot " +
+            "the Trash is emptied; a deleted project takes its to-dos with it). Deleting a repeating " +
+            "series' TEMPLATE is allowed and ends the series: it stops generating new occurrences and " +
+            "its existing occurrences are left in place (the result names how many, and the current " +
+            "one). That one cannot be undone — neither undo nor restore_item brings a template back, " +
+            "so no undo token is returned; the series returns only via Put Back in the Things app's " +
+            "Trash. Deleting a single occurrence leaves the series running. kind area: PERMANENT — " +
+            "areas do not go to the Trash, so this cannot " +
             "be undone and requires dangerously_permanent; deleting an area moves its to-dos and " +
             "projects to the Trash, so a non-empty area is refused unless you pass " +
             "allow_non_empty_area (empty it first to keep its contents). kind tag: PERMANENT — requires " +
@@ -1637,7 +1806,7 @@ export function createThingsMcpServer(options = {}) {
                 return mutationResult(await c.write.deleteTag(args.uuid, opts));
         }
     }));
-    server.registerTool("restore_item", {
+    registerTool("restore_item", {
         description: "Restore a trashed to-do or project. A to-do returns to the Inbox without its " +
             "previous schedule or project/area. A project is restored in place: its schedule, " +
             "area, and children come back exactly as they were.",
@@ -1655,11 +1824,11 @@ export function createThingsMcpServer(options = {}) {
     // write tools: add_todo / add_project (Logbook import), update (rewrite an
     // already-resolved item's timestamps), and set_status (backdate on
     // complete/cancel) — matching the CLI's --created-at/--completed-at flags.
-    server.registerTool("heading", {
+    registerTool("heading", {
         description: "Manage a project's headings — action selects which; project is always required, and a " +
             "heading is selected by its exact title or its uuid (never an ordinal). add_heading: a " +
             "new heading in the project (project + title; returns its uuid; uses the Things proxy " +
-            "shortcuts, set up once with `things setup shortcuts`); a placement flag positions it, " +
+            "shortcuts, set up once with `things setup`); a placement flag positions it, " +
             "else it appends. rename_heading: rename in place (project + heading + title; works on " +
             "archived headings). archive_heading: retire a heading so it leaves the active project " +
             "view (reversible with unarchive_heading); with open children pass children — complete " +
@@ -1669,11 +1838,15 @@ export function createThingsMcpServer(options = {}) {
             "promote_heading: promote a heading into a new project — this REPLACES the heading and " +
             "cannot be undone (its to-dos move under the new project), and requires " +
             "dangerously_drive_gui. move_heading: reposition headings as an ordered block (children " +
-            "follow); pass exactly one placement flag. Reordering headings needs allow-experimental. " +
+            "follow); pass exactly one placement flag. GUI-only (requires dangerously_drive_gui) — " +
+            "Things offers heading order as keyboard shortcuts on a selected heading row and nowhere " +
+            "else, so this moves one heading one slot at a time and re-reads the order after each " +
+            "step; it refuses when the project holds a completed or canceled heading. " +
             "move_heading_to_project: relocate ONE heading (with its to-dos) to a DIFFERENT project " +
             "(project + heading + to_project) — the cross-project move, distinct from move_heading's " +
             "within-project reorder; GUI-only (requires dangerously_drive_gui), fails closed on a " +
-            "source-heading or destination-project title collision, and has no undo (move it back). " +
+            "source-heading or destination-project title collision and on a completed or canceled " +
+            "destination project (reopen it first), and has no undo (move it back). " +
             "dissolve_heading: remove a heading but KEEP its to-dos as direct project children (NOT " +
             "trashed — the opposite of a delete cascade); GUI-only (requires dangerously_drive_gui), " +
             "fails closed on a title collision, no undo.",
@@ -1820,7 +1993,7 @@ export function createThingsMcpServer(options = {}) {
             }
         }
     }));
-    server.registerTool("convert_to_project", {
+    registerTool("convert_to_project", {
         description: "Promote a to-do into a project. This REPLACES the to-do with a new project (its notes " +
             "are kept); the to-do's identity is gone and it cannot be undone. Requires " +
             "dangerously_drive_gui. The new project's uuid is on the result. (To promote a HEADING, " +
@@ -1834,7 +2007,7 @@ export function createThingsMcpServer(options = {}) {
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.run("todo.convert-to-project", { uuid: args.uuid }, writeOptions(args)))));
-    server.registerTool("clear_reminder", {
+    registerTool("clear_reminder", {
         description: "Clear a to-do's time-of-day reminder while keeping its scheduled date. Uses the " +
             "Things proxy shortcuts when installed (in place, and the only path for a repeating " +
             "to-do); otherwise a non-repeating dated to-do falls back to a URL re-schedule that " +
@@ -1921,7 +2094,7 @@ export function createThingsMcpServer(options = {}) {
             fields.startDaysEarlier = a.start_days_earlier;
         return fields;
     };
-    server.registerTool("repeat", {
+    registerTool("repeat", {
         description: "Manage recurrence on a to-do or project (scope) by driving the local Things app's " +
             "interface — every action needs dangerously_drive_gui. action start: turn a plain item " +
             "into a repeating one (promote-via-clone: a disposable copy is promoted and the ORIGINAL " +
@@ -1934,7 +2107,9 @@ export function createThingsMcpServer(options = {}) {
             "pause/resume: stop or restart its new occurrences, keeping the rule. action add: create " +
             "an item and make it repeating in one call — it is created first and PERSISTS even if the " +
             "promote refuses (give a title; for a project give an area to place it or omit it to " +
-            "create in Someday); undo removes the created series. Returns the new template's uuid.",
+            "create in Someday); undo removes the created series. Returns the new template's uuid. " +
+            "Every start/add re-run makes ANOTHER series, so pass op_id when retrying: a resubmission " +
+            "with the same key replays the first result instead of making a second series.",
         inputSchema: {
             scope: z.enum(["todo", "project"]),
             action: z.enum(["start", "reschedule", "pause", "resume", "add"]),
@@ -1943,15 +2118,16 @@ export function createThingsMcpServer(options = {}) {
                 .optional()
                 .describe("start/reschedule/pause/resume: the item (a project also accepts a unique name)"),
             title: z.string().optional().describe("add: the new item's title"),
-            notes: z.string().optional().describe("add: notes"),
+            notes: z.string().optional().describe(`add: notes — ${NOTES_FORMAT}`),
             area: z.string().optional().describe(`add (project): destination area (${REF_FORMAT})`),
             project_deadline: z
                 .string()
                 .optional()
-                .describe(`add: due date (${DATE_FORMAT}). For a to-do it deadlines EVERY occurrence — each ` +
-                `starts (deadline − when) days before its own deadline, so it needs a concrete when ` +
-                `on or before it (an alternative spelling of start_days_earlier — give one or the ` +
-                `other, both must agree). For a project it is the project's own due date.`),
+                .describe(`add: due date (${DATE_FORMAT}). It deadlines EVERY occurrence — each starts ` +
+                `(deadline − when) days before its own deadline, so it needs a concrete when on or ` +
+                `before it. For a to-do it is an alternative spelling of start_days_earlier (give ` +
+                `one or the other, both must agree). Not available with after_completion on a ` +
+                `project, whose occurrences are created without a deadline.`),
             todos: z.array(z.string()).optional().describe("add (project): initial child to-do titles"),
             frequency: z
                 .enum(["daily", "weekly", "monthly", "yearly"])
@@ -1978,6 +2154,7 @@ export function createThingsMcpServer(options = {}) {
             ...driveGuiShape,
             ...dryRunShape,
             ...preserveModifiedShape,
+            ...opIdShape,
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -1992,10 +2169,10 @@ export function createThingsMcpServer(options = {}) {
             }
             // add-repeating carries only the calendar-anchor rule fields here; the rule
             // reminder is set with a follow-up reschedule. A concrete `project_deadline`
-            // maps to the RULE for a to-do (DBLSPAWN1 — each occurrence deadlined, seed
-            // deadline-free) and to the project's own due date for a project. For a to-do,
-            // `start_days_earlier` is the alternative spelling of that deadline geometry
-            // (the two must AGREE when both are given — enforced in the library).
+            // maps to the RULE on BOTH scopes (DBLSPAWN1 — each occurrence deadlined,
+            // the created item deadline-free). For a to-do, `start_days_earlier` is the
+            // alternative spelling of that deadline geometry (the two must AGREE when
+            // both are given — enforced in the library).
             const { reminder: _reminder, deadline: _deadline, startDaysEarlier, ...ruleExtras } = repeatExtras(args, frequency);
             if (args.scope === "todo") {
                 return mutationResult(await c.write.addRepeatingTodo({
@@ -2049,7 +2226,7 @@ export function createThingsMcpServer(options = {}) {
         // scope project, action start → the dedicated make-repeating method
         return mutationResult(await c.write.makeRepeatingProject(args.uuid, { frequency, interval, ...extras }, opts));
     }));
-    server.registerTool("duplicate_item", {
+    registerTool("duplicate_item", {
         description: "Duplicate a to-do or project and return the copy's uuid; a duplicated project " +
             "includes its children. Not available for repeating items.",
         inputSchema: { uuid: z.string(), ...dryRunShape, ...preserveModifiedShape, ...opIdShape },
@@ -2060,7 +2237,7 @@ export function createThingsMcpServer(options = {}) {
             ? await c.write.duplicateTodo(args.uuid, writeOptions(args))
             : await c.write.duplicateProject(args.uuid, writeOptions(args)));
     }));
-    server.registerTool("clone_item", {
+    registerTool("clone_item", {
         description: "Clone a to-do or project — a faithful content copy through official write surfaces and " +
             "return the clone's uuid. Copies title, notes, tags, when, reminder, deadline, checklist " +
             "items and their checked state, container, and completed/canceled state with the exact " +
@@ -2097,12 +2274,12 @@ export function createThingsMcpServer(options = {}) {
             : await c.write.cloneProject(args.uuid, clone, writeOptions(args)));
     }));
     // -------------------------------------------------------------- projects
-    server.registerTool("add_project", {
+    registerTool("add_project", {
         description: "Create a project and return its uuid. Optionally place it in an area, schedule " +
             "it, set a deadline, and seed it with initial to-dos.",
         inputSchema: {
             title: z.string(),
-            notes: z.string().optional(),
+            notes: z.string().optional().describe(`Notes body — ${NOTES_FORMAT}`),
             area: z.string().optional().describe(`Destination area (${REF_FORMAT})`),
             when: whenSchema,
             deadline: z.string().optional().describe(DATE_FORMAT),
@@ -2137,7 +2314,7 @@ export function createThingsMcpServer(options = {}) {
             ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
         }, writeOptions(args)));
     }));
-    server.registerTool("move_project", {
+    registerTool("move_project", {
         description: "Move one or more projects as an ordered block (spec §4/§5). Pass at most one " +
             "destination: to_area, or no_area (leave the area — a project's complete detach). To " +
             "REORDER projects among their siblings without changing area, pass a position " +
@@ -2172,7 +2349,7 @@ export function createThingsMcpServer(options = {}) {
         return moveResult(await getClient().write.moveProjects(request, writeOptions(args)));
     }));
     // ----------------------------------------------------------------- areas
-    server.registerTool("add_area", {
+    registerTool("add_area", {
         description: "Create an area, optionally tagged. Tags must exist unless create_tags is set.",
         inputSchema: {
             title: z.string(),
@@ -2185,7 +2362,7 @@ export function createThingsMcpServer(options = {}) {
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.addArea({ title: args.title, ...(args.tags !== undefined && { tags: args.tags }) }, writeOptions(args)))));
     // ------------------------------------------------------------------ tags
-    server.registerTool("add_tag", {
+    registerTool("add_tag", {
         description: "Create a tag, optionally nested under an existing parent tag.",
         inputSchema: {
             title: z.string(),
@@ -2196,7 +2373,7 @@ export function createThingsMcpServer(options = {}) {
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.addTag({ title: args.title, ...(args.parent !== undefined && { parent: args.parent }) }, writeOptions(args)))));
-    server.registerTool("log_now", {
+    registerTool("log_now", {
         description: "Move completed items to the Logbook now. The result discloses how many items were moved " +
             "(observed.logged); when none are waiting it logs nothing — a clean no-op, not an error. " +
             "This cannot be undone.",
@@ -2204,10 +2381,13 @@ export function createThingsMcpServer(options = {}) {
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.logNow(writeOptions(args)))));
     // -------------------------------------------------- generic + discovery
-    server.registerTool("run_operation", {
+    registerTool("run_operation", {
         description: "Run any cataloged operation by kind — the generic entry for operations without a " +
             "dedicated tool (e.g. trash.empty). Call capabilities first for the catalog of " +
-            "operation kinds and their parameter shapes.",
+            "operation kinds and their parameter shapes (each entry carries a params list naming " +
+            "every field, whether it is optional, and the shape it accepts). A malformed params " +
+            "bag — an unknown field, a wrong type, a bare string where a container reference " +
+            "object belongs — is refused before anything runs.",
         inputSchema: {
             op: z.enum(OPERATION_KINDS),
             params: z
@@ -2233,11 +2413,13 @@ export function createThingsMcpServer(options = {}) {
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.run(args.op, args.params, writeOptions(args)))));
-    server.registerTool("batch", {
+    registerTool("batch", {
         description: "Run several operations in order, each independently — there are no transactions, " +
             "and a failure does not roll back earlier operations. A statically-invalid operation " +
-            "(bad shape, unknown op, a $ref to an undeclared/forward temp_id, a duplicate temp_id) " +
-            "refuses the WHOLE batch before anything runs, naming every bad operation. Otherwise " +
+            "(unknown op, an unknown or wrongly-typed param, a $ref to an undeclared/forward " +
+            "temp_id, a duplicate temp_id) refuses the WHOLE batch before anything runs, naming " +
+            "every bad operation and the field it names. A container param takes an object " +
+            '({"project": {"uuid": "…"}}), never a bare string. Otherwise ' +
             "per-operation results return in order. By DEFAULT a runtime failure STOPS the batch " +
             "(later operations reported not-run, with resume guidance in the summary); " +
             "continue_on_error runs past failures. " +
@@ -2248,8 +2430,11 @@ export function createThingsMcpServer(options = {}) {
             "reference a tag by title) and unique per batch. IDEMPOTENCY: op_id makes resubmission " +
             "safe — an operation matching an earlier success is reported already-applied, not " +
             "re-created (put an op_id on EVERY operation so a stopped batch can be resubmitted " +
-            "verbatim to resume). The result adds temp_id_mapping (handle → uuid) and undo_token, " +
-            "which reverses the whole batch as one unit via the undo tool.",
+            "verbatim to resume). TIMELINE: preserve_modified applies to EVERY operation (an " +
+            "operation may override it with its own options.preserve_modified), so a bulk re-tag " +
+            "stays off the modification-date timeline under one undo token. The result adds " +
+            "temp_id_mapping (handle → uuid) and undo_token, which reverses the whole batch as one " +
+            "unit via the undo tool.",
         inputSchema: {
             ops: z
                 .array(z.object({
@@ -2271,6 +2456,11 @@ export function createThingsMcpServer(options = {}) {
                     acknowledge_tag_subtree: z.boolean().optional(),
                     allow_non_empty_area: z.boolean().optional(),
                     dangerously_drive_gui: z.boolean().optional(),
+                    preserve_modified: z
+                        .boolean()
+                        .optional()
+                        .describe("Keep THIS operation off the modification-date timeline; overrides the " +
+                        "run-level preserve_modified (false opts one operation back on)"),
                 })
                     .optional(),
             }))
@@ -2297,6 +2487,12 @@ export function createThingsMcpServer(options = {}) {
                 ...(o?.acknowledge_tag_subtree === true && { acknowledgeTagSubtree: true }),
                 ...(o?.allow_non_empty_area === true && { allowNonEmptyArea: true }),
                 ...(o?.dangerously_drive_gui === true && { dangerouslyDriveGui: true }),
+                // Per-op override of the run-level preserve_modified; passed through
+                // when EXPLICIT (including false, which opts one op back onto the
+                // timeline) so the batch engine's `??` precedence sees it.
+                ...(o?.preserve_modified !== undefined && {
+                    preserveModified: o.preserve_modified,
+                }),
                 ...(ceiling !== undefined && { maxDisruption: ceiling }),
             };
             return {
@@ -2310,6 +2506,7 @@ export function createThingsMcpServer(options = {}) {
         const batchResult = await getClient().write.batch(ops, {
             ...(args.dry_run === true && { dryRun: true }),
             ...(args.continue_on_error === true && { continueOnError: true }),
+            ...(args.preserve_modified === true && { preserveModified: true }),
             actor: mcpActor(),
         });
         // First block: the per-op results, each FLATTENED to the wire shape (a
@@ -2340,7 +2537,7 @@ export function createThingsMcpServer(options = {}) {
             ],
         };
     }));
-    server.registerTool("reorder", {
+    registerTool("reorder", {
         description: "The ONE reorder tool — rearrange a single-KIND set IN PLACE: to-dos, projects, headings, " +
             "OR sidebar areas. This REARRANGES, never changes what an item belongs to (to change " +
             "membership use move_todo / move_project). All refs must be one kind; only to-dos and " +
@@ -2350,9 +2547,11 @@ export function createThingsMcpServer(options = {}) {
             "assembles the named items as a block at the EARLIEST one's current slot; start/end/" +
             "before/after position the block. A Today or This Evening member also holds a slot in its " +
             "container, so a set coherent on BOTH axes is ambiguous — pass `in` to name the axis. " +
-            "HEADINGS: same-project heading re-ranking runs the native heading-block wire (children " +
-            "follow); an archived heading is reorderable but repositioning it brings it back to open " +
-            "(disclosed in the result). AREAS: this drives the local Things app (sidebar drag) and " +
+            "HEADINGS: same-project heading re-ranking drives the local Things app (keyboard " +
+            "shortcuts on the heading row; children follow) and must be turned on the same way as " +
+            "areas below. It covers the open headings only — a completed or canceled heading is not " +
+            "shown in the project view, so it is stepped over and cannot be moved or used as an " +
+            "anchor. AREAS: this drives the local Things app (sidebar drag) and " +
             "must be turned on with `things config set ui-enabled true` plus dangerously_drive_gui; " +
             "the areas' projects and to-dos are untouched. Ordering the Today, Inbox, or Someday " +
             "lists, or a project's to-dos, must first be enabled once via `things config set " +
@@ -2390,7 +2589,7 @@ export function createThingsMcpServer(options = {}) {
         };
         return moveResult(await getClient().write.reorderAny(request, writeOptions(args)));
     }));
-    server.registerTool("undo", {
+    registerTool("undo", {
         description: "Undo the last N changes, newest first (changes made directly in the Things app " +
             "cannot be undone here). By default this undoes only changes made through THIS " +
             "connection — this client's own writes; it will not touch the user's own edits, or " +
@@ -2453,7 +2652,7 @@ export function createThingsMcpServer(options = {}) {
         });
         return jsonResult(items);
     }));
-    server.registerTool("capabilities", {
+    registerTool("capabilities", {
         description: "Support reference for every operation kind usable with run_operation and batch: " +
             "whether it is available, its caveats, and the confirmation parameters it needs.",
         inputSchema: {
@@ -2464,7 +2663,7 @@ export function createThingsMcpServer(options = {}) {
         },
         annotations: READ_ONLY,
     }, async (args) => guard(() => jsonResult(capabilitiesTable(args.op))));
-    server.registerTool("doctor", {
+    registerTool("doctor", {
         description: "Check the environment: whether the Things app and its database are reachable, " +
             "whether changes can be made, any one-time setup still needed (macOS permissions, " +
             "the app's 'Enable Things URLs' setting), whether the environment changed since " +
@@ -2488,7 +2687,7 @@ export function createThingsMcpServer(options = {}) {
             ? jsonResult(report)
             : errorResult(error ?? { code: "unexpected", message: "no report" });
     }));
-    server.registerTool("op_result", {
+    registerTool("op_result", {
         description: "Look up what happened to a write you dispatched with op_id, from the local change history " +
             "alone (opens no database, changes nothing). Use it to recover the outcome when the write " +
             "call was interrupted before it returned: report FOUND (the final result + target + " +