agent-ready-mcp
by VeldinS
README.md
# agent-ready
[](https://agent-ready-web.vercel.app)
[](https://www.npmjs.com/package/agent-readiness)
[](https://github.com/VeldinS/agent-ready/actions/workflows/ci.yml)
[](LICENSE)
**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.
```bash
npx agent-readiness https://yoursite.com
```
> **No install?** Scan any site in your browser at **[agent-ready-web.vercel.app](https://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](https://webmachinelearning.github.io/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:
```bash
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`](https://cli.github.com/) 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)
```yaml
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:
```md
```
## 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`](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.
```bash
claude mcp add agent-ready -- npx -y @veldins/agent-ready-mcp
```
```json
{ "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](https://agent-ready-web.vercel.app): 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
```bash
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`](https://www.npmjs.com/package/node-html-parser)); Node ≥20.19; ESM; no build step.
MIT.
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues