@cpenned/mcp 0.9.1 → 0.10.0

package/README.md

@@ -15,8 +15,9 @@ Set via environment variables:
 | `OPEN_BRAIN_CLIENT_TYPE` | no       | `X-Client` stamped on the audit log (default `mcp`)                |
 
 The key's scopes gate the tools: resource tools need `<resource>:read|write`,
-review tools `reviews:*`, settings tools `settings:read|write`, and
-`find_tasks` / `ai_triage` need `ai:invoke`. `list_shares`/`list_shared_tasks`
+review tools `reviews:*`, settings tools `settings:read|write`, history tools
+`history:read` (plus `history:write` and the entity's write scope for
+`revert_change`), and `find_tasks` / `ai_triage` need `ai:invoke`. `list_shares`/`list_shared_tasks`
 additionally need the key to have been minted with `includeGrants: true` (via
 `create_key`'s `includeGrants` flag or the web app) - without it, a key only
 ever sees the vault's own data, even with `*`.
@@ -186,6 +187,16 @@ Point the `args` at the absolute `packages/mcp/dist/index.js` path with
 - **Profile**: `get_profile`, `update_profile` (`displayName`, 1-60 chars,
   and/or `notifications: {emailOnMention?, emailOnAssign?}` to turn mention and
   assignment emails on or off; avatar upload is web-only).
+- **History** (every change from every surface, with before/after values):
+  `list_history` (filters `entityType`, `entityId`, `source`, `actor`,
+  `since`/`until` as epoch ms or ISO, `batchId`, `limit` 1-200, `cursor`;
+  only entity types the key can read), `get_history_entry`, `revert_change`
+  (`{id}` or `{batchId}` for a whole bulk action, `force?`). An update revert
+  restores fields still equal to their `after` value and reports the rest as
+  conflicts unless `force`; reverting a create soft-deletes, reverting a delete
+  restores, tag/link adds and removes invert. The result's `batchId` reverts
+  the revert (redo). System rows, recurrence spawns, settings, keys, webhooks
+  and attachments are not revertable (400).
 - **Key management**: `create_key` (optional `includeGrants` so the minted key
   can see gardens shared with its owner - only settable if the calling key
   itself has it), `list_keys`, `rotate_key`, `revoke_key`

package/dist/tools/api.js

@@ -5,6 +5,7 @@ import { registerCalendarTools } from "./calendar.js";
 import { registerCommentTools } from "./comments.js";
 import { registerGardenTools } from "./gardens.js";
 import { registerHabitTools } from "./habits.js";
+import { registerHistoryTools } from "./history.js";
 import { registerKeyTools } from "./keys.js";
 import { registerListTools } from "./lists.js";
 import { registerPeopleTools } from "./people.js";
@@ -37,5 +38,6 @@ export function registerApiTools(server, client) {
     registerSettingsTools(server, client);
     registerShareTools(server, client);
     registerProfileTools(server, client);
+    registerHistoryTools(server, client);
 }
 //# sourceMappingURL=api.js.map

package/dist/tools/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/tools/api.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,UAAU,gBAAgB,CAAC,MAAiB,EAAE,MAAuB;IACzE,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/tools/api.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,UAAU,gBAAgB,CAAC,MAAiB,EAAE,MAAuB;IACzE,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC"}

package/dist/tools/history.js

@@ -0,0 +1,93 @@
+// Change history tools. Every write to the vault (from any surface) is recorded
+// with before/after values; list_history browses it and revert_change undoes a
+// change or a whole batch. Reverting a revert is a redo.
+import { z } from "zod";
+import { apiPath } from "../client.js";
+import { runTool } from "../result.js";
+import { idField } from "./schemas.js";
+export const historyEntityTypeEnum = z.enum([
+    "task",
+    "project",
+    "garden",
+    "tag",
+    "person",
+    "list",
+    "apiKey",
+    "attachment",
+    "webhook",
+    "vault",
+    "readingListItem",
+    "stravaActivity",
+    "habit",
+    "book",
+    "calendarEvent",
+    "calendarConnection",
+    "taskComment",
+]);
+const timeField = z
+    .union([z.number(), z.string()])
+    .describe("Epoch milliseconds or an ISO date/time, e.g. 2026-11-04 or 2026-11-04T09:00:00Z");
+const listHistorySchema = z.object({
+    entityType: historyEntityTypeEnum.optional(),
+    entityId: z.string().optional().describe("Only changes to this entity"),
+    source: z
+        .string()
+        .optional()
+        .describe("Surface that made the change: web, mac, ios, mcp, cli, raycast, api, ai, chat, email, meld, integration, system, strava, linear"),
+    actor: z
+        .string()
+        .optional()
+        .describe('Who made it: an API key id, a user id, "ai", "email" or "system"'),
+    since: timeField.optional(),
+    until: timeField.optional(),
+    batchId: z
+        .string()
+        .optional()
+        .describe("Only the changes of one bulk/multi-entity action"),
+    limit: z.number().int().min(1).max(200).optional().describe("Page size, default 50"),
+    cursor: z.string().optional().describe("nextCursor from a previous page"),
+});
+export function listHistory(client, args) {
+    return client.get("/v1/history", { ...args });
+}
+const getHistoryEntrySchema = z.object({ id: idField.describe("History entry id") });
+export function getHistoryEntry(client, args) {
+    return client.get(apiPath `/v1/history/${args.id}`);
+}
+const revertChangeSchema = z.object({
+    id: idField.optional().describe("History entry id to revert"),
+    batchId: idField
+        .optional()
+        .describe("Revert every change of one batch instead (a bulk or multi-entity action)"),
+    force: z
+        .boolean()
+        .optional()
+        .describe("Overwrite fields that changed since this entry (conflicts). Default false skips them."),
+});
+export function revertChange(client, args) {
+    const body = args.force === undefined ? {} : { force: args.force };
+    if (args.batchId && !args.id)
+        return client.post(apiPath `/v1/history/batches/${args.batchId}/revert`, body);
+    if (args.id && !args.batchId)
+        return client.post(apiPath `/v1/history/${args.id}/revert`, body);
+    throw new Error("Pass exactly one of id or batchId");
+}
+export function registerHistoryTools(server, client) {
+    server.registerTool("list_history", {
+        title: "List change history",
+        description: "Recent changes across the vault, newest first: { items, hasMore, nextCursor }. Each entry has id, entityType, entityId, action, summary, actor, source, at (epoch ms), fields, before/after (changed fields only; a missing key means unset), batchId, revertOf, revertedBy and revertable. Only entity types this key can read are returned. Filter by entity, type, source, actor, time window or batch.",
+        inputSchema: listHistorySchema.shape,
+    }, (args) => runTool(() => listHistory(client, args)));
+    server.registerTool("get_history_entry", {
+        title: "Get history entry",
+        description: "One change history entry by id, with its before/after values.",
+        inputSchema: getHistoryEntrySchema.shape,
+    }, (args) => runTool(() => getHistoryEntry(client, args)));
+    server.registerTool("revert_change", {
+        title: "Revert change",
+        description: "Undo one change (id) or every change of a batch (batchId). Updates write back `before` for each field still equal to `after`; fields edited since are conflicts and skipped unless force. Reverting a create soft-deletes (tasks/projects canceled, gardens/people/habits archived, tags/saved lists hard-deleted); reverting a delete restores; tag/link adds and removes invert. Returns { batchId, results, entries }: per-entity status (reverted, partial, conflict, noop, skipped), reverted fields, conflicts, skipped and newEntityId when a hard-deleted record returns under a new id. Revert the returned batchId to redo. Some changes are not revertable (system rows, recurrence spawns, settings, keys, webhooks, attachments) and fail with 400. Needs history:write plus the entity's write scope.",
+        inputSchema: revertChangeSchema.shape,
+        annotations: { destructiveHint: true },
+    }, (args) => runTool(() => revertChange(client, args)));
+}
+//# sourceMappingURL=history.js.map

package/dist/tools/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../src/tools/history.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cpenned/mcp",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "MCP server for Open Brain - a thin adapter over the /v1 HTTP API.",
   "type": "module",
   "license": "MIT",

package/skills/open-brain-mcp/SKILL.md

@@ -241,6 +241,15 @@ pre-guessing constraints.
   `notifications: {emailOnMention, emailOnAssign}`), `update_profile
   {displayName?, notifications?: {emailOnMention?, emailOnAssign?}}` (pass at
   least one; display name 1-60 chars; avatar upload is web-only).
