Glintscanner

Agent Readiness Scanner & Flight Simulator for developer products.

Analyze whether AI coding agents (Cursor, Claude Code, Copilot, …) can discover, parse, and complete integration journeys against your docs ecosystem — then get a versioned Agent Readiness Score (ARS 3.0) and test your APIs inside the Autonomous Flight Simulator.

• Hosted: scan.glintbase.dev
• Flight Simulator Cockpit: scan.glintbase.dev/simulate
• Resources: Developer Tools hub · MCP gateway · in-repo skills/ agent skill
• Methodology: docs/methodology/ars-3.3.md
• Roadmap / specs: docs/

Features

• Surface discovery — llms.txt, OpenAPI, MCP, sitemap.xml, auth.md, ard.json, robots.txt
• Content validation — empty/HTML soft-404s don’t max machine scores
• ARS 3.x probe engine — 137 registered checks across 4 layers (discovery, access, usability, payments) with Dynamic Denominator scoring. Checks that cannot be verified are reported as skip/na and excluded, never passed by assumption
• Live MCP probing — handshake (2026-07-28 + legacy wire forms), tools/list, schema and annotation inspection, error-channel canary, and a read-only call only on tools annotated readOnlyHint: true
• OpenAPI inspection — operationIds, request/error schemas, pagination, rate-limit headers, problem+json and more, read from the spec itself
• Flight Simulator — separate agent journey simulations with visual DAGs and state replay (#data=) at /simulate; not part of the ARS score
• Authoritative MCP Endpoint — /api/mcp supporting JSON-RPC 2.0 and Server-Sent Events (SSE)
• CLI & Web — Real-time telemetry, visual terminal graphs, shareable reports, and automated CI quality gates

Web vs CLI vs MCP — which should I use?

All three surfaces score with the same engine: the ARS 3.x probes in src/lib/scanner/v2/probes (wrapped by runScan for the web app and MCP). The engine is published as @glintbase/scanner-core, which the CLI depends on. The same URL gets the same score on each; they differ only in how results are delivered.

	Web — scan.glintbase.dev	CLI — @glintbase/cli	MCP — @glintbase/mcp
Best for	One-click hosted scan, sharing, leaderboard	Local runs + CI gates	Driving from inside a coding agent
Setup	None (hosted)	npm i -g, optional init wizard	Zero-config — no .env, no keys
Scoring	ARS 3.x probes (runScan)	ARS 3.x probes (runArs3Probes from @glintbase/scanner-core)	ARS 3.x probes (score_readiness calls runScan)
Extra tools	Flight Simulator (/simulate)	audit (URL or local codebase), check, ci, mcp lint, fix, simulate	Diagnostic crawl / graph / journey tools (not part of the score)
Output	Interactive UI, saved report, badge	Terminal + JSON/Markdown, exit codes	Structured JSON per tool
Persistence	Supabase (history, leaderboard)	Local files	In-memory session (+ file cache)

The ARS 3.x engine is deterministic HTTP probing; it does not crawl pages or run an LLM.

Quick start (web)

npm install
cp .env.local.example .env.local
# Optional: FIRECRAWL_API_KEY, Supabase, Upstash Redis
npm run dev

Open http://localhost:3000.

CLI

npm install
npm run glintscan -- https://docs.example.com
npm run glintscan -- https://docs.example.com --json
npm run glintscan -- https://docs.example.com --markdown --fail-under 70
npm run glintscan -- --score-version

Or after install: npx glintscan <url> (via bin/glintscan.mjs).

Exit code	Meaning
0	Success
1	Scan failed
2	Invalid URL / SSRF blocked
3	Score below --fail-under

MCP Server (@glintbase/mcp)

Zero-config scanner tools for AI coding agents. No API keys, no .env — the agent reasons over results using its own subscription.

Setup

Claude Code (.mcp.json):

{
  "mcpServers": {
    "glintbase": {
      "command": "npx",
      "args": ["-y", "@glintbase/mcp"]
    }
  }
}

Cursor / Windsurf (Settings → MCP):

{
  "glintbase": {
    "command": "npx",
    "args": ["-y", "@glintbase/mcp"]
  }
}

Local dev:

cd mcp && npm install && npm run dev

Optional: Firecrawl for better content extraction

The MCP works zero-config with raw HTML parsing, but for JS-heavy docs sites (Vercel, Next.js, etc.), a Firecrawl API key significantly improves content extraction and journey pass rates:

{
  "mcpServers": {
    "glintbase": {
      "command": "npx",
      "args": ["-y", "@glintbase/mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-your-key-here"
      }
    }
  }
}

Free tier at firecrawl.dev includes 500 credits/month. Firecrawl only affects the diagnostic crawl_pages / build_knowledge_graph / run_journeys tools; score_readiness uses the same probe engine as scan.glintbase.dev and does not crawl.

Even without a Firecrawl key, the deep_crawl tool recovers most JS-rendered content by extracting the framework payloads embedded in the HTML (Next.js __NEXT_DATA__, App Router RSC flight chunks, JSON-LD, <noscript>). Prefer it over crawl_pages for SPA/Next.js docs sites.

Available tools

Tool	Description
discover_surfaces	Find all machine-readable entrypoints (llms.txt, OpenAPI, MCP, docs, …)
check_reachability	Quick single-URL reachability + soft-404 detection
parse_spec	Parse OpenAPI / llms.txt / MCP configs without crawling
crawl_pages	Budgeted crawl with priority queue (quick/deep profiles)
deep_crawl	In-depth crawl that recovers JS-rendered content (Next.js __NEXT_DATA__, App Router RSC, JSON-LD, <noscript>, main-content) with no API key
build_knowledge_graph	Semantic graph from crawled pages
run_journeys	Deterministic agent journey simulations (no LLM)
score_readiness	ARS 3.x score from the same probe engine as the web app and CLI
get_remediation	Prioritized fixes with templates and expected score impact

Example agent flow

User: "Scan docs.stripe.com for agent readiness"
Agent: calls discover_surfaces → score_readiness → get_remediation
Agent: "Score: 82/100 (AI-Friendly). Top fix: add llms.txt with quickstart links."

CLI (@glintbase/cli)

The Glintbase CLI lives in its own repository: athertech/glintbase-cli (npm). From 3.3.0 it scores with @glintbase/scanner-core, so a CLI audit and a scan on scan.glintbase.dev use the same ARS 3.3 rules.

npx @glintbase/cli audit https://docs.example.com            # ARS 3.3 audit
npx @glintbase/cli audit https://docs.example.com --fail-under 70
npx @glintbase/cli mcp lint https://api.example.com/api/mcp   # MCP server lint

See the CLI README for local codebase audits, CI gates and the bundled MCP server.

Programmatic API (@glintbase/scanner-core)

The engine is published as @glintbase/scanner-core (built from core/, which bundles src/lib/scanner with tsup; no runtime dependencies):

import { runArs3Probes, runScan, formatScanMarkdown } from '@glintbase/scanner-core';

const scorecard = await runArs3Probes('https://docs.example.com');
console.log(scorecard.score, scorecard.version, scorecard.evidence); // e.g. 74, ars-3.3.1

const result = await runScan(
  { url: 'https://docs.example.com', options: { profile: 'quick' } },
  { onProgress: (e) => console.error(e) }
);

console.log(result.score, result.score_version); // e.g. 74, ars-3.3.1
console.log(formatScanMarkdown(result));

runScan has no Next.js or Supabase dependency. Inside this repo you can also import it directly from ./src/lib/scanner/core.

Environment

See .env.local.example.

Variable	Required	Purpose
FIRECRAWL_API_KEY	No	Cleaner markdown scrape
NEXT_PUBLIC_SUPABASE_* / SUPABASE_SERVICE_ROLE_KEY	No	Persist scans / leaderboard
UPSTASH_REDIS_*	Prod recommended	Distributed rate limits
ALLOW_HTTP	No	Allow http:// targets (dev)
SCAN_MAX_PAGES / SCAN_MAX_DURATION_MS	No	Crawl budgets
PATHFINDER_BEAM_WIDTH	No	Beam search (default 1 = greedy)

Apply DB schema updates from migration.sql in Supabase SQL editor when using persistence.

Grades and bands (ARS 3.3)

Defined once in src/lib/scanner/shared/scoreBand.ts; bands are groups of grades, so they always agree.

Score	Grade	Band
95–100	A+	Agent-Native
86–94	A	Agent-Native
70–85	B	AI-Friendly
48–69	C	AI-Capable
28–47	D	Legacy
0–27	F	Legacy

Architecture

See ARCHITECTURE.md for the pipeline diagram and module map.

Target URL → URL policy → Discover surfaces → ARS 3.x probes (discovery · access · usability · payments) → Score + remediations

Tests & CI

npm test
npm run typecheck
npm run lint

GitHub Actions (.github/workflows/ci.yml) runs typecheck, tests, lint and a production build for the web app, and typecheck, tests and build for the CLI and MCP packages, on every push and PR to main. Unit tests run with network access blocked (test/blockNetwork.ts); set ALLOW_NETWORK_TESTS=1 to allow it locally.

Contributing

See CONTRIBUTING.md. Spec-driven: update docs/specs/* when changing behavior.

Security

See SECURITY.md. Report vulnerabilities privately — not as public score disputes.

License

Apache License 2.0

---

Built by Glintbase · Infrastructure for AI-agent-ready repositories