How to Interpret OpenSEO Scan Results: Decoding the Site Audit JSON Payload

OpenSEO scan results return a structured JSON payload containing an overallScore, per-page issue buckets (errors, warnings, suggestions), and detailed metrics from Lighthouse and Google Search Console that you can query via the MCP runSiteAuditTool endpoint.

OpenSEO is an open-source technical SEO platform that crawls websites through a Site Audit workflow. When you initiate a scan, the system aggregates data from multiple sources and returns a comprehensive report. Understanding how to interpret open-seo scan results enables you to prioritize fixes based on severity and measure the impact of your optimizations.

Architecture of the Site Audit System

The scan pipeline consists of several coordinated components defined in the every-app/open-seo repository:

• SiteAuditWorkflow.ts – Orchestrates the full audit pipeline from page discovery to final scoring. Located at src/server/workflows/SiteAuditWorkflow.ts.
• site-audit-tools.ts – Provides low-level data gathering helpers for Lighthouse and Google Search Console. Located at src/server/mcp/tools/site-audit-tools.ts.
• audit.schema.ts – Defines the TypeScript schema for the JSON report stored in the database. Located at src/db/audit.schema.ts.
• server.ts – Registers the MCP endpoint runSiteAuditTool that exposes scan results to agents and the UI.
• _marketing/features/site-audit – React components that render the audit dashboard in the web interface at web/src/routes/_marketing/features/site-audit.

Anatomy of the Scan Payload

The MCP endpoint and UI consume a consistent JSON structure. Here is the typical payload schema:

{
  "url": "https://example.com",
  "overallScore": 78,
  "pages": [
    {
      "url": "https://example.com/",
      "score": 85,
      "issues": {
        "errors": ["Missing title tag", "Broken canonical"],
        "warnings": ["Missing meta description"],
        "suggestions": ["Add structured data"]
      },
      "metrics": {
        "lighthouse": { "performance": 90, "seo": 80 },
        "gsc": { "clicks": 1200, "impressions": 5000 }
      }
    }
  ],
  "summary": {
    "totalPages": 42,
    "errorCount": 7,
    "warningCount": 19,
    "suggestionCount": 34,
    "categoryBreakdown": {
      "performance": 80,
      "seo": 70,
      "accessibility": 90,
      "bestPractices": 75
    }
  },
  "createdAt": "2024-09-01T12:34:56Z"
}

Key fields to analyze:

• overallScore – Weighted composite from 0-100 indicating site health.
• pages – Array of individual URL results, each containing a score and issues object.
• issues – Categorized into three severity buckets:
  • Errors: Critical problems blocking indexing (e.g., missing <title>, blocked resources).
  • Warnings: Medium-priority issues degrading SEO (e.g., uncompressed images, duplicate tags).
  • Suggestions: Optional enhancements (e.g., internal linking improvements).
• metrics.lighthouse: Core Web Vitals and performance data.
• metrics.gsc: Real-world performance data from Google Search Console.
• summary.categoryBreakdown: Scores across Performance, SEO, Accessibility, and Best Practices.

How to Prioritize Fixes from Scan Results

Follow this severity-based workflow when interpreting results:

1. Review overallScore first.

   • Above 80: Healthy site with minor optimizations needed.
   • 60-80: Needs work; address warnings to prevent ranking drops.
   • Below 60: Critical issues requiring immediate intervention.

2. Check summary.errorCount.

   • Any errors present indicate crawlability or indexing blockers. Prioritize these above all else.

3. Analyze high-traffic pages in the pages array.

   • Focus on URLs with low individual scores that drag down the aggregate rating.

4. Process issues in severity order:

   • Fix errors immediately (missing title tags, broken canonicals).
   • Address warnings next (meta descriptions, image optimization).
   • Implement suggestions last (structured data, schema markup).

5. Validate Core Web Vitals in metrics.lighthouse.

   • LCP, FID, and CLS values directly impact Google rankings.

6. Correlate with metrics.gsc data.

   • Compare scan dates with impression/click trends to verify that technical fixes improve organic performance.

Accessing Scan Results via the MCP Endpoint

Fetch audit data programmatically using the runSiteAuditTool endpoint registered in src/server.ts:

import fetch from 'node-fetch';

const BASE = 'https://openseo.example.com/mcp';
const SITE = 'https://example.com';

async function getAudit() {
  const res = await fetch(
    `${BASE}/runSiteAuditTool?url=${encodeURIComponent(SITE)}`
  );
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const report = await res.json();

  console.log('Overall Score:', report.overallScore);
  console.log('Errors:', report.summary.errorCount);
  console.log('Top page score:', report.pages[0]?.score);
  
  return report;
}

getAudit().catch(console.error);

This handler wires directly to the SiteAuditWorkflow defined in src/server/workflows/SiteAuditWorkflow.ts.

Key Source Files Reference

File	Purpose
src/server/workflows/SiteAuditWorkflow.ts	Orchestrates the audit pipeline and aggregates results.
src/server/mcp/tools/site-audit-tools.ts	Low-level helpers for fetching Lighthouse and GSC data.
src/db/audit.schema.ts	Database schema defining the JSON report structure.
src/server.ts	MCP server exposing the runSiteAuditTool endpoint.
web/src/routes/_marketing/features/site-audit	Frontend components rendering scan results.

Summary

• OpenSEO scan results use a standardized JSON payload with overallScore, pages, and summary sections.
• Issues are bucketed into errors (critical), warnings (medium), and suggestions (low priority).
• Per-page metrics include Lighthouse scores for Core Web Vitals and Google Search Console performance data.
• Access results programmatically via the runSiteAuditTool MCP endpoint or through the React-based web UI.
• Reference SiteAuditWorkflow.ts and audit.schema.ts to trace how specific fields are calculated and stored.

Frequently Asked Questions

What does the overallScore represent in OpenSEO?

The overallScore is a weighted composite value between 0 and 100 calculated by the SiteAuditWorkflow. It aggregates individual page scores and category metrics (Performance, SEO, Accessibility) to provide a single health indicator for the entire domain.

How do errors differ from warnings in the scan results?

Errors indicate critical issues that prevent proper crawling or indexing, such as missing title tags or server errors. Warnings represent technical debt that degrades user experience and SEO performance but does not block indexing, such as missing meta descriptions or unoptimized images.

Can I customize the audit schema to track additional metrics?

Yes. The JSON structure is defined in src/db/audit.schema.ts. You can extend this schema to include custom fields, but ensure you update the SiteAuditWorkflow to populate those fields during the aggregation phase to maintain data integrity.

How do I access scan results without using the web interface?

You can query the runSiteAuditTool endpoint directly via the MCP server exposed in src/server.ts. This returns the raw JSON payload suitable for integration with CI/CD pipelines, Slack notifications, or external dashboards.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}