Webby MCP Server

Instructions

Implementation Reference

• src/security/ssl-labs.ts:72-158 (handler)

  Core handler function that performs the SSL Labs API call to analyze SSL/TLS configuration, processes the response, handles errors, and formats the result.

  export async function analyzeSSLLabs(
    url: string,
    options: SSLLabsOptions
  ): Promise<SSLLabsResult> {
    try {
      // Extract hostname from URL
      const hostname = new URL(url).hostname;
  
      // Build API URL with parameters
      const params = new URLSearchParams({
        host: hostname,
        all: options.all !== false ? 'on' : 'off',
      });
  
      if (options.maxAge !== undefined) {
        params.set('maxAge', options.maxAge.toString());
      }
  
      if (options.startNew) {
        params.set('startNew', 'on');
      }
  
      const apiUrl = `https://api.ssllabs.com/api/v4/analyze?${params.toString()}`;
  
      // Make GET request with email header
      const response = await fetch(apiUrl, {
        method: 'GET',
        headers: {
          'email': options.email,
        },
      });
  
      if (!response.ok) {
        if (response.status === 429) {
          throw new Error('SSL Labs rate limit exceeded. Please wait and try again.');
        }
        throw new Error(`SSL Labs API error: ${response.status} ${response.statusText}`);
      }
  
      const data: SSLLabsResponse = await response.json();
  
      // Check if assessment is complete
      if (data.status === 'ERROR') {
        return {
          tool: 'ssl_labs',
          success: false,
          status: data.status,
          host: hostname,
          endpoints: [],
          error: data.statusMessage || 'Assessment failed',
          raw: data,
        };
      }
  
      // Format endpoints
      const endpoints = (data.endpoints || []).map(ep => ({
        ip: ep.ipAddress,
        grade: ep.grade,
        hasWarnings: ep.hasWarnings,
        progress: ep.progress,
      }));
  
      // Get best grade from all endpoints
      const grades = data.endpoints?.filter(ep => ep.grade).map(ep => ep.grade!) || [];
      const bestGrade = grades.length > 0 ? grades.sort()[0] : undefined;
  
      return {
        tool: 'ssl_labs',
        success: data.status === 'READY',
        status: data.status,
        grade: bestGrade,
        host: hostname,
        endpoints,
        testTime: data.testTime ? new Date(data.testTime).toISOString() : undefined,
        raw: data,
      };
    } catch (error) {
      return {
        tool: 'ssl_labs',
        success: false,
        status: 'ERROR',
        host: new URL(url).hostname,
        endpoints: [],
        error: error instanceof Error ? error.message : String(error),
      };
    }
  }

• src/security/ssl-labs.ts:164-193 (helper)

  Helper function that polls the SSL Labs API until the assessment is complete or times out.

  export async function analyzeSSLLabsComplete(
    url: string,
    options: SSLLabsOptions,
    maxWaitMinutes: number = 5
  ): Promise<SSLLabsResult> {
    const maxWaitMs = maxWaitMinutes * 60 * 1000;
    const startTime = Date.now();
    const pollInterval = 10000; // 10 seconds
  
    let result = await analyzeSSLLabs(url, options);
  
    // Keep polling until complete or timeout
    while (result.status !== 'READY' && result.status !== 'ERROR') {
      if (Date.now() - startTime > maxWaitMs) {
        return {
          ...result,
          success: false,
          error: `Timeout: Assessment did not complete within ${maxWaitMinutes} minutes`,
        };
      }
  
      // Wait before next poll
      await new Promise(resolve => setTimeout(resolve, pollInterval));
  
      // Poll again (fromCache to get latest status)
      result = await analyzeSSLLabs(url, { ...options, maxAge: 0 });
    }
  
    return result;
  }

• index.ts:71-78 (schema)

  Zod schema for validating input arguments to the validate_security_ssl_labs tool.

  const SSLLabsArgsSchema = z.object({
    url: z.string().url(),
    email: z.string().email(),
    maxAge: z.number().optional(),
    startNew: z.boolean().optional(),
    waitForComplete: z.boolean().optional(),
    maxWaitMinutes: z.number().optional(),
  });

• index.ts:214-229 (registration)

  Tool registration object defining name, description, and input schema for the MCP tool.

  {
    name: 'validate_security_ssl_labs',
    description: 'Analyze SSL/TLS configuration using SSL Labs. Comprehensive certificate and protocol analysis. Long-running (may take minutes).',
    inputSchema: {
      type: 'object',
      properties: {
        url: { type: 'string' },
        email: { type: 'string', description: 'Your email (required by API)' },
        maxAge: { type: 'number', description: 'Max cached report age in hours' },
        startNew: { type: 'boolean', description: 'Force new assessment' },
        waitForComplete: { type: 'boolean', description: 'Wait for completion (default: false)' },
        maxWaitMinutes: { type: 'number', description: 'Max wait time in minutes (default: 5)' },
      },
      required: ['url', 'email'],
    },
  },

• index.ts:379-392 (handler)

  Dispatch handler in main switch that validates args and calls the appropriate SSL Labs analysis function based on waitForComplete flag.

  case 'validate_security_ssl_labs': {
    const validatedArgs = SSLLabsArgsSchema.parse(args);
    const result = validatedArgs.waitForComplete
      ? await analyzeSSLLabsComplete(
          validatedArgs.url,
          { email: validatedArgs.email, maxAge: validatedArgs.maxAge, startNew: validatedArgs.startNew },
          validatedArgs.maxWaitMinutes
        )
      : await analyzeSSLLabs(validatedArgs.url, {
          email: validatedArgs.email,
          maxAge: validatedArgs.maxAge,
          startNew: validatedArgs.startNew,
        });
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };