agent-ready-mcp 0.2.0 → 0.4.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

@@ -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) {
@@ -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;
@@ -31136,7 +31181,7 @@ Skip checks that already pass.`
 // src/resource-content.ts
 var METHODOLOGY_MD = `# How Agent Ready scores a site
 
-> 59 checks across four categories, mapped to the Vercel Agent Readability Spec and the llmstxt.org standard. Every check is open and reproducible.
+> 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?
 
@@ -31173,7 +31218,7 @@ Full guide: <https://agent-ready.dev/methodology>
 `;
 var CHECKS_MD = `# Agent Ready check registry
 
-> 59 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.
+> 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)
 
@@ -31244,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 (11)
+## 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.
 
@@ -31261,10 +31306,11 @@ Discover-then-validate: when the relevant well-known endpoint returns 404, the c
 | 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 59 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 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.
 
@@ -31293,7 +31339,7 @@ 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 59 checks map to seven specifications. Each entry below links to the canonical document and notes the check IDs that implement it.
+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
 
@@ -31345,6 +31391,12 @@ A composite profile that bundles OAuth authorization server metadata ([RFC 8414]
 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
@@ -31354,7 +31406,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 59 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 60 checks across four categories, rating bands, weighting, and JS-rendering handling.",
       mimeType: "text/markdown"
     },
     async () => ({
@@ -31372,7 +31424,7 @@ function registerResources(server) {
     "agent-ready://checks",
     {
       title: "Check registry",
-      description: "Reference table of all 59 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 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 () => ({
@@ -31408,7 +31460,7 @@ function registerResources(server) {
     "agent-ready://specs",
     {
       title: "Specifications Agent Ready validates against",
-      description: "Canonical URLs and check-ID mappings for the seven 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), and x402 Payment Required.",
+      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 () => ({
@@ -31477,22 +31529,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
   };
 }
 
@@ -31500,7 +31552,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) {
@@ -31512,6 +31567,78 @@ 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) }],
+      structuredContent: envelope && typeof envelope === "object" ? envelope : {}
+    };
+  } catch (err) {
+    if (err instanceof ApiError) {
+      throw new ToolError(err.code, err.message);
+    }
+    throw err;
+  }
+}
+
+// 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://...)."),
@@ -31524,11 +31651,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.2.0"
+  version: "0.4.0"
 };
 function createMcpServer(config2) {
   const server = new McpServer(SERVER_INFO);
@@ -31544,6 +31678,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) => {
@@ -31560,6 +31695,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) => {
@@ -31570,6 +31706,23 @@ 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,
+      outputSchema: askOutputShape,
+      annotations: READ_ONLY_OPEN_WORLD
+    },
+    async (args) => {
+      try {
+        return await askQuery(config2, args);
+      } catch (err) {
+        return toolErrorToContent(err);
+      }
+    }
+  );
   registerPrompts(server);
   registerResources(server);
   return server;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "agent-ready-mcp",
-  "version": "0.2.0",
+  "version": "0.4.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.