# aso-mcp — the free Agent Readiness Scanner

[![M8ven Verified](https://m8ven.ai/badge/mcp/forgemeshlabs-aso-audit-mcp-1af1t6?variant=verified)](https://m8ven.ai/mcp/forgemeshlabs-aso-audit-mcp-1af1t6)

**What's your ASO score?**

SEO made you visible to search engines. **ASO (Agent Signal Optimization)** makes you discoverable, trustable, and payable by the AI agents that are becoming the web's next visitors.

`aso-mcp` is the free, open-source **ASO Scanner** — an [MCP](https://modelcontextprotocol.io) server that scans any website and produces an **Agent Readiness Report** scored on the open [ASO framework](https://agentsignaloptimization.com). The beta npm package is `@forgemeshlabs/aso-audit-mcp`.

This release tracks Google's current agent-readiness guidance without overstating it: Google Search says traditional SEO fundamentals still apply to generative AI search, `llms.txt` is ignored by Google Search itself, and browser agents benefit from clean DOM, screenshot, and accessibility-tree signals. The scanner keeps `llms.txt` because non-Google agents use it, and adds a browser-agent UX check for semantic controls, linked labels, ARIA/role fallbacks, and hidden-overlay risk.

> **Beta.** Experimental ASO scanner for evaluating whether agents can discover, trust, understand, and use a website/API/tool. ASO scoring is experimental and will evolve as agent standards mature.

```
=== Agent Readiness Report: https://example.com ===
ASO Score: 70/100
Agent Readiness: Ready
Level: ASO-4 Trustable — Agents can verify trust, reputation, and operational signals.

Discoverability  20/20    Identity  15/20    Trust   11/15
Commerce          5/15    Reputation 4/15    Memory  15/15
```

## What it checks — 34 signals across 6 pillars

Find gaps in **discovery, trust, interoperability, and commerce** — every emerging agent standard in one scan:

| Pillar / Category | Checks |
|---|---|
| **Discovery** | robots.txt, sitemap.xml, Link headers, DNS-AID (`_agent.<domain>`), `/.well-known/ai` |
| **Content** | Markdown content negotiation, llms.txt, LLM-readable docs (`/index.md`, `llms-full.txt`) |
| **Bot Access** | Explicit AI crawler rules (GPTBot, ClaudeBot, Google-Extended, PerplexityBot…), Content Signals, Web Bot Auth |
| **Interoperability** | API Catalog (RFC 9727), OAuth discovery (RFC 8414), OAuth Protected Resource (RFC 9728), auth.md, **MCP Server Card** (`/.well-known/mcp/server-card.json`), **Google A2A Agent Card** (`/.well-known/agent-card.json`, required fields validated), Agent Skills, WebMCP |
| **Commerce** | x402, MPP, UCP, ACP, machine-readable pricing |
| **Identity & Trust** | HTTPS enforcement, JSON-LD/schema.org, agent-friendly browser UX, OpenAPI, agent.json, security.txt, status endpoint, versioning, cross-file identity & signal consistency |

## Deterministic x402 v2 endpoint audit

The MCP tool `audit_x402_endpoint` complements the origin-wide ASO scan with a
no-spend protocol audit of one paid endpoint. It returns a 0-100 score, A-F
grade, compliance verdict, per-check booleans, failed checks, and observed
schemes/networks/extensions. It validates the live 402 challenge but never
sends `PAYMENT-SIGNATURE`, so it cannot authorize or settle a payment.

Checks: HTTPS/TLS, HTTP 402, `PAYMENT-REQUIRED`, Base64 JSON, `x402Version: 2`,
non-empty `accepts`, CAIP-2 networks, required payment fields, and JSON content
type. For body-gated routes, pass `method`, `body`, and optionally
`content_type`.

This is deliberately reported separately from the ASO Score: protocol
compliance does not prove discoverability, trust, settlement, idempotency, or
paid-response quality.

## Living standards model

Agent protocols are changing quickly. The scanner is maintained as part of a
living framework: checks are versioned, and stable standards, optional
capabilities, release candidates, drafts, and vendor conventions are labeled
separately. See the dated [scanner source list](SOURCES.md) and the canonical
[ASO source registry](https://agentsignaloptimization.com/SOURCES.md).

Every check returns **pass / partial / fail** with concrete evidence and a fix recommendation. Results roll up into the six ASO pillars (Discoverability 20, Identity 20, Trust 15, Commerce 15, Reputation 15, Memory 15) → your **ASO Score** and maturity level.

## Install

Requires Node.js ≥ 18. Published on npm as [`@forgemeshlabs/aso-audit-mcp`](https://www.npmjs.com/package/@forgemeshlabs/aso-audit-mcp) — no clone or build needed.

```bash
npm install -g @forgemeshlabs/aso-audit-mcp
```

Or skip the install entirely and run it with `npx` (recommended for MCP clients):

```bash
npx -y @forgemeshlabs/aso-audit-mcp
```

### Claude Code

```bash
claude mcp add aso -- npx -y @forgemeshlabs/aso-audit-mcp
```

### Claude Desktop / Cursor / Windsurf (any MCP client)

```json
{
  "mcpServers": {
    "aso": {
      "command": "npx",
      "args": ["-y", "@forgemeshlabs/aso-audit-mcp"]
    }
  }
}
```

### Development (from source)

Only needed if you're hacking on the scanner itself:

```bash
git clone https://github.com/forgemeshlabs/aso-audit-mcp
cd aso-audit-mcp
npm install && npm run build
claude mcp add aso -- node /path/to/aso-audit-mcp/dist/index.js
```

## Tools

| Tool | What it does |
|---|---|
| `scan_site` | Full ASO scan → Agent Readiness Report: ASO Score, level, pillar breakdown, all 34 checks with evidence + recommendations |
| `get_fix_plan` | Prioritized remediation plan with ready-to-paste templates (robots.txt AI rules, llms.txt, agent.json, A2A agent card, MCP server card, x402 manifest, pricing.json, security.txt, status endpoint) |
| `check_signal` | Run one specific check (e.g. `a2a-agent-card`, `llms-txt`, `x402`) |
| `list_checks` | Catalog of every check with spec links |
| `get_aso_framework` | The ASO rubric: pillars, weights, levels, certification thresholds |

Try it: *"Scan example.com for agent readiness"* · *"What's my ASO score?"* · *"Give me a fix plan to make my site agent-ready."*

### CLI smoke test (from a source checkout)

```bash
npm run smoke -- https://your-site.com
```

## Glama / registry metadata

This repository includes `glama.json` for Glama MCP registry ownership and install metadata.

- **Package:** `@forgemeshlabs/aso-audit-mcp`
- **Current release:** `v0.2.0`
- **Transport:** local `stdio`
- **Authentication:** none required for local `stdio` use. The scanner does not ask for API keys, tokens, cookies, or third-party credentials.
- **HTTP deployment:** not enabled by this npm package. Any public HTTP deployment of this scanner must add authentication, per-client rate limits, request logging, and an egress policy before exposure.

Recommended Glama/MCP install command:

```bash
npx -y @forgemeshlabs/aso-audit-mcp
```

Example usage after connecting the server to an MCP client:

```text
Scan https://example.com for agent readiness.
Give me the ASO fix plan for example.com.
Check only the llms-txt signal for example.com.
List the ASO scanner checks.
```

Release verification:

- Git tag: `v0.2.0`
- npm package: `@forgemeshlabs/aso-audit-mcp`
- MCP server version: `0.2.0`

`v0.2.0` adds the deterministic no-spend x402 v2 endpoint compliance audit while preserving the broader ASO Agent Readiness score as a separate metric.

### Glama release build

Glama installability requires a **Glama release**, which is a containerized build created from the Glama Dockerfile admin page, not a GitHub release. This repo includes a production `Dockerfile` and [GLAMA.md](GLAMA.md) with the build spec values to use in Glama:

Build steps:

```text
npm ci
npm run build
npm prune --omit=dev
```

Runtime command:

```bash
node dist/index.js
```

In Glama's **CMD arguments** field, enter:

```json
["node", "dist/index.js"]
```

Do not leave CMD arguments as `[]`; Glama validates that field separately from the Dockerfile `CMD`.

## The ASO framework

> SEO ranks pages for people. ASO prepares services for agent selection, invocation, payment, and repeat use.

| Level | Name | Score |
|---|---|---|
| ASO-0 | Invisible | 0–9 |
| ASO-1 | Discoverable | 10–29 |
| ASO-2 | Understandable | 30–49 |
| ASO-3 | Invocable | 50–69 |
| ASO-4 | Trustable | 70–89 |
| ASO-5 | Autonomous-Commerce-Ready | 90–100 |

Scores from this scanner are directional self-assessments. **ASO Certification** (ASO-3+) requires verified evidence — see the [scoring rubric](https://agentsignaloptimization.com/docs/ASO-SCORE.md) and [agentsignaloptimization.com](https://agentsignaloptimization.com) for audits, certification, and the full framework.

## Security

This scanner makes outbound requests to URLs you give it, so it is built to resist SSRF abuse:

- **Scheme allow-list** — only `http`/`https`; `file:`, `ftp:`, `gopher:`, `data:` etc. are rejected.
- **Private-target blocking** — after DNS resolution, requests to loopback, private (RFC 1918), link-local, CGNAT, reserved, multicast, and the cloud metadata address (`169.254.169.254`) are refused. IPv6 loopback/ULA/link-local and IPv4-mapped forms are covered too. If a hostname resolves to *any* private address, the scan is refused.
- **Pinned-IP transport** — each request dials the exact public IP that was validated, while TLS still verifies the original hostname. This closes the validate-then-connect DNS rebinding window.
- **Manual redirect validation** — automatic redirect following is disabled; every hop is re-validated against the same rules, capped at 5 redirects. A public URL that 30x-redirects to an internal address cannot slip through.
- **Untrusted remote content** — parsed manifests are omitted from tool output by default (`include_artifacts: true` to opt in, and they are then explicitly labeled untrusted); embedded text excerpts are control-char-sanitized and length-capped. Treat any returned remote content as data, never instructions.
- **Bounded** — `GET` only, `ASO-Scanner/1.0` UA, max 6 concurrent, 10s timeout, 512KB body cap. Never authenticates, never POSTs, never crawls beyond well-known paths.
- **Tested hardening** — `npm test` covers unsafe URL rejection, private IP ranges, artifact sanitization, redirect blocking, redirect hop caps, and the test-only loopback escape hatch.

**Deployment:** `stdio` (local, per-user) is the safe default. A public **HTTP** deployment is a network-egress tool and **must** add authentication, per-client rate limiting, request logging, and an egress policy before exposure.
- Reputation signals (citations, reviews, success rates) cannot be auto-verified by a crawler; they are reported as `manual` and scored 0 until verified by audit — so the auto-verifiable maximum is 89/100. That is intentional honesty, not a bug.
- Emerging specs (MCP Server Cards SEP-1649/SEP-2127, DNS-AID, Web Bot Auth, UCP/ACP/MPP) move fast. PRs updating paths welcome.

## Source alignment

This package intentionally separates Google Search guidance from broader ASO guidance:

- Google Search generative AI features still rely on core Search ranking and quality systems; foundational SEO, crawlability, helpful content, and technical clarity remain the priority.
- Google Search does not use `llms.txt` or special AI markdown files for ranking or AI Overviews/AI Mode visibility. ASO still checks them because other agents and MCP clients can use them.
- Google/web.dev's agent-friendly site guidance focuses on browser-agent usability: stable layouts, semantic HTML, labels tied to inputs, meaningful roles/names/states, and avoiding hidden overlays.
- UCP, AP2, A2A, MCP, x402, DNS-AID, Content Signals, and Web Bot Auth are emerging non-SEO protocols. The scanner treats them as agent-readiness signals, not as Google Search ranking factors.

Primary references:

- https://developers.google.com/search/docs/fundamentals/ai-optimization-guide
- https://web.dev/articles/ai-agent-site-ux
- https://ucp.dev

## License

MIT — free for everyone. If the scanner found gaps, the [ASO framework](https://agentsignaloptimization.com) shows you how to close them.