MCP Server for Intercom

Instructions

Implementation Reference

• src/handlers/toolHandlers.ts:149-183 (handler)

  The main handler function in ToolHandlers class that executes the tool: validates args with schema, fetches tickets via IntercomService.getTicketsByCustomer, formats MCP-compliant response, and handles errors.
  async handleSearchTicketsByCustomer(args: unknown) { try { console.error("Handling search_tickets_by_customer request"); // Validate and parse arguments const validatedArgs = SearchTicketsByCustomerSchema.parse(args); const customerIdentifier = validatedArgs.customerIdentifier; const startDateStr = validatedArgs.startDate; const endDateStr = validatedArgs.endDate; // Create Intercom service and retrieve tickets const intercomService = new IntercomService(this.API_BASE_URL, this.authToken); const tickets = await intercomService.getTicketsByCustomer( customerIdentifier, startDateStr, endDateStr ); console.error(`Retrieved ${tickets.length} tickets for customer: ${customerIdentifier}`); return this.formatResponse(tickets); } catch (error) { console.error('Error handling search_tickets_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:119-159 (schema)

  Zod schema defining and validating input parameters for the tool: required customerIdentifier (email/ID), optional startDate/endDate with DD/MM/YYYY format validation and transformation to ISO.
  export const SearchTicketsByCustomerSchema = 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)" }) }).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:73-93 (registration)

  MCP server capabilities registration declaring the tool's description and input schema for protocol advertisement.
  search_tickets_by_customer: { description: "Searches for tickets 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')" } } } },
• src/handlers/requestHandlers.ts:153-155 (registration)

  Dispatch logic in call_tool request handler that routes execution to the specific tool handler method.
  case "search_tickets_by_customer": console.error("Handling search_tickets_by_customer request"); return await toolHandlers.handleSearchTicketsByCustomer(args);
• src/handlers/requestHandlers.ts:106-132 (registration)

  Tool metadata returned in list_tools response, including detailed description and input schema.
  { name: "search_tickets_by_customer", description: `Searches for tickets by customer email or ID with optional date filtering. Required: customerIdentifier (email/ID) Optional: startDate, endDate (DD/MM/YYYY format) Use when analyzing a customer's support history.`, 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')" } } }, }