Monica CRM MCP Server

Instructions

Implementation Reference

• src/tools/modules/media.ts:69-90 (registration)

  Registers the 'monica_manage_media' tool with server.registerTool, providing title, description, input schema, and a dispatching handler that routes to document or photo handlers based on mediaType.
  export function registerMediaTools(context: ToolRegistrationContext): void { const { server, client, logger } = context; server.registerTool( 'monica_manage_media', { title: 'Manage Monica documents and photos', description: 'List, inspect, upload, or delete documents and photos stored in Monica. Use mediaType to pick the resource.', inputSchema: mediaInputShape }, async (rawInput: unknown) => { const input = mediaInputSchema.parse(rawInput); if (input.mediaType === 'document') { return handleDocument({ input: input as DocumentInput, client, logger }); } return handlePhoto({ input: input as PhotoInput, client, logger }); } ); }
• src/tools/modules/media.ts:7-60 (schema)

  Defines the input schema using Zod (mediaInputShape and mediaInputSchema) with validation rules for mediaType, action, and other parameters specific to Monica media management.
  const mediaInputShape = { mediaType: z.enum(['document', 'photo']), action: z.enum(['list', 'get', 'upload', 'delete']), mediaId: z.number().int().positive().optional(), contactId: z.number().int().positive().optional(), limit: z.number().int().min(1).max(100).optional(), page: z.number().int().min(1).optional(), filePath: z.string().min(1).optional(), base64Data: z.string().min(1).optional(), fileName: z.string().min(1).optional(), mimeType: z.string().min(1).optional() } as const; const mediaInputSchema = z .object(mediaInputShape) .superRefine((input, ctx) => { if (['get', 'delete'].includes(input.action) && input.mediaId == null) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'mediaId is required for get and delete actions.', path: ['mediaId'] }); } if (input.action === 'upload') { if (!input.filePath && !input.base64Data) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Provide either filePath or base64Data when uploading media.', path: ['filePath'] }); } if (input.filePath && input.base64Data) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Choose either filePath or base64Data, not both.', path: ['filePath'] }); } if (!input.filePath && !input.fileName) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'fileName is required when providing base64Data directly.', path: ['fileName'] }); } } }); type MediaInput = z.infer<typeof mediaInputSchema>; type DocumentInput = MediaInput & { mediaType: 'document' };
• src/tools/modules/media.ts:92-174 (handler)

  Handler for document operations (list, get, upload, delete) using Monica client API, with response building and logging.
  async function handleDocument({ input, client, logger }: HandlerArgs<DocumentInput>) { switch (input.action) { case 'list': { const response = await client.listDocuments({ contactId: input.contactId, limit: input.limit, page: input.page }); const documents = response.data.map(normalizeDocument); return buildListResponse({ mediaType: input.mediaType, action: input.action, contactId: input.contactId, records: documents, pagination: response.meta }); } case 'get': { if (input.mediaId == null) { return missingMediaIdError('document', input.action); } const response = await client.getDocument(input.mediaId); const document = normalizeDocument(response.data); return buildSingleRecordResponse({ mediaType: input.mediaType, action: input.action, mediaId: input.mediaId, record: document, text: `Document ${document.originalFilename} (ID ${document.id}).` }); } case 'upload': { const upload = await prepareUploadPayload(input); const response = await client.uploadDocument({ base64Data: upload.base64Data, fileName: upload.fileName, mimeType: upload.mimeType, contactId: input.contactId }); const document = normalizeDocument(response.data); logger.info({ documentId: document.id, contactId: input.contactId }, 'Uploaded Monica document'); return buildSingleRecordResponse({ mediaType: input.mediaType, action: input.action, record: document, text: `Uploaded document ${document.originalFilename} (ID ${document.id}).` }); } case 'delete': { if (input.mediaId == null) { return missingMediaIdError('document', input.action); } await client.deleteDocument(input.mediaId); logger.info({ documentId: input.mediaId }, 'Deleted Monica document'); return { content: [ { type: 'text' as const, text: `Deleted document ID ${input.mediaId}.` } ], structuredContent: { mediaType: input.mediaType, action: input.action, mediaId: input.mediaId, deleted: true } }; } default: return unknownActionError(input.action); } }
• src/tools/modules/media.ts:176-258 (handler)

  Handler for photo operations (list, get, upload, delete) using Monica client API, with response building and logging.
  async function handlePhoto({ input, client, logger }: HandlerArgs<PhotoInput>) { switch (input.action) { case 'list': { const response = await client.listPhotos({ contactId: input.contactId, limit: input.limit, page: input.page }); const photos = response.data.map(normalizePhoto); return buildListResponse({ mediaType: input.mediaType, action: input.action, contactId: input.contactId, records: photos, pagination: response.meta }); } case 'get': { if (input.mediaId == null) { return missingMediaIdError('photo', input.action); } const response = await client.getPhoto(input.mediaId); const photo = normalizePhoto(response.data); return buildSingleRecordResponse({ mediaType: input.mediaType, action: input.action, mediaId: input.mediaId, record: photo, text: `Photo ${photo.originalFilename} (ID ${photo.id}).` }); } case 'upload': { const upload = await prepareUploadPayload(input); const response = await client.uploadPhoto({ base64Data: upload.base64Data, fileName: upload.fileName, mimeType: upload.mimeType, contactId: input.contactId }); const photo = normalizePhoto(response.data); logger.info({ photoId: photo.id, contactId: input.contactId }, 'Uploaded Monica photo'); return buildSingleRecordResponse({ mediaType: input.mediaType, action: input.action, record: photo, text: `Uploaded photo ${photo.originalFilename} (ID ${photo.id}).` }); } case 'delete': { if (input.mediaId == null) { return missingMediaIdError('photo', input.action); } await client.deletePhoto(input.mediaId); logger.info({ photoId: input.mediaId }, 'Deleted Monica photo'); return { content: [ { type: 'text' as const, text: `Deleted photo ID ${input.mediaId}.` } ], structuredContent: { mediaType: input.mediaType, action: input.action, mediaId: input.mediaId, deleted: true } }; } default: return unknownActionError(input.action); } }
• src/tools/modules/media.ts:282-315 (helper)

  Helper function to prepare upload payload by reading file or using base64, resolving MIME types.
  async function prepareUploadPayload(input: MediaInput) { if (!input.filePath && !input.base64Data) { throw new Error('Provide either filePath or base64Data for uploads.'); } if (input.filePath) { const resolvedPath = resolveFilePath(input.filePath); try { const fileBuffer = await readFile(resolvedPath); const fileName = input.fileName ? basename(input.fileName) : basename(resolvedPath); const mimeType = resolveMimeType(fileName, input.mimeType); return { base64Data: fileBuffer.toString('base64'), fileName, mimeType }; } catch (error) { throw new Error(`Unable to read file at ${resolvedPath}: ${(error as Error).message}`); } } if (!input.base64Data || !input.fileName) { throw new Error('Provide base64Data and fileName when not using filePath.'); } const fileName = basename(input.fileName); return { base64Data: input.base64Data, fileName, mimeType: resolveMimeType(fileName, input.mimeType) }; }