Monica CRM MCP Server

Instructions

Implementation Reference

• src/tools/modules/actionItems.ts:125-133 (handler)

  Main tool handler function: validates input and dispatches to task or reminder handler based on itemType.

  async (rawInput) => {
    const input = actionItemSchema.parse(rawInput);
  
    if (input.itemType === 'task') {
      return handleTaskAction({ input: input as TaskActionInput, client, logger });
    }
  
    return handleReminderAction({ input: input as ReminderActionInput, client, logger });
  }

• src/tools/modules/actionItems.ts:137-268 (handler)

  Handler for task actions: list, get, create, update, delete tasks using Monica API.

  async function handleTaskAction({
    input,
    client,
    logger
  }: {
    input: TaskActionInput;
    client: ToolRegistrationContext['client'];
    logger: ToolRegistrationContext['logger'];
  }) {
    switch (input.action) {
      case 'list': {
        const response = await client.listTasks({
          contactId: input.contactId,
          status: input.status,
          limit: input.limit,
          page: input.page
        });
        const tasks = response.data.map(normalizeTask);
        const scope = input.contactId ? `contact ${input.contactId}` : 'your account';
        const summary = tasks.length
          ? `Fetched ${tasks.length} task${tasks.length === 1 ? '' : 's'} for ${scope}.`
          : `No tasks found for ${scope}.`;
  
        return {
          content: [
            {
              type: 'text' as const,
              text: summary
            }
          ],
          structuredContent: {
            itemType: input.itemType,
            action: input.action,
            contactId: input.contactId,
            status: input.status,
            tasks,
            pagination: {
              currentPage: response.meta.current_page,
              lastPage: response.meta.last_page,
              perPage: response.meta.per_page,
              total: response.meta.total
            }
          }
        };
      }
  
      case 'get': {
        const response = await client.getTask(input.taskId!);
        const task = normalizeTask(response.data);
  
        return {
          content: [
            {
              type: 'text' as const,
              text: `Task ${task.title} (ID ${task.id}).`
            }
          ],
          structuredContent: {
            itemType: input.itemType,
            action: input.action,
            task
          }
        };
      }
  
      case 'create': {
        const payload = input.taskPayload!;
        const result = await client.createTask(toTaskCreatePayload(payload));
        const task = normalizeTask(result.data);
        logger.info({ taskId: task.id }, 'Created Monica task');
  
        return {
          content: [
            {
              type: 'text' as const,
              text: `Created task ${task.title || `#${task.id}`} (ID ${task.id}).`
            }
          ],
          structuredContent: {
            itemType: input.itemType,
            action: input.action,
            task
          }
        };
      }
  
      case 'update': {
        const payload = input.taskPayload!;
        const result = await client.updateTask(input.taskId!, toTaskUpdatePayload(payload));
        const task = normalizeTask(result.data);
        logger.info({ taskId: input.taskId }, 'Updated Monica task');
  
        return {
          content: [
            {
              type: 'text' as const,
              text: `Updated task ${task.title || `#${task.id}`} (ID ${task.id}).`
            }
          ],
          structuredContent: {
            itemType: input.itemType,
            action: input.action,
            taskId: input.taskId,
            task
          }
        };
      }
  
      case 'delete': {
        const result = await client.deleteTask(input.taskId!);
        logger.info({ taskId: input.taskId }, 'Deleted Monica task');
  
        return {
          content: [
            {
              type: 'text' as const,
              text: `Deleted task ID ${input.taskId}.`
            }
          ],
          structuredContent: {
            itemType: input.itemType,
            action: input.action,
            taskId: input.taskId,
            result
          }
        };
      }
  
      default:
        return unreachable(input.action as never);
    }
  }

