agent-ready-mcp 0.1.2 → 0.3.0

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). 59 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). 60 checks 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).
 
@@ -8,6 +8,7 @@ Hosted at `https://agent-ready.dev/api/v1/mcp` (Streamable HTTP); this package i
 
 - **`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.
 - **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.
 
@@ -74,6 +75,7 @@ claude mcp add agent-ready \
 |---|---|---|
 | `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. |
 
 ## Prompts
 
@@ -113,7 +115,7 @@ If you'd rather use the hosted MCP server directly (Streamable HTTP transport, n
 
 ## Methodology
 
-The 59 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 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).
 
 ## Development
 

package/dist/mcp-server.mjs

@@ -23108,6 +23108,51 @@ async function getScanFromApi(config2, id) {
     timeoutMs: config2.getTimeoutMs
   });
 }
+async function postAsk(config2, body) {
+  const url2 = `${config2.baseUrl}/api/v1/ask`;
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json"
+  };
+  if (config2.apiKey) headers.Authorization = `Bearer ${config2.apiKey}`;
+  const payloadBody = {
+    query: { q: body.q, itemType: body.itemType },
+    prefer: body.mode ? { mode: body.mode } : void 0
+  };
+  let res;
+  try {
+    res = await fetch(url2, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payloadBody),
+      signal: AbortSignal.timeout(config2.getTimeoutMs)
+    });
+  } catch (err) {
+    if (err instanceof Error && err.name === "TimeoutError") {
+      throw new ApiError(
+        "timeout",
+        `Request to /api/v1/ask timed out after ${config2.getTimeoutMs}ms.`
+      );
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ApiError("network_error", `Network error calling /api/v1/ask: ${message}`);
+  }
+  const text = await res.text();
+  let payload = null;
+  if (text.length > 0) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+    }
+  }
+  if (payload && typeof payload === "object" && "_meta" in payload) {
+    return payload;
+  }
+  if (!res.ok) {
+    throw new ApiError(`http_${res.status}`, text || `HTTP ${res.status}`, res.status);
+  }
+  return payload;
+}
 
 // node_modules/zod/v3/helpers/util.js
 var util;
