pseolint

by ouranos-labs

5 stars

305 downloads

Not rated

GitHub Website

About

SpamBrain-proof your pSEO before you publish, audit page relationships, not just pages. AI-triaged findings, 8 LLM providers, local telemetry, cost caps, MCP server.

Details

Author: ouranos-labs
GitHub stars: 5
Downloads: 305
Categories: Other, Developer Tools

- Graph-level analysis detects issues invisible to per‑page tools.
- Per‑template verdict aggregation with uniformity score.
- 48+ rules across 8 categories including SpamBrain and AI Overview.
- Render‑aware crawl checks for CSR bailout and soft 404s.
- Bring‑your‑own authority score to adjust verdict tiers.
- MCP resources for rule knowledge and skills for coding agents.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name pseolint

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

From the repository

Run npx pseolint http://localhost:3000 to audit a site. Add skills for Claude with npx skills add ouranos-labs/pseolint --skill pseolint aeo. The MCP server provides rule knowledge as resources and supports parameters like authorityScore and --render for advanced checks.

`pseolint_audit_site`

Use when a user asks to check their website for SEO issues, SpamBrain risk, duplicate content, thin pages, or before deploying a programmatic SEO site. Crawls the site, runs 40+ rules scored across 4 categories (integrity, discoverability, citation, data), and returns a verdict (ready/caution/concerning/critical) plus a numeric risk score (0-100, lower is better) with actionable findings. Pre-flight site classification suppresses pSEO-targeted rules on small marketing sites and blogs unless strict mode is set. When the audited site has ≥2 detected URL templates, the response includes a `templates` array with per-template verdicts, risk scores, category grades, variance metrics (uniformityScore, topDriver), and audited-URL counts. Both human-readable text and structured data (structuredContent) are returned. A high-risk site is NOT a tool error — check the `passed` field / `verdict`, not `isError`.

`pseolint_explain_score`

Use when a user wants to understand WHY their pseolint verdict is concerning/critical, what categories are failing, and what to fix first. Returns a prioritized breakdown with quick wins listed before structural fixes, plus a pass/fail verdict against the risk threshold. Both human-readable text and structured data (structuredContent) are returned. A failing threshold is reported via `passed`, not `isError`.

`pseolint_check_page_technical`

Use when a user asks to check a specific page URL for technical SEO issues. Checks per-page rules only: canonical tags, Open Graph tags, JSON-LD schema, robots directives, meta tags, thin content, and author signals. Does NOT check cross-page rules (duplicates, cannibalization, linking) — use pseolint_audit_site for those. Both human-readable text and structured data (structuredContent) are returned.

`pseolint_orchestrate_audit`

Use when a user wants concrete, paste-able fixes (rewritten H1s, JSON-LD blocks, robots.txt patches, internal-link suggestions) — not just a list of issues. An LLM drives 25 tools (sitemap fetch, template clustering, per-page rule checks, AEO probes) and produces a fix manifest with structured patches, each validated against a deterministic schema. Costs real money (~$1-3 per audit on managed Anthropic). Capped at $2 / 60 tool calls / 180 seconds by default — adjust if the user asks for a deeper run. Returns a text summary plus a compact structured summary (structuredContent); pass format:'json' to also get the full manifest in the text content. The structured `reason` field reports why the run stopped — an incomplete run is not flagged via isError. The full manifest can be streamed via the CLI: `pseolint orchestrate <domain> --manifest-out manifest.json`.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "pseolint": {
            "pseolint": {
                "command": "npx",
                "args": [
                    "@pseolint/mcp"
                ]
            }
        }
    }
}

McpServers

{
    "pseolint": {
        "command": "npx",
        "args": [
            "@pseolint/mcp"
        ]
    }
}

How pseolint differs

- Graph-level, not page-level. Detects near-duplicate clusters, doorway patterns, and entity-swap doorways across thousands of pages. Per-page tools can't see these.
- SpamBrain + AI Overview. 48+ rules across 8 categories — SpamBrain-policy mapping (penalty risk) plus aeo/* (AI Overview citability: llms.txt, AI-crawler access, citable facts, answer-first, summary-bait).
- Developer workflow, not SaaS UI. CLI, GitHub Action, JSON/HTML reports, MCP server, browser extension (SERP competitive recon). Lives in your repo and your PRs.
- Actionable, not advisory. Every finding has a fix, an effort tag (quick fix / moderate / structural), and a Google docs reference.
- Safe for hosted use. SSRF guard (DNS-validated), robots.txt honoured for our own crawler, analytics-blocking in render mode, AbortSignal cancellation, safeMode: "saas" preset for embedding in services.
- Calibrated against reputable pSEO (v0.5.2). Engine verdicts are calibrated against a curated corpus of in-production pSEO sites that demonstrably win in search. Doorway-pattern findings cluster (no more per-pair noise); verdicts are reproducible at a fixed sampleSeed. Dated snapshot results, the open-source corpus, and the trade-offs we accepted live at pseolint.dev/methodology. Spec: docs/superpowers/specs/2026-05-03-calibration-against-reputable-pseo.md.
- Authority-blind by design, with a manual override. pseolint analyses static content + the link graph it can see. It does NOT measure backlinks, brand mentions, domain age, or any external trust signal — there is no Moz/Ahrefs/Semrush dependency. This means the engine itself is calibrated for the authority tier of the calibration corpus (established brands). It exposes authorityScore (0-100, via the --authority-score CLI flag, the core API, or the MCP param) so callers can adjust the verdict ladder for their tier: >= 80 shifts one tier lenient (established brand can absorb shapes a newer site can't); <= 30 shifts one tier stricter. Raw risk number unchanged so CI gates stay stable. Without the flag, treat verdicts as a directional minimum.
- Honest about blind spots. Beyond domain authority, pseolint does not currently detect: Core Web Vitals (LCP/INP/CLS), image SEO (alt-text, dimensions), Open Graph completeness, title-tag uniqueness, H1 structure, schema-content drift (e.g. JSON-LD price ≠ rendered price), outbound-link health, search-intent alignment, parameter-URL crawl-budget waste, and a handful of specialty gaps (mobile-friendliness, cookie-banner detection, AMP/News/Video schema). The complete blind-spot audit lives at docs/superpowers/specs/2026-05-03-pseolint-blind-spots.md — every gap categorized by impact tier with the roadmap fix.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

pseolint

About

Details

Jump to

Setting up with Highlight

Setting up with Cursor

JSON

JSON

JSON

Setting up with Claude Desktop

JSON

JSON

JSON

Setting up with Windsurf

JSON

JSON

JSON

Setting up with Cline

JSON

JSON

JSON

Setting up with Goose

JSON

JSON

JSON

From the repository

`pseolint_audit_site`

`pseolint_explain_score`

`pseolint_check_page_technical`

`pseolint_orchestrate_audit`

Claude Desktop / Cursor

McpServers

How pseolint differs

Install

About

Details

Jump to

Setting up with Highlight

From the repository

pseolint_audit_site

pseolint_explain_score

pseolint_check_page_technical

pseolint_orchestrate_audit

Claude Desktop / Cursor

McpServers

How pseolint differs

Install

More like this

Sequential Thinking

Sentry

Github

Filesystem

EverArt

Google Drive

`pseolint_audit_site`

`pseolint_explain_score`

`pseolint_check_page_technical`

`pseolint_orchestrate_audit`