keepsake-mcp 1.11.0 → 1.13.0

package/README.md

@@ -114,7 +114,7 @@ rather than in the chat, which disappears.
 |--------|-----------|-------------|
 | `review_note` | `note_id` | Act as the editor of a note: read it, judge form and substance, leave anchored remarks in the margin, never rewrite the text |
 
-## Available tools (76)
+## Available tools (83)
 
 ### Contacts
 | Tool | Description |
@@ -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,8 @@ 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 |
 | `delete_task` | Delete a task |
@@ -164,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 |
 
@@ -205,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 |
@@ -216,17 +217,20 @@ 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 |
 
-### Contact Links
+### Contact & company links
 | Tool | Description |
 |------|-------------|
+| `link_note_company` / `unlink_note_company` | Link / unlink a company to a note |
 | `link_note_contact` | Link a contact to a note |
 | `unlink_note_contact` | Remove a contact link from a note |
+| `link_entry_company` / `unlink_entry_company` | Add / remove a company as participant of an entry |
 | `link_entry_contact` | Link a contact to an entry |
 | `unlink_entry_contact` | Remove a contact link from an entry |
+| `link_task_company` / `unlink_task_company` | Link / unlink a company to a task |
 | `link_task_contact` | Link a contact to a task |
 | `unlink_task_contact` | Remove a contact link from a task |
 | `link_task_note` | Link a note to a task (non-destructive, the note survives) |

package/build/tools.js

