MCP Server for Intercom

Instructions

Implementation Reference

• src/handlers/toolHandlers.ts:109-143 (handler)

  The main handler function that executes the tool logic: validates input using SearchTicketsByStatusSchema, fetches tickets via IntercomService.getTicketsByStatus, formats and returns MCP-compliant response or error.

  async handleSearchTicketsByStatus(args: unknown) {
      try {
          console.error("Handling search_tickets_by_status request");
          
          // Validate and parse arguments
          const validatedArgs = SearchTicketsByStatusSchema.parse(args);
          
          const status = validatedArgs.status;
          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.getTicketsByStatus(
              status,
              startDateStr,
              endDateStr
          );
          
          console.error(`Retrieved ${tickets.length} tickets with status: ${status}`);
          
          return this.formatResponse(tickets);
      } catch (error) {
          console.error('Error handling search_tickets_by_status:', error);
          
          // Enhanced error message for validation errors
          if (error instanceof Error && error.message.includes("status")) {
              return this.formatErrorResponse(error, 
                  `${error.message}\n\nPlease provide a valid status (open, pending, or resolved), and optional dates in DD/MM/YYYY format (e.g., 15/01/2025)`
              );
          }
          
          return this.formatErrorResponse(error);
      }
  }

• src/types/schemas.ts:22-64 (schema)

  Zod schema defining input validation for the tool: requires 'status' (open/pending/resolved), optional 'startDate' and 'endDate' in DD/MM/YYYY, with transformation to ISO dates and range validation.

  export const SearchTicketsByStatusSchema = z.object({
      // Required status parameter
      status: z.string({
          required_error: "status is required (open, pending, or resolved)"
      }).refine(val => ['open', 'pending', 'resolved'].includes(val.toLowerCase()), {
          message: "status must be one of: open, pending, resolved"
      }),
      
      // 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:51-72 (registration)

  Registers the tool in the MCP server capabilities bundle, specifying name, description, and input parameters schema.

  search_tickets_by_status: {
      description: "Searches for tickets by status with optional date filtering.",
      parameters: {
          type: "object",
          required: ["status"],
          properties: {
              status: {
                  type: "string",
                  description: "Ticket status to search for (open, pending, or resolved)",
                  enum: ["open", "pending", "resolved"]
              },
              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:150-152 (registration)

  Switch case in call_tool request handler that dispatches 'search_tickets_by_status' requests to the ToolHandlers.handleSearchTicketsByStatus method.

  case "search_tickets_by_status":
      console.error("Handling search_tickets_by_status request");
      return await toolHandlers.handleSearchTicketsByStatus(args);