agent-ready-mcp

MCP server for Agent Ready — scan any URL for AI agent readability against the Vercel Agent Readability Spec, the llmstxt.org standard, and agent-protocol manifests (MCP server cards, A2A, agents.json, agent-permissions.json, UCP, x402, NLWeb). 69 checks across four spec families — 38 against the Vercel spec (15 site-wide + 23 per-page), 10 against llmstxt.org, and 21 against agent-protocol manifests — each with per-check fix guidance.

Hosted at https://agent-ready.dev/api/v1/mcp (Streamable HTTP); this package is a thin stdio wrapper around the same REST endpoints, distributed via npm for local MCP clients (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf).

Features

• scan_site — fresh agent-readability scan on any URL. Polls the hosted API up to 60s; returns the full scan or a running placeholder.
• get_scan — fetch a previously-run scan by id.
• ask — natural-language (NLWeb) search over Agent Ready's own methodology, checks, and specs. Public, no API key required; returns Schema.org-typed results.
• validate_structured_data — validate a page's (or a pasted) JSON-LD against Agent Ready's structured-data checks. Public, no API key required; paste mode needs no network, so an agent can check JSON-LD it just authored.
• Three discovery prompts — scan, interpret_scan, remediation_plan. End-to-end workflows from URL → score → fix-it plan.
• SKILL.md — Claude Skill descriptor included under skills/agent-ready/ for activation routing.

Setup

You'll need an Agent Ready Pro API key. Sign up at agent-ready.dev, upgrade to Pro, then issue a key from the dashboard.

Claude Desktop

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

{
  "mcpServers": {
    "agent-ready": {
      "command": "npx",
      "args": ["-y", "agent-ready-mcp@latest"],
      "env": {
        "AGENT_READY_API_KEY": "ar_live_..."
      }
    }
  }
}

Claude Code

claude mcp add agent-ready \
  -e AGENT_READY_API_KEY=ar_live_... \
  -- npx -y agent-ready-mcp@latest

Cursor / VS Code / Windsurf

.cursor/mcp.json, .vscode/mcp.json, or ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "agent-ready": {
      "command": "npx",
      "args": ["-y", "agent-ready-mcp@latest"],
      "env": {
        "AGENT_READY_API_KEY": "ar_live_..."
      }
    }
  }
}

Environment variables

Variable	Required	Default	Purpose
AGENT_READY_API_KEY	Yes	—	Bearer token issued from the Agent Ready dashboard.
AGENT_READY_API_URL	No	https://agent-ready.dev	Override for self-hosted or staging deployments.
AGENT_READY_SCAN_TIMEOUT_MS	No	60000	How long scan_site polls before returning a running placeholder.
AGENT_READY_GET_TIMEOUT_MS	No	5000	Timeout for get_scan and per-poll fetches.

Tools

Tool	Inputs	Returns
scan_site	url (string, required), pageLimit (number, optional, max 2000 — capped by your plan)	Scan object: Vercel score 0–100, llms.txt sub-score 0–100, per-check findings with howToFix strings. Returns { id, status: "running" } placeholder if the scan exceeds the poll deadline.
get_scan	id (string, scan id from a prior scan_site call)	Same scan object as scan_site, or not_found if the id is unknown or doesn't belong to the authenticated user.
ask	q (string, required), itemType (optional corpus filter), mode (optional, list or summarize)	NLWeb /ask over Agent Ready's methodology, checks, and specs. Public — no API key required. Schema.org-typed result objects.
validate_structured_data	exactly one of url (string) or jsonld (string)	D-series structured-data result: mode, url, per-check findings, and a summary verdict. Public — no API key required. Validates schema lint + agent-coherence the first-party validators don't.

Prompts

Prompt	Args	What it does
scan	url	Fresh scan + high-level summary (score, rating, top 3–5 failures, next step).
interpret_scan	id	Plain-English explanation of a previous scan's findings, grouped by category.
remediation_plan	id, optional focus ("seo" or "agents")	Prioritised fix-it doc with Now/Next/Later buckets and per-fix check ids.

Example workflow

You: Use agent-ready to scan https://my-saas.com
Claude: [calls scan_site] Your site scored 78/100 (Good) on the Vercel Agent
        Readability Spec. The top 3 fixes: …
You: Can you build me a remediation plan?
Claude: [calls remediation_plan with the scan id] Here's the prioritised list…

Skill (Anthropic Claude Skills)

A SKILL.md lives at skills/agent-ready/SKILL.md inside the package. To use it in Claude Desktop / Claude Code, copy the skills/agent-ready/ directory into ~/.claude/skills/.

The skill describes when to activate (URL + readability-audit intent), which tool to pick, how to surface scan results without dumping raw JSON, and when to defer to other tools (general SEO, performance profiling, code editing).

How it works

This package is a thin stdio→HTTPS wrapper:

MCP client (stdio) ↔ agent-ready-mcp ↔ HTTPS ↔ agent-ready.dev/api/v1/scans

All scan execution, persistence, and Pro-tier quota enforcement happen on the hosted server. The npm package only translates between MCP JSON-RPC over stdio and the REST API.

If you'd rather use the hosted MCP server directly (Streamable HTTP transport, no local install), point your MCP client at https://agent-ready.dev/api/v1/mcp with Authorization: Bearer ar_live_....

Methodology

The 69 checks, their weights, and the score formula are documented at agent-ready.dev/methodology. Both manifest.json and server.json in this repo conform to the relevant registry schemas (Glama Marketplace v0.3 and MCP registry 2025-12-11 respectively).

Development

npm install
npm run build       # → dist/mcp-server.mjs
npm test
npm run typecheck

Releasing

Two GitHub Actions handle CI and release publishing:

• .github/workflows/ci.yml — runs typecheck, tests, and npm run build on every PR and push to main.
• .github/workflows/release.yml — runs on every v* tag push. Publishes to npm (with Sigstore provenance) and to the MCP registry via GitHub OIDC.

To cut a release:

# bump version in package.json, manifest.json, server.json, src/server.ts
git commit -am "vX.Y.Z: ..."
git tag vX.Y.Z
git push && git push --tags

The release workflow handles npm + MCP registry automatically. Smithery republish (for the .mcpb bundle) and the GitHub release with custom notes are still manual — both have custom-content friction that's not worth automating today.

Required repository secret

• NPM_TOKEN — npm automation token with publish access for agent-ready-mcp. Add at GitHub repo Settings → Secrets and variables → Actions.

The MCP registry publish uses GitHub OIDC (no stored secret required).

License

MIT — see LICENSE.