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')"
                              }
                          }
                      },
                  }