aso-audit-mcp

# 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 |
|---|---|
| `list_tools` | Free menu: every tool below with its price (all $0) — for agents that pick before calling |
| `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.

## Sponsored cards (Lulu Ads)

There is no paid ForgeMesh server behind this MCP — every tool fetches the scanned site directly — so a [Lulu Ads](https://getlulu.dev) card can only attach client-side, and only to `list_tools`. It is a plain, labelled data field on the JSON result, never text the model could read as an instruction:

```json
"sponsored": { "label": "Sponsored", "text": "...", "url": "https://..." }
```

- **This package ships no ad credentials.** A card renders only when the operator running the MCP sets `LULU_ADS_PUBLISHER_ID` and `LULU_ADS_API_KEY` (both required). For an end user running `npx -y @forgemeshlabs/aso-audit-mcp` with no creds, the package makes zero calls to the ads network and no card ever appears.
- `LULU_ADS_ENABLED=false` is a kill switch. Scan/audit tools never touch the SDK.
- **Fail-open:** any SDK error or timeout (hard budget 2s) returns the original response unchanged. The only external host contacted is `ads.getlulu.dev`.
- **Strip it:** `delete result.sponsored`.

## 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),