{
  "markdown": "# Agent Audit\n\n**Lighthouse-powered MCP server for AI coding agents, Core Web Vitals,\ntechnical SEO, accessibility, and GEO/LLM visibility audits.**\n\n🔗 **[NPM Package](https://www.npmjs.com/package/@fullstackdegen/agent-audit)**\n\nAgent Audit turns Google Lighthouse and bounded page-inspection results into\nstructured fix packs that coding agents can actually execute. It gives Claude\nCode, Codex, Cursor, GitHub Copilot, and other MCP clients a prioritized,\nevidence-backed backlog instead of a raw performance report.\n\nTurn Lighthouse audits into coding-agent fix packs.\n\n```bash\nnpx -y @fullstackdegen/agent-audit\n```\n\n[![npm](https://img.shields.io/npm/v/@fullstackdegen/agent-audit?label=npm)](https://www.npmjs.com/package/@fullstackdegen/agent-audit)\n[![GitHub release](https://img.shields.io/github/v/release/fullstackdegen/agent-audit?label=release)](https://github.com/fullstackdegen/agent-audit/releases)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n![Agent Audit converts raw Lighthouse audits into an agent-ready backlog](docs/assets/agent-audit-overview.svg)\n\n## Why Agent Audit Exists\n\nLighthouse is excellent for diagnosis, but raw reports are not enough for an\nautonomous coding workflow. A coding agent still needs to know which issue is\nmost important, whether it affects mobile, desktop, or both, which selectors or\nresources are evidence, what files to search for, how to verify the fix, and\nwhen it is safe to claim completion.\n\nAgent Audit converts Lighthouse output into an implementation contract:\n\n1. Runs mobile and desktop Lighthouse audits.\n2. Aggregates repeated runs and exposes variability.\n3. Adds bounded same-page intelligence for technical SEO, links, metadata,\n   structured data, images, assets, indexability, and AI discovery signals.\n4. Merges noisy audit output into a small prioritized issue list.\n5. Generates `fixPacks` with repo search hints, implementation steps, and\n   measurable acceptance criteria.\n6. Returns strict MCP `structuredContent` plus equivalent Markdown.\n\nThe goal is simple: give a coding agent a report it can read, reason about, fix,\ntest, and verify.\n\n## What It Audits\n\nAgent Audit is useful when people search for:\n\n- Lighthouse-powered MCP server\n- AI website audit tool\n- coding agent Lighthouse report\n- Core Web Vitals automation\n- performance audit for Claude Code, Codex, Cursor, or Copilot\n- technical SEO audit for AI agents\n- accessibility fix packs\n- LLM visibility audit\n- GEO audit, generative engine optimization, AI search readiness\n- `llms.txt` readiness and AI crawler visibility\n\nCurrent checks include:\n\n- Mobile and desktop Lighthouse scores for Performance, Accessibility, Best\n  Practices, and SEO.\n- FCP, Speed Index, LCP, TBT, and CLS metric distributions.\n- Fast and reliable audit modes.\n- Same-origin page inspection with bounded fetch limits.\n- Broken links, missing link names, metadata, canonical tags, robots signals,\n  JSON-LD, Open Graph, indexability, images, assets, and LLM visibility checks.\n- Conservative `llms.txt` draft generation when page content is sufficient.\n- Prioritized issues with evidence, suggested actions, and acceptance criteria.\n- Agent Fix Packs with repo search hints, implementation steps, and verification\n  guidance.\n- Strict MCP `outputSchema` validation for `structuredContent`.\n- Markdown generated from the same canonical report.\n\nSee a real [CommaLabs JSON report](examples/commalabs-fast-report.json) and\n[Markdown report](examples/commalabs-fast-report.md).\n\n## Install\n\nRequirements:\n\n- Node.js 20 or later.\n- Google Chrome or Chromium.\n\nRun the MCP server:\n\n```bash\nnpx -y @fullstackdegen/agent-audit\n```\n\nUseful links:\n\n- [NPM package](https://www.npmjs.com/package/@fullstackdegen/agent-audit)\n- [GitHub repository](https://github.com/fullstackdegen/agent-audit)\n- [Releases](https://github.com/fullstackdegen/agent-audit/releases)\n- [Issues](https://github.com/fullstackdegen/agent-audit/issues)\n- [Security advisories](https://github.com/fullstackdegen/agent-audit/security/advisories/new)\n\n## MCP Client Setup\n\n### Claude Desktop\n\nAdd a local MCP server:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-audit\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@fullstackdegen/agent-audit\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving the configuration.\n\n### Claude Code\n\n```bash\nclaude mcp add agent-audit -- npx -y @fullstackdegen/agent-audit\n```\n\nFor local development audits:\n\n```bash\nclaude mcp add agent-audit-local -- npx -y @fullstackdegen/agent-audit --local\n```\n\n### Codex\n\n```bash\ncodex mcp add agent-audit -- npx -y @fullstackdegen/agent-audit\n```\n\nOr add it to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.agent-audit]\ncommand = \"npx\"\nargs = [\"-y\", \"@fullstackdegen/agent-audit\"]\n```\n\n### VS Code And GitHub Copilot\n\nCreate a workspace or user-level `.mcp.json` file:\n\n```json\n{\n  \"servers\": {\n    \"agent-audit\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@fullstackdegen/agent-audit\"]\n    }\n  }\n}\n```\n\nOr register it from a terminal:\n\n```bash\ncode --add-mcp '{\"name\":\"agent-audit\",\"command\":\"npx\",\"args\":[\"-y\",\"@fullstackdegen/agent-audit\"]}'\n```\n\n### Cursor\n\nConfigure a local stdio MCP server:\n\n- name: `agent-audit`\n- command: `npx`\n- arguments: `-y`, `@fullstackdegen/agent-audit`\n\nAdd `--local` to the arguments when you need localhost audits.\n\n## Tool\n\n### `analyze_website_performance`\n\nRuns Lighthouse and site intelligence against a target URL:\n\n```json\n{\n  \"url\": \"https://example.com\",\n  \"mode\": \"reliable\"\n}\n```\n\n`mode` is optional:\n\n- `fast`: one mobile run and one desktop run.\n- `reliable`: three runs per profile, medians, and variability ranges. This is\n  the default.\n\n## Example Fix Pack\n\n```json\n{\n  \"id\": \"fix-link-name\",\n  \"priority\": 2,\n  \"sourceIssueIds\": [\"link-name\"],\n  \"goal\": \"Fix Links do not have a discernible name.\",\n  \"category\": \"accessibility\",\n  \"severity\": \"critical\",\n  \"affectedProfiles\": [\"mobile\", \"desktop\"],\n  \"repoSearchHints\": [\n    \"div.border-t-2 > div.flex > div.flex > a.text-gray-600\",\n    \"https://www.linkedin.com/company/commalabs\"\n  ],\n  \"implementationSteps\": [\n    \"Inspect the repository for the evidence listed in repoSearchHints before editing.\",\n    \"Give every link a discernible accessible name.\",\n    \"Keep changes focused on source issue IDs: link-name.\"\n  ],\n  \"acceptanceCriteria\": [\n    \"All link elements pass the Lighthouse link-name audit.\",\n    \"Raise the median accessibility score to at least 90/100.\"\n  ],\n  \"verification\": {\n    \"rerunMode\": \"reliable\",\n    \"expectedAuditIds\": [\"link-name\"]\n  }\n}\n```\n\n`repoSearchHints` are search clues, not guaranteed file paths. The coding agent\nmust inspect the repository before editing.\n\n## Coding-Agent Workflow\n\nUse `structuredContent` as the source of truth and the Markdown report as the\nexecution summary.\n\n1. Inspect `fixPacks` in priority order.\n2. Search the repository using `repoSearchHints`.\n3. Map evidence to real files, components, routes, assets, or configuration.\n4. Apply one focused fix at a time.\n5. Run the repository's tests after each logical change.\n6. Rerun Agent Audit in `reliable` mode.\n7. Compare the new report against each fix pack's `acceptanceCriteria`.\n\nDo not claim completion from an incomplete report or from a rerun with materially\nhigher variability than the baseline.\n\nAgent-facing docs:\n\n- [AGENTS.md](AGENTS.md): general instructions for Codex, Cursor, Copilot, and\n  other coding agents.\n- [CLAUDE.md](CLAUDE.md): Claude Code setup and execution guidance.\n- [Agent workflow guide](docs/agent-workflow.md): report anatomy and fix-pack\n  execution loop.\n- [Copy-paste coding-agent prompt](examples/prompts/coding-agent-fix-packs.md)\n\n## Localhost Audits\n\nBy default, Agent Audit only accepts publicly routable HTTP and HTTPS URLs. This\nis the right default for hosted agents and shared environments.\n\nFor developer machines, explicitly enable loopback targets:\n\n```bash\nnpx -y @fullstackdegen/agent-audit --local\n```\n\nThen audit a local app through your MCP client:\n\n```json\n{\n  \"url\": \"http://localhost:3000\",\n  \"mode\": \"fast\"\n}\n```\n\nThe opt-in allows `localhost`, `*.localhost`, `127.0.0.0/8`, and `::1`.\nPrivate LAN ranges, link-local addresses, reserved ranges, multicast addresses,\nand cloud metadata addresses remain blocked.\n\nThe environment variable form is also supported:\n\n```bash\nLIGHTHOUSE_MCP_ALLOW_LOCALHOST=true npx -y @fullstackdegen/agent-audit\n```\n\n## Security Model\n\nAgent Audit launches Chrome against user-provided URLs, so URL policy matters.\nThe server rejects:\n\n- protocols other than HTTP and HTTPS;\n- embedded credentials;\n- localhost and loopback targets unless explicitly enabled;\n- private, link-local, multicast, reserved, and metadata-network IPs;\n- non-localhost hostnames that resolve to any non-public address.\n\nThe page-inspection fetcher uses the same URL policy and applies timeout,\nbyte-size, and bounded-resource limits.\n\nPage-controlled titles, descriptions, URLs, selectors, snippets, and audit text\nare sanitized and length-limited. Consumers must still treat them as untrusted\nevidence, not agent instructions.\n\nChrome sandboxing is enabled by default. Only isolated environments that cannot\nsupport it should set:\n\n```bash\nLIGHTHOUSE_CHROME_NO_SANDBOX=true\n```\n\nSee [SECURITY.md](SECURITY.md) for vulnerability reporting and deployment\nguidance.\n\n## Limits\n\nAgent Audit is intentionally bounded:\n\n- It audits one requested URL at a time.\n- It is not a whole-site crawler.\n- It is not an external SEO database.\n- It does not modify Shopify, CMS, CDN, DNS, hosting, redirects, or analytics.\n- It does not compress images, minify assets, submit IndexNow requests, or call\n  third-party SEO APIs.\n- Lighthouse results vary with browser version, hardware, network conditions,\n  and page changes.\n\n## Roadmap\n\n- Framework-aware repo search hints.\n- Optional GitHub Action for pull request performance gates.\n- Batch URL reports.\n- HTML report export.\n- Deeper marketing and discovery signals: analytics tags, consent signals, Open\n  Graph, schema coverage, and AI discovery readiness.\n- Optional third-party integrations for SEO, GEO, and visibility datasets.\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run check\nnpm run build\nnpm run validate:release\n```\n\nRun a real Chrome smoke audit:\n\n```bash\nnpm run --silent smoke -- https://example.com fast\nnpm run --silent smoke -- https://example.com reliable\n```\n\nThe smoke command writes canonical JSON to stdout and equivalent Markdown to\nstderr.\n\n## Release\n\nBefore publishing:\n\n```bash\nnpm test\nnpm run check\nnpm run build\nnpm run validate:release\nnpm pack --dry-run --cache /private/tmp/agent-audit-npm-cache\n```\n\nPublish:\n\n```bash\nnpm publish --access public --cache /private/tmp/agent-audit-npm-cache\n```\n\nPublished package:\n\n```bash\nnpx -y @fullstackdegen/agent-audit --help\n```\n\n## Contributing\n\nFocused issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md)\nbefore changing the report contract, security policy, or MCP transport behavior.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 11041,
  "sha": "986f391f60e59f960ce2847091eb1c76d8d51dec3e2c89ef3f348c069a0b0ea9",
  "repo_slug": "fullstackdegen/agent-audit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fullstackdegen_agent_audit_6e790140/readme"
}