keepsake-mcp 1.10.0 → 1.11.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 (76)
 
 ### 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 |

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: {

package/package.json

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