MCP Intercom Server

Instructions

Implementation Reference

• src/index.ts:108-137 (handler)

  The MCP tool handler for 'search-conversations' that validates the input arguments using SearchConversationsSchema and executes the search via IntercomClient.

  if (name === "search-conversations") {
    try {
      const validatedArgs = SearchConversationsSchema.parse(args);
      const intercomClient = new IntercomClient();
      const conversations = await intercomClient.searchConversations(
        validatedArgs
      );
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(conversations, null, 2),
          },
        ],
      };
    } catch (error) {
      if (error instanceof Error) {
        return {
          content: [
            {
              type: "text",
              text: `Error: ${error.message}`,
            },
          ],
        };
      }
      throw error;
    }
  }

• src/tools/conversations.ts:11-29 (schema)

  Zod schema defining the input parameters for the 'search-conversations' tool, including optional filters for createdAt, updatedAt, sourceType, state, open, and read.

  export const SearchConversationsSchema = z.object({
    createdAt: z
      .object({
        operator: z.enum(["=", "!=", ">", "<"]),
        value: z.number(),
      })
      .optional(),
    updatedAt: z
      .object({
        operator: z.enum(["=", "!=", ">", "<"]),
        value: z.number(),
      })
      .optional(),
    sourceType: z.string().optional(),
    state: z.string().optional(),
    open: z.boolean().optional(),
    read: z.boolean().optional(),
    // Add more filters as needed
  });

• src/index.ts:18-22 (registration)

  Registration of the 'search-conversations' tool in the MCP server capabilities, specifying description, inputSchema, and outputSchema.

  "search-conversations": {
    description:
      "Search Intercom conversations with filters for created_at, updated_at, source type, state, open, and read status",
    inputSchema: SearchConversationsSchema,
    outputSchema: z.any(),

• src/api/client.ts:39-121 (helper)

  The IntercomClient.searchConversations method, which constructs the search query for Intercom's conversations/search API endpoint and fetches the results. This is the core logic executed by the tool handler.

  async searchConversations(
    filters: {
      createdAt?: { operator: string; value: number };
      updatedAt?: { operator: string; value: number };
      sourceType?: string;
      state?: string;
      open?: boolean;
      read?: boolean;
      // Add more filters as needed
    } = {},
    pagination: { perPage?: number; startingAfter?: string } = {}
  ) {
    const query: any = {
      operator: "AND",
      value: [],
    };
  
    if (filters.createdAt) {
      query.value.push({
        field: "created_at",
        operator: filters.createdAt.operator,
        value: filters.createdAt.value.toString(),
      });
    }
    if (filters.updatedAt) {
      query.value.push({
        field: "updated_at",
        operator: filters.updatedAt.operator,
        value: filters.updatedAt.value.toString(),
      });
    }
    if (filters.sourceType) {
      query.value.push({
        field: "source.type",
        operator: "=",
        value: filters.sourceType,
      });
    }
    if (filters.state) {
      query.value.push({
        field: "state",
        operator: "=",
        value: filters.state,
      });
    }
    if (filters.open !== undefined) {
      query.value.push({
        field: "open",
        operator: "=",
        value: filters.open.toString(),
      });
    }
    if (filters.read !== undefined) {
      query.value.push({
        field: "read",
        operator: "=",
        value: filters.read.toString(),
      });
    }
  
    const body = {
      query,
      pagination: {
        per_page: pagination.perPage || 20,
        starting_after: pagination.startingAfter || null,
      },
    };
  
    const response = await axios.post(
      `${INTERCOM_API_BASE}/conversations/search`,
      body,
      {
        headers: {
          Authorization: `Bearer ${this.apiKey}`,
          Accept: "application/json",
          "Content-Type": "application/json",
          "Intercom-Version": "2.11",
        },
      }
    );
  
    return response.data as { conversations: IntercomConversation[] };
  }