Monica CRM MCP Server

Instructions

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
    };
  }