@hasna/contacts 0.1.0 → 0.2.1

package/dist/mcp/index.js

@@ -181,6 +181,25 @@ var MIGRATIONS = [
   END;
 
   CREATE TABLE IF NOT EXISTS _migrations (version INTEGER PRIMARY KEY);
+  `,
+  `
+  ALTER TABLE contacts ADD COLUMN last_contacted_at TEXT;
+  ALTER TABLE contacts ADD COLUMN website TEXT;
+  ALTER TABLE contacts ADD COLUMN preferred_contact_method TEXT;
+
+  CREATE TABLE IF NOT EXISTS groups (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    description TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS contact_groups (
+    contact_id TEXT NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
+    group_id TEXT NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
+    PRIMARY KEY (contact_id, group_id)
+  );
   `
 ];
 var _db = null;
@@ -263,7 +282,8 @@ function rowToContact(row) {
   return {
     ...row,
     source: row.source,
-    custom_fields: JSON.parse(row.custom_fields || "{}")
+    custom_fields: JSON.parse(row.custom_fields || "{}"),
+    preferred_contact_method: row.preferred_contact_method ?? null
   };
 }
 function rowToEmail(row) {
@@ -344,8 +364,8 @@ function createContact(input, db) {
   const firstName = input.first_name ?? "";
   const lastName = input.last_name ?? "";
   const displayName = input.display_name ?? (firstName || lastName ? `${firstName} ${lastName}`.trim() : "Unnamed Contact");
-  d.run(`INSERT INTO contacts (id, first_name, last_name, display_name, nickname, avatar_url, notes, birthday, company_id, job_title, source, custom_fields, created_at, updated_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+  d.run(`INSERT INTO contacts (id, first_name, last_name, display_name, nickname, avatar_url, notes, birthday, company_id, job_title, source, custom_fields, last_contacted_at, website, preferred_contact_method, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
     id,
     firstName,
     lastName,
@@ -358,6 +378,9 @@ function createContact(input, db) {
     input.job_title ?? null,
     input.source ?? "manual",
     JSON.stringify(input.custom_fields ?? {}),
+    input.last_contacted_at ?? null,
+    input.website ?? null,
+    input.preferred_contact_method ?? null,
     timestamp,
     timestamp
   ]);
@@ -469,6 +492,18 @@ function updateContact(id, input, db) {
     setClauses.push("custom_fields = ?");
     params.push(JSON.stringify(input.custom_fields));
   }
+  if (input.last_contacted_at !== undefined) {
+    setClauses.push("last_contacted_at = ?");
+    params.push(input.last_contacted_at);
+  }
+  if (input.website !== undefined) {
+    setClauses.push("website = ?");
+    params.push(input.website);
+  }
+  if (input.preferred_contact_method !== undefined) {
+    setClauses.push("preferred_contact_method = ?");
+    params.push(input.preferred_contact_method);
+  }
   params.push(id);
   d.run(`UPDATE contacts SET ${setClauses.join(", ")} WHERE id = ?`, params);
   logActivity(d, { contact_id: id, action: "contact.updated", details: `Updated contact: ${existing.display_name}` });
@@ -571,6 +606,96 @@ function mergeContacts(keepId, mergeId, db) {
   return loadContactDetails(d, rowToContact(finalRow));
 }
 
+// src/db/groups.ts
+function createGroup(db, input) {
+  const id = uuid();
+  db.query(`INSERT INTO groups(id, name, description, created_at, updated_at) VALUES(?,?,?,?,?)`).run(id, input.name, input.description ?? null, now(), now());
+  return getGroup(db, id);
+}
+function getGroup(db, id) {
+  return db.query(`SELECT * FROM groups WHERE id = ?`).get(id);
+}
+function listGroups(db) {
+  return db.query(`SELECT g.*, COUNT(cg.contact_id) as member_count FROM groups g LEFT JOIN contact_groups cg ON g.id = cg.group_id GROUP BY g.id ORDER BY g.name`).all();
+}
+function updateGroup(db, id, input) {
+  const fields = [];
+  const vals = [];
+  if (input.name !== undefined) {
+    fields.push("name = ?");
+    vals.push(input.name);
+  }
+  if (input.description !== undefined) {
+    fields.push("description = ?");
+    vals.push(input.description ?? null);
+  }
+  fields.push("updated_at = ?");
+  vals.push(now());
+  vals.push(id);
+  db.query(`UPDATE groups SET ${fields.join(", ")} WHERE id = ?`).run(...vals);
+  return getGroup(db, id);
+}
+function deleteGroup(db, id) {
+  db.query(`DELETE FROM groups WHERE id = ?`).run(id);
+}
+function addContactToGroup(db, contactId, groupId) {
+  db.query(`INSERT OR IGNORE INTO contact_groups(contact_id, group_id) VALUES(?,?)`).run(contactId, groupId);
+}
+function removeContactFromGroup(db, contactId, groupId) {
+  db.query(`DELETE FROM contact_groups WHERE contact_id = ? AND group_id = ?`).run(contactId, groupId);
+}
+function listContactsInGroup(db, groupId) {
+  const rows = db.query(`SELECT contact_id FROM contact_groups WHERE group_id = ?`).all(groupId);
+  return rows.map((r) => r.contact_id);
+}
+function listGroupsForContact(db, contactId) {
+  return db.query(`SELECT g.* FROM groups g JOIN contact_groups cg ON g.id = cg.group_id WHERE cg.contact_id = ? ORDER BY g.name`).all(contactId);
+}
+
+// src/db/tags.ts
+function rowToTag2(row) {
+  return { ...row };
+}
+function createTag(input, db) {
+  const d = db || getDatabase();
+  const existing = d.query(`SELECT id FROM tags WHERE name = ?`).get(input.name);
+  if (existing)
+    throw new DuplicateTagNameError(input.name);
+  const id = uuid();
+  d.run(`INSERT INTO tags (id, name, color, description) VALUES (?, ?, ?, ?)`, [id, input.name, input.color ?? "#6366f1", input.description ?? null]);
+  return rowToTag2(d.query(`SELECT * FROM tags WHERE id = ?`).get(id));
+}
+function getTagByName(name, db) {
+  const d = db || getDatabase();
+  const row = d.query(`SELECT * FROM tags WHERE name = ?`).get(name);
+  return row ? rowToTag2(row) : null;
+}
+function listTags(db) {
+  const d = db || getDatabase();
+  return d.query(`SELECT * FROM tags ORDER BY name ASC`).all().map(rowToTag2);
+}
+function deleteTag(id, db) {
+  const d = db || getDatabase();
+  const row = d.query(`SELECT id FROM tags WHERE id = ?`).get(id);
+  if (!row)
+    throw new TagNotFoundError(id);
+  d.run(`DELETE FROM tags WHERE id = ?`, [id]);
+}
+function addTagToContact(contactId, tagId, db) {
+  const d = db || getDatabase();
+  const contact = d.query(`SELECT id FROM contacts WHERE id = ?`).get(contactId);
+  if (!contact)
+    throw new ContactNotFoundError(contactId);
+  const tag = d.query(`SELECT id FROM tags WHERE id = ?`).get(tagId);
+  if (!tag)
+    throw new TagNotFoundError(tagId);
+  d.run(`INSERT OR IGNORE INTO contact_tags (contact_id, tag_id) VALUES (?, ?)`, [contactId, tagId]);
+}
+function removeTagFromContact(contactId, tagId, db) {
+  const d = db || getDatabase();
+  d.run(`DELETE FROM contact_tags WHERE contact_id = ? AND tag_id = ?`, [contactId, tagId]);
+}
+
 // src/db/companies.ts
 function rowToCompany2(row) {
   return {
@@ -773,45 +898,6 @@ function searchCompanies(query, db) {
   return rows.map((row) => loadCompanyDetails(d, rowToCompany2(row)));
 }
 
-// src/db/tags.ts
-function rowToTag2(row) {
-  return { ...row };
-}
-function createTag(input, db) {
-  const d = db || getDatabase();
-  const existing = d.query(`SELECT id FROM tags WHERE name = ?`).get(input.name);
-  if (existing)
-    throw new DuplicateTagNameError(input.name);
-  const id = uuid();
-  d.run(`INSERT INTO tags (id, name, color, description) VALUES (?, ?, ?, ?)`, [id, input.name, input.color ?? "#6366f1", input.description ?? null]);
-  return rowToTag2(d.query(`SELECT * FROM tags WHERE id = ?`).get(id));
-}
-function listTags(db) {
-  const d = db || getDatabase();
-  return d.query(`SELECT * FROM tags ORDER BY name ASC`).all().map(rowToTag2);
-}
-function deleteTag(id, db) {
-  const d = db || getDatabase();
-  const row = d.query(`SELECT id FROM tags WHERE id = ?`).get(id);
-  if (!row)
-    throw new TagNotFoundError(id);
-  d.run(`DELETE FROM tags WHERE id = ?`, [id]);
-}
-function addTagToContact(contactId, tagId, db) {
-  const d = db || getDatabase();
-  const contact = d.query(`SELECT id FROM contacts WHERE id = ?`).get(contactId);
-  if (!contact)
-    throw new ContactNotFoundError(contactId);
-  const tag = d.query(`SELECT id FROM tags WHERE id = ?`).get(tagId);
-  if (!tag)
-    throw new TagNotFoundError(tagId);
-  d.run(`INSERT OR IGNORE INTO contact_tags (contact_id, tag_id) VALUES (?, ?)`, [contactId, tagId]);
-}
-function removeTagFromContact(contactId, tagId, db) {
-  const d = db || getDatabase();
-  d.run(`DELETE FROM contact_tags WHERE contact_id = ? AND tag_id = ?`, [contactId, tagId]);
-}
-
 // src/db/relationships.ts
 function rowToRelationship(row) {
   return {
@@ -1304,18 +1390,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: "create_contact",
-      description: "Create a new contact",
+      description: "Create a new contact. Provide at minimum display_name or first_name+last_name. Emails, phones, addresses, and social_profiles are arrays of objects. relationship_type values: colleague|friend|family|reports_to|mentor|investor|partner|client|vendor|other. source values: manual|import|linkedin|github|twitter|email|calendar|crm|other.",
       inputSchema: {
         type: "object",
         properties: {
           first_name: { type: "string" },
           last_name: { type: "string" },
-          display_name: { type: "string", description: "Display name" },
+          display_name: { type: "string", description: "Display name (auto-generated from first+last if omitted)" },
           nickname: { type: "string" },
           job_title: { type: "string" },
           company_id: { type: "string" },
           notes: { type: "string" },
           birthday: { type: "string", description: "YYYY-MM-DD" },
+          website: { type: "string", description: "Personal or professional website URL" },
+          last_contacted_at: { type: "string", description: "ISO 8601 datetime of last contact" },
+          preferred_contact_method: { type: "string", enum: ["email", "phone", "telegram", "whatsapp", "linkedin", "twitter", "other"] },
           emails: {
             type: "array",
             items: {
@@ -1369,13 +1458,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             }
           },
           tag_ids: { type: "array", items: { type: "string" }, description: "Tag IDs to assign" },
-          source: { type: "string" }
+          source: { type: "string", enum: ["manual", "import", "linkedin", "github", "twitter", "email", "calendar", "crm", "other"] }
         }
       }
     },
     {
       name: "get_contact",
-      description: "Get a contact by ID",
+      description: "Get a contact by ID, returning all details including emails, phones, addresses, social profiles, tags, and company.",
       inputSchema: {
         type: "object",
         properties: { id: { type: "string" } },
@@ -1384,7 +1473,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "update_contact",
-      description: "Update an existing contact",
+      description: "Update an existing contact's fields. Only provided fields are changed; omitted fields remain unchanged. Supports all contact fields including last_contacted_at, website, preferred_contact_method.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1396,14 +1485,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           job_title: { type: "string" },
           company_id: { type: "string" },
           notes: { type: "string" },
-          birthday: { type: "string" }
+          birthday: { type: "string", description: "YYYY-MM-DD" },
+          website: { type: "string" },
+          last_contacted_at: { type: "string", description: "ISO 8601 datetime of last contact" },
+          preferred_contact_method: { type: "string", enum: ["email", "phone", "telegram", "whatsapp", "linkedin", "twitter", "other"] },
+          source: { type: "string", enum: ["manual", "import", "linkedin", "github", "twitter", "email", "calendar", "crm", "other"] }
         },
         required: ["id"]
       }
     },
     {
       name: "delete_contact",
-      description: "Delete a contact by ID",
+      description: "Permanently delete a contact by ID. All associated emails, phones, addresses, tags, and relationships are also deleted.",
       inputSchema: {
         type: "object",
         properties: { id: { type: "string" } },
@@ -1412,7 +1505,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "list_contacts",
-      description: "List contacts with optional filters",
+      description: "List contacts with optional filters. Supports filtering by company, tag, or source. Returns paginated results with total count.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1427,7 +1520,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "search_contacts",
-      description: "Full-text search across contacts",
+      description: "Full-text search across contacts by name, nickname, notes, job title, and more. Also searches email addresses and phone numbers. Returns up to 50 results.",
       inputSchema: {
         type: "object",
         properties: { query: { type: "string" } },
@@ -1436,15 +1529,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "create_company",
-      description: "Create a new company",
+      description: "Create a new company/organization. Attach emails, phones, addresses, and social_profiles as arrays. Tag with tag_ids.",
       inputSchema: {
         type: "object",
         properties: {
           name: { type: "string" },
-          domain: { type: "string" },
+          domain: { type: "string", description: "Primary domain, e.g. acme.com" },
           description: { type: "string" },
           industry: { type: "string" },
-          size: { type: "string" },
+          size: { type: "string", description: "e.g. '1-10', '11-50', '51-200', '201-500', '500+'" },
           founded_year: { type: "number" },
           notes: { type: "string" },
           emails: { type: "array", items: { type: "object" } },
@@ -1458,7 +1551,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "get_company",
-      description: "Get a company by ID",
+      description: "Get a company by ID, including all emails, phones, addresses, social profiles, tags, and employee count.",
       inputSchema: {
         type: "object",
         properties: { id: { type: "string" } },
@@ -1467,7 +1560,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "update_company",
-      description: "Update an existing company",
+      description: "Update an existing company's fields. Only provided fields are changed; omitted fields remain unchanged.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1485,7 +1578,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "delete_company",
-      description: "Delete a company by ID",
+      description: "Permanently delete a company by ID. Contacts that belong to this company will have their company_id cleared.",
       inputSchema: {
         type: "object",
         properties: { id: { type: "string" } },
@@ -1494,7 +1587,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "list_companies",
-      description: "List companies with optional filters",
+      description: "List companies with optional filters by industry or tag. Returns paginated results with total count.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1507,7 +1600,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "search_companies",
-      description: "Search companies by name or domain",
+      description: "Search companies by name or domain using full-text search. Returns up to 50 matches.",
       inputSchema: {
         type: "object",
         properties: { query: { type: "string" } },
@@ -1516,12 +1609,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "create_tag",
-      description: "Create a new tag",
+      description: "Create a new tag for categorizing contacts and companies. Tags are shared across contacts and companies.",
       inputSchema: {
         type: "object",
         properties: {
           name: { type: "string" },
-          color: { type: "string", description: "Hex color (e.g. #FF5733)" },
+          color: { type: "string", description: "Hex color (e.g. #FF5733). Defaults to indigo." },
           description: { type: "string" }
         },
         required: ["name"]
@@ -1529,12 +1622,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "list_tags",
-      description: "List all tags",
+      description: "List all available tags with their colors and descriptions.",
       inputSchema: { type: "object", properties: {} }
     },
     {
       name: "delete_tag",
-      description: "Delete a tag by ID",
+      description: "Delete a tag by ID. The tag will be removed from all contacts and companies it was applied to.",
       inputSchema: {
         type: "object",
         properties: { id: { type: "string" } },
@@ -1543,7 +1636,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "add_tag_to_contact",
-      description: "Add a tag to a contact",
+      description: "Apply an existing tag to a contact. Use list_tags to find tag IDs.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1555,7 +1648,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "remove_tag_from_contact",
-      description: "Remove a tag from a contact",
+      description: "Remove a tag from a contact. The tag itself is not deleted.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1567,7 +1660,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "add_relationship",
-      description: "Add a relationship between two contacts",
+      description: "Link two contacts with a typed relationship. relationship_type: colleague (work peer), friend (personal), family (relative), reports_to (A reports to B), mentor (A mentors B), investor (A invests in B), partner (business partner), client, vendor, other.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1584,7 +1677,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "list_relationships",
-      description: "List all relationships for a contact",
+      description: "List all relationships for a contact, showing both directions (where contact is A or B).",
       inputSchema: {
         type: "object",
         properties: { contact_id: { type: "string" } },
@@ -1593,7 +1686,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "delete_relationship",
-      description: "Delete a relationship by ID",
+      description: "Delete a relationship by its ID. Use list_relationships to find relationship IDs.",
       inputSchema: {
         type: "object",
         properties: { id: { type: "string" } },
@@ -1602,7 +1695,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "merge_contacts",
-      description: "Merge two contacts \u2014 keeps one, removes the other, merging all data",
+      description: "Merge two contacts into one \u2014 all emails, phones, addresses, tags, and relationships from merge_id are moved to keep_id, then merge_id is deleted. Fields missing in keep_id are filled from merge_id.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1614,32 +1707,226 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "import_contacts",
-      description: "Import contacts from CSV, vCard, or JSON format",
+      description: "Import contacts from CSV (Google Contacts format), vCard (.vcf, v3/v4), or JSON array. Pass raw file contents as the data string. format: 'csv'|'vcf'|'json'.",
       inputSchema: {
         type: "object",
         properties: {
           format: { type: "string", enum: ["json", "csv", "vcf"] },
-          data: { type: "string" }
+          data: { type: "string", description: "Raw file contents (CSV text, vCard text, or JSON array string)" }
         },
         required: ["format", "data"]
       }
     },
     {
       name: "export_contacts",
-      description: "Export contacts to CSV, vCard, or JSON format",
+      description: "Export contacts to CSV, vCard (.vcf), or JSON format. Optionally specify contact_ids to export a subset; omit to export all contacts.",
       inputSchema: {
         type: "object",
         properties: {
           format: { type: "string", enum: ["json", "csv", "vcf"] },
-          contact_ids: { type: "array", items: { type: "string" } }
+          contact_ids: { type: "array", items: { type: "string" }, description: "Specific contact IDs to export (omit for all)" }
         },
         required: ["format"]
       }
     },
     {
       name: "get_stats",
-      description: "Get database statistics (counts of contacts, companies, tags)",
+      description: "Get database statistics: total counts of contacts, companies, tags, and groups.",
       inputSchema: { type: "object", properties: {} }
+    },
+    {
+      name: "log_interaction",
+      description: "Record a contact interaction \u2014 sets last_contacted_at to now (or a provided date) and optionally appends a timestamped note. Use this to track when you last spoke with someone.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          contact_id: { type: "string" },
+          note: { type: "string", description: "Optional note about the interaction to append to the contact's notes" },
+          date: { type: "string", description: "ISO 8601 datetime (defaults to now)" }
+        },
+        required: ["contact_id"]
+      }
+    },
+    {
+      name: "find_or_create_contact",
+      description: "Find an existing contact by email or name, or create a new one if not found. Returns { contact, found: boolean, created: boolean }. The #1 tool for agent workflows \u2014 avoids duplicate creation. Searches by email first (exact match), then by display_name.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          first_name: { type: "string" },
+          last_name: { type: "string" },
+          display_name: { type: "string" },
+          nickname: { type: "string" },
+          job_title: { type: "string" },
+          company_id: { type: "string" },
+          notes: { type: "string" },
+          birthday: { type: "string" },
+          website: { type: "string" },
+          last_contacted_at: { type: "string" },
+          preferred_contact_method: { type: "string", enum: ["email", "phone", "telegram", "whatsapp", "linkedin", "twitter", "other"] },
+          emails: { type: "array", items: { type: "object", properties: { address: { type: "string" }, type: { type: "string" }, is_primary: { type: "boolean" } }, required: ["address"] } },
+          phones: { type: "array", items: { type: "object" } },
+          addresses: { type: "array", items: { type: "object" } },
+          social_profiles: { type: "array", items: { type: "object" } },
+          tag_ids: { type: "array", items: { type: "string" } },
+          source: { type: "string" }
+        }
+      }
+    },
+    {
+      name: "upsert_contact",
+      description: "Update a contact if one with matching email exists, otherwise create a new one. Returns { contact, action: 'created'|'updated' }. Ideal for syncing data from external sources. Requires email in the emails array or as a top-level email field.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          first_name: { type: "string" },
+          last_name: { type: "string" },
+          display_name: { type: "string" },
+          nickname: { type: "string" },
+          job_title: { type: "string" },
+          company_id: { type: "string" },
+          notes: { type: "string" },
+          birthday: { type: "string" },
+          website: { type: "string" },
+          last_contacted_at: { type: "string" },
+          preferred_contact_method: { type: "string", enum: ["email", "phone", "telegram", "whatsapp", "linkedin", "twitter", "other"] },
+          email: { type: "string", description: "Primary email address (alternative to emails array)" },
+          emails: { type: "array", items: { type: "object", properties: { address: { type: "string" }, type: { type: "string" }, is_primary: { type: "boolean" } }, required: ["address"] } },
+          phones: { type: "array", items: { type: "object" } },
+          addresses: { type: "array", items: { type: "object" } },
+          social_profiles: { type: "array", items: { type: "object" } },
+          tag_ids: { type: "array", items: { type: "string" } },
+          source: { type: "string" }
+        }
+      }
+    },
+    {
+      name: "add_note",
+      description: "Append a timestamped note to a contact's notes field. Fast and ergonomic \u2014 no need for full update_contact. Note is appended as '\\n\\n[YYYY-MM-DD] text' to existing notes.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          contact_id: { type: "string" },
+          note: { type: "string" }
+        },
+        required: ["contact_id", "note"]
+      }
+    },
+    {
+      name: "list_contacts_by_company",
+      description: "List all contacts belonging to a specific company. Equivalent to list_contacts with company_id filter but more ergonomic.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          company_id: { type: "string" },
+          limit: { type: "number", description: "Max results (default 50)" },
+          offset: { type: "number" }
+        },
+        required: ["company_id"]
+      }
+    },
+    {
+      name: "list_contacts_by_tag",
+      description: "List all contacts with a specific tag. Accepts either a tag ID (UUID) or a tag name string.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          tag: { type: "string", description: "Tag name or tag ID (UUID)" },
+          limit: { type: "number", description: "Max results (default 50)" },
+          offset: { type: "number" }
+        },
+        required: ["tag"]
+      }
+    },
+    {
+      name: "create_group",
+      description: "Create a new group for organizing contacts. Groups are named collections that can hold multiple contacts.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          description: { type: "string" }
+        },
+        required: ["name"]
+      }
+    },
+    {
+      name: "list_groups",
+      description: "List all groups with their member counts.",
+      inputSchema: { type: "object", properties: {} }
+    },
+    {
+      name: "get_group",
+      description: "Get a group by ID.",
+      inputSchema: {
+        type: "object",
+        properties: { id: { type: "string" } },
+        required: ["id"]
+      }
+    },
+    {
+      name: "update_group",
+      description: "Update a group's name or description.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          name: { type: "string" },
+          description: { type: "string" }
+        },
+        required: ["id"]
+      }
+    },
+    {
+      name: "delete_group",
+      description: "Delete a group by ID. Contacts in the group are not deleted \u2014 only the group itself.",
+      inputSchema: {
+        type: "object",
+        properties: { id: { type: "string" } },
+        required: ["id"]
+      }
+    },
+    {
+      name: "add_contact_to_group",
+      description: "Add a contact to a group.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          contact_id: { type: "string" },
+          group_id: { type: "string" }
+        },
+        required: ["contact_id", "group_id"]
+      }
+    },
+    {
+      name: "remove_contact_from_group",
+      description: "Remove a contact from a group.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          contact_id: { type: "string" },
+          group_id: { type: "string" }
+        },
+        required: ["contact_id", "group_id"]
+      }
+    },
+    {
+      name: "list_contacts_in_group",
+      description: "List all contact IDs in a group.",
+      inputSchema: {
+        type: "object",
+        properties: { group_id: { type: "string" } },
+        required: ["group_id"]
+      }
+    },
+    {
+      name: "list_groups_for_contact",
+      description: "List all groups that a contact belongs to.",
+      inputSchema: {
+        type: "object",
+        properties: { contact_id: { type: "string" } },
+        required: ["contact_id"]
+      }
     }
   ]
 }));
@@ -1658,6 +1945,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           company_id: a.company_id,
           notes: a.notes,
           birthday: a.birthday,
+          website: a.website,
+          last_contacted_at: a.last_contacted_at,
+          preferred_contact_method: a.preferred_contact_method,
           emails: a.emails,
           phones: a.phones,
           addresses: a.addresses,
@@ -1682,7 +1972,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           job_title: rest.job_title,
           company_id: rest.company_id,
           notes: rest.notes,
-          birthday: rest.birthday
+          birthday: rest.birthday,
+          website: rest.website,
+          last_contacted_at: rest.last_contacted_at,
+          preferred_contact_method: rest.preferred_contact_method,
+          source: rest.source
         };
         const contact = updateContact(id, input);
         return { content: [{ type: "text", text: JSON.stringify(contact, null, 2) }] };
@@ -1847,13 +2141,210 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const contactCount = db.prepare("SELECT COUNT(*) as count FROM contacts").get().count;
         const companyCount = db.prepare("SELECT COUNT(*) as count FROM companies").get().count;
         const tagCount = db.prepare("SELECT COUNT(*) as count FROM tags").get().count;
+        const groupCount = db.prepare("SELECT COUNT(*) as count FROM groups").get().count;
         return {
           content: [{
             type: "text",
-            text: JSON.stringify({ contacts: contactCount, companies: companyCount, tags: tagCount }, null, 2)
+            text: JSON.stringify({ contacts: contactCount, companies: companyCount, tags: tagCount, groups: groupCount }, null, 2)
           }]
         };
       }
+      case "log_interaction": {
+        const contactId = a.contact_id;
+        const interactionDate = a.date ?? new Date().toISOString();
+        const note = a.note;
+        const existing = getContact(contactId);
+        const updateInput = { last_contacted_at: interactionDate };
+        if (note) {
+          const dateStr = interactionDate.slice(0, 10);
+          const existingNotes = existing.notes ?? "";
+          updateInput.notes = existingNotes ? `${existingNotes}
+
+[${dateStr}] ${note}` : `[${dateStr}] ${note}`;
+        }
+        const contact = updateContact(contactId, updateInput);
+        return { content: [{ type: "text", text: JSON.stringify(contact, null, 2) }] };
+      }
+      case "find_or_create_contact": {
+        const db = getDatabase();
+        const emailAddresses = a.emails?.map((e) => e.address) ?? [];
+        let found = null;
+        for (const addr of emailAddresses) {
+          const emailRow = db.prepare(`SELECT contact_id FROM emails WHERE address = ? AND contact_id IS NOT NULL LIMIT 1`).get(addr);
+          if (emailRow) {
+            found = getContact(emailRow.contact_id);
+            break;
+          }
+        }
+        if (!found && a.display_name) {
+          const results = searchContacts(a.display_name);
+          if (results.length > 0)
+            found = results[0];
+        }
+        if (found) {
+          return { content: [{ type: "text", text: JSON.stringify({ contact: found, found: true, created: false }, null, 2) }] };
+        }
+        const input = {
+          first_name: a.first_name,
+          last_name: a.last_name,
+          display_name: a.display_name,
+          nickname: a.nickname,
+          job_title: a.job_title,
+          company_id: a.company_id,
+          notes: a.notes,
+          birthday: a.birthday,
+          website: a.website,
+          last_contacted_at: a.last_contacted_at,
+          preferred_contact_method: a.preferred_contact_method,
+          emails: a.emails,
+          phones: a.phones,
+          addresses: a.addresses,
+          social_profiles: a.social_profiles,
+          tag_ids: a.tag_ids,
+          source: a.source
+        };
+        const contact = createContact(input);
+        return { content: [{ type: "text", text: JSON.stringify({ contact, found: false, created: true }, null, 2) }] };
+      }
+      case "upsert_contact": {
+        const db = getDatabase();
+        const upsertEmails = a.emails?.map((e) => e.address) ?? [];
+        if (a.email)
+          upsertEmails.unshift(a.email);
+        let existingContact = null;
+        for (const addr of upsertEmails) {
+          const emailRow = db.prepare(`SELECT contact_id FROM emails WHERE address = ? AND contact_id IS NOT NULL LIMIT 1`).get(addr);
+          if (emailRow) {
+            existingContact = getContact(emailRow.contact_id);
+            break;
+          }
+        }
+        if (existingContact) {
+          const updateInput = {
+            first_name: a.first_name,
+            last_name: a.last_name,
+            display_name: a.display_name,
+            nickname: a.nickname,
+            job_title: a.job_title,
+            company_id: a.company_id,
+            notes: a.notes,
+            birthday: a.birthday,
+            website: a.website,
+            last_contacted_at: a.last_contacted_at,
+            preferred_contact_method: a.preferred_contact_method,
+            source: a.source
+          };
+          const updated = updateContact(existingContact.id, updateInput);
+          return { content: [{ type: "text", text: JSON.stringify({ contact: updated, action: "updated" }, null, 2) }] };
+        }
+        const createInput = {
+          first_name: a.first_name,
+          last_name: a.last_name,
+          display_name: a.display_name,
+          nickname: a.nickname,
+          job_title: a.job_title,
+          company_id: a.company_id,
+          notes: a.notes,
+          birthday: a.birthday,
+          website: a.website,
+          last_contacted_at: a.last_contacted_at,
+          preferred_contact_method: a.preferred_contact_method,
+          emails: a.email ? [{ address: a.email, is_primary: true }, ...a.emails ?? []] : a.emails,
+          phones: a.phones,
+          addresses: a.addresses,
+          social_profiles: a.social_profiles,
+          tag_ids: a.tag_ids,
+          source: a.source
+        };
+        const created = createContact(createInput);
+        return { content: [{ type: "text", text: JSON.stringify({ contact: created, action: "created" }, null, 2) }] };
+      }
+      case "add_note": {
+        const contactId = a.contact_id;
+        const note = a.note;
+        const existing = getContact(contactId);
+        const dateStr = new Date().toISOString().slice(0, 10);
+        const existingNotes = existing.notes ?? "";
+        const updatedNotes = existingNotes ? `${existingNotes}
+
+[${dateStr}] ${note}` : `[${dateStr}] ${note}`;
+        const contact = updateContact(contactId, { notes: updatedNotes });
+        return { content: [{ type: "text", text: JSON.stringify(contact, null, 2) }] };
+      }
+      case "list_contacts_by_company": {
+        const result = listContacts({
+          company_id: a.company_id,
+          limit: a.limit,
+          offset: a.offset
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "list_contacts_by_tag": {
+        const tagInput = a.tag;
+        const db = getDatabase();
+        const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(tagInput);
+        let tagId = isUuid ? tagInput : null;
+        if (!tagId) {
+          const tag = getTagByName(tagInput, db);
+          if (!tag)
+            return { content: [{ type: "text", text: `Tag not found: ${tagInput}` }], isError: true };
+          tagId = tag.id;
+        }
+        const result = listContacts({
+          tag_id: tagId,
+          limit: a.limit,
+          offset: a.offset
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      }
+      case "create_group": {
+        const db = getDatabase();
+        const group = createGroup(db, { name: a.name, description: a.description });
+        return { content: [{ type: "text", text: JSON.stringify(group, null, 2) }] };
+      }
+      case "list_groups": {
+        const db = getDatabase();
+        const groups = listGroups(db);
+        return { content: [{ type: "text", text: JSON.stringify(groups, null, 2) }] };
+      }
+      case "get_group": {
+        const db = getDatabase();
+        const group = getGroup(db, a.id);
+        if (!group)
+          return { content: [{ type: "text", text: `Group not found: ${a.id}` }], isError: true };
+        return { content: [{ type: "text", text: JSON.stringify(group, null, 2) }] };
+      }
+      case "update_group": {
+        const db = getDatabase();
+        const { id: groupId, ...groupRest } = a;
+        const group = updateGroup(db, groupId, { name: groupRest.name, description: groupRest.description });
+        return { content: [{ type: "text", text: JSON.stringify(group, null, 2) }] };
+      }
+      case "delete_group": {
+        const db = getDatabase();
+        deleteGroup(db, a.id);
+        return { content: [{ type: "text", text: `Group ${a.id} deleted successfully` }] };
+      }
+      case "add_contact_to_group": {
+        const db = getDatabase();
+        addContactToGroup(db, a.contact_id, a.group_id);
+        return { content: [{ type: "text", text: `Contact ${a.contact_id} added to group ${a.group_id}` }] };
+      }
+      case "remove_contact_from_group": {
+        const db = getDatabase();
+        removeContactFromGroup(db, a.contact_id, a.group_id);
+        return { content: [{ type: "text", text: `Contact ${a.contact_id} removed from group ${a.group_id}` }] };
+      }
+      case "list_contacts_in_group": {
+        const db = getDatabase();
+        const contactIds = listContactsInGroup(db, a.group_id);
+        return { content: [{ type: "text", text: JSON.stringify(contactIds, null, 2) }] };
+      }
+      case "list_groups_for_contact": {
+        const db = getDatabase();
+        const groups = listGroupsForContact(db, a.contact_id);
+        return { content: [{ type: "text", text: JSON.stringify(groups, null, 2) }] };
+      }
       default:
         return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
     }