circal-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,10 @@
 # circal-mcp
 
 A stdio [MCP](https://modelcontextprotocol.io) server that reads and writes
-circal's own mirror file — the `.json` a browser tab keeps in sync on disk
-through the File System Access API (see `src/lib/mirror.ts` and
-`src/lib/mirrorLink.ts`). It imports circal's own domain layer
+circal's own mirror file — the `.json` a browser tab or the macOS app keeps
+in sync on disk, through the File System Access API on the web and the
+shell's own bridge in the app (see `src/lib/mirror.ts`, `src/lib/mirrorLink.ts`
+and `mac/main.swift`'s `MirrorFile`). It imports circal's own domain layer
 (`src/lib/events.ts`, `recur.ts`, `quickadd.ts`, `mutate.ts`, `backup.ts`, …),
 so an agent and the app can never disagree about what a legal event, an
 occurrence, or a recurrence rule is.
@@ -18,10 +19,11 @@ again, the same as any second writer would.
 
 ## Quick start
 
-A `FileSystemFileHandle` (what the browser hands circal when the mirror is
-turned on) never exposes the full path it came from: that is deliberate
-browser privacy design, so circal cannot print it for you. `--find` searches
-the places a mirror file usually lands and does that work instead.
+A `FileSystemFileHandle` (what a browser hands circal when the mirror is turned on there) never
+exposes the full path it came from: that is deliberate browser privacy design, so circal cannot print
+it for you. The macOS app does not have this problem — it mints and adopts a mirror at a fixed path
+on first launch, no gesture required — so `--find` checks that path first, by name, then falls back
+to the browser case and searches the places a mirror file usually lands.
 
 ```sh
 npx -y circal-mcp --find
@@ -32,6 +34,22 @@ zone, revision) plus a ready-to-paste config block. Paste that block into
 your client below, swap the path if it picked up the wrong file, then
 restart the client.
 
+> **Use a locally built bundle, not `npx circal-mcp`.** The published
+> `circal-mcp@0.1.0` predates several fields in `src/lib` (`free`,
+> `remindLead`, `organizer` and the guest pair on an event; `backupNudge`,
+> `backupInterval`, `deviceZone`, `stampedZones` in settings). Every write
+> round-trips the whole document through its reader, so it silently drops
+> those nine keys — measured, same fixture, two bundles. A current server
+> refuses to write a file whose format is newer than its own, so this cannot
+> happen unnoticed any more, but the published bundle is still stale.
+>
+> ```sh
+> pnpm build:mcp   # -> mcp/dist/circal-mcp.mjs
+> ```
+>
+> Then use `node /absolute/path/to/circal/mcp/dist/circal-mcp.mjs` wherever
+> the examples below say `npx -y circal-mcp`.
+
 ### Claude Desktop
 
 Add to `claude_desktop_config.json`:
@@ -81,9 +99,9 @@ Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
 }
 ```
 
-No mirror file yet: turn it on from circal's Settings panel, then run
-`--find` again. Run `npx -y circal-mcp --help` for the full flag and
-environment variable list.
+No mirror file yet: on the Mac app there is almost always one already (`--find` should have caught
+it); in a browser, turn the mirror on from circal's Settings panel, then run `--find` again. Run
+`npx -y circal-mcp --help` for the full flag and environment variable list.
 
 ## From source (contributors)
 

package/dist/circal-mcp.mjs

@@ -1460,7 +1460,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 
 // mcp/file.ts
 import { randomBytes } from "node:crypto";
-import { readFile, rename, writeFile } from "node:fs/promises";
+import { open, readFile, rename, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 // src/lib/time.ts
@@ -2162,6 +2162,78 @@ function fuzzyScore(text, query) {
 
 // src/lib/events.ts
 var ICON_MAX = 16;
+var ICON_NAME_MAX = 48;
+function isIconName(icon) {
+  return /^[a-z0-9-]+$/.test(icon);
+}
+function firstGrapheme(value) {
+  const text = value.trim();
+  if (!text) return "";
+  if (typeof Intl.Segmenter === "function") {
+    const [first] = new Intl.Segmenter(void 0, { granularity: "grapheme" }).segment(text);
+    return first ? first.segment.slice(0, ICON_MAX) : "";
+  }
+  return [...text][0]?.slice(0, ICON_MAX) ?? "";
+}
+function readMark(value) {
+  if (typeof value !== "string") return "";
+  const mark = value.trim();
+  if (mark === "") return "";
+  if (isIconName(mark)) return mark.length <= ICON_NAME_MAX ? mark : "";
+  return firstGrapheme(mark);
+}
+var REMIND_INHERIT = -1;
+var REMIND_SILENT = -2;
+var REMIND_LEAD_MAX = 40320;
+function readRemindLead(value) {
+  if (value === REMIND_SILENT) return REMIND_SILENT;
+  if (typeof value !== "number" || !Number.isInteger(value)) return REMIND_INHERIT;
+  if (value < 0 || value > REMIND_LEAD_MAX) return REMIND_INHERIT;
+  return value;
+}
+var PARTSTATS = ["needs-action", "accepted", "declined", "tentative"];
+var ATTENDEE_MAX = 32;
+var GUEST_NAME_MAX = 64;
+var GUEST_ADDRESS_MAX = 254;
+var ATTENDEE_COUNT_MAX = 9999;
+function readText(value, max) {
+  return typeof value === "string" ? value.trim().slice(0, max) : "";
+}
+function readPartstat(value) {
+  if (typeof value !== "string") return "needs-action";
+  const lower = value.trim().toLowerCase();
+  return PARTSTATS.includes(lower) ? lower : "needs-action";
+}
+function readPerson(value) {
+  if (value === null || typeof value !== "object") return null;
+  const record = value;
+  const address = readText(record.address, GUEST_ADDRESS_MAX);
+  if (!address) return null;
+  return { name: readText(record.name, GUEST_NAME_MAX), address };
+}
+function readGuests(list, count) {
+  const seen = /* @__PURE__ */ new Set();
+  const people = [];
+  if (Array.isArray(list)) {
+    for (const entry of list) {
+      const person = readPerson(entry);
+      if (!person) continue;
+      const key = person.address.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      people.push({
+        ...person,
+        status: readPartstat(entry.status)
+      });
+    }
+  }
+  const attendees = people.slice(0, ATTENDEE_MAX);
+  const claimed = typeof count === "number" && Number.isInteger(count) && count > 0 ? count : people.length;
+  return {
+    attendees,
+    attendeeCount: Math.min(Math.max(claimed, people.length), ATTENDEE_COUNT_MAX)
+  };
+}
 function overridesIn(events) {
   const out = /* @__PURE__ */ new Map();
   for (const event of events) {
@@ -2249,7 +2321,7 @@ function toggleDoneKey(keys, at) {
 }
 var DEFAULT_WAKING = { from: 8 * 60, to: 22 * 60 };
 function freeGaps(occurrences, minMinutes, from, to) {
-  const busy = occurrences.filter((o) => !o.event.allDay).map((o) => ({ start: Math.max(o.startMin, from), end: Math.min(o.endMin, to) })).filter((b) => b.end > b.start).sort((a, b) => a.start - b.start);
+  const busy = occurrences.filter((o) => !o.event.allDay && !o.event.free).map((o) => ({ start: Math.max(o.startMin, from), end: Math.min(o.endMin, to) })).filter((b) => b.end > b.start).sort((a, b) => a.start - b.start);
   const gaps = [];
   let cursor = from;
   for (const block of busy) {
@@ -3098,6 +3170,13 @@ var DEFAULT_SETTINGS = {
   // a day here, not half of one, so an hour has exactly one place on it and
   // `13` is where `13` is. AM/PM is a preference, and it is one click away.
   clock: "24h",
+  // Unknown until the first launch writes it, and written silently there: a
+  // browser with nothing stored has no "before", and the question this field
+  // exists to ask is only ever about a change.
+  deviceZone: "",
+  // Nothing stamped, which is every browser that has never travelled and
+  // every one that answered "move".
+  stampedZones: [],
   secondZone: "",
   showZoneName: true,
   showZoneOffset: true,
@@ -3178,6 +3257,14 @@ var DEFAULT_SETTINGS = {
   // Ten minutes. Long enough to walk somewhere, short enough that the thing
   // is still the next thing when it lands.
   remindLead: 10,
+  // On. This is the one interruption in the app that defends against losing
+  // everything rather than missing one thing, and the browsers it is aimed at
+  // have no other warning — so unlike `remind` it earns the aggressive default.
+  backupNudge: true,
+  // Thirty days. A month is long enough that a working calendar has changed
+  // enough to be worth saving again, short enough that a lost month is a loss
+  // and not a catastrophe.
+  backupInterval: 30,
   // An hour, which is what `DEFAULT_DURATION` has always been and what a
   // VEVENT with no DTEND is read as. This setting exists to be *changed* — a
   // day of thirty-minute meetings is a real working life — not to have a new
@@ -3231,7 +3318,19 @@ function draftEvent(day, startMin, endMin, calendarId, repeat = "never") {
     color: "",
     icon: "",
     task: false,
-    doneKeys: []
+    doneKeys: [],
+    // Busy: a gesture that named a time meant that time to be spoken for.
+    free: false,
+    // Inheriting, which is the only answer a gesture gives: the drag named a
+    // time, not how much warning it wants about it.
+    remindLead: REMIND_INHERIT,
+    // Nobody, and no way to make it anybody: circal has no channel to send an
+    // invitation on, so a draft has no guest list and the editor offers no
+    // control that would make one. These fields only ever arrive from a file
+    // somebody else wrote.
+    organizer: null,
+    attendees: [],
+    attendeeCount: 0
   };
 }
 
@@ -3245,6 +3344,17 @@ function readSettings(value) {
     // version that has ever had the setting.
     clock: value.clock === "12h" || value.clock === "24h" ? value.clock : DEFAULT_SETTINGS.clock,
     secondZone: typeof value.secondZone === "string" ? value.secondZone : "",
+    // The zone the browser that wrote this backup was in. Carried rather than
+    // dropped, and deliberately not replaced with the reader's own: a Berlin
+    // calendar restored in New York is exactly the journey the travel notice
+    // exists to ask about, and the events in the file are floating. `sane()`
+    // refuses a zone `Intl` cannot resolve; absent reads as a first run, which
+    // asks nothing.
+    deviceZone: typeof value.deviceZone === "string" ? value.deviceZone : "",
+    // The zones that browser's "keep" answer stamped, so the row that offers
+    // to take them off survives a restore with the events it is about. Strings
+    // only here; `sane()` is what refuses one `Intl` cannot resolve.
+    stampedZones: Array.isArray(value.stampedZones) ? value.stampedZones.filter((zone) => typeof zone === "string") : [],
     // The dial switches read absent-as-on: a backup written before they
     // existed came from a dial that was showing all of them.
     showZoneName: value.showZoneName !== false,
@@ -3309,6 +3419,12 @@ function readSettings(value) {
     moon: value.moon === true || typeof value.moonPhase === "string" && value.moonPhase !== "off",
     remind: value.remind === true,
     remindLead: typeof value.remindLead === "number" ? value.remindLead : DEFAULT_SETTINGS.remindLead,
+    // Absent-as-on, like the dial switches: a backup written before the nudge
+    // existed came from a build that could not have turned this data-safety
+    // warning off, so it reads as the default rather than as a choice.
+    backupNudge: value.backupNudge !== false,
+    // Types only: `sane()` pins an interval off the list to the default.
+    backupInterval: typeof value.backupInterval === "number" ? value.backupInterval : DEFAULT_SETTINGS.backupInterval,
     // What a new event starts as. `sane()` clamps the length; the calendar is
     // an id and is deliberately not checked against the backup's own
     // calendars — `defaultCalendarId` resolves it at the moment it is used,
@@ -3363,12 +3479,33 @@ function readEvent(value) {
     seriesId: typeof value.seriesId === "string" ? value.seriesId : "",
     seriesKey: typeof value.seriesKey === "string" ? value.seriesKey : "",
     color: typeof value.color === "string" ? value.color : "",
-    icon: typeof value.icon === "string" ? value.icon.slice(0, ICON_MAX) : "",
+    // What a legal mark is lives in `events.ts`, next to the two vocabularies
+    // it has to tell apart. This used to slice at one shared cap, which turned
+    // ten of the 247 shipped names into strings matching no path.
+    icon: readMark(value.icon),
     task,
     // The same instant-key check EXDATE gets, and the same reason: a key this
     // does not spell matches no occurrence, so it is a row of dead weight that
     // survives every future export.
-    doneKeys: readDoneKeys(value.doneKeys)
+    doneKeys: readDoneKeys(value.doneKeys),
+    // Anything other than a literal `true` is busy, which is what an event
+    // exported before this field existed was. A truthy string in a
+    // hand-edited blob must not quietly take a meeting off the day's total.
+    free: value.free === true,
+    // What a legal lead is lives in `remind.ts`, beside the three states it
+    // has to distinguish: an unreadable one comes back inheriting, which is
+    // what an event exported before this field existed already did.
+    remindLead: readRemindLead(value.remindLead),
+    // The one field on this model that arrives from a stranger with no natural
+    // length, so this is where the caps are enforced rather than where they are
+    // chosen: `readGuests` in `events.ts` owns the numbers, because a
+    // subscription's ATTENDEE lines never pass through this file and the two
+    // paths must not disagree about how big a guest list may be. The count
+    // comes through so a restore prints the same "and 40 others" the import
+    // did — clamped up to the list it labels, since a blob understating it
+    // would print a negative remainder.
+    organizer: readPerson(value.organizer),
+    ...readGuests(value.attendees, value.attendeeCount)
   };
 }
 function readCalendar(value) {
@@ -3380,11 +3517,12 @@ function readCalendar(value) {
     id,
     name: typeof name === "string" && name ? name : id,
     color: typeof color === "string" && color ? color : "#8ecbff",
-    // Length is the whole check. An icon name this build does not carry
-    // renders as the dot rather than as nothing, so an unknown one is worth
-    // keeping — a backup restored into an older build and back again should
-    // not lose the mark — but an unbounded string here is a paste.
-    icon: typeof icon === "string" ? icon.slice(0, ICON_MAX) : "",
+    // Same validator as an event's, same reason. An icon name this build does
+    // not carry still renders as the dot rather than as nothing, so an unknown
+    // one is worth keeping — a backup restored into an older build and back
+    // again should not lose the mark — but an unbounded string is a paste, and
+    // an over-long *name* is now dropped rather than cut into junk.
+    icon: readMark(icon),
     visible: value.visible !== false,
     ...feedUrl ? { feed: { url: feedUrl, fetchedAt: 0, error: "" } } : {}
   };
@@ -3447,7 +3585,11 @@ function readMirrorFile(text) {
     // A plain `.json` backup has no zone. Absent means "written by something
     // that did not say", which the reader treats as agreeing with it — the
     // alternative is refusing to open every backup ever exported.
-    zone: typeof envelope.zone === "string" ? envelope.zone : ""
+    zone: typeof envelope.zone === "string" ? envelope.zone : "",
+    // Absent reads as this build's own, for the reason `zone` does: a plain
+    // `.json` backup handed to the mirror is a case the shared format exists
+    // to allow, and refusing every export ever taken would be the wrong trade.
+    version: typeof envelope.version === "number" && Number.isFinite(envelope.version) ? envelope.version : MIRROR_VERSION
   };
 }
 
@@ -3474,9 +3616,30 @@ async function readMirror(path2) {
   return contents;
 }
 async function atomicWrite(path2, body) {
-  const tmp = join(dirname(path2), `.circal-mcp-${randomBytes(6).toString("hex")}.tmp`);
-  await writeFile(tmp, body, "utf8");
-  await rename(tmp, path2);
+  const dir = dirname(path2);
+  const tmp = join(dir, `.circal-mcp-${randomBytes(6).toString("hex")}.tmp`);
+  try {
+    const file = await open(tmp, "w");
+    try {
+      await file.writeFile(body, "utf8");
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+    await rename(tmp, path2);
+  } catch (error) {
+    await rm(tmp, { force: true });
+    throw error;
+  }
+  try {
+    const entry = await open(dir, "r");
+    try {
+      await entry.sync();
+    } finally {
+      await entry.close();
+    }
+  } catch {
+  }
 }
 function zoneWarning(contents) {
   const here = localZone();
@@ -3491,6 +3654,12 @@ function assertZoneAllowsMutation(contents, env) {
     `Refusing to write: the file's zone (${contents.zone}) does not match this server's (${here}) \u2014 a write here could land on the wrong day there. Set CIRCAL_ALLOW_ZONE_MISMATCH=1 to write anyway.`
   );
 }
+function assertVersionAllowsMutation(contents) {
+  if (contents.version <= MIRROR_VERSION) return;
+  throw new RefusalError(
+    `Refusing to write: the file's format is version ${contents.version} and this server understands ${MIRROR_VERSION}. Writing it would drop every field this build has no name for. Rebuild circal-mcp from the matching source (pnpm build:mcp) and retry.`
+  );
+}
 async function loadForRead(ctx2) {
   const contents = await readMirror(ctx2.path);
   return { contents, warning: zoneWarning(contents) };
@@ -3498,6 +3667,7 @@ async function loadForRead(ctx2) {
 async function casWriteOnce(ctx2, mutate) {
   for (let attempt = 0; attempt < 2; attempt++) {
     const before = await readMirror(ctx2.path);
+    assertVersionAllowsMutation(before);
     assertZoneAllowsMutation(before, ctx2.env);
     const { result, summary } = mutate(before);
     const after = await readMirror(ctx2.path);
@@ -3542,6 +3712,9 @@ function roots(home) {
     join2(home, "Sync")
   ];
 }
+function appDefault(home) {
+  return join2(home, "Library", "Application Support", "circal", "calendar.json");
+}
 async function jsonFilesUnder(root) {
   const found = [];
   const top = await listDir(root);
@@ -3581,6 +3754,7 @@ async function asMirror(path2) {
 async function runFind(home = homedir()) {
   const searchRoots = roots(home);
   const candidates = /* @__PURE__ */ new Set();
+  candidates.add(appDefault(home));
   for (const root of searchRoots) {
     for (const path2 of await jsonFilesUnder(root)) candidates.add(path2);
   }
@@ -3592,6 +3766,7 @@ async function runFind(home = homedir()) {
   if (hits.length === 0) {
     console.log("No circal mirror file found.\n");
     console.log("Searched these locations (their own files, and one level of subdirectories):");
+    console.log(`  ${appDefault(home)}`);
     for (const root of searchRoots) console.log(`  ${root}`);
     console.log(
       "\nTurn the mirror on from circal's Settings panel to create a file, then run this again."
@@ -3836,7 +4011,20 @@ function buildEventRecord(input, calendars, settings) {
     color: input.color ?? "",
     icon: input.icon ?? "",
     task: span.task,
-    doneKeys: []
+    doneKeys: [],
+    // Busy. There is no tool argument for this yet, and an agent asked to put
+    // an hour in the diary means the hour to be spoken for.
+    free: false,
+    // Inheriting, for the same reason: no tool argument names a lead, and an
+    // event created with one of its own would be an agent quietly deciding
+    // how much warning its user wants.
+    remindLead: REMIND_INHERIT,
+    // Nobody, for the reason there is no tool argument and never will be: an
+    // agent has no channel to invite anyone on either, so a guest list it
+    // assembled would be a list of people who were never asked.
+    organizer: null,
+    attendees: [],
+    attendeeCount: 0
   });
 }
 function applyPatchToEvent(base, input, calendars, settings, anchorMs = base.start) {
@@ -3858,7 +4046,25 @@ function applyPatchToEvent(base, input, calendars, settings, anchorMs = base.sta
     color: input.color ?? base.color,
     icon: input.icon ?? base.icon,
     task: span.task,
-    doneKeys: base.doneKeys
+    doneKeys: base.doneKeys,
+    // Carried, like every other field a patch does not name: `validate` reads
+    // the draft through `backup.readEvent`, which defaults an absent `free`
+    // to busy — so leaving it out would quietly rebook a free event the
+    // moment its title was edited.
+    free: base.free,
+    // Carried for exactly the reason above, and this is the field where it
+    // costs most: an event the user silenced would start speaking again the
+    // moment an assistant fixed a typo in its title, because `readEvent`
+    // reads an absent lead as inheriting.
+    remindLead: base.remindLead,
+    // Carried, and this is the field where dropping it would be least
+    // recoverable: the guest list is a record of a message somebody else sent,
+    // and `readEvent` reads an absent one as no invitation at all — so an
+    // assistant fixing a typo in the title would erase the only copy of who
+    // had asked and who was coming.
+    organizer: base.organizer,
+    attendees: base.attendees,
+    attendeeCount: base.attendeeCount
   });
 }
 function calendarName(calendars, id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circal-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "MCP server for circal — read and write your calendar through its mirror file",
   "license": "MIT",