+- **History** (every write from every surface, with before/after values):
+  `list_history` (filters `entityType`, `entityId`, `source`, `actor`,
+  `since`/`until` as epoch ms or ISO date/time, `batchId`, `limit` 1-200
+  default 50, `cursor`; newest first, `{ items, hasMore, nextCursor }`),
+  `get_history_entry {id}`, `revert_change {id}` or `revert_change
+  {batchId}` (plus `force?`). Entries carry `summary` (human line),
+  `actor`, `source`, `at`, `fields`, `before`/`after` (changed fields only;
+  a missing key means unset), `batchId`, `revertOf`, `revertedBy`,
+  `revertable`. See the undo workflow below.
 - **Keys**: `create_key` (optional `includeGrants` to let the new key see
   gardens shared with its owner - only settable if the calling key itself
   has it), `list_keys`, `rotate_key`, `revoke_key`. `rotate_key` and
@@ -331,6 +340,21 @@ pre-guessing constraints.
   link it to a person at the same time, pass `tagIds`/`personIds` inline
   instead of following up with separate calls.
 
+- **Undo a change** → `list_history` filtered by `entityId` (or `since`)
+  to find the entry, check `revertable`, then `revert_change {id}`. A bulk or
+  multi-entity action shares one `batchId`; undo all of it with
+  `revert_change {batchId}`. Update reverts write `before` back only for
+  fields whose current value still equals `after`; fields edited since come
+  back as `conflicts` (`{field, expected, current}`) and are left alone.
+  Show the user the conflicts and only re-run with `force: true` if they want
+  them overwritten. Reverting a create soft-deletes (tasks/projects
+  canceled, gardens/people/habits archived, books/reading/Strava deleted;
+  tags and saved lists are hard-deleted), reverting a delete restores (a
+  hard-deleted tag/saved list returns under `newEntityId`), tag/link
+  add/remove invert. The result is `{ batchId, results, entries }` with a
+  per-entity `status` (`reverted`, `partial`, `conflict`, `noop`,
+  `skipped`). To redo, revert the returned `batchId`.
+
 ## Gotchas
 
 - Tools act on the vault behind the configured API key. If the user's web tasks
@@ -339,7 +363,10 @@ pre-guessing constraints.
 - Scopes gate tools: resource tools need `<resource>:read|write` (people tools
   `people:read|write`, settings tools `settings:read|write`, reading list tools
   `reading:read|write`, Strava tools `strava:read|write`, book tools
-  `books:read|write`, calendar tools `calendar:read|write`), review tools
+  `books:read|write`, calendar tools `calendar:read|write`), history tools
+  `history:read` (rows only for entity types the key can also read) and
+  `revert_change` `history:write` plus the write scope of each entity it
+  touches, review tools
   `reviews:*`, `find_tasks` needs `ai:invoke` + `tasks:read`, `ai_triage` needs
   `ai:invoke` + `tasks:write`, `reading:write`, `habits:write`, and
   `books:write` (it can create any of those), the `*_key` tools need `keys:manage`. A missing scope returns a
@@ -348,6 +375,10 @@ pre-guessing constraints.
   web-only flow, `POST /v1/uploads` before setting `coverStorageId`), but a
   key used for that flow needs `books:write` alongside `tasks:write`/
   `projects:write`.
+- `revert_change` fails with a 400 "Invalid revert" for changes that are not
+  revertable (`revertable: false`: system rows, recurrence spawns, settings,
+  keys, webhooks, attachments, oversized values). Check the flag before
+  offering an undo.
 - `sync_strava_activities` requires a Strava account already connected (via
   the web UI's Settings page) — it does nothing useful if nobody has
   authorized the app yet.