monica_search_contacts
Search contacts in Monica CRM by name, nickname, or email to find contact IDs and basic information for further actions.
Instructions
Search Monica CRM contacts by name, nickname, or email. Returns contact IDs and basic info. Use the returned ID with other tools to get details or make updates.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No | ||
| page | No | ||
| includePartial | No |
Implementation Reference
- src/tools/modules/search.ts:19-65 (handler)The async handler function that performs the contact search using the Monica client, processes and formats the results with normalizeContactSummary, limits output, and returns a structured response including text summary and pagination metadata.async ({ query, limit, page, includePartial }) => { const maxDefault = 5; const maxAllowed = 25; const effectiveLimit = limit ? Math.min(Math.max(limit, 1), maxAllowed) : maxDefault; const results = await client.searchContacts({ query, limit: effectiveLimit, page, includePartial }); const contacts = results.data.map(normalizeContactSummary); const maxDisplay = Math.min(effectiveLimit, maxDefault); const displayed = contacts.slice(0, maxDisplay); const truncated = contacts.length > maxDisplay; const text = contacts.length ? `Found ${contacts.length} contact(s) matching "${query}":\n\n${displayed .map((contact) => { const emails = contact.emails.length ? ` (${contact.emails.join(', ')})` : ''; const phones = contact.phones.length ? ` [${contact.phones.join(', ')}]` : ''; const nickname = contact.nickname ? ` "${contact.nickname}"` : ''; return `• ID: ${contact.id} - ${contact.name}${nickname}${emails}${phones}`; }) .join('\n')}${truncated ? '\n\nOnly the first matches are shown. Refine your search or request another page if you need the rest.' : ''}` : `No Monica contacts matched "${query}".`; return { content: [ { type: 'text' as const, text } ], structuredContent: { contacts, pagination: { currentPage: results.meta.current_page, lastPage: results.meta.last_page, perPage: results.meta.per_page, total: results.meta.total } } }; }
- src/tools/modules/search.ts:12-17 (schema)Zod input schema for the tool parameters: query (string min length 2), optional limit (1-100), page (>=1), includePartial (boolean).inputSchema: { query: z.string().min(2, 'Provide at least 2 characters to search.'), limit: z.number().int().min(1).max(100).optional(), page: z.number().int().min(1).optional(), includePartial: z.boolean().optional() }
- src/tools/modules/search.ts:5-67 (registration)registerSearchTools exported function that calls server.registerTool to register 'monica_search_contacts' with title, description, inputSchema, and the handler function.export function registerSearchTools({ server, client }: ToolRegistrationContext): void { server.registerTool( 'monica_search_contacts', { title: 'Search Monica contacts', description: 'Search Monica CRM contacts by name, nickname, or email. Returns contact IDs and basic info. Use the returned ID with other tools to get details or make updates.', inputSchema: { query: z.string().min(2, 'Provide at least 2 characters to search.'), limit: z.number().int().min(1).max(100).optional(), page: z.number().int().min(1).optional(), includePartial: z.boolean().optional() } }, async ({ query, limit, page, includePartial }) => { const maxDefault = 5; const maxAllowed = 25; const effectiveLimit = limit ? Math.min(Math.max(limit, 1), maxAllowed) : maxDefault; const results = await client.searchContacts({ query, limit: effectiveLimit, page, includePartial }); const contacts = results.data.map(normalizeContactSummary); const maxDisplay = Math.min(effectiveLimit, maxDefault); const displayed = contacts.slice(0, maxDisplay); const truncated = contacts.length > maxDisplay; const text = contacts.length ? `Found ${contacts.length} contact(s) matching "${query}":\n\n${displayed .map((contact) => { const emails = contact.emails.length ? ` (${contact.emails.join(', ')})` : ''; const phones = contact.phones.length ? ` [${contact.phones.join(', ')}]` : ''; const nickname = contact.nickname ? ` "${contact.nickname}"` : ''; return `• ID: ${contact.id} - ${contact.name}${nickname}${emails}${phones}`; }) .join('\n')}${truncated ? '\n\nOnly the first matches are shown. Refine your search or request another page if you need the rest.' : ''}` : `No Monica contacts matched "${query}".`; return { content: [ { type: 'text' as const, text } ], structuredContent: { contacts, pagination: { currentPage: results.meta.current_page, lastPage: results.meta.last_page, perPage: results.meta.per_page, total: results.meta.total } } }; } ); }
- src/tools/registerTools.ts:25-25 (registration)In the main registerTools function, calls registerSearchTools(context) to register the search tools including monica_search_contacts.registerSearchTools(context);
- src/utils/formatters.ts:30-40 (helper)normalizeContactSummary utility function imported and used to normalize contact data from search results into a summary format with id, name, nickname, emails, phones, isPartial.export function normalizeContactSummary(contact: MonicaContact) { return { id: contact.id, name: [contact.first_name, contact.last_name].filter(Boolean).join(' ').trim(), nickname: contact.nickname ?? undefined, gender: contact.gender ?? undefined, emails: contact.information?.emails?.map((email) => email.value) ?? [], phones: contact.information?.phones?.map((phone) => phone.value) ?? [], isPartial: contact.is_partial }; }