convez.ai
MCP ServerIntegração & APIsIntermediário
AJ-EN

AEO Auditor

AJ-EN/aeo-audit

PageSpeed para agentes de IA — audita readiness de websites

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que audita sites para medir readiness de IA, analisando 26 verificações em 5 dimensões: Discovery, Identity, Capabilities, Commerce e Trust. Gera relatórios em terminal, HTML, PDF e JSON com scores comparativos contra benchmark de agent-readiness.

Instalação

$npx convez-ai AJ-EN/aeo-audit

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
v1.2.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Avaliar se um website está otimizado para descoberta e integração por agentes de IA
  • Diagnosticar pontos fracos em identidade digital, capacidades e sinais de confiança
  • Gerar relatórios estruturados (HTML, PDF, JSON) de conformidade AEO para stakeholders

Veredito

Ferramenta especializada e bem-arquitetada para avaliar a prontidão de websites para agentes de IA. Preenche um nicho claro com abordagem rigorosa (26 checks, scoring relativo), mas o mercado de AEO é ainda emergente — útil principalmente para desenvolvedores de plataformas de agentes ou empresas que buscam otimização proativa.

README

A tradução para o português deste README ainda está na fila.

AEO Auditor CLI

PyPI version Build Status License: MIT Python 3.11+

PageSpeed for AI agents. Scan any website and score its Agent/Engine Optimization (AEO) readiness across 5 dimensions — Discovery, Identity, Capabilities, Commerce, and Trust — then get a graded report with prioritized, actionable fixes.

Grades are relative: a site is ranked against a benchmark corpus (A = top tier of agent-readiness today), so the score stays a meaningful, movable target while agent-native standards are still emerging.

aeo-audit demo: scanning stripe.com

⚡ Try it in your browser — paste a URL, get a scorecard in ~30s — no install, no signup. (Rate-limited; the CLI below is unlimited.)

🔗 Live leaderboard, methodology & example report → aj-en.github.io/aeo-audit


Architecture Overview

graph TD
    CLI[CLI: aeo-audit] --> Engine[ScanEngine]
    Engine --> Config[ConfigLoader]
    Engine --> Crawler[Playwright Crawler]
    Engine --> Registry[CheckRegistry]
    Crawler --> Fetch[Fetch URL & Render DOM]
    Registry --> Run[Run 26 Audit Checks]
    Run --> Score[Scoring Pipeline]
    Score --> Reporter[ReporterFactory]
    Reporter --> Terminal[Rich Terminal]
    Reporter --> HTML[HTML Report]
    Reporter --> PDF[WeasyPrint PDF]
    Reporter --> JSON[JSON Metadata]

Installation

1. System Dependencies (Required for WeasyPrint PDF)

PDF reports require external layout libraries installed on your OS:

  • macOS (Homebrew):

    brew install pango cairo gdk-pixbuf upx
    
  • Ubuntu/Debian:

    sudo apt-get update
    sudo apt-get install -y libpango-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 upx
    

2. Install Methods

Method A: Via pip / pipx (Recommended)

pipx install aeo-audit      # isolated CLI install (recommended)
# or:  pip install aeo-audit

# bleeding edge from main:
# pipx install git+https://github.com/AJ-EN/aeo-audit.git

That's it — on your first scan, aeo-audit downloads the headless Chromium it needs automatically (one-time, ~30s). To pre-install it yourself:

playwright install chromium

Method B: Standalone Binary Installer (No Python Needed)

Run the automated installation script:

curl -fsSL https://raw.githubusercontent.com/AJ-EN/aeo-audit/main/scripts/install.sh | bash

[!IMPORTANT] The binary still needs a Chromium runtime. If a scan reports a missing browser, install one with playwright install chromium and point the binary at it: export PLAYWRIGHT_BROWSERS_PATH="$HOME/Library/Caches/ms-playwright" (macOS) or the equivalent cache path on your OS.

Method C: Source installation

git clone https://github.com/AJ-EN/aeo-audit.git
cd aeo-audit
pip install -e .
playwright install chromium

[!NOTE] If WeasyPrint throws rendering or font warnings on Python 3.14+, we recommend pinning pydyf==0.10.0.


Quick Start

Scan a site and generate reports using the scan command:

# Terminal report (default)
aeo-audit scan https://api.example.com --format terminal

# Premium HTML report with embedded graphs
aeo-audit scan https://api.example.com --format html --output report.html

# Accessible PDF report
aeo-audit scan https://api.example.com --format pdf --output report.pdf

# Machine-readable JSON report
aeo-audit scan https://api.example.com --format json --output report.json

Scoring & Grading

Each of the 26 checks returns a raw score (0.0–1.0). Checks roll up into 5 weighted category scores, which roll up into a single 0–100 overall score. The grade is then assigned by percentile rank against a benchmark corpus — so it reflects how a site compares to the field, not an absolute bar that nobody clears yet.

Category weights

aeo-audit is foundation-weighted: dimensions where well-run APIs already differ today (Trust, Capabilities, Discovery) carry the most weight, while emerging agent-native dimensions (Identity, parts of Commerce) contribute upside without dominating the score.

CategoryWeightWhat it measures
Discovery0.25robots/agent access, sitemap, .well-known, DNS, and MCP discovery.
Capabilities0.25Interface docs — OpenAPI, JSON Schema, GraphQL, async webhooks.
Trust0.25SLA/status page, structured errors, health checks, audit logs.
Commerce0.15Agent transactions — pricing, Stripe/crypto hints, usage metering.
Identity0.10Ownership & auth — DID docs, OAuth metadata, wallet hints.

Grade bands (percentile)

GradePercentileMeaning
Atop 10%Leading the field on agent-readiness.
Btop 30%Strong; a few high-leverage gaps.
Ctop 60%Foundational signals present, frontier gaps.
Dtop 85%Minimal agent-readiness.
Fbottom 15%Not addressed.

Weights, thresholds, and grade bands are all defined in config.yaml and overridable via a custom config. See docs/CONFIG_REFERENCE.md.


CI/CD Pipeline Integration

You can easily configure aeo-audit as a compliance block (exits with code 2 if scores drop below requirements). Here's a brief example for GitHub Actions:

- name: AEO Compliance Gate
  run: aeo-audit scan https://preview.example.com --fail-on-grade B --format terminal

See docs/CI_RECIPES.md for GitHub Actions, GitLab CI, and Git hooks code snippets.


Extending: Custom Check Plugins

To implement custom checking rules, subclass BaseCheck and expose it under the aeo_audit.checks entrypoint.

See docs/CUSTOM_CHECKS.md for a complete template walkthrough.


FAQ

1. How do I install Playwright browser binaries?

If running the scanner for the first time, you may need to install Playwright's headless browser binaries:

playwright install chromium

2. Where is the SQLite cache stored?

By default, the SQLite cache database is created in your working directory as .aeo_cache.db to speed up consecutive audit scans. This can be customized or disabled using --no-cache.

3. Why are my PDF files empty or raising font errors?

Ensure you have installed the native pango and cairo system dependencies (see Step 1 of installation).

4. Can I self-host the browser demo?

Yes — the hosted "paste a URL, get a scorecard" demo lives in webdemo/ and wraps the exact same ScanEngine the CLI runs. It ships with a Dockerfile (Chromium baked in), a Fly.io config that scales to zero, SSRF guarding, and per-IP rate limiting. See webdemo/README.md.

Ver o original no GitHub

Bom para

Relacionados