MCP Server for Intercom

Instructions

Implementation Reference

• src/handlers/toolHandlers.ts:67-103 (handler)

  Core handler function that executes the tool: validates input with schema, fetches conversations via IntercomService.getConversationsByCustomer, formats and returns MCP-compliant response or error.
  async handleSearchConversationsByCustomer(args: unknown) { try { console.error("Handling search_conversations_by_customer request"); // Validate and parse arguments const validatedArgs = SearchConversationsByCustomerSchema.parse(args); const customerIdentifier = validatedArgs.customerIdentifier; const startDateStr = validatedArgs.startDate; const endDateStr = validatedArgs.endDate; const keywords = validatedArgs.keywords; // Create Intercom service and retrieve conversations const intercomService = new IntercomService(this.API_BASE_URL, this.authToken); const conversations = await intercomService.getConversationsByCustomer( customerIdentifier, startDateStr, endDateStr, keywords ); console.error(`Retrieved ${conversations.length} conversations for customer: ${customerIdentifier}`); return this.formatResponse(conversations); } catch (error) { console.error('Error handling search_conversations_by_customer:', error); // Enhanced error message for validation errors if (error instanceof Error && error.message.includes("customerIdentifier")) { return this.formatErrorResponse(error, `${error.message}\n\nPlease provide a valid customer email or ID, and optional dates in DD/MM/YYYY format (e.g., 15/01/2025)` ); } return this.formatErrorResponse(error); } }
• src/types/schemas.ts:70-113 (schema)

  Zod schema defining and validating tool inputs: required customerIdentifier, optional startDate/endDate/keywords with date transformation and validation.
  export const SearchConversationsByCustomerSchema = z.object({ // Required customer identifier parameter customerIdentifier: z.string({ required_error: "customerIdentifier is required (email or ID)" }), // Optional date range parameters in DD/MM/YYYY format startDate: z.string().optional().refine(val => !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().optional().refine(val => !val || /^\d{2}\/\d{2}\/\d{4}$/.test(val), { message: "endDate must be in DD/MM/YYYY format (e.g., 21/01/2025)" }), // Optional keywords array for filtering conversations keywords: z.array(z.string()).optional().describe("Array of keywords to filter conversations by content") }).transform(data => { console.error("Raw arguments received:", JSON.stringify(data)); try { // Convert DD/MM/YYYY to ISO strings if provided if (data.startDate) { data.startDate = validateAndTransformDate(data.startDate, true); } if (data.endDate) { data.endDate = validateAndTransformDate(data.endDate, false); } // Validate date range if both dates are provided if (data.startDate && data.endDate) { validateDateRange(data.startDate, data.endDate); } } 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/index.ts:25-50 (registration)

  Tool registration in MCP server capabilities, specifying name, description, and input parameters schema.
  search_conversations_by_customer: { description: "Searches for conversations by customer email or ID with optional date filtering.", parameters: { type: "object", required: ["customerIdentifier"], properties: { customerIdentifier: { type: "string", description: "Customer email or ID to search for" }, startDate: { type: "string", description: "Optional start date in DD/MM/YYYY format (e.g., '15/01/2025')" }, endDate: { type: "string", description: "Optional end date in DD/MM/YYYY format (e.g., '21/01/2025')" }, keywords: { type: "array", items: { type: "string" }, description: "Optional keywords to filter conversations by content" } } } },
• src/handlers/requestHandlers.ts:147-149 (registration)

  Dispatcher in call_tool request handler that routes requests for this tool to the specific ToolHandlers method.
  case "search_conversations_by_customer": console.error("Handling search_conversations_by_customer request"); return await toolHandlers.handleSearchConversationsByCustomer(args);
• src/handlers/requestHandlers.ts:15-46 (registration)

  Tool metadata provided in list_tools response, including detailed description and input schema.
  name: "search_conversations_by_customer", description: `Searches for conversations by customer email or ID with optional date filtering. Required: customerIdentifier (email/ID) Optional: startDate, endDate (DD/MM/YYYY format) Optional: keywords (array of terms to filter by) Use when looking for conversation history with a specific customer.`, inputSchema: { type: "object", required: ["customerIdentifier"], properties: { customerIdentifier: { type: "string", description: "Customer email or ID to search for" }, startDate: { type: "string", description: "Optional start date in DD/MM/YYYY format (e.g., '15/01/2025')" }, endDate: { type: "string", description: "Optional end date in DD/MM/YYYY format (e.g., '21/01/2025')" }, keywords: { type: "array", items: { type: "string" }, description: "Optional keywords to filter conversations by content" } } }, },