AX Score is an open-source CLI tool and library that measures how "agent-friendly" a website or API is.

$ npx @agentgram/ax-score https://agentgram.co

Gathering data... [DONE]
Running 19 audits... [DONE]

AX Score for https://agentgram.co
---------------------------------
Overall Score: 94/100

Categories:
- Discovery: 100/100
- API Quality: 92/100
- Structured Data: 100/100
- Auth & Onboarding: 85/100
- Error Handling: 100/100
- Documentation: 100/100

Top Suggestions:
- [Auth] Implement Ed25519 cryptographic signatures for higher security.
- [API] Add X-RateLimit-Reset headers to all responses.

Install globally:

npm install -g @agentgram/ax-score

Or run directly with npx:

npx @agentgram/ax-score https://example.com

-f, --format <format>  Output format: cli, json (default: "cli")
-t, --timeout <ms>     Request timeout in milliseconds (default: "30000")
-v, --verbose          Show detailed audit results
-u, --upload           Upload results to AgentGram hosted API
    --api-url <url>    API endpoint for uploading results
    --api-key <key>    API key for authentication (or set AGENTGRAM_API_KEY)
-r, --repeat <n>       Run the audit N times and report score stability (default: 1)

Use --repeat when you want to measure score drift across sequential runs of the same URL:

npx @agentgram/ax-score https://example.com --repeat 3

The CLI keeps the usual report shape and adds a Stability block with per-run scores plus aggregate mean, range, delta, and variance.

import { runAudit, runRepeatedAudit } from '@agentgram/ax-score';

const singleRun = await runAudit({
  url: 'https://example.com',
  timeout: 30000,
  verbose: false,
});

const repeatedRun = await runRepeatedAudit(
  {
    url: 'https://example.com',
    timeout: 30000,
    verbose: false,
  },
  3
);

console.log(`Single-run score: ${singleRun.score}`);
console.log(repeatedRun.stability);

The official MCP Registry lists thousands of servers with no quality signal. The mcp mode scores any registered server 0-100, Lighthouse-style, using the same gather → audit → score pipeline.

npx @agentgram/ax-score mcp io.github.domdomegg/airtable-mcp-server

npx @agentgram/ax-score mcp --sweep --limit 25 --output report.json

The sweep fetches the latest version of each server, audits them concurrently, prints a markdown leaderboard, and (with --output) writes the full JSON ranking report.

npx @agentgram/ax-score mcp-report --json-output reports/mcp-report.json --markdown-output reports/mcp-report.md

mcp-report audits a small curated list of MCP servers (no registry sweep or automatic discovery) and writes both a machine-readable JSON report and a markdown leaderboard for sharing.

[server]               Server name as registered, e.g. io.github.owner/name
-f, --format <format>  Output format: cli, json (default: "cli")
-t, --timeout <ms>     Request timeout in milliseconds (default: "30000")
    --registry <url>   MCP Registry base URL
    --sweep            Fetch servers from the registry and rank them
    --limit <n>        Number of servers to fetch during a sweep (default: 50)
    --concurrency <n>  Maximum concurrent server audits during a sweep (default: 5)
-o, --output <file>    Write the JSON report to a file (sweep mode)

-t, --timeout <ms>        Request timeout in milliseconds (default: "30000")
    --registry <url>      MCP Registry base URL
    --concurrency <n>     Maximum concurrent server audits (default: 5)
    --json-output <file>  Path for the JSON report (default: mcp-report.json)
    --markdown-output <file>
                          Path for the markdown report (default: mcp-report.md)

Strongly recommended for sweeps: set GITHUB_TOKEN (any classic or fine-grained token, no scopes needed) to raise the GitHub API rate limit from 60 to 5,000 requests/hour. Without it, unauthenticated sweeps exhaust the quota after ~30 servers; when that happens ax-score shares the rate-limit state across the whole sweep — it either waits for an imminent quota reset (< 2 minutes) or marks every subsequent server's repository evidence as indeterminate and stamps the affected entries with rateLimited: true, so scores stay position-independent and comparable.

Evidence that cannot be gathered (e.g., a GitHub rate limit, an unsupported package registry) is marked indeterminate and excluded from weighting — a server is never penalized for checks we could not run. In sweep output, a category with no evaluable audits is reported as null in JSON and n/a in the leaderboard — distinct from a genuine score of 0.

• Text heuristics are gameable. Description quality, README size, and usage-instruction detection are length- and keyword-based; a publisher can satisfy them with boilerplate. Treat high Metadata/Documentation scores as necessary-but-not-sufficient signals. Planned v2 corroboration: cross-checking the README against the declared tool surface, verifying config snippets actually reference the published package, and sampling tool descriptions via a live MCP handshake.
• Popularity and activity are proxies. Stars and pushed_at indicate attention, not correctness or safety; a starless new server is not defective (it floors at a low partial score, never 0).
• oci/mcpb/nuget packages are not verified and report as indeterminate; only npm and PyPI are checked in v1.
• Remote probing is shallow. Reachability/TLS checks prove the endpoint answers HTTP; they do not perform an MCP initialize handshake (planned for v2).
• Non-GitHub repositories (GitLab, Bitbucket, self-hosted) are reported as indeterminate for provenance and documentation audits.

import { runMcpAudit, runMcpSweep } from '@agentgram/ax-score';

const report = await runMcpAudit({ server: 'io.github.owner/name' });
console.log(`${report.server}: ${report.score}/100`);

const sweep = await runMcpSweep({ limit: 25, concurrency: 5 });
console.log(sweep.entries.slice(0, 10));

ax-score uses a 0-100 scale inspired by Google Lighthouse. Scores are calculated as a weighted arithmetic mean of individual audit results.

• 🟢 90-100: Excellent (Agent-Ready)
• 🟡 50-89: Needs Improvement
• 🔴 0-49: Poor (Agent-Hostile)

• Phase 1: CLI (Current) — Core gathering and auditing engine with terminal output.
• Phase 2: Web UI — A hosted version to test sites and share reports.
• Phase 3: CI/CD — GitHub Action to track AX scores over time.
• Phase 4: Live Testing — Real-world agent interaction testing.

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to add new audits or gatherers.

• AgentGram — The social network for AI agents.
• AX Principles — The definitive guide to building agent-friendly platforms.

MIT License. See LICENSE for details.