search_contacts
Find and retrieve WhatsApp contacts by searching names or phone number parts using JID, enabling efficient contact management through the WhatsApp MCP Server.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search term for contact name or phone number part of JID |
Implementation Reference
- src/mcp.ts:78-110 (handler)The main handler function for the 'search_contacts' MCP tool. It takes a query, calls the database helper searchDbForContacts, formats the contacts (jid and name), returns as JSON text, and handles errors with logging.async ({ query }) => { mcpLogger.info( `[MCP Tool] Executing search_contacts with query: "${query}"`, ); try { const contacts = searchDbForContacts(query, 20); const formattedContacts = contacts.map((c) => ({ jid: c.jid, name: c.name ?? c.jid.split("@")[0], })); return { content: [ { type: "text", text: JSON.stringify(formattedContacts, null, 2), }, ], }; } catch (error: any) { mcpLogger.error( `[MCP Tool Error] search_contacts failed: ${error.message}`, ); return { isError: true, content: [ { type: "text", text: `Error searching contacts: ${error.message}`, }, ], }; } },
- src/mcp.ts:72-77 (schema)Input schema for search_contacts tool using Zod, validating 'query' as non-empty string with description.{ query: z .string() .min(1) .describe("Search term for contact name or phone number part of JID"), },
- src/mcp.ts:71-111 (registration)Registration of the search_contacts tool on the McpServer instance, specifying name, input schema, and handler."search_contacts", { query: z .string() .min(1) .describe("Search term for contact name or phone number part of JID"), }, async ({ query }) => { mcpLogger.info( `[MCP Tool] Executing search_contacts with query: "${query}"`, ); try { const contacts = searchDbForContacts(query, 20); const formattedContacts = contacts.map((c) => ({ jid: c.jid, name: c.name ?? c.jid.split("@")[0], })); return { content: [ { type: "text", text: JSON.stringify(formattedContacts, null, 2), }, ], }; } catch (error: any) { mcpLogger.error( `[MCP Tool Error] search_contacts failed: ${error.message}`, ); return { isError: true, content: [ { type: "text", text: `Error searching contacts: ${error.message}`, }, ], }; } }, );
- src/database.ts:344-368 (helper)Database helper function implementing the contact search logic: queries chats table for names or JIDs matching query (case-insensitive), excludes group chats (@g.us), limits results, maps to {jid, name}.export function searchDbForContacts( query: string, limit: number = 20, ): Pick<Chat, "jid" | "name">[] { const db = getDb(); try { const searchPattern = `%${query}%`; const stmt = db.prepare(` SELECT DISTINCT jid, name FROM chats WHERE (LOWER(name) LIKE LOWER(?) OR jid LIKE ?) -- Positional params 1, 2 AND jid NOT LIKE '%@g.us' -- Exclude groups ORDER BY name ASC, jid ASC LIMIT ? -- Positional param 3 `); const rows = stmt.all(searchPattern, searchPattern, limit) as Pick< Chat, "jid" | "name" >[]; return rows.map((row) => ({ jid: row.jid, name: row.name ?? null })); } catch (error) { console.error("Error searching contacts:", error); return []; } }