heroicons-mcp

Instructions

Implementation Reference

• src/utils.ts:136-152 (handler)

  Handler function that filters icons from iconMeta based on search query in name, optional category, style, and limit, then returns a JSON-formatted text response.

  async ({ query, style, category, limit }) => {
    let results = iconMeta.filter((icon) => {
      const matchName = icon.name.toLowerCase().includes(query.toLowerCase());
      const matchCat = category ? icon.categories.includes(category) : true;
      const matchStyle = style ? icon.style === style : true;
      return matchName && matchCat && matchStyle;
    });
    if (limit) results = results.slice(0, limit);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(results, null, 2)
        }
      ]
    };
  }

• src/utils.ts:118-135 (schema)

  Zod input schema for the search_icons tool parameters: query (required string), style (optional enum), category (optional string), limit (optional number, default 20, 1-100).

  {
    query: z.string().describe("Search term for icon name or category"),
    style: z
      .enum(["solid", "outline"])
      .optional()
      .describe("Icon style: solid or outline"),
    category: z
      .string()
      .optional()
      .describe("Category to filter by (optional)"),
    limit: z
      .number()
      .min(1)
      .max(100)
      .default(20)
      .optional()
      .describe("Max results to return")
  },

• src/utils.ts:115-153 (registration)

  Registers the search_icons tool on the MCP server with name, description, input schema, and handler function.

  server.tool(
    "search_icons",
    "Search for icons from heroicons by name or category",
    {
      query: z.string().describe("Search term for icon name or category"),
      style: z
        .enum(["solid", "outline"])
        .optional()
        .describe("Icon style: solid or outline"),
      category: z
        .string()
        .optional()
        .describe("Category to filter by (optional)"),
      limit: z
        .number()
        .min(1)
        .max(100)
        .default(20)
        .optional()
        .describe("Max results to return")
    },
    async ({ query, style, category, limit }) => {
      let results = iconMeta.filter((icon) => {
        const matchName = icon.name.toLowerCase().includes(query.toLowerCase());
        const matchCat = category ? icon.categories.includes(category) : true;
        const matchStyle = style ? icon.style === style : true;
        return matchName && matchCat && matchStyle;
      });
      if (limit) results = results.slice(0, limit);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(results, null, 2)
          }
        ]
      };
    }
  );

• src/utils.ts:95-106 (helper)

  Precomputed array of metadata for all solid and outline icons from Heroicons, including name, style, and categories; used by the search_icons handler.

  export const iconMeta = [
    ...allIcons.solid.map((name) => ({
      name,
      style: "solid",
      categories: categorizeIcon(name)
    })),
    ...allIcons.outline.map((name) => ({
      name,
      style: "outline",
      categories: categorizeIcon(name)
    }))
  ];