agent-ready-mcp 0.3.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # agent-ready-mcp
 
-MCP server for [Agent Ready](https://agent-ready.dev) — scan any URL for AI agent readability against the [Vercel Agent Readability Spec](https://vercel.com/kb/guide/agent-readability-spec), the [llmstxt.org](https://llmstxt.org) standard, and agent-protocol manifests (MCP server cards, A2A, agents.json, agent-permissions.json, UCP, x402, NLWeb). 60 checks with per-check fix guidance.
+MCP server for [Agent Ready](https://agent-ready.dev) — scan any URL for AI agent readability against the [Vercel Agent Readability Spec](https://vercel.com/kb/guide/agent-readability-spec), the [llmstxt.org](https://llmstxt.org) standard, and agent-protocol manifests (MCP server cards, A2A, agents.json, agent-permissions.json, UCP, x402, NLWeb). 68 checks across four spec families — 38 against the Vercel spec (15 site-wide + 23 per-page), 10 against llmstxt.org, and 20 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).
 
@@ -115,7 +115,7 @@ If you'd rather use the hosted MCP server directly (Streamable HTTP transport, n
 
 ## Methodology
 
-The 60 checks, their weights, and the score formula are documented at [agent-ready.dev/methodology](https://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).
+The 68 checks, their weights, and the score formula are documented at [agent-ready.dev/methodology](https://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
 

package/dist/mcp-server.mjs

@@ -9229,13 +9229,13 @@ var $ZodType = /* @__PURE__ */ $constructor("$ZodType", (inst, def) => {
         canary.aborted = true;
         return canary;
       }
-      const checkResult = runChecks(payload, checks, ctx);
-      if (checkResult instanceof Promise) {
+      const checkResult2 = runChecks(payload, checks, ctx);
+      if (checkResult2 instanceof Promise) {
         if (ctx.async === false)
           throw new $ZodAsyncError();
-        return checkResult.then((checkResult2) => inst._zod.parse(checkResult2, ctx));
+        return checkResult2.then((checkResult3) => inst._zod.parse(checkResult3, ctx));
       }
-      return inst._zod.parse(checkResult, ctx);
+      return inst._zod.parse(checkResult2, ctx);
     };
     inst._zod.run = (payload, ctx) => {
       if (ctx.skipChecks) {
@@ -31181,7 +31181,7 @@ Skip checks that already pass.`
 // src/resource-content.ts
 var METHODOLOGY_MD = `# How Agent Ready scores a site
 
-> 60 checks across four categories, mapped to the Vercel Agent Readability Spec and the llmstxt.org standard. Every check is open and reproducible.
+> 68 checks across four categories, mapped to the Vercel Agent Readability Spec and the llmstxt.org standard. Every check is open and reproducible.
 
 ## What does Agent Ready measure?
 
@@ -31218,7 +31218,7 @@ Full guide: <https://agent-ready.dev/methodology>
 `;
 var CHECKS_MD = `# Agent Ready check registry
 
-> 60 checks total across four categories. IDs are stable and referenced in every scan result's \`details\` array. Each check is implemented as a single function in \`src/lib/checks/{category}/{id}-{slug}.ts\` in the agent-ready repository.
+> 68 checks total across four categories. IDs are stable and referenced in every scan result's \`details\` array. Each check is implemented as a single function in \`src/lib/checks/{category}/{id}-{slug}.ts\` in the agent-ready repository.
 
 ## Site checks (15)
 
@@ -31289,7 +31289,7 @@ Run when the site has an \`llms.txt\` file. Validate against the [llmstxt.org](h
 | L9 | Content-Type: text/plain |
 | L10 | llms-full.txt available |
 
-## Protocol checks (12)
+## Protocol checks (20)
 
 Discover-then-validate: when the relevant well-known endpoint returns 404, the check drops rather than failing. A marketing site doesn't score itself against agent manifests it has no reason to ship.
 
@@ -31307,10 +31307,18 @@ Discover-then-validate: when the relevant well-known endpoint returns 404, the c
 | C10 | x402 Payment Required response |
 | C11 | x402 accepts entries |
 | C12 | NLWeb endpoint |
+| C13 | API Catalog (RFC 9727) |
+| C14 | Web Bot Auth directory |
+| C15 | Agent Skills Discovery |
+| C16 | Content parity (no cloaking) |
+| C17 | Agent-driven UI (A2UI) |
+| C18 | MPP Payment challenge |
+| C19 | MPP challenge params |
+| C20 | AP2 payment protocol support |
 `;
 var LLMS_TXT = `# Agent Ready
 
-> Agent Ready is a free tool that scores any website against the Vercel Agent Readability Spec, the llmstxt.org specification, and agent-protocol specs (MCP, A2A, agents.json). It runs 60 checks and provides actionable fix guidance for every failing check.
+> Agent Ready is a free tool that scores any website against the Vercel Agent Readability Spec, the llmstxt.org specification, and agent-protocol specs (MCP, A2A, agents.json). It runs 68 checks and provides actionable fix guidance for every failing check.
 
 This resource mirrors agent-ready.dev's own /llms.txt so MCP clients can introspect the same surface that ChatGPT, Perplexity, and other AI agents see when discovering Agent Ready as a tool.
 
@@ -31339,64 +31347,37 @@ This resource mirrors agent-ready.dev's own /llms.txt so MCP clients can introsp
 `;
 var SPECS_MD = `# Specs Agent Ready validates against
 
-Agent Ready's 60 checks map to the specifications below. Each entry links to the canonical document and notes the check IDs that implement it.
+Agent Ready's checks map to the specifications below. Each entry links to the canonical document (where one exists) and notes the check IDs that implement it. Entries marked \`pre-standard\` are drafts or emerging conventions; \`behavioural\` entries have no published document. Protocol (C) checks are reported but unscored.
 
-## Vercel Agent Readability Spec
+## Readability
 
-Canonical: <https://vercel.com/kb/guide/agent-readability-spec>
+- **Vercel Agent Readability Spec** \u2014 The core spec for exposing a site to AI agents \u2014 discovery files, structured data, clean HTML, and markdown mirrors. Drives most site (S) and every page (P) check. Canonical: <https://vercel.com/kb/guide/agent-readability-spec> Checks: S5\u2013S15, P1\u2013P23.
+- **llmstxt.org** \u2014 The /llms.txt curated-context file (and optional llms-full.txt companion). Structural checks carry 3\xD7 weight in the llms.txt sub-score. Canonical: <https://llmstxt.org> Checks: S1\u2013S4, L1\u2013L10.
 
-Maintained on the Vercel Knowledge Base. Drives the S- (site, 15 checks), P- (page, 23 checks), and most C- (protocol) check series.
+## Agent protocols
 
-## llmstxt.org
+- **MCP Server Cards (SEP-1649)** \u2014 The Model Context Protocol discovery card at /.well-known/mcp.json \u2014 its presence (C1) and required fields (C2). Canonical: <https://modelcontextprotocol.io> Checks: C1, C2.
+- **OAuth Protected Resource Metadata (RFC 9728)** \u2014 Protected-resource metadata an MCP server advertises so agents can locate its authorization server. Canonical: <https://datatracker.ietf.org/doc/html/rfc9728> Checks: C3.
+- **A2A Protocol \u2014 Agent Cards** \u2014 The agent card at /.well-known/agent-card.json that lets agents discover and call other agents \u2014 existence with correct Content-Type (C4) and required fields (C5). Canonical: <https://a2a-protocol.org> Checks: C4, C5.
+- **Wildcard agents.json** _(pre-standard)_ \u2014 An OpenAPI extension declaring which existing REST endpoints agents should call. Pre-standard (v0.1.0). Canonical: <https://github.com/wild-card-ai/agents-json> Checks: C6.
+- **agent-permissions.json** _(pre-standard)_ \u2014 A manifest declaring per-path agent access policies, served at /.well-known/agent-permissions.json. No canonical spec document yet \u2014 defined by the discovery path. Canonical: _none published_ Checks: C7.
+- **UCP \u2014 Unified Capability Profile** \u2014 A composite profile at /.well-known/ucp bundling OAuth authorization-server metadata with capability declarations. Canonical: <https://ucp.dev> Checks: C8.
+- **OAuth Authorization Server Metadata (RFC 8414)** \u2014 The authorization-server metadata a UCP profile references so agents can complete an OAuth flow. Gated on C8. Canonical: <https://datatracker.ietf.org/doc/html/rfc8414> Checks: C9.
 
-Canonical: <https://llmstxt.org>
+## Payments
 
-The \`llms.txt\` file specification (and the optional \`llms-full.txt\` companion). Drives the L1\u2013L10 check series. Structural checks (file accessible, H1 present, valid markdown) carry 3\xD7 weight in the llms.txt sub-score; content checks 1\xD7; \`llms-full.txt\` presence 0.5\xD7.
+- **x402 \u2014 HTTP 402 Payment Required** \u2014 A behavioural payments scheme: a paid endpoint answers with HTTP 402 and a JSON body carrying an accepts array \u2014 the 402 response (C10) and valid accepts entries (C11). Canonical: <https://www.x402.org> Checks: C10, C11.
+- **MPP \u2014 Machine Payments Protocol** _(pre-standard)_ \u2014 The Stripe- and Tempo-authored "Payment" HTTP auth scheme on the IETF standards track \u2014 the WWW-Authenticate: Payment challenge (C18) and its required params (C19). Canonical: <https://paymentauth.org/> Checks: C18, C19.
+- **AP2 \u2014 Agent Payments Protocol** _(pre-standard)_ \u2014 Google's trust/authorization layer for agent-led payments, built on A2A: a participant advertises support via the AP2 extension URI in its A2A Agent Card. Detection only \u2014 mandate verifiable credentials are runtime SD-JWTs with no static artifact. Pre-standard (v0.2.0). Canonical: <https://github.com/google-agentic-commerce/AP2> Checks: C20.
 
-## Model Context Protocol \u2014 Server Cards (SEP-1649)
+## Discovery & integrity
 
-Canonical: <https://modelcontextprotocol.io>
-SEP: <https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649> (ratified 2025-11-25)
-
-The discovery card published at \`/.well-known/mcp.json\`. Drives C1 (exists), C2 (required fields), and C3 (OAuth Protected Resource metadata per [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)).
-
-## A2A Protocol \u2014 Agent Cards
-
-Canonical: <https://a2a-protocol.org>
-Schema: a2a.proto v1.0.0
-
-The agent card published at \`/.well-known/agent-card.json\`. Drives C4 (exists with correct Content-Type) and C5 (required fields).
-
-## Wildcard agents.json
-
-Canonical: <https://github.com/wild-card-ai/agents-json>
-Version: v0.1.0 (pre-standard)
-
-OpenAPI extension declaring which existing REST endpoints agents should call. Published at \`/agents.json\` or \`/.well-known/agents.json\`. Drives C6.
-
-## agent-permissions.json
-
-Discovery path: \`/.well-known/agent-permissions.json\` (preferred) or \`/agent-permissions.json\`
-
-A manifest declaring per-path agent access policies. Drives C7.
-
-## UCP \u2014 Unified Capability Profile
-
-Discovery path: \`/.well-known/ucp\`
-
-A composite profile that bundles OAuth authorization server metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) with capability declarations. Drives C8 (profile exists) and C9 (OAuth Authorization Server metadata, gated on C8).
-
-## x402 \u2014 HTTP 402 Payment Required
-
-Reference: <https://www.x402.org>
-
-Behavioural rather than manifest-based. Agent Ready probes the scanned URL preserving its path; if the response is HTTP 402 with valid \`accepts\` entries, C10 and C11 pass. Otherwise both drop.
-
-## NLWeb
-
-Canonical: <https://nlweb.ai/docs/specification>
-
-An open natural-language query protocol: a site exposes \`POST /ask\` returning Schema.org-typed JSON, and every NLWeb instance is also an MCP server. NLWeb has no discovery standard, so detection is heuristic \u2014 Agent Ready does a low-aggression GET to the conventional \`/ask\` path and correlates with the MCP server card. Drives C12 (best-effort NLWeb endpoint detection, informational).
+- **NLWeb** \u2014 An open natural-language query protocol: a site exposes POST /ask returning Schema.org-typed JSON. Detection is heuristic and informational. Canonical: <https://nlweb.ai/docs/specification> Checks: C12.
+- **API Catalog (RFC 9727)** \u2014 A /.well-known/api-catalog linkset advertising a site's APIs so agents can enumerate them from one well-known entry point. Canonical: <https://www.rfc-editor.org/info/rfc9727> Checks: C13.
+- **Web Bot Auth** _(pre-standard)_ \u2014 An HTTP message-signatures directory at /.well-known/http-message-signatures-directory letting well-behaved bots prove their identity. IETF draft. Canonical: <https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/> Checks: C14.
+- **Agent Skills Discovery** _(pre-standard)_ \u2014 A /.well-known/agent-skills/index.json manifest advertising installable agent skills. Pre-standard (Cloudflare RFC v0.2.0). Canonical: <https://github.com/cloudflare/agent-skills-discovery> Checks: C15.
+- **Content parity (anti-cloaking)** _(behavioural)_ \u2014 Not a published spec \u2014 a behavioural check comparing the AI-bot response to the baseline to detect cloaking (serving agents different content than humans). Canonical: _none published_ Checks: C16.
+- **Agent-driven UI (A2UI)** _(pre-standard)_ \u2014 MCP-Apps / OpenAI Apps SDK UI surfaces declared on an MCP Server Card, letting agents render interactive widgets inline. Emerging. Canonical: <https://modelcontextprotocol.io> Checks: C17.
 `;
 
 // src/resources.ts
@@ -31406,7 +31387,7 @@ function registerResources(server) {
     "agent-ready://methodology",
     {
       title: "Scoring methodology",
-      description: "How Agent Ready computes the 0\u2013100 readability score and the llms.txt sub-score. Covers the 60 checks across four categories, rating bands, weighting, and JS-rendering handling.",
+      description: "How Agent Ready computes the 0\u2013100 readability score and the llms.txt sub-score. Covers the 68 checks across four categories, rating bands, weighting, and JS-rendering handling.",
       mimeType: "text/markdown"
     },
     async () => ({
@@ -31424,7 +31405,7 @@ function registerResources(server) {
     "agent-ready://checks",
     {
       title: "Check registry",
-      description: "Reference table of all 60 checks Agent Ready runs, grouped by category (site, page, llms.txt, protocol). Each row pairs the stable check ID (e.g. P11, S15, L9, C3) with its human-readable name. Use this to identify a check by id when interpreting scan results.",
+      description: "Reference table of all 68 checks Agent Ready runs, grouped by category (site, page, llms.txt, protocol). Each row pairs the stable check ID (e.g. P11, S15, L9, C3) with its human-readable name. Use this to identify a check by id when interpreting scan results.",
       mimeType: "text/markdown"
     },
     async () => ({
@@ -31460,7 +31441,7 @@ function registerResources(server) {
     "agent-ready://specs",
     {
       title: "Specifications Agent Ready validates against",
-      description: "Canonical URLs and check-ID mappings for the specifications Agent Ready implements: Vercel Agent Readability Spec, llmstxt.org, MCP Server Cards (SEP-1649 / RFC 9728), A2A Agent Cards (a2a.proto v1.0.0), Wildcard agents.json, agent-permissions.json, UCP (RFC 8414), x402 Payment Required, and NLWeb.",
+      description: "Canonical URLs and check-ID mappings for the specifications Agent Ready implements: Vercel Agent Readability Spec, llmstxt.org, MCP Server Cards (SEP-1649 / RFC 9728), A2A Agent Cards (a2a.proto v1.0.0), Wildcard agents.json, agent-permissions.json, UCP (RFC 8414), x402 and MPP payments, NLWeb, API Catalog (RFC 9727), Web Bot Auth, Agent Skills Discovery, content parity, and Agent-driven UI (A2UI).",
       mimeType: "text/markdown"
     },
     async () => ({
@@ -31529,22 +31510,22 @@ async function scanSite(config2, input) {
       throw err;
     }
     if (last && last.status && last.status !== "running") {
-      return { content: [{ type: "text", text: JSON.stringify(last) }] };
+      return {
+        content: [{ type: "text", text: JSON.stringify(last) }],
+        structuredContent: last
+      };
     }
   }
+  const running = {
+    id: placeholder.id,
+    status: "running",
+    url: input.url,
+    pollUrl: placeholder.pollUrl ?? `/api/v1/scans/${placeholder.id}`,
+    message: "Scan still running after the local poll deadline. Call get_scan with this id to fetch the final result."
+  };
   return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify({
-          id: placeholder.id,
-          status: "running",
-          url: input.url,
-          pollUrl: placeholder.pollUrl ?? `/api/v1/scans/${placeholder.id}`,
-          message: "Scan still running after the local poll deadline. Call get_scan with this id to fetch the final result."
-        })
-      }
-    ]
+    content: [{ type: "text", text: JSON.stringify(running) }],
+    structuredContent: running
   };
 }
 
@@ -31552,7 +31533,10 @@ async function scanSite(config2, input) {
 async function getScanById(config2, input) {
   try {
     const scan = await getScanFromApi(config2, input.id);
-    return { content: [{ type: "text", text: JSON.stringify(scan) }] };
+    return {
+      content: [{ type: "text", text: JSON.stringify(scan) }],
+      structuredContent: scan
+    };
   } catch (err) {
     if (err instanceof ApiError) {
       if (err.status === 404) {
@@ -31568,7 +31552,10 @@ async function getScanById(config2, input) {
 async function askQuery(config2, input) {
   try {
     const envelope = await postAsk(config2, input);
-    return { content: [{ type: "text", text: JSON.stringify(envelope) }] };
+    return {
+      content: [{ type: "text", text: JSON.stringify(envelope) }],
+      structuredContent: envelope && typeof envelope === "object" ? envelope : {}
+    };
   } catch (err) {
     if (err instanceof ApiError) {
       throw new ToolError(err.code, err.message);
@@ -31577,6 +31564,62 @@ async function askQuery(config2, input) {
   }
 }
 
+// src/output.ts
+var checkResult = external_exports.object({
+  checkId: external_exports.string(),
+  name: external_exports.string(),
+  status: external_exports.enum(["pass", "fail", "warn", "error"]),
+  message: external_exports.string(),
+  howToFix: external_exports.string().nullable(),
+  details: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
+var pageResult = external_exports.object({
+  url: external_exports.string(),
+  checks: external_exports.array(checkResult)
+});
+var scanOutputShape = {
+  id: external_exports.string(),
+  status: external_exports.enum(["running", "completed", "failed"]),
+  rootUrl: external_exports.string().optional(),
+  createdAt: external_exports.string().optional(),
+  completedAt: external_exports.string().nullable().optional(),
+  pagesDiscovered: external_exports.number().optional(),
+  pagesScanned: external_exports.number().optional(),
+  vercelScore: external_exports.number().optional(),
+  vercelRating: external_exports.string().optional(),
+  llmstxtScore: external_exports.number().optional(),
+  siteChecks: external_exports.array(checkResult).optional(),
+  llmstxtChecks: external_exports.array(checkResult).optional(),
+  pageResults: external_exports.array(pageResult).optional(),
+  shareToken: external_exports.string().optional(),
+  // Present only on the running placeholder, not on a full Scan.
+  url: external_exports.string().optional(),
+  pollUrl: external_exports.string().optional(),
+  message: external_exports.string().optional()
+};
+var askResult = external_exports.object({
+  url: external_exports.string().optional(),
+  name: external_exports.string().optional(),
+  site: external_exports.string().optional(),
+  score: external_exports.number().optional(),
+  description: external_exports.string().optional(),
+  schema_object: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
+});
+var askOutputShape = {
+  _meta: external_exports.object({
+    response_type: external_exports.string(),
+    version: external_exports.string().optional(),
+    mode: external_exports.string().optional()
+  }).optional(),
+  query_id: external_exports.string().optional(),
+  site: external_exports.string().optional(),
+  mode: external_exports.string().optional(),
+  query: external_exports.string().optional(),
+  results: external_exports.array(askResult).optional(),
+  summary: external_exports.string().optional(),
+  error: external_exports.object({ code: external_exports.string(), message: external_exports.string() }).optional()
+};
+
 // src/types.ts
 var scanSiteInputShape = {
   url: external_exports.string().url().max(2e3).describe("Fully-qualified URL to scan, including scheme (https://...)."),
@@ -31600,7 +31643,7 @@ var askInputShape = {
 // src/server.ts
 var SERVER_INFO = {
   name: "agent-ready",
-  version: "0.3.0"
+  version: "0.4.0"
 };
 function createMcpServer(config2) {
   const server = new McpServer(SERVER_INFO);
@@ -31616,6 +31659,7 @@ function createMcpServer(config2) {
       title: "Scan a site for AI agent readability",
       description: "Runs the agent-ready.dev scanner against a URL and returns structured results: Vercel score, llmstxt.org score, and per-check findings with remediation hints. Scans may take up to ~60s; if the local poll deadline elapses, the tool returns the scan id and asks you to poll with get_scan.",
       inputSchema: scanSiteInputShape,
+      outputSchema: scanOutputShape,
       annotations: READ_ONLY_OPEN_WORLD
     },
     async (args) => {
@@ -31632,6 +31676,7 @@ function createMcpServer(config2) {
       title: "Get a previous scan by id",
       description: "Fetches a completed or in-progress scan by its id. Only scans owned by the authenticated API key's user are returned.",
       inputSchema: getScanInputShape,
+      outputSchema: scanOutputShape,
       annotations: READ_ONLY_OPEN_WORLD
     },
     async (args) => {
@@ -31648,6 +31693,7 @@ function createMcpServer(config2) {
       title: "Ask Agent Ready in natural language",
       description: "Natural-language search (NLWeb /ask) over Agent Ready's own content \u2014 scoring methodology, the check registry, and the specs it validates. Public, no API key required. Returns Schema.org-typed result objects; optional itemType narrows to a corpus type and mode 'summarize' adds an extractive summary.",
       inputSchema: askInputShape,
+      outputSchema: askOutputShape,
       annotations: READ_ONLY_OPEN_WORLD
     },
     async (args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-ready-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "mcpName": "io.github.mlava/agent-ready-mcp",
   "description": "MCP server for Agent Ready — scan any URL for AI-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). 60 checks with per-check fix guidance.",
   "license": "MIT",