@@ -31133,6 +31178,303 @@ 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.
+
+## What does Agent Ready measure?
+
+Agent Ready is an independent validator for the [Vercel Agent Readability Spec](https://vercel.com/kb/guide/agent-readability-spec) and the [llmstxt.org standard](https://llmstxt.org). The score reports how well your site exposes itself to AI agents and LLM-based clients \u2014 the same way a Lighthouse score reports how well your site performs for human users. We fetch your URL once, fan out to the discovery files and well-known endpoints AI agents probe, and grade the result.
+
+## How is the score calculated?
+
+Two scores are reported: an overall agent readability score (0\u2013100) and an llms.txt sub-score (0\u2013100).
+
+The overall score is a simple percentage: count of passing checks divided by total checks, rounded. Warns and fails both count against you; \`pass\` is the only state that earns credit. Checks marked \`unreliable\` by the JS-rendering check (P23) are excluded entirely so a single architectural choice doesn't penalise four dependent checks at once.
+
+Rating bands:
+
+| Score | Rating | Meaning |
+|---|---|---|
+| 90\u2013100 | excellent | Ready for AI citation; all critical surfaces present. |
+| 70\u201389 | good | Discoverable, but a few extractability gaps. |
+| 50\u201369 | fair | Partial coverage; multiple required surfaces missing. |
+| 0\u201349 | needs improvement | Not yet AI-readable; start with llms.txt and AGENTS.md. |
+
+## Why is the llms.txt sub-score weighted differently?
+
+The llmstxt.org spec treats some properties as foundational and others as optional. We mirror that with weights: structural checks (file accessible, H1 present, valid markdown) count 3\xD7, content checks count 1\xD7, and the optional \`llms-full.txt\` presence check counts 0.5\xD7. The overall score is unweighted because every check on the Vercel spec is equally normative; the llmstxt.org spec is explicitly layered.
+
+## How are JavaScript-rendered pages handled?
+
+P23 detects pages where the static HTML response lacks data that only appears after client-side rendering \u2014 missing H1, empty body text, JSON-LD that injects after hydration. When P23 fires, the runner marks dependent checks (P10, P11, P12, P14) as \`unreliable\` and the scorer excludes them from both numerator and denominator. Without this, a single SPA architecture choice would compound into a 4-point score drop across unrelated checks.
+
+## Where is the source for each check?
+
+Every check is implemented as a single function in \`src/lib/checks/{site,page,llmstxt,protocol}/\`. The naming convention is \`{id}-{slug}.ts\` (e.g. \`p11-json-ld-fields.ts\`). Each file exports a check definition; the registry collects them into a single array that the runner iterates. One check per file \u2014 read the source to see exactly what is being asserted.
+
+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.
+
+## Site checks (15)
+
+Run once per scan against the root URL. Cover discovery files (\`llms.txt\`, \`robots.txt\`, \`sitemap.xml\`, \`AGENTS.md\`), HTTPS, and the OpenAPI spec probe.
+
+| ID | Check |
+|---|---|
+| S1 | llms.txt exists |
+| S2 | llms.txt Content-Type |
+| S3 | llms.txt not empty |
+| S4 | llms.txt URL format |
+| S5 | robots.txt \u2014 AI bots allowed |
+| S6 | robots.txt \u2014 /llms.txt not blocked |
+| S7 | robots.txt exists |
+| S8 | sitemap.xml valid |
+| S9 | sitemap.xml has lastmod |
+| S10 | sitemap.md exists |
+| S11 | sitemap.md has headings + links |
+| S12 | AGENTS.md exists |
+| S13 | AGENTS.md has required sections |
+| S14 | HTTPS |
+| S15 | Root OpenAPI spec |
+
+## Page checks (23)
+
+Run against every URL fetched in the scan. Cover HTTP semantics, metadata, JSON-LD, markdown mirrors, content negotiation, code-block language tags, and JS-rendering dependency.
+
+| ID | Check |
+|---|---|
+| P1 | HTTP 200 |
+| P2 | Redirect chain |
+| P3 | Content-Type header |
+| P4 | x-robots-tag |
+| P5 | Canonical link |
+| P6 | Meta description |
+| P7 | og:title |
+| P8 | og:description |
+| P9 | HTML lang attribute |
+| P10 | JSON-LD present |
+| P11 | JSON-LD has required fields |
+| P12 | Section headings |
+| P13 | Text-to-HTML ratio |
+| P14 | Glossary link |
+| P15 | Markdown mirror exists |
+| P16 | Markdown frontmatter |
+| P17 | Alternate link (markdown) |
+| P18 | Link header in markdown |
+| P19 | Content negotiation |
+| P20 | Sitemap section in markdown |
+| P21 | Code block language tags |
+| P22 | API schema link |
+| P23 | JS rendering dependency |
+
+## llms.txt checks (10)
+
+Run when the site has an \`llms.txt\` file. Validate against the [llmstxt.org](https://llmstxt.org) specification. Weighted in the llms.txt sub-score: structural 3\xD7, content 1\xD7, \`llms-full.txt\` 0.5\xD7.
+
+| ID | Check |
+|---|---|
+| L1 | File accessible |
+| L2 | H1 present |
+| L3 | Valid markdown |
+| L4 | Blockquote summary |
+| L5 | H2 file-list sections |
+| L6 | Link format correct |
+| L7 | Links are accessible |
+| L8 | Optional section used correctly |
+| L9 | Content-Type: text/plain |
+| L10 | llms-full.txt available |
+
+## Protocol checks (12)
+
+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.
+
+| ID | Check |
+|---|---|
+| C1 | MCP Server Card exists |
+| C2 | MCP Server Card fields |
+| C3 | MCP OAuth Protected Resource metadata |
+| C4 | A2A Agent Card exists |
+| C5 | A2A Agent Card fields |
+| C6 | Wildcard agents.json |
+| C7 | agent-permissions.json |
+| C8 | UCP profile (/.well-known/ucp) |
+| C9 | UCP OAuth Authorization Server metadata |
+| C10 | x402 Payment Required response |
+| C11 | x402 accepts entries |
+| C12 | NLWeb endpoint |
+`;
+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.
+
+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.
+
+## Tools
+
+- Home: <https://agent-ready.dev>
+- Agent Readability Score: <https://agent-ready.dev/agent-readability-score>
+- llms.txt Checker: <https://agent-ready.dev/llms-txt-checker>
+- AGENTS.md Validator: <https://agent-ready.dev/agents-md-validator>
+- MCP Server Card Validator: <https://agent-ready.dev/mcp-card-validator>
+- A2A Agent Card Validator: <https://agent-ready.dev/agent-card-validator>
+- agents.json Validator: <https://agent-ready.dev/agents-json-validator>
+- agent-permissions.json Validator: <https://agent-ready.dev/agent-permissions-validator>
+- UCP Validator: <https://agent-ready.dev/ucp-validator>
+- x402 Checker: <https://agent-ready.dev/x402-checker>
+- API & integrations: <https://agent-ready.dev/docs/api>
+- MCP server install guide: <https://agent-ready.dev/mcp>
+
+## Specs
+
+- Vercel Agent Readability Spec: <https://vercel.com/kb/guide/agent-readability-spec>
+- llmstxt.org: <https://llmstxt.org>
+- Model Context Protocol: <https://modelcontextprotocol.io>
+- A2A Protocol: <https://a2a-protocol.org>
+- Wildcard agents.json: <https://github.com/wild-card-ai/agents-json>
+`;
+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.
+
+## Vercel Agent Readability Spec
+
+Canonical: <https://vercel.com/kb/guide/agent-readability-spec>
+
+Maintained on the Vercel Knowledge Base. Drives the S- (site, 15 checks), P- (page, 23 checks), and most C- (protocol) check series.
+
+## llmstxt.org
+
+Canonical: <https://llmstxt.org>
+
+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.
+
+## Model Context Protocol \u2014 Server Cards (SEP-1649)
+
+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).
+`;
+
+// src/resources.ts
+function registerResources(server) {
+  server.registerResource(
+    "methodology",
+    "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.",
+      mimeType: "text/markdown"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "agent-ready://methodology",
+          mimeType: "text/markdown",
+          text: METHODOLOGY_MD
+        }
+      ]
+    })
+  );
+  server.registerResource(
+    "checks",
+    "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.",
+      mimeType: "text/markdown"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "agent-ready://checks",
+          mimeType: "text/markdown",
+          text: CHECKS_MD
+        }
+      ]
+    })
+  );
+  server.registerResource(
+    "llms-txt",
+    "agent-ready://llms.txt",
+    {
+      title: "Agent Ready's own llms.txt",
+      description: "The /llms.txt file agent-ready.dev publishes for AI agents discovering it as a tool. Mirrors the live document at https://agent-ready.dev/llms.txt. Useful as a worked example for the llms.txt validator and for clients introspecting Agent Ready's surface.",
+      mimeType: "text/markdown"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "agent-ready://llms.txt",
+          mimeType: "text/markdown",
+          text: LLMS_TXT
+        }
+      ]
+    })
+  );
+  server.registerResource(
+    "specs",
+    "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.",
+      mimeType: "text/markdown"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "agent-ready://specs",
+          mimeType: "text/markdown",
+          text: SPECS_MD
+        }
+      ]
+    })
+  );
+}
+
 // src/tools/scanSite.ts
 var ToolError = class extends Error {
   constructor(code, message) {
@@ -31222,6 +31564,19 @@ async function getScanById(config2, input) {
   }
 }
 
+// src/tools/ask.ts
+async function askQuery(config2, input) {
+  try {
+    const envelope = await postAsk(config2, input);
+    return { content: [{ type: "text", text: JSON.stringify(envelope) }] };
+  } catch (err) {
+    if (err instanceof ApiError) {
+      throw new ToolError(err.code, err.message);
+    }
+    throw err;
+  }
+}
+
 // src/types.ts
 var scanSiteInputShape = {
   url: external_exports.string().url().max(2e3).describe("Fully-qualified URL to scan, including scheme (https://...)."),
@@ -31234,11 +31589,18 @@ var getScanInputShape = {
     "Scan id returned by a previous scan_site call (10-character nanoid)."
   )
 };
+var askInputShape = {
+  q: external_exports.string().min(1).max(2e3).describe(
+    "Natural-language question about Agent Ready's scoring methodology, its check registry, or the specs it validates."
+  ),
+  itemType: external_exports.enum(["methodology", "checks", "specs", "llms-txt", "check", "any"]).optional().describe("Optional filter narrowing the search to one corpus type."),
+  mode: external_exports.enum(["list", "summarize"]).optional().describe("'summarize' adds an extractive summary over the top results.")
+};
 
 // src/server.ts
 var SERVER_INFO = {
   name: "agent-ready",
-  version: "0.1.2"
+  version: "0.3.0"
 };
 function createMcpServer(config2) {
   const server = new McpServer(SERVER_INFO);
@@ -31280,7 +31642,24 @@ function createMcpServer(config2) {
       }
     }
   );
