Webby MCP Server

Instructions

Implementation Reference

• src/security/mozilla-observatory.ts:42-108 (handler)

  Core handler function that executes the Mozilla Observatory security scan via API, extracts hostname, fetches scan results, handles errors, and formats the response with grade, score, and test results.

  export async function analyzeMozillaObservatory(
    url: string,
    options: MozillaObservatoryOptions = {}
  ): Promise<MozillaObservatoryResult> {
    try {
      // Extract hostname from URL
      const hostname = new URL(url).hostname;
  
      // Build API URL
      const apiUrl = `https://observatory-api.mdn.mozilla.net/api/v2/scan?host=${encodeURIComponent(hostname)}`;
  
      // Make POST request to trigger/retrieve scan
      const response = await fetch(apiUrl, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
      });
  
      if (!response.ok) {
        throw new Error(`Mozilla Observatory API error: ${response.status} ${response.statusText}`);
      }
  
      const data: MozillaObservatoryResponse = await response.json();
  
      // Check for API errors
      if (data.error) {
        return {
          tool: 'mozilla_observatory',
          success: false,
          grade: 'F',
          score: 0,
          tests_passed: 0,
          tests_failed: 0,
          scanned_at: data.scanned_at || new Date().toISOString(),
          details_url: data.details_url || '',
          error: data.error,
          raw: data,
        };
      }
  
      // Return formatted result
      return {
        tool: 'mozilla_observatory',
        success: true,
        grade: data.grade,
        score: data.score,
        tests_passed: data.tests_passed,
        tests_failed: data.tests_failed,
        scanned_at: data.scanned_at,
        details_url: data.details_url,
        raw: data,
      };
    } catch (error) {
      return {
        tool: 'mozilla_observatory',
        success: false,
        grade: 'F',
        score: 0,
        tests_passed: 0,
        tests_failed: 0,
        scanned_at: new Date().toISOString(),
        details_url: '',
        error: error instanceof Error ? error.message : String(error),
      };
    }
  }

• index.ts:202-213 (registration)

  Tool registration in the MCP server tools array, defining name, description, and input schema.

  {
    name: 'validate_security_mozilla_observatory',
    description: 'Analyze HTTP security headers using Mozilla Observatory. Tests CSP, HSTS, etc. Free API, 1 scan per minute per domain.',
    inputSchema: {
      type: 'object',
      properties: {
        url: { type: 'string' },
        forceRescan: { type: 'boolean', description: 'Force new scan (default: false)' },
      },
      required: ['url'],
    },
  },

• index.ts:66-69 (schema)

  Zod schema for validating input arguments to the Mozilla Observatory tool.

  const MozillaObservatoryArgsSchema = z.object({
    url: z.string().url(),
    forceRescan: z.boolean().optional(),
  });

• index.ts:371-377 (handler)

  Dispatch handler in the main switch statement that validates args, calls the core analyze function, and returns JSON result.

  case 'validate_security_mozilla_observatory': {
    const validatedArgs = MozillaObservatoryArgsSchema.parse(args);
    const result = await analyzeMozillaObservatory(validatedArgs.url, {
      forceRescan: validatedArgs.forceRescan,
    });
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }

• src/security/mozilla-observatory.ts:6-36 (schema)

  TypeScript interfaces defining input options, API response, and output result structures for the tool.

  export interface MozillaObservatoryOptions {
    /** Force a rescan (default: false, uses cached results if < 1 minute old) */
    forceRescan?: boolean;
  }
  
  export interface MozillaObservatoryResponse {
    id: number;
    details_url: string;
    algorithm_version: number;
    scanned_at: string;
    error: string | null;
    grade: string;
    score: number;
    status_code: number;
    tests_failed: number;
    tests_passed: number;
    tests_quantity: number;
  }
  
  export interface MozillaObservatoryResult {
    tool: 'mozilla_observatory';
    success: boolean;
    grade: string;
    score: number;
    tests_passed: number;
    tests_failed: number;
    scanned_at: string;
    details_url: string;
    error?: string;
    raw?: MozillaObservatoryResponse;
  }