@cpenned/mcp 0.8.4 → 0.9.0

package/dist/tools/views.js

@@ -1,20 +1,22 @@
 // Opinionated read tools: computed views and the review system. Views are
-// timezone-aware (tz overrides the vault default); review tools cover the due
+// timezone-aware (tz overrides the host timezone the server sends); review tools cover the due
 // queue, garden deep-review, forcing a garden into review, and marking items
 // reviewed (which restarts their clock).
 import { z } from "zod";
+import { apiPath } from "../client.js";
 import { runTool } from "../result.js";
+import { idField } from "./schemas.js";
 const getViewSchema = z.object({
     view: z.enum(["today", "upcoming", "overdue"]),
     tz: z
         .string()
         .optional()
-        .describe("IANA timezone (e.g. America/New_York); defaults to the vault timezone"),
+        .describe("IANA timezone (e.g. America/New_York); defaults to the timezone of the machine running this MCP server"),
     limit: z.number().int().positive().optional(),
     cursor: z.string().optional(),
 });
 export function getView(client, args) {
-    return client.get(`/v1/views/${args.view}`, {
+    return client.get(apiPath `/v1/views/${args.view}`, {
         tz: args.tz,
         limit: args.limit,
         cursor: args.cursor,
@@ -27,20 +29,20 @@ const getReviewsSchema = z.object({
 export function getReviews(client, args) {
     return client.get("/v1/reviews", { gardenId: args.gardenId, limit: args.limit });
 }
-const gardenIdSchema = z.object({ gardenId: z.string() });
+const gardenIdSchema = z.object({ gardenId: idField });
 export function reviewGarden(client, args) {
-    return client.get(`/v1/gardens/${args.gardenId}/review`);
+    return client.get(apiPath `/v1/gardens/${args.gardenId}/review`);
 }
 export function requestGardenReview(client, args) {
-    return client.post(`/v1/gardens/${args.gardenId}/request-review`);
+    return client.post(apiPath `/v1/gardens/${args.gardenId}/request-review`);
 }
-const markTaskReviewedSchema = z.object({ taskId: z.string() });
+const markTaskReviewedSchema = z.object({ taskId: idField });
 export function markTaskReviewed(client, args) {
-    return client.post(`/v1/tasks/${args.taskId}/reviewed`);
+    return client.post(apiPath `/v1/tasks/${args.taskId}/reviewed`);
 }
-const markProjectReviewedSchema = z.object({ projectId: z.string() });
+const markProjectReviewedSchema = z.object({ projectId: idField });
 export function markProjectReviewed(client, args) {
-    return client.post(`/v1/projects/${args.projectId}/reviewed`);
+    return client.post(apiPath `/v1/projects/${args.projectId}/reviewed`);
 }
 export function registerViewTools(server, client) {
     server.registerTool("get_view", {

package/dist/tools/views.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cpenned/mcp",
-  "version": "0.8.4",
+  "version": "0.9.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

@@ -122,7 +122,9 @@ pre-guessing constraints.
   `assignee: "me"|"unassigned"|<userId>` filters the home vault by assignee),
   `get_task`, `update_task` (drives status), `delete_task`, batch
   `create_tasks`/`update_tasks`, `add_task_tags`/`remove_task_tags`.
-  `create_task`/`update_task` accept `eventId` to link a synced calendar event
+  `create_task`/`create_tasks` accept an initial `status` (default `todo`;
+  e.g. `backlog` to park it). `create_task`/`update_task` accept `eventId` to
+  link a synced calendar event
   (read-only mirror); `eventId: null` on update unlinks it.
   `create_task`/`create_tasks`/`update_task`/`update_tasks` also accept
   `assigneeUserId` (a user id, `"me"`, or `null` to unassign) - only
@@ -132,6 +134,7 @@ pre-guessing constraints.
   `sharedFrom` marker).
 - **Projects**: `create_project`, `list_projects`, `get_project`,
   `update_project`, `delete_project`, `create_projects`/`update_projects`.
+  `create_project(s)` accept an initial `status` (default `todo`).
   Project reads carry `taskCounts {open, done}` (canceled in neither) and
   `nextTaskId` (first open task by manual order; `get_task` it to see what's
   next), so progress needs no extra task listing.
@@ -145,8 +148,8 @@ pre-guessing constraints.
   (null clears a field, e.g. `contactInterval: null`; `archived: false`
   restores), `delete_person` (archives, links kept), `mark_contacted`
   (optional `at` backdates the touch), `add_person_links`/`remove_person_links`
-  (`{id, taskIds?, projectIds?, gardenIds?, readingListItemIds?, bookIds?,
-  people?}` — `people` is `[{id, label?}]` for person-to-person connections;
+  (`{id, taskIds?, projectIds?, gardenIds?, readingListItemIds?, habitIds?,
+  bookIds?, people?}`: `people` is `[{id, label?}]` for person-to-person connections;
   symmetric, shown on both people, re-link with a new label to change it or
   `label: null` to clear it; unlink takes the same shape, ids only for
   `people`). `create_task(s)` accept `personIds` inline; `list_tasks` filters
@@ -159,9 +162,10 @@ pre-guessing constraints.
   `archived`/`deleted` toggle independently of status), `delete_reading_item`
   (true soft delete, hidden everywhere; restore with `update_reading_item
   {deleted: false}`),   `add_reading_tags`/`remove_reading_tags`.
-- **Habits**: `create_habit`, `list_habits`, `get_habit`, `update_habit`,
+- **Habits**: `create_habit`, `list_habits` (pages; pass `cursor`), `get_habit`, `update_habit`,
   `archive_habit`/`unarchive_habit`, `complete_habit` (`quantity?`, `durationMinutes?`,
-  `force?` skips time window), `remove_habit_completion` (by `completionId` or `day`),
+  `force?` skips time window), `remove_habit_completion` (by `completionId` or `day`;
+  a `day` lookup reaches back through the newest 200 check-ins),
   `reorder_habits`, `add_habit_tags`/`remove_habit_tags`.
   Schedules: `{kind: daily}`, `{kind: weekly, times, byWeekday?}`, `{kind: monthly, times}`,
   `{kind: every_n_days, interval}`. Optional `graceDays` (daily streak tolerance),
@@ -191,20 +195,37 @@ pre-guessing constraints.
   `delete_book` (soft delete, cover blob kept, restore with `{deleted:
   false}`), `add_book_tags`/`remove_book_tags`, `log_book_session` (`day?`,
   `pagesRead?`, `minutes?`, `endPage?`, `notes?`; retroactive OK, multiple
-  sessions per day), `remove_book_session` (never retroactively un-satisfies
+  sessions per day; `pagesRead` alone continues from the current page and
+  moves it forward), `remove_book_session` (never retroactively un-satisfies
   a habit day), `refresh_book_metadata` (`overwrite?` to replace non-empty
   fields). Person links via `add_person_links`/`remove_person_links` with
   `bookIds`.
 - **Saved lists** (named, reusable task-list filters): `list_saved_lists`,
   `create_saved_list`, `update_saved_list`, `delete_saved_list`.
-- **Views & reviews**: `get_view` (today/upcoming/overdue, timezone-aware),
+- **Comments**: `list_task_comments {taskId}` (oldest first, max 200, plus
+  `participants`: the people in the task's garden who can be @mentioned,
+  `{userId, displayName, avatarUrl, role}`), `add_task_comment {taskId, body,
+  mentions?}`, `edit_task_comment {taskId, commentId, body, mentions?}`
+  (author only), `delete_task_comment {taskId, commentId}` (author or garden
+  owner). Each comment has `body` (Markdown with mention tokens), `text`
+  (tokens rendered as `@Name`), `mentions` (user ids), `canEdit`,
+  `canDelete`, and `editedAt` once edited. Tasks carry `commentCount`
+  (omitted when 0). Needs `tasks:read` / `tasks:write`.
+- **Attachments** (read-only; upload is web/app-only): `list_task_attachments
+  {taskId}`, `get_attachment {id}` (metadata), `get_attachment_url {id,
+  variant?}` (short-lived signed URL; `variant` is `served` (default),
+  `original`, or `thumbnail`). Needs `tasks:read`.
+- **Views & reviews**: `get_view` (today/upcoming/overdue, timezone-aware;
+  without `tz` it uses the timezone of the machine running the MCP server),
   `get_reviews` (due queue), `review_garden` (deep review),
   `request_garden_review`, `mark_task_reviewed`, `mark_project_reviewed`.
 - **AI**: `find_tasks` (hybrid keyword + semantic search), `ai_triage`
   (brain dump → garden-assigned tasks, recurring habits, reading-list
   saves/edits/cancels, and books - see Workflows).
-- **UI (read-only)**: `ui_view`, `ui_review_queue`, `ui_garden_board` return
-  `ui://` HTML resources.
+- **UI (read-only)**: `ui_view`, `ui_review_queue`, `ui_garden_board`,
+  `ui_habits` return `ui://` HTML resources. `ui_view` and `ui_habits` take a
+  `cursor`; when a page is cut short the result adds a text note with the
+  cursor for the next page.
 - **Settings**: `get_settings`, `update_settings` (the default review period
   applied to new tasks/projects; `defaultReviewInterval: null` disables it;
   `defaultTimezone`, an IANA string, is also settable - it's what date-only
@@ -216,11 +237,15 @@ pre-guessing constraints.
   owner, participants - empty unless the key has `includeGrants`),
   `list_shared_tasks {shareId, status?, includeCanceled?}` (that garden's
   tasks, capped at 500).
-- **Profile**: `get_profile` (user id, display name, avatar URL),
-  `update_profile {displayName}` (1-60 chars; avatar upload is web-only).
+- **Profile**: `get_profile` (user id, display name, avatar URL,
+  `notifications: {emailOnMention, emailOnAssign}`), `update_profile
+  {displayName?, notifications?: {emailOnMention?, emailOnAssign?}}` (pass at
+  least one; display name 1-60 chars; avatar upload is web-only).
 - **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`.
+  has it), `list_keys`, `rotate_key`, `revoke_key`. `rotate_key` and
+  `revoke_key` refuse the key this MCP server itself authenticates with (it
+  would lock the server out); rotate or revoke that one from the CLI or web app.
 
 ## Workflows
 
@@ -235,16 +260,20 @@ pre-guessing constraints.
   archives it, reversibly, independent of status) — it matches existing
   items by exact title, so an unmatched or ambiguous reference comes back as a
   reading-list clarification rather than a silent no-op or a task.
-- **Plan today** → `get_view today`. Pass the user's IANA `tz` if known so the
-  day boundary is correct.
+- **Plan today** → `get_view today`. It defaults to this machine's timezone;
+  pass the user's IANA `tz` if they are somewhere else so the day boundary is
+  correct.
 - **Add a task** → need a garden: `list_gardens` first, then `create_task` with
   `gardenId`. Set `deadline` for "today"/hard dates — that's what lands it in
   the Today view. `create_task`/`create_tasks` accept `tagIds`, `recurrence`,
   `deferDate`, `deadline`, and `habitId` (completing the task checks in the
   habit) **inline** — set them at creation, never create-then-patch.
   `deferDate`/`deadline` are calendar days `"YYYY-MM-DD"` (no timezone); inputs
-  also accept relative tokens (`"today"`, `"tomorrow"`, `"+3d"`), so no
-  client-side date math. Returned values are always `"YYYY-MM-DD"`.
+  also accept relative tokens (`"today"`, `"tomorrow"`, `"+3d"`, `"friday"`,
+  `"next week"`; a weekday is its next occurrence after today), so no
+  client-side date math. The local (stdio) server sends the machine's
+  timezone, so relative tokens resolve in the user's zone; the hosted server
+  falls back to the vault timezone. Returned values are always `"YYYY-MM-DD"`.
 - **Recurring task** → set `recurrence` at creation:
   `{mode, frequency, interval, byWeekday?}`. `mode`: `on_schedule` (next = prior
   due + interval; self-heals missed days) or `on_completion` (next = completed +
@@ -281,6 +310,19 @@ pre-guessing constraints.
   pagesRead}` as pages are read (auto-promotes `want_to_read` to `reading`)
   → `update_book {id, status: "read"}` when finished (stamps `finishedDay`
   and force-completes a linked page-goal habit for that day).
+- **Comment on a task / loop someone in** → `list_task_comments {taskId}` to
+  read the thread and see who can be mentioned, then `add_task_comment {taskId,
+  body, mentions: ["Sam"]}`. `mentions` takes participant user ids or display
+  names (case-insensitive, leading `@` ok): a plain `@Sam` already in the
+  body becomes a mention token, otherwise the token is prepended; an unknown
+  name is a 400, so check `participants` first. You can also write the token
+  inline: `@[Display Name](userId)`; a token for someone outside the task's
+  garden becomes plain `@Name` text. Anyone who can see the task can comment,
+  including watch-only guests of a shared garden (the key needs
+  `includeGrants` for shared tasks). Mentioned people, and people newly
+  assigned a task, get an email from the server (never the caller), unless
+  they turned it off via `update_profile {notifications: {emailOnMention:
+  false}}` (or `emailOnAssign`).
 - **Find something** → `find_tasks` (handles fuzzy/semantic queries; narrow to a
   due window with `deadlineBefore` / `deadlineAfter`, inclusive day bounds,
   e.g. `"2026-07-10"` or `"+1w"`).
@@ -298,8 +340,9 @@ pre-guessing constraints.
   `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
-  `reviews:*`, `find_tasks`/`ai_triage` need
-  `ai:invoke`, the `*_key` tools need `keys:manage`. A missing scope returns a
+  `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
   403 tool error. Keys minted before a feature shipped won't carry its scope
   unless they hold `*`. There is no upload tool here (cover uploads are a
   web-only flow, `POST /v1/uploads` before setting `coverStorageId`), but a