Lighthouse MCP

Instructions

Implementation Reference

• src/lighthouse-analysis.ts:5-44 (handler)

  Core handler function that runs a Lighthouse performance audit, extracts unused JavaScript from the 'unused-javascript' audit, filters items by minimum byte threshold, computes totals, and returns structured results including URL, device, total unused bytes, filtered items, and fetch time.

  export async function findUnusedJavaScript(
    url: string,
    device: "desktop" | "mobile" = "desktop",
    minBytes = DEFAULTS.MIN_UNUSED_JS_BYTES,
  ) {
    const runnerResult = await runRawLighthouseAudit(url, ["performance"], device);
    const { lhr } = runnerResult;
  
    const unusedJsAudit = lhr.audits["unused-javascript"];
  
    if (!unusedJsAudit || !unusedJsAudit.details) {
      return {
        url: lhr.finalDisplayedUrl,
        device,
        totalUnusedBytes: 0,
        items: [],
        fetchTime: lhr.fetchTime,
      };
    }
  
    // Filter items by minimum bytes
    const items = (unusedJsAudit.details.items || [])
      .filter((item: Record<string, unknown>) => (item.wastedBytes as number) >= minBytes)
      .map((item: Record<string, unknown>) => ({
        url: item.url as string,
        totalBytes: item.totalBytes as number,
        wastedBytes: item.wastedBytes as number,
        wastedPercent: Math.round(((item.wastedBytes as number) / (item.totalBytes as number)) * 100),
      }));
  
    const totalUnusedBytes = items.reduce((sum: number, item: { wastedBytes: number }) => sum + item.wastedBytes, 0);
  
    return {
      url: lhr.finalDisplayedUrl,
      device,
      totalUnusedBytes,
      items,
      fetchTime: lhr.fetchTime,
    };
  }

• src/schemas.ts:104-108 (schema)

  Zod schema defining input parameters for the tool: URL (validated HTTP/HTTPS), device (desktop/mobile), minBytes (minimum wasted bytes threshold, default 2048).

  export const unusedJavaScriptSchema = {
    url: baseSchemas.url,
    device: baseSchemas.device,
    minBytes: z.number().min(0).default(2048).describe("Minimum unused bytes to report (default: 2048)"),
  };

• src/tools/analysis.ts:20-92 (registration)

  MCP server tool registration for 'find_unused_javascript', providing description, input schema, and async handler that calls the core findUnusedJavaScript function, processes results into AI-friendly structured data with summaries and recommendations, handles errors, and returns formatted content.

  server.tool(
    "find_unused_javascript",
    "Find unused JavaScript code to reduce bundle size",
    unusedJavaScriptSchema,
    async ({ url, device, minBytes }) => {
      try {
        const result = await findUnusedJavaScript(url, device, minBytes);
  
        // Create structured, AI-friendly response
        const analysisData = {
          url: result.url,
          device: result.device,
          timestamp: result.fetchTime,
          thresholdBytes: minBytes,
          summary: {
            totalUnusedKB: Math.round((result.totalUnusedBytes / 1024) * 100) / 100,
            totalFilesAnalyzed: result.items.length,
            hasUnusedCode: result.items.length > 0,
          },
          unusedFiles: result.items.map((item) => ({
            filename: item.url.split("/").pop() || item.url,
            totalKB: Math.round((item.totalBytes / 1024) * 100) / 100,
            unusedKB: Math.round((item.wastedBytes / 1024) * 100) / 100,
            unusedPercent: item.wastedPercent,
            url: item.url,
          })),
          recommendations:
            result.items.length > 0
              ? [
                  "Remove unused JavaScript code",
                  "Implement code splitting",
                  "Use tree shaking",
                  "Add lazy loading for non-critical scripts",
                ]
              : ["No optimization needed - minimal unused code detected"],
        };
  
        const summary =
          result.items.length > 0
            ? `Found ${result.items.length} files with unused JavaScript (${analysisData.summary.totalUnusedKB}KB total)`
            : `No significant unused JavaScript found above ${minBytes} byte threshold`;
  
        return {
          content: createStructuredAnalysis("Unused JavaScript Analysis", analysisData, summary),
        };
      } catch (error: unknown) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        return {
          content: [
            {
              type: "text" as const,
              text: `Analysis failed: ${errorMessage}`,
            },
            {
              type: "text" as const,
              text: JSON.stringify(
                {
                  error: true,
                  url,
                  device,
                  message: errorMessage,
                  timestamp: new Date().toISOString(),
                },
                null,
                2,
              ),
            },
          ],
          isError: true,
        };
      }
    },
  );

• src/index.ts:27-27 (registration)

  Top-level call to register all analysis tools, including find_unused_javascript, on the MCP server.

  registerAnalysisTools(server);