Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 9 additions & 16 deletions .github/workflows/quality.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: Quality

# All correctness gates: Go build + unit/integration tests, the OpenAPI↔router
# and A2A contract suites, web build + unit tests, Helm render validation, and
# contract suites, web build + unit tests, Helm render validation, and
# the Playwright + k6 end-to-end suite. Static analysis (gofmt/vet/eslint/tsc/
# helm lint/...) lives in the separate Lint workflow via pre-commit.
on:
Expand Down Expand Up @@ -46,17 +46,13 @@ jobs:

# Explicit conformance + contract suite run. Everything under this step
# already ran as part of `go test ./...` above — the repeat is deliberate
# so the CI log surfaces these tests by name. If the A2A Agent Card schema,
# OpenAPI↔router contract, or the admin-guard router contract are ever
# deleted or renamed without updating this step, CI fails loudly instead
# of silently passing.
# so the CI log surfaces these tests by name. If the OpenAPI↔router or the
# admin-guard router contract is ever deleted or renamed without updating
# this step, CI fails loudly instead of silently passing.
- name: Contract & conformance suites (named)
working-directory: server
run: |
set -euo pipefail
go test -count=1 -v \
-run '^(TestAgentCardHandler_PerAgentCard_A2AConformance$|TestAgentCardHandler_GlobalAgentCard_A2AConformance$|TestAgentCardHandler_GlobalAgentCard_MisconfiguredReturns500$|TestRegistryCard_A2AConformance$)' \
./internal/http/handlers/...
go test -count=1 -v \
-run '^(TestOpenAPIContract_MatchesRouter$|TestAllWriteRoutesRequireAdmin$|TestPublicWriteRoutesBypassAdmin$)' \
./internal/http/
Expand All @@ -79,12 +75,12 @@ jobs:
}

# ── OpenAPI ↔ router contract ────────────────────────────────────────────────
# Dedicated, fast job that only runs the OpenAPI↔router and A2A Agent Card
# conformance suites. Duplicates what the server job covers, but surfaces the
# Dedicated, fast job that only runs the OpenAPI↔router contract suites.
# Duplicates what the server job covers, but surfaces the
# result as its own required check so a spec drift is obvious in the PR UI
# without digging into a long log.
contract:
name: API contract (OpenAPI + A2A)
name: API contract (OpenAPI)
runs-on: ubuntu-latest
timeout-minutes: 5

Expand All @@ -105,9 +101,6 @@ jobs:
go test -count=1 -v \
-run '^(TestOpenAPIContract_MatchesRouter$|TestAllWriteRoutesRequireAdmin$|TestPublicWriteRoutesBypassAdmin$)' \
./internal/http/
go test -count=1 -v \
-run '^(TestAgentCardHandler_PerAgentCard_A2AConformance$|TestAgentCardHandler_GlobalAgentCard_A2AConformance$|TestAgentCardHandler_GlobalAgentCard_MisconfiguredReturns500$|TestRegistryCard_A2AConformance$)' \
./internal/http/handlers/...

# ── Web: build/typecheck, OpenAPI sync, unit tests ───────────────────────────
web:
Expand Down Expand Up @@ -383,8 +376,8 @@ jobs:
echo "Server ready."

# ── Web (native Vite server) ──────────────────────────────────────────
# The Vite server binds :3000 and proxies /api, /config.json, and the A2A
# agent-card paths to the server on :8081 (see web/vite.config.ts), the
# The Vite server binds :3000 and proxies /api, /config.json, and
# /.well-known to the server on :8081 (see web/vite.config.ts), the
# same surface nginx serves in production.
#
# `--host 0.0.0.0` forces the dev server onto IPv4. Vite's default host is
Expand Down
38 changes: 14 additions & 24 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ How the AI Registry is put together and why. Commands to run it live in

