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