Monica CRM MCP Server

Instructions

Implementation Reference

• src/tools/modules/contactWrappers.ts:86-107 (registration)

  Registration of the monica_manage_contact_profile tool. This thin wrapper registers a dedicated tool that delegates to the shared handleContactOperation with section='profile'.

  server.registerTool(
    'monica_manage_contact_profile',
    {
      title: 'Manage contact profile',
      description:
        'Create, update, or delete a contact profile. Use this simplified tool instead of monica_manage_contact when working with contact profiles. Provide firstName, lastName, and optional fields like nickname, description, genderName, birthdate, etc. Gender is optional - omit if unknown.',
      inputSchema: profileInputSchema
    },
    async (rawInput) => {
      const input = z.object(profileInputSchema).parse(rawInput);
  
      return handleContactOperation(
        {
          section: 'profile',
          action: input.action,
          contactId: input.contactId,
          profile: input.profile
        },
        context
      );
    }
  );

• src/tools/modules/contacts.ts:233-296 (handler)

  Handler logic for profile operations (create, update, delete contact profiles) in the shared handleContactOperation function, invoked by the wrapper tool.

  case 'profile': {
    if (input.action === 'delete') {
      await client.deleteContact(input.contactId!);
      logger.info({ contactId: input.contactId }, 'Deleted Monica contact');
  
      return {
        content: [
          {
            type: 'text' as const,
            text: `Deleted contact ID ${input.contactId}.`
          }
        ],
        structuredContent: {
          section: input.section,
          action: input.action,
          contactId: input.contactId
        }
      };
    }
  
    const profile = input.profile!;
    const contactId = input.contactId;
    const genderId = await resolveGenderId(client, profile.genderId, profile.genderName);
    const payload = toContactProfileInput({ ...profile, genderId });
  
    if (input.action === 'create') {
      const response = await client.createContact(payload);
      const contact = normalizeContactDetail(response.data);
      logger.info({ contactId: contact.id }, 'Created Monica contact');
  
      return {
        content: [
          {
            type: 'text' as const,
            text: `Created contact ${contact.name || `#${contact.id}`} (ID ${contact.id}).`
          }
        ],
        structuredContent: {
          section: input.section,
          action: input.action,
          contact
        }
      };
    }
  
    const response = await client.updateContact(contactId!, payload);
    const contact = normalizeContactDetail(response.data);
    logger.info({ contactId }, 'Updated Monica contact');
  
    return {
      content: [
        {
          type: 'text' as const,
          text: `Updated contact ${contact.name || `#${contact.id}`} (ID ${contact.id}).`
        }
      ],
      structuredContent: {
        section: input.section,
        action: input.action,
        contactId,
        contact
      }
    };
  }

• src/tools/modules/contactWrappers.ts:43-55 (schema)

  Zod schema defining the contact profile input structure, used in the tool's inputSchema.

  const contactProfileSchema = z.object({
    firstName: z.string().min(1).max(50),
    lastName: z.string().max(100).optional().nullable(),
    nickname: z.string().max(100).optional().nullable(),
    description: z.string().max(2000).optional().nullable(),
    genderId: z.number().int().positive().optional(),
    genderName: z.string().min(1).max(50).optional(),
    isPartial: z.boolean().optional(),
    isDeceased: z.boolean().optional(),
    birthdate: birthdateSchema.optional(),
    deceasedDate: deceasedDateSchema.optional(),
    remindOnDeceasedDate: z.boolean().optional()
  });

• src/tools/modules/contacts.ts:597-610 (helper)

  Helper function to transform the input profile form to the Monica API ContactProfileInput format.

  function toContactProfileInput(profile: ContactProfileForm & { genderId?: number }): ContactProfileInput {
    return {
      firstName: profile.firstName,
      lastName: profile.lastName ?? null,
      nickname: profile.nickname ?? null,
      description: profile.description ?? null,
      genderId: profile.genderId,
      isPartial: profile.isPartial,
      isDeceased: profile.isDeceased,
      birthdate: profile.birthdate as ContactProfileInput['birthdate'],
      deceasedDate: profile.deceasedDate as ContactProfileInput['deceasedDate'],
      remindOnDeceasedDate: profile.remindOnDeceasedDate
    };
  }

• src/tools/modules/contactWrappers.ts:80-84 (schema)

  Tool-specific input schema combining action, optional contactId, and profile data.

  const profileInputSchema = {
    action: z.enum(['create', 'update', 'delete']),
    contactId: z.number().int().positive().optional(),
    profile: contactProfileSchema.optional()
  };