keepsake-mcp 1.12.0 → 1.14.0

package/README.md

@@ -143,7 +143,7 @@ rather than in the chat, which disappears.
 ### Entries (Interactions)
 | Tool | Description |
 |------|-------------|
-| `list_entries` | List interactions (calls, emails, meetings, etc.) |
+| `list_entries` | List interactions (calls, emails, meetings, etc.) — filter by type, contact, company, page (`tag_id`), dates |
 | `create_entry` | Log a new interaction — supports `#tag#` and `[[tag]]` syntax |
 | `update_entry` | Update an interaction |
 | `delete_entry` | Delete an interaction |
@@ -151,7 +151,7 @@ rather than in the chat, which disappears.
 ### Tasks
 | Tool | Description |
 |------|-------------|
-| `list_tasks` | List tasks with status/date filters |
+| `list_tasks` | List tasks — filter by status, date, company, page (`tag_id`) |
 | `get_task` | Get a task with its tags, contacts, companies and linked notes |
 | `create_task` | Create a task — supports `#tag#` and `[[tag]]` syntax |
 | `update_task` | Update task fields |
@@ -165,12 +165,12 @@ rather than in the chat, which disappears.
 ### QuickNotes
 | Tool | Description |
 |------|-------------|
-| `list_notes` | List notes (filter by pinned/archived) |
+| `list_notes` | List notes — filter by pinned/archived, day, company, page (`tag_id`) |
 | `get_note` | Get one note by ID with its tags, contacts, tasks and linked notes |
 | `create_note` | Create a note — supports `#tag#` and `[[tag]]` syntax |
 | `update_note` | Update note content |
 | `delete_note` | Soft-delete (or permanent) |
-| `pin_note` | Pin to top |
+| `pin_note` | Pin as a post-it (short reference always at hand) |
 | `archive_note` | Archive a note |
 | `restore_note` | Restore a deleted/archived note |
 
@@ -188,9 +188,9 @@ Material kept *alongside* a note without entering its text — an idea, a refere
 ### Days (intention or question of the day)
 | Tool | Description |
 |------|-------------|
-| `list_days` | List days with their intention or question of the day, by date range |
-| `get_day` | Get a day and its intention or question (field `note`) |
-| `update_day` | Set a day's intention or question — one short line, not a journal (upsert) |
+| `list_days` | List days with their intention or question of the day (the one in force, which stays until changed), by date range |
+| `get_day` | Get a day, its intention in force (`intention`, carried over until changed) and what was written that day (`note`) |
+| `update_day` | Set a day's intention or question — one short line, not a journal (upsert); it stays in place on the following days until changed |
 
 ### Day blocks (Day-view timeline)
 | Tool | Description |
@@ -206,7 +206,7 @@ Material kept *alongside* a note without entering its text — an idea, a refere
 | `list_tags` | List tags (lightweight — ordering arrays omitted), with optional name search (`q`) |
 | `get_tag` | Get a tag by ID with all properties, including `tasks_order` (section markers `h:<header_id>`) |
 | `create_tag` | Create a new tag |
-| `update_tag` | Update a tag (name, description, color, icon, view mode, favorite) |
+| `update_tag` | Update a tag (name, description, color, icon, favorite, order of tasks and sections via `tasks_order`) |
 | `delete_tag` | Permanently delete a tag and all its links |
 | `get_tag_items` | Get items linked to a tag — filter by `types`/`status`, `summary` mode, task `sections` included |
 | `link_tag` | Link any entity to a tag |
@@ -217,7 +217,7 @@ Material kept *alongside* a note without entering its text — an idea, a refere
 |------|-------------|
 | `list_task_headers` | List all task headers (section separators) |
 | `get_task_header` | Get a task header by ID |
-| `create_task_header` | Create a task header (section) |
+| `create_task_header` | Create a task header (section) — insert `h:<id>` in the tag's `tasks_order` to place it |
 | `update_task_header` | Update a task header (name, description, collapsed) |
 | `delete_task_header` | Permanently delete a task header |
 

package/build/tools.js