+  server.registerTool(
+    "ask",
+    {
+      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,
+      annotations: READ_ONLY_OPEN_WORLD
+    },
+    async (args) => {
+      try {
+        return await askQuery(config2, args);
+      } catch (err) {
+        return toolErrorToContent(err);
+      }
+    }
+  );
   registerPrompts(server);
+  registerResources(server);
   return server;
 }
 function toolErrorToContent(err) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "agent-ready-mcp",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "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). 59 checks with per-check fix guidance.",
+  "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",
   "author": "Agent Ready",
   "repository": {

package/skills/agent-ready/SKILL.md

@@ -67,7 +67,7 @@ When grouping or filtering, use the check-id prefix:
 - **S1–S15** — site-wide checks (run once per scan): llms.txt, robots.txt, sitemap.xml, sitemap.md, AGENTS.md, HTTPS, OpenAPI
 - **P1–P23** — per-page checks (run on every fetched URL): HTTP semantics, metadata, JSON-LD, markdown mirrors, content negotiation, code-block language, JS-rendering dependency
 - **L1–L10** — llms.txt content checks (run when llms.txt exists): structure, link format, content-type, llms-full.txt companion
-- **C1–C11** — agent-protocol checks (run when the relevant `/.well-known` endpoint exists): MCP server cards, A2A agent cards, agents.json, agent-permissions.json, UCP, x402
+- **C1–C12** — agent-protocol checks (run when the relevant endpoint exists): MCP server cards, A2A agent cards, agents.json, agent-permissions.json, UCP, x402, NLWeb (`/ask`)
 
 C-series checks follow a discover-then-validate pattern: missing endpoints drop the check rather than failing it. Don't report a missing C-check as a problem unless the user explicitly wants that protocol.