site-doctor

site-doctor

Audit rendered websites for broken links, images, accessibility violations, security header gaps, design issues, SEO metadata problems, console errors, hydration errors, and mixed content. Works with any URL — localhost, staging, or production.

MCP server included — use site-doctor directly from Claude, Cursor, Windsurf, or any MCP-compatible AI tool.

Install

npm install -g site-doctor

Or run without installing:

npx site-doctor audit --url http://localhost:3000

CLI Usage

Interactive mode

Run without --url to launch an interactive prompt:

site-doctor audit

You'll be guided through selecting a URL, checks, severity filters, and output format.

One-shot mode

site-doctor audit --url http://localhost:3000

Options

Option	Description	Default
--url <url>	Base URL to audit. Omit to launch interactive mode.	—
--max-pages <number>	Maximum pages to crawl.	25
--report <terminal|json|html>	Output format.	terminal
--output <path>	Write JSON or HTML report to a file.	—
--open	Open HTML report in the browser.	true for HTML
--no-open	Do not open HTML report in the browser.	—
--open-files	Open source files with critical/high issues in your editor.	false
--project-dir <path>	Path to project source for source-file links.	—
--editor <vscode|cursor|webstorm>	Editor for source-file links.	vscode
--only <checks>	Run only these checks (comma-separated). Mutually exclusive with --skip.	—
--skip <checks>	Skip these checks (comma-separated). Mutually exclusive with --only.	—
--severity <levels>	Filter issues by severity (comma-separated: critical,high,medium,low,info).	—
--category <cats>	Filter issues by category (comma-separated: links,images,accessibility,security,console,hydration,metadata,mixed-content,design,performance).	—

Check name aliases

--only and --skip accept both kebab-case and common aliases:

Check	Aliases
links	links
images	images
accessibility	accessibility, a11y
securityHeaders	security-headers, securityheaders
consoleErrors	console-errors, consoleerrors
hydrationErrors	hydration-errors, hydrationerrors
metadata	metadata, seo
mixedContent	mixed-content, mixedcontent
designIssues	design-issues, designissues, design
performance	performance, perf

Examples

Interactive audit (prompts for URL, checks, severity, format):

site-doctor audit

Terminal report:

site-doctor audit --url http://localhost:3000 --max-pages 10

Run only design and accessibility checks:

site-doctor audit --url http://localhost:3000 --only design,a11y

Skip console and hydration checks, show only critical/high issues:

site-doctor audit --url http://localhost:3000 --skip console-errors,hydration-errors --severity critical,high

Filter by category and output as JSON:

site-doctor audit --url http://localhost:3000 --category design,security --report json --output report.json

HTML report (auto-opens browser):

site-doctor audit --url http://localhost:3000 --report html --project-dir ./apps/web

Open source files in VSCode for critical/high issues:

site-doctor audit --url http://localhost:3000 --report html --project-dir ./apps/web --open-files

List available checks

site-doctor list-checks

MCP Server

site-doctor ships a built-in Model Context Protocol server so AI agents can run audits without the CLI.

Tools

Tool	Description
audit	Run a full audit. Parameters: url (required), maxPages (default 25), checks (toggle individual checks). Returns a markdown summary grouped by severity.
list-checks	List all available audit checks with descriptions. Use this before running a full audit.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "site-doctor": {
      "command": "npx",
      "args": ["-y", "site-doctor-mcp"]
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global settings):

{
  "mcpServers": {
    "site-doctor": {
      "command": "npx",
      "args": ["-y", "site-doctor-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "site-doctor": {
      "command": "npx",
      "args": ["-y", "site-doctor-mcp"]
    }
  }
}

opencode

Add to opencode.json:

{
  "mcp": {
    "site-doctor": {
      "type": "local",
      "command": ["npx", "-y", "site-doctor-mcp"],
      "enabled": true
    }
  }
}

Global install

If installed globally, you can use the binary directly instead of npx:

{
  "mcpServers": {
    "site-doctor": {
      "command": "site-doctor-mcp"
    }
  }
}

Checks

Check	Flag name	What it finds
Crawl	—	Discovers same-origin pages, respects maxPages, skips downloads
Links	links	Broken internal/external links, redirect loops, blocked URLs
Images	images	Broken images, missing alt, missing dimensions, oversized files, lazy-loaded hero images
Accessibility	accessibility (a11y)	axe-core WCAG violations — contrast, labels, landmarks, ARIA, heading order
Security headers	security-headers	Missing CSP, HSTS, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, frame protection
Console errors	console-errors	Grouped browser console errors with page context
Hydration errors	hydration-errors	React / Next.js hydration mismatches
Metadata	metadata (seo)	Missing title, description, canonical, Open Graph image, H1 issues
Mixed content	mixed-content	HTTP resources loaded on HTTPS pages
Design issues	design-issues (design)	Heading hierarchy, typography scale & readability, color contrast, touch targets, responsive layout, text walls
Performance	performance (perf)	LCP, CLS, INP, render-blocking resources, JS/CSS bundle size, DOM size, compression, third-party hosts

Source-file links

When you pass --project-dir, the HTML report links each page to its source file. Supports Next.js app/ and pages/ routers, including monorepos. Click the file link to open it in VS Code, Cursor, or WebStorm.

Programmatic API

You can also use site-doctor as a library:

import { runAudit, buildConfig } from "site-doctor";

const config = buildConfig({ url: "http://localhost:3000", maxPages: 10 });
const result = await runAudit(config);

console.log(`Found ${result.issues.length} issues`);
for (const issue of result.issues) {
  console.log(`[${issue.severity}] ${issue.category}: ${issue.message}`);
}

License

MIT