@@ -295,7 +295,7 @@ export function registerAllTools(server, fetchApi) {
     // ENTRIES (Interactions)
     // ===========================================================================
     server.registerTool("list_entries", {
-        description: "List interaction entries (calls, emails, meetings, events, etc.). Supports filtering by type, contact, and date range.",
+        description: "List interaction entries (calls, emails, meetings, events, etc.). Supports filtering by type, contact, company, tag (page) and date range.",
         inputSchema: {
             type: z
                 .enum(["call", "email", "meeting", "event", "gift", "letter", "message", "log", "other"])
@@ -303,14 +303,15 @@ export function registerAllTools(server, fetchApi) {
                 .describe("Filter by entry type"),
             contact_id: z.string().uuid().optional().describe("Filter by associated contact ID"),
             company_id: z.string().uuid().optional().describe("Only entries where this company is a participant"),
+            tag_id: z.string().uuid().optional().describe("Only entries linked to this tag (page)"),
             from: z.string().optional().describe("Start date (YYYY-MM-DD)"),
             to: z.string().optional().describe("End date (YYYY-MM-DD)"),
             limit: z.number().int().positive().optional().describe("Max results (default 20)"),
             offset: z.number().int().nonnegative().optional().describe("Pagination offset"),
         },
         annotations: { title: "List entries", readOnlyHint: true, openWorldHint: false },
-    }, async ({ type, contact_id, company_id, from, to, limit, offset }) => {
-        return toContent(await fetchApi(`/entries${qs({ type, contact_id, company_id, from, to, limit, offset })}`));
+    }, async ({ type, contact_id, company_id, tag_id, from, to, limit, offset }) => {
+        return toContent(await fetchApi(`/entries${qs({ type, contact_id, company_id, tag_id, from, to, limit, offset })}`));
     });
     server.registerTool("create_entry", {
         description: "An ENTRY is a dated interaction log tied to contacts. Records something that happened (call, meeting, email…) on a specific date.\n\nCreate a new interaction entry. Content supports #tag# and [[tag]] syntax for automatic tag linking.",
@@ -377,7 +378,7 @@ export function registerAllTools(server, fetchApi) {
     // TASKS
     // ===========================================================================
     server.registerTool("list_tasks", {
-        description: "List tasks. Filter by status (pending/completed), date_type, or specific date.",
+        description: "List tasks. Filter by status (pending/completed), date_type, specific date, company, or tag (page) — e.g. tag_id + status=pending lists a project's open tasks.",
         inputSchema: {
             status: z.enum(["pending", "completed"]).optional().describe("Filter by status"),
             date_type: z
@@ -386,12 +387,13 @@ export function registerAllTools(server, fetchApi) {
                 .describe("Filter by date type: specific (has a due date), asap (do as soon as possible), one_day (someday/no rush)"),
             date: z.string().optional().describe("Filter by specific date (YYYY-MM-DD)"),
             company_id: z.string().uuid().optional().describe("Only tasks linked directly to this company"),
+            tag_id: z.string().uuid().optional().describe("Only tasks linked to this tag (page)"),
             limit: z.number().int().positive().optional().describe("Max results (default 20)"),
             offset: z.number().int().nonnegative().optional().describe("Pagination offset"),
         },
         annotations: { title: "List tasks", readOnlyHint: true, openWorldHint: false },
-    }, async ({ status, date_type, date, company_id, limit, offset }) => {
-        return toContent(await fetchApi(`/tasks${qs({ status, date_type, date, company_id, limit, offset })}`));
+    }, async ({ status, date_type, date, company_id, tag_id, limit, offset }) => {
+        return toContent(await fetchApi(`/tasks${qs({ status, date_type, date, company_id, tag_id, limit, offset })}`));
     });
     server.registerTool("get_task", {
         description: "Get a single task by ID, with its tags, linked contacts (contact_ids), linked companies (company_ids) and linked notes (note_ids). Use it when you already know which task you need instead of listing everything.",
@@ -540,7 +542,7 @@ export function registerAllTools(server, fetchApi) {
     // QUICK NOTES
     // ===========================================================================
     server.registerTool("list_notes", {
-        description: "List notes. QuickNotes (inbox, not yet archived) and Notes (archived, permanent). Filter by pinned or archived status, or by the day(s) a note is linked to (`date`, or `date_from`/`date_to`) — e.g. \"what did I note for tomorrow?\". Each note carries `dates`, the days it is linked to.",
+        description: "List notes. QuickNotes (inbox, not yet archived) and Notes (archived, permanent). Filter by pinned or archived status, by tag (page) with `tag_id`, or by the day(s) a note is linked to (`date`, or `date_from`/`date_to`) — e.g. \"what did I note for tomorrow?\". Each note carries `dates`, the days it is linked to.",
         inputSchema: {
             pinned: z.boolean().optional().describe("Filter pinned notes only"),
             archived: z.boolean().optional().describe("Filter by status: true = Notes (archived/permanent), false = QuickNotes (inbox)"),
@@ -548,12 +550,13 @@ export function registerAllTools(server, fetchApi) {
             date_from: z.string().optional().describe("Only notes linked to a day on or after this date (YYYY-MM-DD)"),
             date_to: z.string().optional().describe("Only notes linked to a day on or before this date (YYYY-MM-DD)"),
             company_id: z.string().uuid().optional().describe("Only notes linked directly to this company"),
+            tag_id: z.string().uuid().optional().describe("Only notes linked to this tag (page)"),
             limit: z.number().int().positive().optional().describe("Max results (default 20)"),
             offset: z.number().int().nonnegative().optional().describe("Pagination offset"),
         },
         annotations: { title: "List notes", readOnlyHint: true, openWorldHint: false },
-    }, async ({ pinned, archived, date, date_from, date_to, company_id, limit, offset }) => {
-        return toContent(await fetchApi(`/notes${qs({ pinned, archived, date, date_from, date_to, company_id, limit, offset })}`));
+    }, async ({ pinned, archived, date, date_from, date_to, company_id, tag_id, limit, offset }) => {
+        return toContent(await fetchApi(`/notes${qs({ pinned, archived, date, date_from, date_to, company_id, tag_id, limit, offset })}`));
     });
     server.registerTool("get_note", {
         description: "Get a single note by ID, including its tags, linked contacts, linked tasks, linked notes and the days it is linked to (`dates`). Use this when the user points you at one specific note (e.g. gives you its URL — the UUID is the last path segment) instead of listing everything.",
@@ -624,7 +627,7 @@ export function registerAllTools(server, fetchApi) {
         return toContent(await fetchApi(`/notes/${id}${query}`, "DELETE"));
     });
     server.registerTool("pin_note", {
-        description: "Pin a QuickNote or Note so it appears at the top of the Inbox.",
+        description: "Pin a QuickNote or Note so it stays in view. A pin is a POST-IT: a short reference the user wants always at hand (gate code, hotel room number, Wi-Fi password). Do not pin a note just because it is important — meeting prep is linked to its day, project material to a tag, actions become tasks. Pin only when the user asks or the note is clearly such a post-it.",
         inputSchema: {
             id: z.string().uuid().describe("Note UUID"),
         },
@@ -654,7 +657,7 @@ export function registerAllTools(server, fetchApi) {
     // DAYS (Daily Summaries)
     // ===========================================================================
     server.registerTool("list_days", {
-        description: "List days with their intention or question of the day (field `note`). Filter by date range.",
+        description: "List stored days with their intention or question of the day. An intention stays in place until changed: `intention` is the one in force that day (the last one written on that day or before, `intention_date` = when it was written); `note` is what was written on that exact day (null = nothing written). Filter by date range.",
         inputSchema: {
             from: z.string().optional().describe("Start date (YYYY-MM-DD)"),
             to: z.string().optional().describe("End date (YYYY-MM-DD)"),
@@ -666,7 +669,7 @@ export function registerAllTools(server, fetchApi) {
         return toContent(await fetchApi(`/days${qs({ from, to, limit, offset })}`));
     });
     server.registerTool("get_day", {
-        description: "Get a specific day by date: its intention or question of the day (field `note`, one short line) AND the notes linked to that day (field `notes`, via link_note_date / `dates`). Always 200 — `exists: false` means no intention is stored yet, the linked notes are returned regardless.",
+        description: "Get a specific day by date: its intention or question of the day AND the notes linked to that day (field `notes`, via link_note_date / `dates`). An intention stays in place until changed: `intention` is the one in force that day, as the user sees it (the last one written on that day or before; `intention_date` = the day it was written), while `note` is what was written on that exact day (null = nothing written there, '' = intention stopped from that day). Always 200 — `exists: false` means no row is stored for that date; `intention` and the linked notes are returned regardless.",
         inputSchema: {
             date: z.string().describe("Date (YYYY-MM-DD)"),
         },
@@ -675,10 +678,10 @@ export function registerAllTools(server, fetchApi) {
         return toContent(await fetchApi(`/days/${date}`));
     });
     server.registerTool("update_day", {
-        description: "Create or update a day's intention or question of the day (upsert on the date). The `note` field is the intention or question of the day — one short line at the top of the Today view (a mantra, an intention, a single priority, or a question to keep in mind). Not a journal: never write a summary of the day here.\n\nNOT for attaching a note to a day: this field is a single line and you would overwrite the user's intention. To put a note on a day, use create_note with `dates` or link_note_date.",
+        description: "Create or update a day's intention or question of the day (upsert on the date). The `note` field is the intention or question of the day — one short line at the top of the Today view (a mantra, an intention, a single priority, or a question to keep in mind). Not a journal: never write a summary of the day here.\n\nAn intention stays in place until changed: writing it on a day replaces the intention from that day onward (following days show it too, until the next day with its own intention — set one on a future date for a one-off, e.g. before a meeting). `null` removes what was written on that day (the day goes back to the intention in force before it); an empty string stops any intention from that day onward. Check `intention` with get_day before writing: you may be replacing a long-running intention the user cares about.\n\nNOT for attaching a note to a day: this field is a single line and you would overwrite the user's intention. To put a note on a day, use create_note with `dates` or link_note_date.",
         inputSchema: {
             date: z.string().describe("Date (YYYY-MM-DD)"),
-            note: z.string().describe("The intention or question of the day: one short line (mantra, intention, single priority, or a question to keep in mind). Not a journal summary."),
+            note: z.string().nullable().describe("The intention or question of the day: one short line (mantra, intention, single priority, or a question to keep in mind). Not a journal summary. null = remove what was written on this day (back to the previous intention); empty string = stop any intention from this day onward."),
         },
         annotations: { title: "Update day", destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (params) => {
@@ -809,14 +812,17 @@ export function registerAllTools(server, fetchApi) {
         return toContent(await fetchApi("/tags", "POST", body));
     });
     server.registerTool("update_tag", {
-        description: "Update an existing tag. Only send the fields you want to change. Supports name, description, color, icon, view mode, and favorite status.",
+        description: "Update an existing tag. Only send the fields you want to change. Supports name, description, color, icon, favorite status, and the order of the page's tasks and sections (tasks_order).",
         inputSchema: {
             id: z.string().uuid().describe("Tag UUID"),
             name: z.string().optional().describe("Tag name"),
             description: z.string().optional().describe("Tag description"),
             color: z.string().optional().describe("Tag color (e.g. 'blue', 'red', 'green')"),
             icon: z.string().optional().describe("Tag icon (emoji or icon name)"),
-            view_mode: z.string().optional().describe("View mode for the tag page"),
+            tasks_order: z
+                .array(z.string())
+                .optional()
+                .describe("Full display order of the page's tasks: task ids and \"h:<header_id>\" entries for sections, top to bottom. Read the current one with get_tag, insert or move entries, send the whole array back. Tasks listed after a section belong to it."),
             is_favorite: z.boolean().optional().describe("Whether the tag is a favorite"),
         },
         annotations: { title: "Update tag", destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -881,7 +887,7 @@ export function registerAllTools(server, fetchApi) {
         return toContent(await fetchApi(`/task-headers/${id}`));
     });
     server.registerTool("create_task_header", {
-        description: "Create a new task header (section separator). Add it to a tag's items_order to position it.",
+        description: "Create a new task header (section separator). To show it on a tag page, insert \"h:<header_id>\" into that tag's tasks_order (get_tag, then update_tag) where the section should start: the tasks listed after it belong to that section.",
         inputSchema: {
             name: z.string().describe("Header name"),
             description: z.string().optional().describe("Optional description below the header"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keepsake-mcp",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "MCP server for Keepsake personal CRM \u2014 connect your AI agent to your contacts, tasks, notes, and more",
   "type": "module",
   "bin": {