Skip to main content
Glama

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.

field

meaning

id

dev.bouch/<name>; file name must be <name>.json

type

one of the eight types below

title, summary

summary says when to consult this, not what a manifest already says

domains, tags

lowercase slugs; domains must be declared in domains.json

lifecycle

experimental, active, frozen (requires source.ref) or deprecated

source

repository name, url (null if unpublished), ref (durable tag), note

native

only for native types: spec, manifest (repo-relative path or https URL, or null with a note)

entrypoints

role (contract, knowledge, skill, tool, evidence), repo-relative path, title

related

other registry ids

Types

type

native spec

manifest

agent-plugin

Agent Plugins 1.0

plugin.json

agent-skill

Agent Skills

SKILL.md

mcp-server

MCP Registry server.json

server.json

remote-agent

A2A Agent Card

agent-card.json

reference-workbench

none (Bouch-specific)

—

evidence-repository

none (Bouch-specific)

—

observability-tool

none (Bouch-specific)

—

routing-pointer

none (Bouch-specific)

—

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 Finder

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables discovering existing MCP servers for any capability by federating the official MCP Registry, Smithery, and npm, ranking remote Streamable HTTP servers first. It provides search and detail tools so agents can find, evaluate, and install a suitable server.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to resolve, inspect, acquire, verify, and query routes, capabilities, schema, and health for public and authorized web resources, with fail-closed statuses and artifact production.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a shared registry that lets MCP clients search remote/stdio MCP servers and A2A agents and retrieve their current capabilities, transports, addresses, and credential references. Consumers use the returned connection details to call the selected targets directly from their own environment.
      Apache 2.0