agent-aso

Agent Search Optimization (ASO) CLI. Make products, APIs, and tools discoverable, evaluable, and callable by autonomous AI agents.

agent-aso is the open-source command-line tool for ASO — the discipline of optimizing for the agent's tool-selection and invocation pipeline, not for human readers (SEO) or for LLM-generated answers consumed by humans (GEO).

SEO   →  optimize for Google   →  human reads search result
GEO   →  optimize for LLM      →  human reads AI answer
ASO   →  optimize for agent    →  agent invokes the tool

See SPEC.md for the full specification.

Status

v1.0 — feature-complete across audit + generate + submit + simulate + monitor.

All commands are implemented as thin wrappers over upstream OSS — no first-party validation, parsing, or model-orchestration logic. The composite aso audit site reports findings grouped by Discoverability / Evaluability / Actionability. aso monitor diffs against a cached prior run for drift detection.

See CHANGELOG.md for the v1.0 surface.

Install

Not yet published to npm. From source:

git clone https://github.com/recomby-ai/agent-aso.git
cd agent-aso
npm install
npm run build
npm link        # optional: makes `aso` available globally

Usage

# AUDIT — all delegate to upstream OSS validators
aso audit openapi ./openapi.yaml             # → Spectral + agent-friendliness ruleset
aso audit mcp ./server.json                  # → mcp-registry-validator
aso audit llms-txt example.com               # → llmstxt.org structural rules
aso audit agents-json example.com            # → ajv against wild-card-ai schema
aso audit site https://example.com           # → composite, grouped by D / E / A

# GENERATE — emit starter templates per upstream spec
aso generate llms-txt                        # writes ./llms.txt
aso generate agents-md                       # writes ./AGENTS.md
aso generate agents-json                     # writes ./agents.json

# SUBMIT — guided MCP Registry publishing workflow
aso submit mcp ./server.json                 # validates + checks mcp-publisher install
aso submit mcp ./server.json --publish       # forwards to `mcp-publisher publish`

# SIMULATE — multi-agent tool-selection eval (BYOK; wraps promptfoo)
aso simulate "best CLI for API governance" --target agent-aso

# MONITOR — drift detection against cached prior run
aso monitor https://example.com              # one-shot diff
aso monitor https://example.com --watch 5m   # watch loop, ctrl-C to stop

Under the hood every audit delegates to upstream OSS:

| Audit | Wraps | |---|---| | openapi | Spectral (default ruleset extends spectral:oas) | | mcp | mcp-registry-validator library API | | llms-txt | structural rules ported verbatim from the AnswerDotAI/llms-txt reference parser | | agents-json | ajv against the official wild-card-ai schema (vendored in schemas/) | | site | robots-parser + parallel HEAD/GET probes |

Roadmap

| Command | Status | Upstream wrapped | |---|---|---| | aso audit openapi | v0.2 ✅ | @stoplight/spectral-cli + custom agent-friendliness ruleset (rulesets/aso.spectral.yaml) | | aso audit mcp | v0.1 ✅ | mcp-registry-validator | | aso audit llms-txt | v0.1 ✅ | llmstxt.org spec, port of AnswerDotAI parser | | aso audit agents-json | v0.1 ✅ | wild-card-ai/agents-json | | aso audit site | v0.2 ✅ | composite grouped by D/E/A + robots-parser + schema.org JSON-LD detection + OpenAPI auto-discovery | | aso generate llms-txt | v0.1 ✅ | static template per llmstxt.org | | aso generate agents-md | v0.1 ✅ | static template per agentsmd/agents.md | | aso generate agents-json | v0.1 ✅ | static template per wild-card-ai schema | | Custom Spectral ruleset for agent-friendliness | v1.0 ✅ | layered on spectral:oas (7 ASO rules) | | aso submit mcp | v1.0 ✅ | mcp-publisher guided workflow | | aso simulate | v1.0 ✅ | promptfoo wrap (multi-agent eval, BYOK) | | aso monitor | v1.0 ✅ | drift diff against ~/.aso/state/, optional --watch interval | | aso generate llms-txt --from-url | v1.1 | firecrawl/llmstxt-generator auto-fill (BYOK) |

Design rules

This project is an assembly of upstream OSS — it does not reimplement existing tools. See SPEC.md §6 and §8.

• Every audit / generate / submit / simulate / monitor command is a thin wrapper over a named npm package, CLI, or HTTP probe.
• First-party code is limited to: a Spectral ruleset (YAML), CLI dispatch (commander), report formatters, and a tiny diff-vs-cache layer for monitor.
• v1.0 first-party TypeScript: 990 LOC. Heavy upstreams (promptfoo, mcp-publisher) are spawned on-demand rather than bundled. If a contribution adds first-party validation/parsing logic, the reviewer's first question is: which upstream did you miss?

License

MIT © Recomby.ai