lighthouse-mcp

Instructions

Implementation Reference

• src/index.ts:267-314 (handler)

  The primary handler function for the 'get_performance_score' tool. It validates input args, configures a performance-only Lighthouse audit, executes it via handleRunAudit, parses the result, extracts the performance score and metrics, and returns formatted JSON response.

  private async handleGetPerformanceScore(args: any) {
    if (!isValidAuditArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid performance score arguments'
      );
    }
  
    try {
      // Run a focused performance audit
      const auditArgs: RunAuditArgs = {
        url: args.url,
        categories: ['performance'],
        device: args.device || 'mobile',
        throttling: true,
      };
  
      const result = await this.handleRunAudit(auditArgs);
      
      // Extract just the performance data
      const resultData = JSON.parse(result.content[0].text);
      const performanceData = {
        url: resultData.url,
        performanceScore: resultData.scores.performance.score,
        metrics: resultData.metrics,
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(performanceData, null, 2),
          },
        ],
      };
    } catch (error: any) {
      console.error('Performance score error:', error);
      return {
        content: [
          {
            type: 'text',
            text: `Error getting performance score: ${error.message || error}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:117-131 (schema)

  The input schema defining the expected arguments for the 'get_performance_score' tool: required 'url' string and optional 'device' enum.

  inputSchema: {
    type: 'object',
    properties: {
      url: {
        type: 'string',
        description: 'URL to audit',
      },
      device: {
        type: 'string',
        enum: ['mobile', 'desktop'],
        description: 'Device to emulate (defaults to mobile)',
      },
    },
    required: ['url'],
  },

• src/index.ts:114-132 (registration)

  Registration of the 'get_performance_score' tool in the ListToolsRequestSchema handler, including name, description, and input schema.

  {
    name: 'get_performance_score',
    description: 'Get just the performance score for a URL',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'URL to audit',
        },
        device: {
          type: 'string',
          enum: ['mobile', 'desktop'],
          description: 'Device to emulate (defaults to mobile)',
        },
      },
      required: ['url'],
    },
  },

• src/index.ts:140-141 (registration)

  Dispatch/registration of the tool handler in the switch statement within CallToolRequestSchema handler.

  case 'get_performance_score':
    return this.handleGetPerformanceScore(request.params.arguments);

• src/index.ts:33-46 (helper)

  Helper validation function `isValidAuditArgs` used by the get_performance_score handler to validate input arguments.

  const isValidAuditArgs = (args: any): args is RunAuditArgs => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.url === 'string' &&
      (args.categories === undefined ||
        (Array.isArray(args.categories) &&
          args.categories.every((cat: any) => typeof cat === 'string'))) &&
      (args.device === undefined ||
        args.device === 'mobile' ||
        args.device === 'desktop') &&
      (args.throttling === undefined || typeof args.throttling === 'boolean')
    );
  };