MCP Server for Intercom

Instructions

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