Lighthouse MCP

Instructions

Implementation Reference

• src/tools/audit.ts:170-231 (handler)

  MCP tool handler for 'get_seo_analysis' that runs SEO analysis via helper, processes results including audits if requested, structures response with recommendations, and handles errors.

  server.tool(
    "get_seo_analysis",
    "Get SEO analysis and recommendations for a website",
    detailedAuditSchema,
    async ({ url, device, includeDetails }) => {
      try {
        const result = await getSeoAnalysis(url, device, includeDetails);
  
        const data: Record<string, unknown> = {
          seoScore: result.seoScore,
          fetchTime: result.fetchTime,
          includeDetails,
        };
  
        if (includeDetails && "audits" in result) {
          data.audits = result.audits.map((audit) => ({
            title: audit.title,
            score: audit.score !== null ? Math.round((audit.score || 0) * 100) : null,
            description: audit.description,
            displayValue: audit.displayValue || "N/A",
          }));
        }
  
        const structuredResult = createStructuredAudit("SEO Analysis", result.url, result.device, data, [
          "Optimize meta titles and descriptions",
          "Implement structured data markup",
          "Ensure mobile-friendly responsive design",
          "Improve page loading speed",
          "Create XML sitemap and robots.txt",
        ]);
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(structuredResult, null, 2),
            },
          ],
        };
      } catch (error: unknown) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(
                {
                  error: "SEO analysis failed",
                  url,
                  device: device || "desktop",
                  message: errorMessage,
                },
                null,
                2,
              ),
            },
          ],
          isError: true,
        };
      }
    },
  );

• src/schemas.ts:48-52 (schema)

  Input schema (Zod) for the get_seo_analysis tool, defining url, device, and includeDetails parameters.

  export const detailedAuditSchema = {
    url: baseSchemas.url,
    device: baseSchemas.device,
    includeDetails: baseSchemas.includeDetails,
  };

• src/lighthouse-categories.ts:28-45 (helper)

  Core helper function that performs Lighthouse SEO audit, returns score and optional detailed audits.

  export async function getSeoAnalysis(url: string, device: "desktop" | "mobile" = "desktop", includeDetails = false) {
    const result = await runLighthouseAudit(url, ["seo"], device);
    const categoryData = result.categories.seo;
  
    const baseData = {
      url: result.url,
      device: result.device,
      seoScore: categoryData?.score || 0,
      fetchTime: result.fetchTime,
    };
  
    if (includeDetails) {
      const { audits } = await getDetailedAuditResults(url, "seo", device);
      return { ...baseData, audits };
    }
  
    return baseData;
  }