ARD Explorer

A web UI for exploring and exercising Agentic Resource Discovery (ARD) endpoints — point it at any registry, including one running on localhost.

Think MCP Inspector, but for ARD.

npx ard-explorer

Why

ARD has good CLI tooling (@ardregistry/cli, hf discover, OpenARD) and a hosted public directory at ardregistry.org. What was missing was a web client you can aim at an arbitrary endpoint — especially your own, while you're building it.

That's this. It's protocol-generic: nothing in here knows or cares who implemented the registry.

What it does

• Connect to any registry by base URL, or discover one from a static /.well-known/ai-catalog.json — per §7, a manifest advertises its API as an application/ai-registry+json entry, and the explorer follows that.
• Probe capabilities. POST /search is mandatory; /explore and /agents are optional, so a 404/501 from them is shown as "not implemented" — a conformant answer — rather than as a failure.
• Search with the full §7.1 query model: natural-language text, structured filter (dot-separated paths, OR within a key / AND across keys), pageSize, pageToken pagination, and the federation mode. Referrals are rendered with a one-click connect so you can walk a federated network.
• Explore facets, with bucket counts and otherCount.
• List via GET /agents, including a nudge when a registry returns results instead of the items envelope the conformance tool expects.
• Validate manifests against the entry-level rules the official conformance tool checks: URN shape, strict value-or-reference, representativeQueries 2–5, the removed collections property, duplicate identifiers.
• Raw tab — every request and response, newest first.

It also understands metadata.policyVerdict (allow / allow_sandboxed / deny) and renders it as a badge. That's an extension, not part of ARD — registries that don't emit it are unaffected.

Usage

npx ard-explorer [options]

  -p, --port <port>       Port to listen on (default: 7842, 0 for ephemeral)
  -e, --endpoint <url>    Pre-fill the registry base URL
  -m, --manifest <url>    Pre-fill a manifest URL
      --host <host>       Interface to bind (default: 127.0.0.1)
      --no-open           Don't open a browser
      --allow-remote      Permit binding to a non-loopback interface

The connect box is prefilled with the public reference implementations the ARD project lists — Hugging Face Discover, GitHub Agent Finder, Cisco AI Catalog, Ora Directory — and remembers anything else you type.

Try it without a registry

A small spec-shaped mock registry ships with the repo:

npm run mock                      # http://localhost:9010/api
npx ard-explorer -e http://localhost:9010/api

It implements /search, /explore and /agents over a handful of sample entries covering MCP servers, an A2A agent, a skill, trust manifests, referrals and pagination.

How it's built

• Server — plain node:http. Serves the UI and proxies to ARD endpoints.
• UI — React 18 + Fluent UI v9, bundled with esbuild.
• Zero runtime dependencies. React and Fluent are bundled into the shipped asset, so npx ard-explorer pulls down the tarball and nothing else.

Why a proxy?

A browser page can't call an arbitrary ARD registry directly — the registry would need permissive CORS headers, and localhost registries generally have none. So requests go through the explorer's own /__ard/proxy, the same approach MCP Inspector takes.

Consequence worth knowing: the explorer will happily reach anything your machine can reach, which is the point when you're testing a local registry. It binds 127.0.0.1 and refuses any other interface unless you pass --allow-remote.

Development

npm install
npm run build          # tsc for the server, esbuild for the web bundle
npm run dev:web        # esbuild --watch
npm run typecheck
npm run mock           # sample registry to develop against

Conformance

The manifest validation here is a convenience for fast feedback while iterating — it is not a JSON Schema validator and not a substitute for the official tool:

curl -O https://raw.githubusercontent.com/ards-project/ard-spec/main/conformance/bin/conformance-test
pip install jsonschema
python conformance-test manifest ./my-catalog.json
python conformance-test registry http://localhost:9010/api

Releasing

Published to npm via Trusted Publishing (OIDC) — there is no NPM_TOKEN anywhere in this repo. npm mints a short-lived credential from the GitHub Actions OIDC token, so the only thing that can publish this package is .github/workflows/publish.yml running in this repository. Provenance attestation is generated automatically.

To cut a release:

npm version patch      # or minor / major — commits and tags
git push --follow-tags

The tag triggers the workflow, which typechecks, builds, verifies the tag matches package.json, smoke-tests the CLI, and publishes.

Status

Early. Built against ARD v0.9 (draft); the spec is moving, so expect churn. Issues and PRs welcome.

License

MIT