keepsake-mcp 1.10.0 → 1.12.0

package/README.md

@@ -114,17 +114,17 @@ 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 (73)
+## Available tools (83)
 
 ### Contacts
 | Tool | Description |
 |------|-------------|
-| `list_contacts` | List all contacts with pagination and sorting |
+| `list_contacts` | List contacts with pagination, sorting, field selection and filters (linked company, has_company, updated_since) |
 | `get_contact` | Get a contact with recent interactions, tags, and stats |
-| `create_contact` | Create a new contact |
+| `create_contact` | Create a new contact (`company` links it to a company record, created if missing) |
 | `update_contact` | Update contact fields |
 | `delete_contact` | Permanently delete a contact |
-| `search_contacts` | Accent-insensitive search by name, email, company |
+| `search_contacts` | Accent-insensitive search by name, email, notes, phone and linked company names |
 | `get_contact_timeline` | Unified chronological feed of all items for a contact |
 
 ### Companies
@@ -136,6 +136,9 @@ rather than in the chat, which disappears.
 | `update_company` | Update company fields |
 | `delete_company` | Soft-delete (or permanent delete) a company |
 | `search_companies` | Accent-insensitive company search |
+| `link_contact_company` | Link a contact to a company (optional role) |
+| `unlink_contact_company` | Remove a contact–company link |
+| `merge_companies` | Merge a duplicate company into another (contacts, entries, tags, details, notes) |
 
 ### Entries (Interactions)
 | Tool | Description |
@@ -149,6 +152,7 @@ rather than in the chat, which disappears.
 | Tool | Description |
 |------|-------------|
 | `list_tasks` | List tasks with status/date filters |
+| `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 |
@@ -217,13 +221,16 @@ Material kept *alongside* a note without entering its text — an idea, a refere
 | `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

