list_conversations
Retrieve Intercom conversations within a specific date range using startDate and endDate (DD/MM/YYYY format). Filter results by keyword or exclude content as needed. Ideal for analyzing support ticket history.
Instructions
Retrieves Intercom conversations within a specific date range.
Required: startDate, endDate (DD/MM/YYYY format, max 7-day range) Optional: keyword, exclude (for content filtering)
Always ask for specific dates when user makes vague time references.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | Yes | End date in DD/MM/YYYY format (e.g., '21/01/2025'). Required. | |
| exclude | No | Optional exclusion filter for conversation content. | |
| keyword | No | Optional keyword to filter conversations by content. | |
| startDate | Yes | Start date in DD/MM/YYYY format (e.g., '15/01/2025'). Required. |
Implementation Reference
- src/handlers/toolHandlers.ts:185-221 (handler)Core handler function executing the list_conversations tool: validates arguments with schema, calls Intercom service to fetch conversations by date range and filters, formats MCP-compliant response or error.
async handleListConversations(args: unknown) { try { console.error("Handling list_conversations request"); // Validate and parse arguments const validatedArgs = ListConversationsArgumentsSchema.parse(args); const startDateStr = validatedArgs.startDate; const endDateStr = validatedArgs.endDate; const keyword = validatedArgs.keyword; const exclude = validatedArgs.exclude; // Create Intercom service and retrieve conversations const intercomService = new IntercomService(this.API_BASE_URL, this.authToken); const conversations = await intercomService.getConversations( startDateStr, endDateStr, keyword, exclude ); console.error(`Retrieved ${conversations.length} conversations within date range`); return this.formatResponse(conversations); } catch (error) { console.error('Error handling list_conversations:', error); // Enhanced error message for validation errors if (error instanceof Error && (error.message.includes("startDate") || error.message.includes("endDate"))) { return this.formatErrorResponse(error, `${error.message}\n\nPlease provide both startDate and endDate in DD/MM/YYYY format (e.g., 15/01/2025)` ); } return this.formatErrorResponse(error); } } - src/types/schemas.ts:165-204 (schema)Zod schema for validating and transforming list_conversations input arguments, including date format checks, range validation (max 7 days), and conversion to ISO format.
export const ListConversationsArgumentsSchema = z.object({ // Required date range parameters in DD/MM/YYYY format startDate: z.string({ required_error: "startDate is required in DD/MM/YYYY format (e.g., 15/01/2025)" }).refine(val => /^\d{2}\/\d{2}\/\d{4}$/.test(val), { message: "startDate must be in DD/MM/YYYY format (e.g., 15/01/2025)" }), endDate: z.string({ required_error: "endDate is required in DD/MM/YYYY format (e.g., 21/01/2025)" }).refine(val => /^\d{2}\/\d{2}\/\d{4}$/.test(val), { message: "endDate must be in DD/MM/YYYY format (e.g., 21/01/2025)" }), // Optional string filters keyword: z.string().optional(), exclude: z.string().optional() }).transform(data => { console.error("Raw arguments received:", JSON.stringify(data)); try { // Convert DD/MM/YYYY to ISO strings data.startDate = validateAndTransformDate(data.startDate, true); data.endDate = validateAndTransformDate(data.endDate, false); // Validate date range validateDateRange(data.startDate, data.endDate); // Enforce 7-day maximum range validateMaxDateRange(data.startDate, data.endDate, 7); } catch (e) { // Throw error to be caught by the handler console.error(`Error processing date parameters: ${e}`); throw new Error(`${e instanceof Error ? e.message : 'Invalid date format'} - Please provide dates in DD/MM/YYYY format (e.g., 15/01/2025)`); } console.error("Final parameters:", JSON.stringify(data)); return data; }); - src/handlers/requestHandlers.ts:144-146 (registration)Dispatch logic in CallToolRequest handler that routes list_conversations calls to the toolHandlers.handleListConversations method.
case "list_conversations": console.error("Handling list_conversations request"); return await toolHandlers.handleListConversations(args); - src/index.ts:94-118 (registration)MCP server capabilities registration defining the list_conversations tool's description and input parameters schema.
list_conversations: { description: "Retrieves Intercom conversations within a specific date range (max 7 days).", parameters: { type: "object", required: ["startDate", "endDate"], properties: { startDate: { type: "string", description: "Start date in DD/MM/YYYY format (e.g., '15/01/2025'). Required." }, endDate: { type: "string", description: "End date in DD/MM/YYYY format (e.g., '21/01/2025'). Required." }, keyword: { type: "string", description: "Optional keyword to filter conversations by content." }, exclude: { type: "string", description: "Optional exclusion filter for conversation content." } } } } - src/handlers/requestHandlers.ts:76-105 (registration)Tool metadata (name, description, inputSchema) provided in response to list_tools requests.
name: "list_conversations", description: `Retrieves Intercom conversations within a specific date range. Required: startDate, endDate (DD/MM/YYYY format, max 7-day range) Optional: keyword, exclude (for content filtering) Always ask for specific dates when user makes vague time references.`, inputSchema: { type: "object", required: ["startDate", "endDate"], properties: { startDate: { type: "string", description: "Start date in DD/MM/YYYY format (e.g., '15/01/2025'). Required." }, endDate: { type: "string", description: "End date in DD/MM/YYYY format (e.g., '21/01/2025'). Required." }, keyword: { type: "string", description: "Optional keyword to filter conversations by content." }, exclude: { type: "string", description: "Optional exclusion filter for conversation content." } } }, },