• src/tools/modules/actionItems.ts:270-445 (handler)

  Handler for reminder actions: list, get, create, update, delete reminders using Monica API.

  async function handleReminderAction({
    input,
    client,
    logger
  }: {
    input: ReminderActionInput;
    client: ToolRegistrationContext['client'];
    logger: ToolRegistrationContext['logger'];
  }) {
    switch (input.action) {
      case 'list': {
        const response = await client.listReminders({
          contactId: input.contactId,
          limit: input.limit,
          page: input.page
        });
        const reminders = response.data.map(normalizeReminder);
        const scope = input.contactId ? `contact ${input.contactId}` : 'your account';
        const text = reminders.length
          ? `Found ${reminders.length} reminder${reminders.length === 1 ? '' : 's'} for ${scope}.`
          : `No reminders found for ${scope}.`;
  
        return {
          content: [
            {
              type: 'text' as const,
              text
            }
          ],
          structuredContent: {
            itemType: input.itemType,
            action: input.action,
            contactId: input.contactId,
            reminders,
            pagination: {
              currentPage: response.meta.current_page,
              lastPage: response.meta.last_page,
              perPage: response.meta.per_page,
              total: response.meta.total
            }
          }
        };
      }
  
      case 'get': {
        const response = await client.getReminder(input.reminderId!);
        const reminder = normalizeReminder(response.data);
        const contactName = reminder.contact?.name || `Contact ${reminder.contactId}`;
  
        return {
          content: [
            {
              type: 'text' as const,
              text: `Reminder "${reminder.title}" for ${contactName}. Next due ${reminder.nextExpectedDate ?? 'unknown'}.`
            }
          ],
          structuredContent: {
            itemType: input.itemType,
            action: input.action,
            reminder
          }
        };
      }
  
      case 'create': {
        const payload = input.reminderPayload!;
        let createPayload: CreateReminderPayload;
        try {
          createPayload = toReminderCreatePayload(payload);
        } catch (error) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: (error as Error).message }
            ]
          };
        }
  
        try {
          const response = await client.createReminder(createPayload);
          const reminder = normalizeReminder(response.data);
          logger.info({ reminderId: reminder.id, contactId: reminder.contactId }, 'Created Monica reminder');
  
          return {
            content: [
              {
                type: 'text' as const,
                text: `Created reminder "${reminder.title}" for contact ${reminder.contactId}.`
              }
            ],
            structuredContent: {
              itemType: input.itemType,
              action: input.action,
              reminder
            }
          };
        } catch (error) {
          if (error instanceof MonicaApiError) {
            return buildErrorResponse(formatMonicaApiError(error));
          }
          throw error;
        }
      }
  
      case 'update': {
        const payload = input.reminderPayload!;
        let updatePayload: UpdateReminderPayload;
        try {
          updatePayload = toReminderUpdatePayload(payload);
        } catch (error) {
          return {
            isError: true as const,
            content: [
              { type: 'text' as const, text: (error as Error).message }
            ]
          };
        }
  
        try {
          const response = await client.updateReminder(input.reminderId!, updatePayload);
          const reminder = normalizeReminder(response.data);
          logger.info({ reminderId: input.reminderId }, 'Updated Monica reminder');
  
          return {
            content: [
              {
                type: 'text' as const,
                text: `Updated reminder "${reminder.title}" (ID ${reminder.id}).`
              }
            ],
            structuredContent: {
              itemType: input.itemType,
              action: input.action,
              reminderId: input.reminderId,
              reminder
            }
          };
        } catch (error) {
          if (error instanceof MonicaApiError) {
            return buildErrorResponse(formatMonicaApiError(error));
          }
          throw error;
        }
      }
  
      case 'delete': {
        try {
          const result = await client.deleteReminder(input.reminderId!);
          logger.info({ reminderId: input.reminderId }, 'Deleted Monica reminder');
  
          return {
            content: [
              {
                type: 'text' as const,
                text: `Deleted reminder ID ${input.reminderId}.`
              }
            ],
            structuredContent: {
              itemType: input.itemType,
              action: input.action,
              reminderId: input.reminderId,
              result
            }
          };
        } catch (error) {
          if (error instanceof MonicaApiError) {
            return buildErrorResponse(formatMonicaApiError(error));
          }
          throw error;
        }
      }
  
      default:
        return unreachable(input.action as never);
    }
  }

• src/tools/modules/actionItems.ts:41-108 (schema)

  Zod schemas for tool input validation, including sub-schemas for task and reminder payloads and superRefine for action-specific checks.

  const actionItemInputShape = {
    itemType: z.enum(['task', 'reminder']),
    action: z.enum(['list', 'get', 'create', 'update', 'delete']),
    taskId: z.number().int().positive().optional(),
    reminderId: z.number().int().positive().optional(),
    contactId: z.number().int().positive().optional(),
    status: z.enum(['open', 'completed', 'all']).optional(),
    limit: z.number().int().min(1).max(100).optional(),
    page: z.number().int().min(1).optional(),
    taskPayload: taskPayloadSchema.optional(),
    reminderPayload: reminderPayloadSchema.optional()
  } as const;
  
  const actionItemSchema = z.object(actionItemInputShape).superRefine((data, ctx) => {
    if (data.itemType === 'task') {
      switch (data.action) {
        case 'list':
          break;
        case 'get':
        case 'delete':
          if (typeof data.taskId !== 'number') {
            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide taskId for this action.' });
          }
          break;
        case 'create':
          if (!data.taskPayload) {
            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide task details when creating a task.' });
          }
          break;
        case 'update':
          if (typeof data.taskId !== 'number') {
            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide taskId when updating a task.' });
          }
          if (!data.taskPayload) {
            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide task details when updating a task.' });
          }
          break;
        default:
          break;
      }
    } else {
      switch (data.action) {
        case 'list':
          break;
        case 'get':
        case 'delete':
          if (typeof data.reminderId !== 'number') {
            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide reminderId for this action.' });
          }
          break;
        case 'create':
          if (!data.reminderPayload) {
            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide reminder details when creating a reminder.' });
          }
          break;
        case 'update':
          if (typeof data.reminderId !== 'number') {
            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide reminderId when updating a reminder.' });
          }
          if (!data.reminderPayload) {
            ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide reminder details when updating a reminder.' });
          }
          break;
        default:
          break;
      }
    }
  });

• src/tools/modules/actionItems.ts:117-134 (registration)

  Registers the 'monica_manage_task_reminder' tool with the MCP server.

  server.registerTool(
    'monica_manage_task_reminder',
    {
      title: 'Manage Monica tasks and reminders',
      description:
        'List, inspect, create, update, or delete Monica tasks and reminders. Choose itemType="task" for to-dos or itemType="reminder" for stay-in-touch nudges.',
      inputSchema: actionItemInputShape
    },
    async (rawInput) => {
      const input = actionItemSchema.parse(rawInput);
  
      if (input.itemType === 'task') {
        return handleTaskAction({ input: input as TaskActionInput, client, logger });
      }
  
      return handleReminderAction({ input: input as ReminderActionInput, client, logger });
    }
  );