# Aviary

An end-to-end SEO testing toolkit for websites using browser automation. Built with TypeScript and Playwright for comprehensive SEO analysis.

# Prerequisites

• Node.js: >= 20.0.0 (required by modern runtime dependencies and the MCP server)
• Browsers: Chromium (automatically downloaded on first run if missing, with fallback to system Google Chrome)

# Features

The library executes 235 individual checks across 28 categories. Below is an overview of the core checker modules:

# Installation

Install the package into your project:

# Using npm
npm install @ru1vly/aviary

# Using pnpm
pnpm add @ru1vly/aviary

To install globally as a command-line tool:

npm install -g @ru1vly/aviary
# or with pnpm
pnpm add -g @ru1vly/aviary

Or run directly without installing:

npx @ru1vly/aviary -u https://example.com

# Quick start

Analyze any URL directly from your shell.

Running the command with no arguments launches the full-screen interactive Terminal User Interface (TUI) Dashboard:

# Launch interactive TUI Dashboard
aviary

To run checks directly in stdout mode (e.g. for scripts, CI pipelines, or AI agents), you must pass the target URL using the -u or --url flag:

# Run direct audit
aviary -u https://example.com

# Save detailed JSON report to a file
aviary -u https://example.com --output report.json

# Save a visual HTML report to a file
aviary -u https://example.com --html report.html

# Run checks with verbose outputs (lists failure details)
aviary -u https://example.com --verbose

# Run with a mobile viewport simulation
aviary -u https://example.com --viewport 375x667

# Programmatic API

Import the SEOChecker class to run checks programmatically within your Node.js application:

import { SEOChecker } from '@ru1vly/aviary';

async function runAudit() {
  const checker = new SEOChecker({
    url: 'https://example.com',
    headless: true,
  });

  const report = await checker.check();
  console.log(`Overall SEO Score: ${report.score}/100`);
  console.log(`Passed: ${report.summary.passed}/${report.summary.total} checks`);
}

runAudit();

# Model Context Protocol (MCP) Server

Aviary includes a built-in Model Context Protocol (MCP) server that exposes real-browser SEO auditing tools directly to AI coding agents (Claude Desktop, Cursor, Windsurf, Antigravity, etc.).

The server communicates via standard I/O (stdio) and provides three registered tools:

# Running the MCP Server

# Via binary entry point
aviary-mcp

# Or via npx
npx @ru1vly/aviary aviary-mcp

# Agent Configuration (claude_desktop_config.json / MCP Settings)

{
  "mcpServers": {
    "aviary": {
      "command": "npx",
      "args": ["-y", "@ru1vly/aviary", "aviary-mcp"]
    }
  }
}

# Command line options

The command-line interface supports the following parameters:

# Environment variables (12-Factor config)

All CLI options can be configured via environment variables for 12-factor deployment and CI pipelines:

# Prometheus Metrics

Aviary automatically starts a lightweight background Prometheus metrics server on port 9090 (or AVIARY_METRICS_PORT). Scrape http://localhost:9090/metrics to monitor execution histograms (llm_inference_time_ms) and default Node.js runtime metrics.

# Configuration

You can customize which audits to run and modify their rules via custom config files or presets.

[!NOTE]
Presets restrict or expand the check list:

• basic: Fast, essential checks (ideal for rapid CI checks)
• advanced: Comprehensive analysis covering heatmap simulations (default)
• strict: Full checks with stricter scoring rules

Most checks compare against a built-in numeric threshold (minimum word count, title length bounds, image count ceilings, and so on). Any of these can be overridden per rule via an options object, without forking the checker:

{
  "rules": {
    "content": {
      "word-count-adequate": {
        "enabled": true,
        "options": { "minWords": 500, "excellentWords": 1500 }
      }
    }
  }
}

An option you don't set keeps its built-in default — there's no need to repeat every threshold to override one.

To write an HTML report programmatically:

import { SEOChecker, generateHtmlReport } from '@ru1vly/aviary';

async function exportReport() {
  const checker = new SEOChecker({ url: 'https://example.com' });
  const report = await checker.check();
  
  // Write the report to disk
  generateHtmlReport(report, './reports/seo-analysis.html');
}

# Native architecture & terminal UI

Aviary combines a high-fidelity TypeScript + Playwright browser crawler with high-performance Rust components:

1. Interactive TUI Dashboard: Built with Ratatui and Crossterm in tui/. Running aviary with no arguments boots into a responsive terminal dashboard with real-time audit navigation, score meters, and issue inspectors.
2. Fast Static Engine (aviary-fast): Native Rust parser built with reqwest, scraper, and tokio for microsecond-level raw HTTP checks.
3. Platform Prebuilt Binaries: Shipped via optional dependencies for zero-compilation startup across Linux, macOS, and Windows.

# Project structure

aviary/
├── src/                   # Source code (TypeScript auditing engine)
│   ├── checkers/          # 28 SEO checker modules
│   ├── config/            # Loader, presets, and configuration types
│   ├── errors/            # Logger, error handlers, and retry mechanism
│   ├── mcp/               # Model Context Protocol (MCP) server
│   ├── types/             # Common TypeScript interfaces
│   ├── index.ts           # Core library entry point
│   ├── cli.ts             # CLI command runner
│   └── reporter.ts        # HTML report template compiler
├── tui/                   # Rust interactive terminal dashboard (Ratatui)
├── engine/                # Rust fast static engine (aviary-fast)
├── examples/              # Code samples and config file templates
├── tests/                 # Unit, integration, and E2E tests
└── dist/                  # Compiled JavaScript distribution

# Development setup

To build and test the tool locally:

# Clone the repository
git clone https://github.com/Ru1vly/Aviary.git
cd Aviary

# Install project dependencies
pnpm install

# Download required browser binaries
pnpm exec playwright install chromium

# Compile TypeScript code to distribution folder
pnpm run build

# Run unit and integration tests
pnpm run test

# License

This project is licensed under the MIT License.