@@ -109,17 +109,24 @@ export function registerAllTools(server, fetchApi) {
     // CONTACTS
     // ===========================================================================
     server.registerTool("list_contacts", {
-        description: "List all contacts in the user's Keepsake CRM. Supports pagination, sorting, and optional last_interaction_date enrichment.",
+        description: "List contacts in the user's Keepsake CRM. Supports pagination, sorting, field selection (use `fields` to skip long notes when scanning many contacts), filters on linked companies and on last update, and optional last_interaction_date enrichment. Each contact's companies are company records, returned in `companies`.",
         inputSchema: {
-            limit: z.number().int().positive().optional().describe("Max results (default 20)"),
+            limit: z.number().int().positive().optional().describe("Max results (default 20, max 100)"),
             offset: z.number().int().nonnegative().optional().describe("Pagination offset"),
-            sort: z.string().optional().describe("Sort field: last_name, first_name, created_at"),
+            sort: z.string().optional().describe("Sort field: last_name, first_name, created_at, updated_at"),
             order: z.enum(["asc", "desc"]).optional().describe("Sort order"),
             include_last_interaction: z.boolean().optional().describe("Include last_interaction_date for each contact (default: false)"),
+            fields: z
+                .array(z.string())
+                .optional()
+                .describe("Only return these fields (id is always included). Columns: first_name, last_name, email, phone, job_title, address, birth_day, birth_month, birth_year, notes, created_at, updated_at. Computed: companies, last_interaction_date. Omit for everything."),
+            company: z.string().optional().describe("Only contacts linked to this company: a company UUID, or part of its name (case and accents ignored)"),
+            has_company: z.boolean().optional().describe("true: only contacts linked to at least one company; false: only contacts without any company"),
+            updated_since: z.string().optional().describe("Only contacts updated after this ISO date or timestamp"),
         },
         annotations: { title: "List contacts", readOnlyHint: true, openWorldHint: false },
-    }, async ({ limit, offset, sort, order, include_last_interaction }) => {
-        return toContent(await fetchApi(`/contacts${qs({ limit, offset, sort, order, include_last_interaction })}`));
+    }, async ({ limit, offset, sort, order, include_last_interaction, fields, company, has_company, updated_since }) => {
+        return toContent(await fetchApi(`/contacts${qs({ limit, offset, sort, order, include_last_interaction, fields: fields?.join(","), company, has_company, updated_since })}`));
     });
     server.registerTool("get_contact", {
         description: "Get a single contact by ID, including recent entries (interactions), tags, last_interaction_date, and total_entries count.",
@@ -138,7 +145,7 @@ export function registerAllTools(server, fetchApi) {
             last_name: z.string().optional().describe("Last name (optional)"),
             email: z.string().optional().describe("Email address"),
             phone: z.string().optional().describe("Phone number"),
-            company: z.string().optional().describe("Company name"),
+            company: z.string().optional().describe("Company name. Links the contact to that company record (matched by name ignoring case and accents, created if missing). Adds a link, never removes one. The contact's companies are returned in `companies`."),
             birthday: z.string().optional().describe("Birthday as ISO date string (YYYY-MM-DD), e.g. '1980-02-14'"),
             notes: z.string().optional().describe("Notes about the contact"),
         },
@@ -154,7 +161,7 @@ export function registerAllTools(server, fetchApi) {
             last_name: z.string().optional().describe("Last name"),
             email: z.string().optional().describe("Email address"),
             phone: z.string().optional().describe("Phone number"),
-            company: z.string().optional().describe("Company name"),
+            company: z.string().optional().describe("Company name. Links the contact to that company record (matched by name ignoring case and accents, created if missing). Adds a link, never removes one. The contact's companies are returned in `companies`."),
             birthday: z.string().nullable().optional().describe("Birthday as ISO date string (YYYY-MM-DD), e.g. '1980-02-14'. Set to null to clear."),
             notes: z.string().optional().describe("Notes about the contact"),
         },
@@ -244,6 +251,37 @@ export function registerAllTools(server, fetchApi) {
         const query = permanent ? "?permanent=true" : "";
         return toContent(await fetchApi(`/companies/${id}${query}`, "DELETE"));
     });
+    server.registerTool("link_contact_company", {
+        description: "Link a contact to a company record (idempotent: linking twice keeps one link). A contact can belong to several companies. Optionally set the contact's role there. Shortcut when you only know the company's name: create_contact / update_contact with `company`.",
+        inputSchema: {
+            company_id: z.string().uuid().describe("Company UUID"),
+            contact_id: z.string().uuid().describe("Contact UUID"),
+            role: z.string().optional().describe("Role or job at this company (e.g. 'Training advisor')"),
+        },
+        annotations: { title: "Link contact to company", destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ company_id, contact_id, role }) => {
+        return toContent(await fetchApi(`/companies/${company_id}/contacts`, "POST", { contact_id, ...(role !== undefined && { role }) }));
+    });
+    server.registerTool("unlink_contact_company", {
+        description: "Remove the link between a contact and a company. Neither the contact nor the company is deleted.",
+        inputSchema: {
+            company_id: z.string().uuid().describe("Company UUID"),
+            contact_id: z.string().uuid().describe("Contact UUID"),
+        },
+        annotations: { title: "Unlink contact from company", destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ company_id, contact_id }) => {
+        return toContent(await fetchApi(`/companies/${company_id}/contacts${qs({ contact_id })}`, "DELETE"));
+    });
+    server.registerTool("merge_companies", {
+        description: "Merge a duplicate company INTO another one: its contacts, entries and tags move to the target (no duplicates), the target's empty details (website, email, phone, address) are filled from it, its notes are appended to the target's, then it is deleted. Use it when two records describe the same organization (e.g. 'CNCP' and 'Cncp'). Confirm with your user which record to keep.",
+        inputSchema: {
+            source_id: z.string().uuid().describe("UUID of the company to merge away (it will be deleted)"),
+            target_id: z.string().uuid().describe("UUID of the company to keep"),
+        },
+        annotations: { title: "Merge companies", destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    }, async ({ source_id, target_id }) => {
+        return toContent(await fetchApi(`/companies/${source_id}/merge`, "POST", { target_id }));
+    });
     server.registerTool("search_companies", {
         description: "Search companies by name, email, website, or address. Search is accent-insensitive.",
         inputSchema: {
@@ -264,14 +302,15 @@ export function registerAllTools(server, fetchApi) {
                 .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"),
             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, from, to, limit, offset }) => {
+        return toContent(await fetchApi(`/entries${qs({ type, contact_id, company_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.",
@@ -285,6 +324,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()
@@ -308,6 +351,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()
@@ -338,12 +385,22 @@ 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"),
             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, limit, offset }) => {
+        return toContent(await fetchApi(`/tasks${qs({ status, date_type, date, company_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.",
@@ -382,6 +439,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()
@@ -421,6 +482,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()
@@ -482,12 +547,13 @@ export function registerAllTools(server, fetchApi) {
             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"),
             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, limit, offset }) => {
+        return toContent(await fetchApi(`/notes${qs({ pinned, archived, date, date_from, date_to, company_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.",
@@ -507,6 +573,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()
@@ -525,6 +595,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()
@@ -901,6 +975,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.10.0",
+  "version": "1.12.0",
   "description": "MCP server for Keepsake personal CRM \u2014 connect your AI agent to your contacts, tasks, notes, and more",
   "type": "module",
   "bin": {