agentic-readiness

Check what your website exposes to AI agents, and whether each technology you publish actually works.

Install

Nothing to install and nothing to configure:

npx agentic-readiness example.com

Agentic readiness of example.com

  OK    Access policies (robots.txt / ai.txt / TDMRep)
  FAIL  MCP server card
        mcpServerEndpointUnavailable: the advertised endpoint did not answer, so an agent that
        reads this card reaches nothing; fix: serve the MCP endpoint at the advertised URL
  OK    OpenAPI description

  3 of 13 technologies published, 1 with defects.

It will not fail your build because you did not adopt something

This is the rule the whole tool is built on. Missing is not the same as broken.

If you do not publish an MCP server card, nothing is reported. If you publish one and its endpoint answers nothing, that is a defect and the build fails. A site that publishes none of these technologies exits 0 with a note saying so.

It also will not fail a build for a check it could not finish. A timeout, a blocked request or a spent budget is us failing to look, not you failing to publish, so those are reported as "partly assessed" and exit clean. A checker that goes red for its own network trouble is a checker teams learn to ignore.

In CI

- name: Agent readiness
  run: npx agentic-readiness ${{ env.PREVIEW_HOST }}

In --json, checked is every technology this tool can check and adopted is how many the site publishes, so adopted / checked is the same fraction the web UI shows for that host. requests lists every request each check made, one line each (GET https://example.com/robots.txt → 200 text/plain), so a verdict can be repeated with curl, and a file that answered 404 can be told apart from one that never answered.

Exit codes: 0 no defects, 1 at least one published technology is broken, 2 the run could not happen (bad usage, unresolvable host, or a site that refused us). Use --fail-on security to fail only on security findings, or --fail-on never for a reporting-only job.

--timeout is the budget for the whole host, and it is handed to the checks rather than wrapped around them: a check that runs out of it withholds its verdict, is reported as PART, and the run still exits 0. A slow site is not a broken one. Very small budgets are topped up to a 5s floor for the checks themselves, so a run can still report what it found rather than nothing at all.

npx agentic-readiness example.com --json > readiness.json   # machine-readable
npx agentic-readiness example.com --user-agent "GPTBot/1.0" # what does that crawler get?
npx agentic-readiness localhost:3000 --allow-private        # your own preview build
npx agentic-readiness example.com --header "X-Token: abc"   # past your own WAF

Private and loopback addresses are refused unless you pass --allow-private. The default protects the hosted scanner, where the address comes from a stranger; on your own machine you own the target, so the flag opens the door deliberately rather than by accident.

Requests identify themselves as agentic-readiness/<version> (+https://agentic-readiness.lumar.io), so a run against your own preview host does not trip your own bot rules. --user-agent overrides it deliberately.

scan is the default subcommand and can be written explicitly. build and docs are reserved for a later release, so agentic-readiness build mcp-server will not one day change the meaning of a line you already have in CI. For now the builders and the reference are at https://agentic-readiness.lumar.io.

If we cannot look, we say so — and a 404 home page is not that

Before judging anything it knocks once on the origin, and there are three answers, not two.

A site whose WAF refuses every request, or that never answers at all, emits no signals. Reporting that as "publishes none of these technologies" would be the tool confidently claiming absence after a total failure to look — a false green, which in CI is worse than a false red. So that exits 2:

  FAIL  We could not look at this site.
        the site refused our request, which usually means bot protection (HTTP 403)

  Nothing is reported about what it publishes, because nothing was measured.

An origin that answers with an error is a different fact. api.example.com often has no route at /, and it is exactly the kind of host that publishes an OpenAPI document and an MCP card. The origin is up and talking, so every check runs and the home page status is reported as context:

  OK    Access policies (robots.txt / ai.txt / TDMRep)
  NOTE  the site has no home page at this address (HTTP 404).
        The origin answered, so everything below was measured normally.

In --json this is reach: { state, status, reason }, where state is ok, error, refused or unreachable — a named state rather than a boolean, because the four lead to different decisions.

--fail-on never governs defects. A site that refused us still exits 2, because that run produced no report rather than a clean one.

What it checks

Site-wide signals, fetched once per host: robots.txt (including per-bot rules and Content Signals), ai.txt, TDMRep, XML sitemap, llms.txt, Markdown negotiation, MCP server card, MCP authorization, OpenAPI description, API catalog, NLWeb endpoint, UCP profile, Web Bot Auth key directory, and the A2A agent card.

Per-URL and in-browser checks — canonical, JSON-LD, Product schema, schema:Action, editorial metadata, WebMCP — need a rendered page and a real browser, so they are not in this package. Run them at https://agentic-readiness.lumar.io.

Where the checks come from

The analyzers are the same code Lumar's crawler runs, imported from the container in this repository rather than reimplemented, so a defect reported here is the defect reported there. Every finding is a sentence naming the fault, why an agent cares, and the fix, and every defect is pinned to a specific revision of a specific specification. The reasoning and the sources are published at https://agentic-readiness.lumar.io/docs.

MIT licensed.