The registry is one Go HTTP service backed by PostgreSQL, plus a static React
SPA that is purely a client of the service's versioned API. The service owns
every piece of state and every rule: catalog entries (MCP servers, A2A agents),
their immutable versions, the review workflow, publisher-scoped RBAC, and token
every piece of state and every rule: catalog entries (MCP servers), their
immutable versions, the review workflow, publisher-scoped RBAC, and token
issuance. An external OIDC provider is optional and only authenticates people;
it never decides what they may do.

Expand Down Expand Up @@ -44,11 +44,10 @@ docker-compose, nginx (or the Vite dev server) proxies `/api` as well.

### `server/` — the registry service

The single source of truth. It serves the API under `/api/v1`, the discovery
documents (`/.well-known/jwks.json`, `/.well-known/agent-card.json`, per-agent
cards under `/agents/{namespace}/{slug}/.well-known/agent-card.json`), the
OpenAPI document at `/openapi.yaml`, `/config.json` for the SPA, the
`/healthz` / `/readyz` probes and Prometheus `/metrics`.
The single source of truth. It serves the API under `/api/v1`, the JWKS at
`/.well-known/jwks.json`, the OpenAPI document at `/openapi.yaml`,
`/config.json` for the SPA, the `/healthz` / `/readyz` probes and Prometheus
`/metrics`.

On start-up, in order: load configuration, set up OpenTelemetry, run the
database migrations, seed the bootstrap Server Admin, reconcile the
Expand All @@ -65,9 +64,8 @@ flush. See [server/cmd/server/main.go](server/cmd/server/main.go).
| [`internal/auth`](server/internal/auth/) | Token authority, refresh tokens, OIDC broker, password hashing, bearer authentication, RBAC guards. |
| [`internal/domain`](server/internal/domain/) | Entity types, the role lattice, validation, lifecycle rules. No I/O. |
| [`internal/store`](server/internal/store/) | Hand-written SQL over `pgx`, migrations runner, seeding. Every query is traced. |
| [`internal/agents`](server/internal/agents/) | Builds A2A Agent Cards from stored agent versions. |
| [`internal/tooldiscovery`](server/internal/tooldiscovery/) | MCP client behind "Fetch from server" and "Detect from server": connects to a remote server's declared URL and transport, runs `tools/list`, probes the protocol revisions it accepts, refuses internal addresses. Stores nothing. |
| [`internal/bootstrap`](server/internal/bootstrap/) | Declarative YAML/JSON loader that upserts publishers, servers and agents. |
| [`internal/bootstrap`](server/internal/bootstrap/) | Declarative YAML/JSON loader that upserts publishers and servers. |
| [`internal/config`](server/internal/config/) | Resolves every setting from env, YAML file, then default. |
| [`internal/observability`](server/internal/observability/) | The one OTel SDK setup (tracer, meter, logger providers) and the metric definitions. |
| [`internal/problem`](server/internal/problem/) | RFC 7807 `application/problem+json` responses. |
Expand Down Expand Up @@ -164,25 +162,21 @@ forward-only migrations in [server/migrations/](server/migrations/).
```mermaid
erDiagram
publishers ||--o{ mcp_servers : owns
publishers ||--o{ agents : owns
mcp_servers ||--o{ mcp_server_versions : has
agents ||--o{ agent_versions : has
publishers ||--o{ role_grants : "scopes (null = global)"
users ||--o{ role_grants : "granted to"
groups ||--o{ role_grants : "granted to"
groups ||--o{ group_members : has
users ||--o{ group_members : "member of"
users ||--o{ refresh_tokens : holds
mcp_servers ||--o{ entry_change_requests : "pending changes"
agents ||--o{ entry_change_requests : "pending changes"
```

- **Publishers own everything.** Every MCP server and agent belongs to exactly
- **Publishers own everything.** Every MCP server belongs to exactly
one publisher, and its `{namespace}` path segment *is* that publisher's slug.
Slugs are unique per publisher, not globally.
- **Versions are immutable once published.** A version row is never edited
after `published_at` is set, because consumers cache server metadata and agent
cards.
after `published_at` is set, because consumers cache server metadata.
- **`audit_log` and `reports` are polymorphic** (`resource_type` +
`resource_id`, `target_type` + `target_id`); the bootstrap loader writes
synthetic audit events too.
Expand Down Expand Up @@ -231,8 +225,7 @@ carries the proposed mutation as a JSONB `payload`, and approval dispatches on
`(resource_type, action)` to apply it in the same transaction
([server/internal/store/entrychange.go](server/internal/store/entrychange.go)).
A partial unique index allows one pending entry-change per entry, independently
of the pending version and pending deletion an entry may also have. Agents
mirror MCP servers exactly.
of the pending version and pending deletion an entry may also have.

## Design decisions

Expand Down Expand Up @@ -310,10 +303,7 @@ span ([server/internal/http/](server/internal/http/)).
`(created_at, id)`, so inserts do not shift pages under a paging client. The
SPA mirrors this with "Load more" rather than page numbers.

**The MCP wire format follows the upstream `server.json` shapes** and agent
cards follow the A2A Agent Card schema, pinned in
[server/api/a2a-agent-card.schema.json](server/api/a2a-agent-card.schema.json)
and checked by conformance tests. `tools[]` on an MCP version is the
**The MCP wire format follows the upstream `server.json` shapes.** `tools[]` on an MCP version is the
publisher-declared tool list, distinct from the spec's `capabilities.tools`
negotiation flag.

Expand Down Expand Up @@ -378,10 +368,10 @@ states (`success`, `warning`, `highlight`) are tokens rather than Tailwind
colors so both themes stay in step; only instance-tag colors, which a Server
Admin picks, keep the stock palette.

**Detail pages lead with how to connect.** An MCP server or agent page puts
**Detail pages lead with how to connect.** An MCP server page puts
the endpoint (or run command) in a side column that is always in view, above
the README on a phone, and keeps the README in the Overview tab so a long one
never pushes Usage, Tools or Skills off screen. Cards in a listing carry one
never pushes Usage or Tools off screen. Cards in a listing carry one
link target and one row of facts; status shows only when it is not
`published`, since everything in the public catalog is.

Expand Down Expand Up @@ -434,7 +424,7 @@ link target and one row of facts; status shows only when it is not
direct `publish` endpoint without a second pair of eyes.
- There are no registry-native API keys: machine access requires an OIDC
provider issuing tokens with the configured audience.
- The catalog covers MCP servers and A2A agents only.
- The catalog covers MCP servers only.
- "Fetch from server" and "Detect from server" reach only remote servers
that accept anonymous connections. A stdio server runs on the consumer's
machine and a server behind authentication rejects the registry, so their
Expand Down
8 changes: 3 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@ Guidance for Claude Code when working in this repository.

## Project

AI Registry — a centralized catalog for AI ecosystem artifacts (MCP servers,
A2A agents), exposed via a versioned HTTP API with two SPA
clients (read-only user UI, authenticated admin UI).
AI Registry — a centralized catalog for MCP servers, exposed via a versioned
HTTP API with two SPA clients (read-only user UI, authenticated admin UI).

## Tech stack

Expand All @@ -33,7 +32,7 @@ clients (read-only user UI, authenticated admin UI).

## Repository layout

- `server/` — Go service. `internal/{http,agents,auth,bootstrap,config,domain,store,observability,problem}`,
- `server/` — Go service. `internal/{http,auth,bootstrap,config,domain,store,observability,problem}`,
`api/` (embedded OpenAPI spec), `migrations/`, `cmd/`.
- `web/` — the SPA (pages in `src/pages/`).
- `deploy/` — ops (compose files, Helm, example configs).
Expand Down Expand Up @@ -97,4 +96,3 @@ from env/secrets, not a committed file.
## References

- MCP: https://modelcontextprotocol.io/
- A2A / Agent Card: https://a2a-protocol.org/
5 changes: 2 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,9 +117,8 @@ cd server && go test -coverprofile=coverage.out ./... && go tool cover -func=cov
```

The contract suites are part of `go test ./...`; they assert that the OpenAPI
operations and the chi routes match one-to-one, that every write route is
guarded, and that emitted Agent Cards conform to the pinned A2A schema. Adding
a route without its spec entry, or the reverse, fails them.
operations and the chi routes match one-to-one and that every write route is
guarded. Adding a route without its spec entry, or the reverse, fails them.

### Web — unit and component

Expand Down
15 changes: 6 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,14 @@

# AI Registry

A self-hostable registry for AI ecosystem artifacts — **MCP servers** and
**A2A agents** — with a versioned HTTP API, a public catalog UI and an admin
console.
A self-hostable registry for **MCP servers**, with a versioned HTTP API, a
public catalog UI and an admin console.

[![Lint](https://github.com/Haibread/ai-registry/actions/workflows/lint.yml/badge.svg)](https://github.com/Haibread/ai-registry/actions/workflows/lint.yml) [![Quality](https://github.com/Haibread/ai-registry/actions/workflows/quality.yml/badge.svg)](https://github.com/Haibread/ai-registry/actions/workflows/quality.yml) [![Docker](https://github.com/Haibread/ai-registry/actions/workflows/docker.yml/badge.svg)](https://github.com/Haibread/ai-registry/actions/workflows/docker.yml)

## Description

Teams building with MCP servers and A2A agents end up with them scattered
Teams building with MCP servers end up with them scattered
across repositories, wikis and chat threads. The AI Registry is one catalog
where publishers declare them, reviewers approve them, and people and machines
discover them.
Expand All @@ -19,9 +18,7 @@ discover them.
move through draft, published and deprecated.
- **Spec-aware** — MCP metadata follows the
[Model Context Protocol](https://modelcontextprotocol.io/) `server.json`
shapes; every agent gets an [A2A](https://a2a-protocol.org/) Agent Card at
`/agents/{namespace}/{slug}/.well-known/agent-card.json`, and the registry
publishes its own at `/.well-known/agent-card.json`.
shapes.
- **Review workflow** — Editors propose versions, deletions and entry changes;
Reviewers approve them.
- **Publisher-scoped RBAC** — Viewer, Editor, Reviewer and Admin roles granted
Expand All @@ -32,8 +29,8 @@ discover them.
3.1 document is served at `/openapi.yaml`.
- **Observable** — OpenTelemetry traces, metrics and logs over OTLP.

It hosts metadata only: it does not run, proxy or sandbox the servers and
agents it lists. The only connections it makes to a listed server are the
It hosts metadata only: it does not run, proxy or sandbox the servers it
lists. The only connections it makes to a listed server are the
handshakes and `tools/list` an author asks for from the MCP forms.

The documentation lives at <https://haibread.github.io/ai-registry/>
Expand Down
11 changes: 4 additions & 7 deletions deploy/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@

# ── Bootstrap file (optional) ─────────────────────────────────────────────────
# Path to a YAML or JSON file containing initial registry data (publishers,
# MCP servers, agents). When set, the server upserts all entries on startup
# MCP servers). When set, the server upserts all entries on startup
# before accepting traffic. Safe to run repeatedly — existing entries are
# skipped. Leave unset in production if you do not want any pre-loaded data.
# See deploy/bootstrap.example.yaml for the format.
Expand Down Expand Up @@ -59,12 +59,9 @@ SHUTDOWN_DRAIN_DELAY=5s
# Example: http://localhost:3000,https://registry.example.com
CORS_ALLOWED_ORIGINS=

# Public-facing base URL of this deployment. Used by the A2A global agent
# card at /.well-known/agent-card.json, as the access-token issuer and to
# derive the OIDC redirects. Must be the externally reachable URL (the address
# clients use), not an internal Docker network address. The agent card
# returns HTTP 500 when this is empty rather than silently advertising
# localhost to external consumers. YAML key:
# Public-facing base URL of this deployment. Used as the access-token issuer
# and to derive the OIDC redirects. Must be the externally reachable URL (the
# address clients use), not an internal Docker network address. YAML key:
# `http.public_base_url`. Default is empty.
# Example: https://registry.example.com
PUBLIC_BASE_URL=http://localhost:3000
Expand Down
Loading
Loading