@rivi-software/agentic-seo-check 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rik Visser, Rivi Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+<img src="assets/icon.svg" width="64" height="64" alt="">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# agentic-seo-check
+
+SEO analysis built for coding agents. One core, two interfaces:
+
+- **CLI** `agentic-seo-check` with JSON (default when piped) or Markdown output and CI-friendly exit codes.
+- **MCP server** exposing five tools for Claude Code, Cursor, Codex and any other MCP client.
+
+It audits **URLs** (production, staging, `localhost` dev servers), **static build output** (`dist/`, `out/`, `build/`) and **raw HTML**, and returns findings an agent can act on: a stable rule id, severity, what is wrong, the fix, a CSS selector for where it lives, and evidence with the current values.
+
+## What it checks
+
+| Area | Examples (123 rules in total, `agentic-seo-check rules` lists them) |
+| --- | --- |
+| On-page basics | title missing/long/short/placeholder ("React App"), meta description, H1 and heading outline, canonical (missing, conflicting, relative, pointing elsewhere), robots meta and `X-Robots-Tag`, `lang`, viewport, charset, doctype |
+| Social | Open Graph completeness, absolute `og:image`, `og:url` vs canonical, Twitter card |
+| Images and links | alt text, filename-style alt, missing dimensions (CLS), empty or generic anchor text, `href="#"`/`javascript:` anchors, http links on https pages, internal nofollow |
+| International | hreflang syntax, absolute URLs, self reference, x-default, return links (crawl) |
+| Structured data | JSON-LD parse errors, `@context`/`@type`, required and recommended properties for Article, Product, Offer, Organization, WebSite, BreadcrumbList, FAQPage, LocalBusiness, Event, Recipe, VideoObject, JobPosting, HowTo, Review, SoftwareApplication and more, ISO 8601 dates; microdata too |
+| Content | empty or thin content, "lorem ipsum", readability, keyword presence in title/H1/body/description/URL and density |
+| Response | 4xx/5xx, redirects and chains, slow HTML response, non-HTML content type, http instead of https |
+| Site-level (crawl or directory) | robots.txt (missing, blocking, disallowed pages), sitemap (missing, invalid, noindex/non-canonical/broken/redirecting URLs, pages not in sitemap, orphan pages), broken internal links with their sources, redirected links and chains, duplicate titles/descriptions/H1s/content, deep pages, soft 404, http→https and www redirects, hreflang return links |
+| Rendering (`--render`, Playwright) | title/description/canonical/H1/content/links/structured data that only exist after JavaScript runs; noindex injected or removed by JavaScript; console errors |
+| Performance (`--lighthouse`, Chrome) | LCP, CLS, TBT, FCP, Speed Index, TTFB with Core Web Vitals thresholds, Lighthouse opportunities with estimated savings, failed Lighthouse SEO and agentic-browsing audits |
+
+## Install
+
+Requires Node 22.19 or newer. Published on npm as [`@rivi-software/agentic-seo-check`](https://www.npmjs.com/package/@rivi-software/agentic-seo-check); the commands it installs are `agentic-seo-check` and `agentic-seo-check-mcp`.
+
+```bash
+npx @rivi-software/agentic-seo-check audit https://example.com   # no install
+npm install -g @rivi-software/agentic-seo-check                  # or pnpm add -D / npm i -D in a project
+agentic-seo-check --help
+```
+
+Optional, only for `--render` and `--lighthouse`: `playwright` and `lighthouse` (+ `chrome-launcher`) are optional peer dependencies, so install them next to the tool, plus Google Chrome or `npx playwright install chromium`. The renderer uses a Playwright-managed Chromium when present and falls back to the installed Google Chrome or Edge.
+
+From source: `pnpm install && pnpm build && node dist/cli.js --help`.
+
+## CLI
+
+```bash
+# one page (Markdown on a terminal, JSON when piped or with --format json)
+agentic-seo-check audit https://www.example.com/pricing
+
+# whole site
+agentic-seo-check crawl https://www.example.com --max-pages 100 --max-depth 4
+
+# local dev server, ignore the dev robots.txt, include JS rendering comparison
+agentic-seo-check audit http://localhost:3000 --crawl --ignore-robots --render
+
+# static export, with the production origin for canonical/sitemap comparison
+agentic-seo-check audit ./out --base-url https://www.example.com
+
+# raw HTML from stdin
+cat page.html | agentic-seo-check audit - --base-url https://www.example.com/page
+
+# keyword focus, Lighthouse, Markdown report to a file
+agentic-seo-check audit https://www.example.com/widgets --keyword "blue widgets" --lighthouse -o report.md
+
+# CI: exit 1 when errors exist, smaller output
+agentic-seo-check audit https://staging.example.com --crawl --fail-on error --compact --no-info
+
+# rule reference
+agentic-seo-check rules --category structured-data
+agentic-seo-check rules --rule canonical.multiple
+```
+
+Exit codes: `0` success, `1` findings at or above `--fail-on`, `2` usage or runtime error. Progress goes to stderr, the report to stdout.
+
+## MCP server
+
+Add to a project `.mcp.json` (Claude Code reads it automatically):
+
+```json
+{
+  "mcpServers": {
+    "agentic-seo-check": {
+      "command": "npx",
+      "args": ["-y", "@rivi-software/agentic-seo-check", "mcp"]
+    }
+  }
+}
+```
+
+Or `claude mcp add agentic-seo-check -- npx -y @rivi-software/agentic-seo-check mcp`. From a source checkout, use `node /absolute/path/to/agentic-seo-check/dist/mcp-bin.js` instead (this repo's own `.mcp.json` does that).
+
+| Tool | Purpose |
+| --- | --- |
+| `seo_audit_page` | Audit one URL or an HTML string. Options: `keyword`, `render`, `lighthouse`, `formFactor`, `includeInfo`, `disableRules`, `headers`, `format` (json/markdown), `detail` (compact/full). |
+| `seo_crawl_site` | Crawl and audit a site. Options: `maxPages`, `maxDepth`, `concurrency`, `delayMs`, `respectRobots`, `includeSubdomains`, `checkExternalLinks`, `includePatterns`, `excludePatterns`, `pageDetail`. |
+| `seo_audit_directory` | Audit built HTML files in a directory. Options: `dir`, `baseUrl`, `maxPages`, `pageDetail`. |
+| `seo_lighthouse` | Lighthouse performance + SEO + agentic-browsing for one URL. |
+| `seo_list_rules` | Rule reference, filter by `category` or `rule`. |
+
+All tools are read-only. Results are returned both as text (JSON or Markdown) and as `structuredContent`.
+
+## Agent skill
+
+`skills/seo-audit/SKILL.md` teaches an agent the audit → fix → re-audit loop, how to map rule ids to framework code (Next.js, Astro, Nuxt, SvelteKit, Remix, TanStack Start), and the caveats (preview-host noindex, localhost limits). Copy it to `.claude/skills/seo-audit/` in a project or `~/.claude/skills/` to make it available; this repo links it under `.claude/skills/`.
+
+## Output shape
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "kind": "page",                    // or "site"
+  "url": "https://www.example.com/",
+  "score": 67,                       // 100 - 15/error - 5/warning - 1/info, floored at 0
+  "counts": { "error": 0, "warning": 6, "info": 3 },
+  "summary": { "title": "…", "metaDescription": null, "canonical": null, "indexable": true, "h1": [], "wordCount": 25, "...": "…" },
+  "findings": [
+    {
+      "rule": "meta-description.missing",
+      "severity": "warning",
+      "category": "meta",
+      "message": "Page has no meta description.",
+      "recommendation": "Add a unique meta description (about 70-160 characters) …",
+      "selector": "head > meta[name=\"description\"]",
+      "url": "https://www.example.com/",
+      "docs": "https://developers.google.com/search/docs/appearance/snippet"
+    }
+  ],
+  "response": { "status": 200, "finalUrl": "…", "redirectChain": [], "timeMs": 142, "headers": { "content-type": "text/html" } },
+  "performance": { "metrics": { "performanceScore": 99, "lcpMs": 848, "cls": 0, "...": "…" }, "opportunities": [] },   // with --lighthouse
+  "rendering": { "raw": { "wordCount": 25 }, "rendered": { "wordCount": 137 }, "...": "…" }                         // with --render
+}
+```
+
+Site audits add `crawl` stats, `robotsTxt`, `sitemaps`, `siteFindings`, `issues` (page findings rolled up per rule with example URLs) and `pages`.
+
+## Library
+
+```ts
+import { auditUrl, auditSite, auditDirectory, auditHtml, renderMarkdown } from '@rivi-software/agentic-seo-check';
+
+const page = await auditUrl('https://www.example.com/', { keyword: 'example', render: true });
+const site = await auditSite('https://www.example.com/', { maxPages: 100 });
+console.log(renderMarkdown(site));
+```
+
+## Development
+
+```bash
+pnpm test        # vitest: extractor, rules, crawler against a local fixture server, directory scan, MCP client
+pnpm typecheck
+pnpm dev audit https://example.com   # run from source with tsx
+```
+
+## Scope of this first version
+
+- Crawls are breadth-first, same-site, HTML only, and obey robots.txt by default. `--render`/`--lighthouse` apply to the start page only during a crawl.
+- Scores are indicative. Thresholds (title 30-60 chars, description 70-160, thin content 300 words, slow response 2 s, deep page depth 3) are configurable through the library `thresholds` option.
+- Not included yet: gzip sitemaps, rendering every page in a crawl, field (CrUX) data, rank tracking, backlink data, AI-generated copy suggestions.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Created in [T3 Code](https://t3.codes).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { promises as fs } from 'node:fs';
+import { Command, InvalidArgumentError, Option } from 'commander';
+import { auditTarget, compactAudit } from './core/audit.js';
+import { renderMarkdown } from './core/report/markdown.js';
+import { ALL_RULES } from './core/rules/index.js';
+import { SEVERITY_RANK } from './core/types.js';
+import { startMcpServer } from './mcp.js';
+import { VERSION } from './version.js';
+const program = new Command();
+program
+    .name('agentic-seo-check')
+    .description('SEO analysis for coding agents. Audits URLs, static build output or raw HTML and prints machine-readable findings.')
+    .version(VERSION)
+    .showHelpAfterError();
+const intArg = (value) => {
+    const n = Number.parseInt(value, 10);
+    if (!Number.isFinite(n) || n < 0)
+        throw new InvalidArgumentError('Expected a non-negative integer.');
+    return n;
+};
+function addAuditOptions(cmd, crawlDefault) {
+    if (!crawlDefault)
+        cmd.option('--crawl', 'Crawl the whole site starting at the URL instead of auditing one page');
+    return cmd
+        .option('--max-pages <n>', 'Maximum pages to crawl', intArg, 50)
+        .option('--max-depth <n>', 'Maximum link depth from the start URL', intArg, 3)
+        .option('--concurrency <n>', 'Parallel requests while crawling', intArg, 5)
+        .option('--delay <ms>', 'Delay between requests per worker', intArg, 0)
+        .option('-k, --keyword <keyword>', 'Target keyword for keyword.* checks')
+        .option('--render', 'Render with headless Chromium (Playwright) and compare with the server HTML')
+        .option('--lighthouse', 'Run Lighthouse for Core Web Vitals and Lighthouse SEO audits (slow)')
+        .addOption(new Option('--form-factor <type>', 'Lighthouse device emulation').choices(['mobile', 'desktop']).default('mobile'))
+        .option('--base-url <url>', 'Origin used for directories, files and stdin HTML (default http://localhost/)')
+        .option('--ignore-robots', 'Do not obey robots.txt while crawling')
+        .option('--include-subdomains', 'Treat subdomains as internal when crawling')
+        .option('--check-external', 'Probe external links for 4xx/5xx while crawling')
+        .option('--include <regex...>', 'Only crawl URLs matching these patterns')
+        .option('--exclude <regex...>', 'Skip URLs matching these patterns')
+        .addOption(new Option('-f, --format <format>', 'Output format (default: json when piped, md on a terminal)').choices(['json', 'md']))
+        .option('-o, --out <file>', 'Write the report to a file instead of stdout')
+        .addOption(new Option('--fail-on <severity>', 'Exit with code 1 when findings at or above this severity exist').choices(['error', 'warning', 'info', 'none']).default('none'))
+        .option('--no-info', 'Omit info-level findings')
+        .option('--compact', 'Trim evidence lists and bulky fields (smaller output for LLM consumption)')
+        .addOption(new Option('--page-detail <level>', 'Per-page detail in site reports').choices(['full', 'summary']).default('full'))
+        .option('--disable <rule...>', 'Rule ids to skip')
+        .option('--timeout <ms>', 'Per-request timeout', intArg, 15_000)
+        .option('--user-agent <ua>', 'Custom User-Agent header')
+        .option('-H, --header <header...>', 'Extra request header "Name: value" (repeatable)')
+        .option('-q, --quiet', 'Suppress progress output on stderr');
+}
+async function runAudit(target, opts, forceCrawl) {
+    const headers = {};
+    for (const h of opts.header ?? []) {
+        const idx = h.indexOf(':');
+        if (idx === -1)
+            throw new InvalidArgumentError(`Header "${h}" must be "Name: value".`);
+        headers[h.slice(0, idx).trim()] = h.slice(idx + 1).trim();
+    }
+    const showProgress = !opts.quiet && process.stderr.isTTY;
+    const onProgress = (e) => {
+        if (!showProgress)
+            return;
+        const counter = e.crawled !== undefined ? ` [${e.crawled}/${e.discovered}]` : '';
+        process.stderr.write(`\x1b[2m${e.phase}${counter}: ${e.message}\x1b[0m\n`);
+    };
+    const options = {
+        crawl: forceCrawl || Boolean(opts.crawl),
+        maxPages: opts.maxPages,
+        maxDepth: opts.maxDepth,
+        concurrency: opts.concurrency,
+        delayMs: opts.delay,
+        keyword: opts.keyword,
+        render: opts.render,
+        lighthouse: opts.lighthouse,
+        formFactor: opts.formFactor,
+        baseUrl: opts.baseUrl,
+        respectRobots: !opts.ignoreRobots,
+        includeSubdomains: opts.includeSubdomains,
+        checkExternalLinks: opts.checkExternal,
+        includePatterns: opts.include,
+        excludePatterns: opts.exclude,
+        includeInfo: opts.info,
+        disableRules: opts.disable,
+        pageDetail: opts.pageDetail,
+        fetch: { timeoutMs: opts.timeout, userAgent: opts.userAgent, headers: Object.keys(headers).length ? headers : undefined },
+        onProgress,
+    };
+    let audit = await auditTarget(target, options);
+    if (opts.compact)
+        audit = compactAudit(audit);
+    const format = opts.format ?? (opts.out ? (opts.out.endsWith('.md') ? 'md' : 'json') : process.stdout.isTTY ? 'md' : 'json');
+    const output = format === 'md' ? renderMarkdown(audit) : JSON.stringify(audit, null, 2);
+    if (opts.out) {
+        await fs.writeFile(opts.out, output + '\n', 'utf8');
+        if (!opts.quiet)
+            process.stderr.write(`Report written to ${opts.out}\n`);
+    }
+    else {
+        process.stdout.write(output + '\n');
+    }
+    if (opts.failOn !== 'none') {
+        const threshold = SEVERITY_RANK[opts.failOn];
+        const counts = audit.counts;
+        const hits = ['error', 'warning', 'info'].filter((s) => SEVERITY_RANK[s] >= threshold).reduce((n, s) => n + counts[s], 0);
+        if (hits > 0) {
+            if (!opts.quiet)
+                process.stderr.write(`${hits} finding(s) at or above "${opts.failOn}" severity.\n`);
+            process.exitCode = 1;
+        }
+    }
+}
+addAuditOptions(program
+    .command('audit')
+    .argument('<target>', 'URL, directory of HTML files, .html file, or "-" for HTML on stdin')
+    .description('Audit a page, a site (--crawl), a build directory or raw HTML'), false).action(async (target, opts) => {
+    await runAudit(target, opts, false);
+});
+addAuditOptions(program.command('crawl').argument('<url>', 'Start URL').description('Crawl a site and audit every page (same as "audit --crawl")'), true).action(async (url, opts) => {
+    await runAudit(url, opts, true);
+});
+program
+    .command('rules')
+    .description('List the rules this tool can report')
+    .option('--category <category>', 'Filter by category')
+    .option('--rule <id>', 'Show one rule')
+    .addOption(new Option('-f, --format <format>', 'Output format').choices(['json', 'md']).default(process.stdout.isTTY ? 'md' : 'json'))
+    .action((opts) => {
+    const rules = ALL_RULES.filter((r) => (!opts.category || r.category === opts.category) && (!opts.rule || r.id === opts.rule));
+    if (opts.format === 'json') {
+        process.stdout.write(JSON.stringify({ count: rules.length, rules }, null, 2) + '\n');
+        return;
+    }
+    const lines = ['| Rule | Severity | Category | Checks |', '| --- | --- | --- | --- |'];
+    for (const r of rules)
+        lines.push(`| \`${r.id}\` | ${r.severity} | ${r.category} | ${r.description.replace(/\|/g, '\\|')}${r.requires ? ` _(requires ${r.requires})_` : ''} |`);
+    process.stdout.write(lines.join('\n') + '\n');
+});
+program
+    .command('mcp')
+    .description('Start the MCP server on stdio (for Claude Code, Cursor, Codex, etc.)')
+    .action(async () => {
+    await startMcpServer();
+});
+program.parseAsync(process.argv).catch((err) => {
+    process.stderr.write(`agentic-seo-check: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(2);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/core/audit.d.ts

@@ -0,0 +1,72 @@
+import { type ProgressEvent } from './crawl.js';
+import { type FetchOptions } from './fetch.js';
+import { type Audit, type IssueRollup, type PageAudit, type PageSource, type ResponseInfo, type SiteAudit, type Thresholds } from './types.js';
+export type { ProgressEvent } from './crawl.js';
+export interface AuditOptions {
+    /** Target keyword/phrase for the keyword.* rules. */
+    keyword?: string;
+    /** Render with headless Chromium (Playwright) and compare against the server HTML. */
+    render?: boolean;
+    /** Run Lighthouse (performance + SEO + agentic-browsing categories). */
+    lighthouse?: boolean;
+    formFactor?: 'mobile' | 'desktop';
+    /** Include info-level findings (default true). */
+    includeInfo?: boolean;
+    /** Rule ids to skip. */
+    disableRules?: string[];
+    thresholds?: Partial<Thresholds>;
+    fetch?: FetchOptions;
+    /** Base URL for inline HTML, files and directories (default http://localhost/). */
+    baseUrl?: string;
+    includeSubdomains?: boolean;
+    onProgress?: (event: ProgressEvent) => void;
+}
+export interface CrawlOptions extends AuditOptions {
+    maxPages?: number;
+    maxDepth?: number;
+    concurrency?: number;
+    delayMs?: number;
+    respectRobots?: boolean;
+    checkExternalLinks?: boolean;
+    maxLinkChecks?: number;
+    includePatterns?: string[];
+    excludePatterns?: string[];
+    /** How much per-page detail to keep in the site result. */
+    pageDetail?: 'full' | 'summary';
+}
+export interface HtmlAuditInput {
+    url?: string;
+    response?: ResponseInfo;
+    source?: PageSource;
+    target?: string;
+    depth?: number;
+}
+export declare const DEFAULT_CRAWL: {
+    readonly maxPages: 50;
+    readonly maxDepth: 3;
+    readonly concurrency: 5;
+    readonly delayMs: 0;
+    readonly maxLinkChecks: 200;
+};
+/** Audit an HTML string. `url` is used to resolve links and for display. */
+export declare function auditHtml(html: string, input?: HtmlAuditInput, options?: AuditOptions): Promise<PageAudit>;
+/** Fetch and audit one URL. Optionally render and/or run Lighthouse. */
+export declare function auditUrl(url: string, options?: AuditOptions): Promise<PageAudit>;
+/** Audit a single .html file from disk. */
+export declare function auditFile(filePath: string, options?: AuditOptions): Promise<PageAudit>;
+/** Crawl a site and audit every page plus site-level checks. */
+export declare function auditSite(startUrl: string, options?: CrawlOptions): Promise<SiteAudit>;
+/** Audit a directory of built HTML files (dist/, out/, build/). */
+export declare function auditDirectory(dir: string, options?: CrawlOptions): Promise<SiteAudit>;
+/**
+ * Auto-detect the target type: http(s) URL, directory, .html file, or "-" for stdin.
+ * `crawl` forces a site crawl for URLs.
+ */
+export declare function auditTarget(target: string, options?: CrawlOptions & {
+    crawl?: boolean;
+    stdinHtml?: string;
+}): Promise<Audit>;
+export declare function recomputeSite(site: SiteAudit): void;
+export declare function rollupIssues(pages: PageAudit[]): IssueRollup[];
+/** Drop bulky, low-value fields to save tokens when the result is consumed by an LLM. */
+export declare function compactAudit<T extends Audit>(audit: T): T;