@@ -295,21 +295,23 @@ 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"])
                 .optional()
                 .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, from, to, limit, offset }) => {
-        return toContent(await fetchApi(`/entries${qs({ type, contact_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.",
@@ -323,6 +325,10 @@ export function registerAllTools(server, fetchApi) {
                 .array(z.string().uuid())
                 .optional()
                 .describe("Array of contact UUIDs to associate"),
+            company_ids: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("Array of company UUIDs to associate (companies are separate from contacts)"),
             tag_ids: z
                 .array(z.string().uuid())
                 .optional()
@@ -346,6 +352,10 @@ export function registerAllTools(server, fetchApi) {
                 .array(z.string().uuid())
                 .optional()
                 .describe("Replace associated contacts"),
+            company_ids: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("Replace associated companies (send [] to unlink all). Contacts are unaffected."),
             tag_ids: z
                 .array(z.string().uuid())
                 .optional()
@@ -368,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
@@ -376,12 +386,23 @@ export function registerAllTools(server, fetchApi) {
                 .optional()
                 .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, limit, offset }) => {
-        return toContent(await fetchApi(`/tasks${qs({ status, date_type, date, 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.",
+        inputSchema: {
+            id: z.string().uuid().describe("Task UUID"),
+        },
+        annotations: { title: "Get task", readOnlyHint: true, openWorldHint: false },
+    }, async ({ id }) => {
+        return toContent(await fetchApi(`/tasks/${id}`));
     });
     server.registerTool("create_task", {
         description: "A TASK is an action item to accomplish. Can have due date, recurrence, priority, linked to contacts and tags.\n\nCreate a new task. Title supports #tag# and [[tag]] for automatic tag linking.",
@@ -420,6 +441,10 @@ export function registerAllTools(server, fetchApi) {
                 .array(z.string().uuid())
                 .optional()
                 .describe("Array of contact UUIDs to associate"),
+            company_ids: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("Array of company UUIDs to associate (companies are separate from contacts)"),
             tag_ids: z
                 .array(z.string().uuid())
                 .optional()
@@ -459,6 +484,10 @@ export function registerAllTools(server, fetchApi) {
                 .array(z.string().uuid())
                 .optional()
                 .describe("Replace associated contacts"),
+            company_ids: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("Replace associated companies (send [] to unlink all). Contacts are unaffected."),
             tag_ids: z
                 .array(z.string().uuid())
                 .optional()
@@ -513,19 +542,21 @@ 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)"),
             date: z.string().optional().describe("Only notes linked to this day (YYYY-MM-DD)"),
             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, limit, offset }) => {
-        return toContent(await fetchApi(`/notes${qs({ pinned, archived, date, date_from, date_to, 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.",
@@ -545,6 +576,10 @@ export function registerAllTools(server, fetchApi) {
                 .array(z.string().uuid())
                 .optional()
                 .describe("Array of contact UUIDs to associate"),
+            company_ids: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("Array of company UUIDs to associate (companies are separate from contacts)"),
             dates: z
                 .array(z.string())
                 .optional()
@@ -563,6 +598,10 @@ export function registerAllTools(server, fetchApi) {
                 .array(z.string().uuid())
                 .optional()
                 .describe("Replace associated contacts"),
+            company_ids: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("Replace associated companies (send [] to unlink all). Contacts are unaffected."),
             tag_ids: z
                 .array(z.string().uuid())
                 .optional()
@@ -588,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"),
         },
@@ -773,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 },
@@ -845,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"),
@@ -939,6 +981,66 @@ export function registerAllTools(server, fetchApi) {
     }, async ({ task_id, contact_id }) => {
         return toContent(await fetchApi(`/tasks/${task_id}/contacts/${contact_id}`, "DELETE"));
     });
+    server.registerTool("link_entry_company", {
+        description: "Link a company to an entry (the company becomes a participant of that interaction). Idempotent. Companies are separate records from contacts: use this (or company_ids) for an organization, link_entry_contact for a person.",
+        inputSchema: {
+            entry_id: z.string().uuid().describe("Entry UUID"),
+            company_id: z.string().uuid().describe("Company UUID"),
+        },
+        annotations: { title: "Link entry company", destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ entry_id, company_id }) => {
+        return toContent(await fetchApi(`/entries/${entry_id}/companies/${company_id}`, "POST"));
+    });
+    server.registerTool("unlink_entry_company", {
+        description: "Remove the link between a company and an entry.",
+        inputSchema: {
+            entry_id: z.string().uuid().describe("Entry UUID"),
+            company_id: z.string().uuid().describe("Company UUID"),
+        },
+        annotations: { title: "Unlink entry company", destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ entry_id, company_id }) => {
+        return toContent(await fetchApi(`/entries/${entry_id}/companies/${company_id}`, "DELETE"));
+    });
+    server.registerTool("link_task_company", {
+        description: "Link a company to a task. Idempotent. Companies are separate records from contacts: use this (or company_ids) for an organization, link_task_contact for a person.",
+        inputSchema: {
+            task_id: z.string().uuid().describe("Task UUID"),
+            company_id: z.string().uuid().describe("Company UUID"),
+        },
+        annotations: { title: "Link task company", destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ task_id, company_id }) => {
+        return toContent(await fetchApi(`/tasks/${task_id}/companies/${company_id}`, "POST"));
+    });
+    server.registerTool("unlink_task_company", {
+        description: "Remove the link between a company and a task.",
+        inputSchema: {
+            task_id: z.string().uuid().describe("Task UUID"),
+            company_id: z.string().uuid().describe("Company UUID"),
+        },
+        annotations: { title: "Unlink task company", destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ task_id, company_id }) => {
+        return toContent(await fetchApi(`/tasks/${task_id}/companies/${company_id}`, "DELETE"));
+    });
+    server.registerTool("link_note_company", {
+        description: "Link a company to a note. Idempotent. Companies are separate records from contacts: use this (or company_ids) for an organization, link_note_contact for a person.",
+        inputSchema: {
+            note_id: z.string().uuid().describe("Note UUID"),
+            company_id: z.string().uuid().describe("Company UUID"),
+        },
+        annotations: { title: "Link note company", destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ note_id, company_id }) => {
+        return toContent(await fetchApi(`/notes/${note_id}/companies/${company_id}`, "POST"));
+    });
+    server.registerTool("unlink_note_company", {
+        description: "Remove the link between a company and a note.",
+        inputSchema: {
+            note_id: z.string().uuid().describe("Note UUID"),
+            company_id: z.string().uuid().describe("Company UUID"),
+        },
+        annotations: { title: "Unlink note company", destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ note_id, company_id }) => {
+        return toContent(await fetchApi(`/notes/${note_id}/companies/${company_id}`, "DELETE"));
+    });
     server.registerTool("link_task_note", {
         description: "Link an existing note to a task (non-destructive, N-N). The note stays in the inbox/notes list and the task keeps a live link back to it — use this instead of deleting a note after creating a task from it. The note shows its linked tasks; the task shows the source note.",
         inputSchema: {

package/package.json

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