bouch-registry

The Bouch capability registry: one remote place for an agent to discover what Bouch already knows and has built before treating a domain or environment as capability-empty.

It is a metaregistry. Each record identifies a capability, names its versioned source repository, points at the native manifest where an open specification exists, and lists the entrypoint documents to read next. It is not a package manager, installer, orchestrator or copy of native manifests, and it holds no live state (versions, tool counts, git or runtime status) — derive those from the systems themselves.

Service identity: https://registry.bouch.dev/ — /health, /registry.json and MCP at /mcp. https://bouch-registry.fly.dev/ serves the same app and is the origin the custom domain points at.

Data

registry/ is the only dataset. The MCP tools, MCP resources, /registry.json and bouch-registry export are all rendered from it.

registry/
├── domains.json          # closed domain vocabulary with routing summaries
└── entries/<name>.json   # one record per capability, id dev.bouch/<name>

The model (bouch_registry/model.py) is the schema. Records reject unknown fields, so manifest content such as version or keywords cannot creep in.

Types

agent-skill means an Agent Skills SKILL.md. It is unrelated to an A2A AgentSkill, which is a capability tag inside an Agent Card.

The type set and the native/Bouch-specific split come from the agent-enumeration-lab finding bouch-registry-standards-fit.

Adding or changing a record

1. Edit registry/entries/<name>.json. Point only at files committed in the source repository (at source.ref if set). Never use local checkout paths.

2. uv run bouch-registry validate

3. Check the pointers against real checkouts (paths are passed on the command line, never stored): uv run bouch-registry verify-sources --checkout <repository>=<path> ... and, for published sources, against the remote exactly as MCP clients read them: uv run bouch-registry verify-sources --remote

4. uv run pytest

Related MCP server: MCP Registry Search

MCP surface

Tools (read-only, structured output):

• search_capabilities(query, domain?, type?, limit?) — deterministic weighted keyword search with IDF; empty query browses.

• get_capability(id) — the full record.

• list_domains() — domains, routing summaries and member ids.

• read_capability_entrypoint(capability_id, entrypoint) — one declared entrypoint read from the canonical remote source; returns content, mime_type, repository, ref, commit, path and git_blob. The tool counterpart of bouch://source/... for tool-only clients (e.g. ChatGPT).

Resources:

• bouch://registry — the whole registry (identical to /registry.json)

• bouch://domains/{domain} — a domain with its full records

• bouch://capabilities/dev.bouch/{name} — one record

• bouch://source/dev.bouch/{name}/{path*} — one declared entrypoint (or repo-relative native manifest) read from the record's canonical remote source, e.g. bouch://source/dev.bouch/audio/skills/electronic-production/SKILL.md

Reading entrypoints remotely

A consumer without the source checked out can read what a record declares, one document at a time: resource-capable clients through bouch://source/..., tool-only clients through read_capability_entrypoint. Both call the same resolver (bouch_registry/remote.py), so they share one allowlist, ref resolution, integrity report and failure behaviour. The registry stores no content: each read follows the pointer at request time.

• Only declared paths. Entrypoint paths and a repo-relative native.manifest; anything else is refused before any network call. To make a document reachable (for example a reference a Skill routes to), declare it as an entrypoint. verify-sources enforces this for records with a published source: every repo-relative file link in a declared Markdown entrypoint must itself be declared (external URLs, anchors, code and directory links are exempt).

• Pinned to the source. source.ref is resolved to a commit from the repository's own git ref advertisement (annotated tags are peeled); a record without a ref resolves the remote HEAD. The file is then fetched by commit id. Only github.com sources are supported.

• Checkable. Provenance — repository, ref, commit, path and git_blob — is in the resource content's _meta and in the tool's structured output; git_blob equals git rev-parse <commit>:<path> in any clone.

• No fallback. An unpublished source (source.url null), a missing ref, a path absent at that commit, a non-UTF-8 file or one over 512 KiB is a resource error naming the cause. Nothing falls back to a local file, another ref or a cached copy.

HTTP routes: /mcp (streamable HTTP, stateless, JSON responses, with the fleet's claude.ai GET/DELETE guard), /registry.json, /health.

Commands

uv sync --group dev
uv run bouch-registry serve --port 8080       # MCP + /registry.json
uv run bouch-registry validate
uv run bouch-registry export registry.json    # static copy, e.g. for static hosting
uv run pytest                                 # offline: model, search, portability, CLI, MCP in-memory + HTTP
scripts/inspector-smoke.sh http://127.0.0.1:8080/mcp     # independent client (MCP Inspector CLI)
scripts/remote-acceptance.sh https://registry.bouch.dev  # the deployed boundary

Deployment

One Fly.io app, bouch-registry in lhr, running the container in Dockerfile: the package is installed, registry/ is copied beside it, and the service is started with --data /app/registry so a running container cannot serve any other copy of the dataset. /health reports the capability and domain counts it loaded, so a stale or truncated deployment is visible without opening the data.

Deploys run in GitHub Actions (.github/workflows/deploy.yml): tests and validate, then flyctl deploy. Publishing a GitHub release deploys that release; workflow_dispatch redeploys main. Do not deploy from a laptop — the live service should always correspond to a commit on main. There is no PyPI package: this is a service over a dataset, not a library.

registry.bouch.dev is a DNS-only (unproxied) CNAME in Cloudflare to the app's Fly hostname, with the certificate issued by Fly. Proxying it would break both certificate validation and the held-open GET /mcp event stream that claude.ai's connector opens.

The registry holds no record of itself: a record's job is to point at a versioned source and its entrypoints, and a deployment URL is live state, which records do not carry. bouch-registry's own source is this repository.