agent-readiness

v0.4.0

Published

16 days ago

Make any website agent-ready: scan it, generate llms.txt + WebMCP tool scaffolds, inject them into your project, score it, and open the fix as a PR.

0High
0Medium
0Low

veldins

webmcp llms.txt llmstxt agentic-web agent-ready agent-readiness mcp model-context-protocol ai-agents lighthouse agentic-browsing structured-data website-scanner

agent-ready

Make any website agent-ready in one command. Scan a site, get an agent-readiness score, and auto-generate the two things the agentic web now expects — an llms.txt and a WebMCP tool scaffold — so AI agents can understand and act on your site instead of blindly scraping it.

npx agent-readiness https://yoursite.com

No install? Scan any site in your browser at agent-ready-web.vercel.app — paste a URL, get the score + per-check breakdown, and download the generated llms.txt + WebMCP scaffold.

agent-ready — scanning https://yoursite.com

  ✗ llms.txt present (0/22)
     → Add /llms.txt so agents get a clean, token-cheap map of your site (generated below).
  ✗ WebMCP tools (document.modelContext) (0/22)
     → Expose your key actions as WebMCP tools so agents can ACT, not just scrape (scaffold generated below).
  ✔ Structured data (JSON-LD / OpenGraph) (+13/13)
  ✔ Semantic landmarks + an H1 (+13/13)
  ✔ Title + meta description (+10/10)
  ✗ robots.txt + sitemap.xml (0/8)
  ✔ Canonical URL (<link rel="canonical">) (+4/4)
  ✔ Document language (<html lang>) (+4/4)
  ✔ Image alt-text coverage (18/20, 90%) (+4/4)

  Agent-Readiness: 48/100
  pages: 17  •  forms: 2  •  inferred actions: 3
  Generated → ./agent-ready-out/llms.txt, ./agent-ready-out/webmcp.tools.js, ./agent-ready-out/structured-data.html, ./agent-ready-out/agent-ready.json

Why this exists

Chrome's Lighthouse now ships an "Agentic Browsing" audit in the default config (13.3, May 2026), and WebMCP is a W3C draft in origin trial. Millions of sites are about to see a failing agent-readiness grade with no obvious way to fix it. agent-ready is the fix: it doesn't just diagnose (every scanner does that) — it generates the artifacts and is built to run in CI.

llms.txt — a clean, machine-readable map of your pages (with one-line summaries) and actions, built from a multi-page crawl (the emerging standard agents read first).
webmcp.tools.js — a WebMCP scaffold that registers each <form> and inferred action (search / login / signup / cart / checkout / contact / subscribe) as a callable agent tool via document.modelContext.registerTool(...), so an agent can complete the signup / search / booking instead of guessing at your DOM.
structured-data.html — a JSON-LD + OpenGraph snippet to drop into your <head> so machines get explicit, structured meaning.

One command, one PR (the fixer)

Every other tool scans. agent-ready also fixes — and opens the fix as a pull request:

npx agent-readiness fix ./my-site --pr

It detects your framework (Next.js App/Pages Router, Vite, or plain static HTML), writes llms.txt + webmcp.tools.js into the right place, injects the <script> tag and the missing <html lang> / meta description / JSON-LD + OpenGraph into your entry HTML or layout, then branches, commits, and opens a PR with a clear before → after score:

agent-ready fix — ./my-site

  Framework: Static / plain HTML
  Score: 17/100 → 88/100

  Files:
    + llms.txt          (token-cheap site map for agents)
    + webmcp.tools.js   (WebMCP tool scaffold)
    inject → index.html (html-lang, meta-description, structured-data, webmcp-script)

  ✔ Opened pull request: https://github.com/you/my-site/pull/42

--dry-run — print the plan (and the exact git/gh commands) without touching anything.
--url https://yoursite.com — scan the live site for a richer llms.txt (multi-page) and to fill real URLs + a canonical tag.
--base <branch> / --branch <name> — control the PR target and head branch.
Injection is idempotent — re-running never duplicates a tag. --pr needs a git repo with an origin remote and the gh CLI authenticated.

Prefer to apply locally without a PR? agent-ready fix ./my-site writes + injects in place; agent-ready <url> --apply ./my-site just drops the files into public/.

Use it in CI (GitHub Action)

permissions:
  contents: read
  pull-requests: write   # so it can comment the score on the PR
steps:
  - uses: VeldinS/agent-ready@v0
    with:
      url: https://yoursite.com
      comment: true        # post a sticky agent-readiness comment on the PR (default)
      min-score: 60        # optional: fail the job if the score drops below this

On every pull request it posts (and updates) a single comment with the score and per-check breakdown. Add the badge to your README once you're green:

![agent-ready](https://img.shields.io/badge/agent--ready-100%2F100-brightgreen)

Use it from your agent (MCP server)

Run "make my site agent-ready" right inside Claude Code / Cursor / Claude Desktop. The @veldins/agent-ready-mcp server exposes two tools — scan_site (score + per-check breakdown) and generate_fixes (the llms.txt + WebMCP scaffold + structured-data contents) — over stdio, sharing the same scanner core.

claude mcp add agent-ready -- npx -y @veldins/agent-ready-mcp

{ "mcpServers": { "agent-ready": { "command": "npx", "args": ["-y", "@veldins/agent-ready-mcp"] } } }

What it checks

| Check | Weight | |-------|:--:| | llms.txt present | 22 | | WebMCP tools (document.modelContext) | 22 | | Structured data (JSON-LD / OpenGraph) | 13 | | Semantic landmarks + an <h1> | 13 | | Title + meta description | 10 | | robots.txt + sitemap.xml | 8 | | Canonical URL (<link rel="canonical">) | 4 | | Document language (<html lang>) | 4 | | Image alt-text coverage (≥80%) | 4 |

The score reflects the server-rendered HTML an agent first sees; heavily client-rendered SPAs will under-report content checks until they ship meaningful HTML.

Roadmap

[x] fix mode: write + inject the artifacts and open a PR with a before → after score
[x] Framework adapters (Next.js App/Pages Router, Vite, static HTML)
[x] GitHub Action comments the score on every PR
[x] Web scanner page: paste a URL → scored report + downloadable fixes (no install)
[x] MCP server so Claude Code / Cursor can run "make my site agent-ready" (@veldins/agent-ready-mcp)
[ ] Re-grade against live Lighthouse Agentic Browsing on each PR

Local dev

npm install
node bin/agent-ready.mjs examples/sample-site.html
npm test          # node --test — fixtures, generators, crawl, CLI

One runtime dependency (node-html-parser); Node ≥20.19; ESM; no build step.

MIT.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme