agent-ready-mcp 0.1.1 → 0.2.0

package/README.md

@@ -124,6 +124,30 @@ 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](https://registry.modelcontextprotocol.io) via GitHub OIDC.
+
+To cut a release:
+
+```bash
+# 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](LICENSE).

package/dist/mcp-server.mjs

@@ -31133,6 +31133,296 @@ 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.
+
+## 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
+
+> 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.
+
+## 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 (11)
+
+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 |
+`;
+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.
+
+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 59 checks map to seven specifications. Each entry below 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.
+`;
+
+// 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 59 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 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.",
+      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 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.",
+      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) {
@@ -31238,7 +31528,7 @@ var getScanInputShape = {
 // src/server.ts
 var SERVER_INFO = {
   name: "agent-ready",
-  version: "0.1.1"
+  version: "0.2.0"
 };
 function createMcpServer(config2) {
   const server = new McpServer(SERVER_INFO);
@@ -31281,6 +31571,7 @@ function createMcpServer(config2) {
     }
   );
   registerPrompts(server);
+  registerResources(server);
   return server;
 }
 function toolErrorToContent(err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-ready-mcp",
-  "version": "0.1.1",
+  "version": "0.2.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.",
   "license": "MIT",