Skip to content

One registry over the command line, HTTP, OpenAPI, Swagger UI and MCP

Every agent, script and person reads the same repository through the interface it already speaks, and none of the interfaces is maintained by hand.

status
feature status: stable
domain
Surfaces

What it does

The first majordomus mcp in a repository binds one shared server on the loopback interface and logs every surface it serves: the home page, this documentation, the crate's rustdoc, the Cockpit, the Swagger UI, the OpenAPI document, the capability routes and MCP over HTTP. Every later client attaches to it instead of starting another, and the server ends when its last client leaves. The client configurations at the repository root — one per provider that reads one, as docs/generated/providers.md lists them — name one launcher, so opening the repository in any of them is enough.

What the server answers is the registry: a tool, a resource, a route or a command exists because a declaration exists, and the same declaration is what the reference and the website render. A surface — the documentation mount, the crate's rustdoc, a generated report, the Swagger UI — is discovered from the thing that produces it, or from the source that says it exists, and resolved once into a topology the router, the home page, the publication and the validator all read.

What it does not do

Most of what is served reads. Every capability carries its effect in the registry: a read, a change to the answering runtime's own state (the peer board, the mesh journal, the evidence ledger), or a change to the repository. The ones that write the repository are continuity.publish, continuity.resume, continuity.sync, executions.start, intents.propose, mesh.enrol, plan.transition, reasoning.record and recover.orphans; the initialize instructions every client reads name them from the registry, and case 3363 refuses this page when its list and the registry's differ, because a sentence that promises a read-only surface is exactly the sentence an agent acts on. There is no authentication and no remote binding by default; the server is for the clients on this machine. When it is bound beyond loopback, its reads answer whoever reaches it, and every capability that changes something is refused to a remote caller unless a linked node signed the input. It does not run a model and it does not route work to one.

Why it exists

Operational moments from the Why catalogue that name one of this feature's mechanisms. Nothing here was assigned: a moment appears because it names a rule, a command, a capability or a claim this feature also names.

Every moment it answers (31)

How it works

The capability modules of the executable this feature names, each with the capabilities it composes. The interfaces each one reaches are listed under Interfaces below: they are projections of one declaration, not separate registrations.

Repository repository behaviorally verified

The repository this process serves: its layer, its git state, the state of the index built from it, and its scope: what a worker reads of it and what it never reads.

Objects objects behaviorally verified

The declarative objects of the repository's AI layer: rules, prompts, profiles, policy, documents, milestones, issues, claims, and whatever kinds the repository adds; listed, read by URI, and searched.

Web surfaces web behaviorally verified

What this repository exposes over HTTP, resolved from the producers that make it rather than from a register anybody maintains: the routes the executable answers itself, the documentation build, and every generated report that declared its own mount. The same resolution serves the router, renders the home page and composes a publication.

Repository environment environment behaviorally verified

What this checkout is right now: the project and its version, the repository and its layer, version control, the toolchains it declares, what the layer holds, the workflows a person can run, the provider projections and the local services — one typed snapshot, with a provenance entry for every value in it. The direnv banner, the Cockpit's overview and this route are renderings of the same value.

Executions executions behaviorally verified

Running a capability of this registry as work that can be watched: started, followed event by event over the live channel, read back afterwards, and asked to stop. One plane per checkout: `majordomus run` executes in its own process and reports the execution to the server already serving the checkout, so that server lists it beside its own; with no server it says that nothing else can see the run. In memory; an execution does not outlive the server that holds it.

Command graph commands implemented

Every command this repository offers, from whichever program offers it: the Rust executable, the shell tool that carries the task lifecycle, and the workflows the repository declares for a person to run. Composed from the three declarations that already exist — the clap tree, the shipped command registry and the workflow runner's own dump — never from a list. Each command carries what running it changes, what it needs, where its argument values come from, and every surface that carries it, with the reason when one does not.

Editor and agent projections editors behaviorally verified

The files Zed and Google Antigravity read from this repository, derived from the skills and the tracked justfile: what each product supports and on what evidence, the state and content address of every projected file, and what to do about each finding.

Entities entity implemented

Every object of the layer as an addressable, cross-linked node: its route, its outgoing references, the references that resolve to it, the surfaces that answer for it, and what can be said about its enforcement without running anything. Nothing here enumerates kinds, entities or routes — an object of the index has a route because it is an object.

MCP projection mcp experimental

The MCP projection of this registry, described as one typed value: who answers `initialize` and with which protocol versions, the transports and how many sessions each holds, what of the protocol is served and what is not, every tool with the effect and the hints its annotations are derived from, the tools that write the repository, the resources, and where each declared client's configuration stands in this repository. Nothing in it is a list of its own: the tools are the registry's, the effect is the capability's classification, the clients are the distribution's providers.

Where it sits

domain
Surfaces — One declaration in the repository becomes the command line, the HTTP API, MCP, the UI, the Cockpit, the documentation and this site, and a projection that disagrees with it fails the build.

Interfaces

Each capability behind it, on every interface it is projected onto. A link goes to this site's reference for that interface; an HTTP route and an MCP tool are answered by a running majordomus serve, not by this site.

The capabilities behind this feature, by interface
capabilitycommand lineHTTPMCP tool
repository.info —none GET /api/v1/repository majordomus_repository
repository.scope majordomus scope GET /api/v1/scope majordomus_scope
repository.scope_classify —none GET /api/v1/scope/classify majordomus_scope_classify
objects.get —none GET /api/v1/object majordomus_get
objects.list —none GET /api/v1/objects majordomus_list
objects.search —none GET /api/v1/search majordomus_search
objects.verify —none GET /api/v1/objects/verify majordomus_verify_objects
web.surfaces —none GET /api/v1/web/surfaces majordomus_web_surfaces
environment.explain —none GET /api/v1/environment/explain majordomus_environment_explain
environment.preflight —none GET /api/v1/environment/preflight majordomus_preflight
environment.status —none GET /api/v1/environment majordomus_environment
executions.cancel majordomus executions cancel POST /api/v1/executions/cancel majordomus_execution_cancel
executions.demonstrate —none GET /api/v1/executions/demonstrate majordomus_demonstrate_execution
executions.events majordomus executions events GET /api/v1/executions/events majordomus_execution_events
executions.get majordomus executions show GET /api/v1/executions/get majordomus_execution
executions.list majordomus executions list GET /api/v1/executions majordomus_executions
executions.protocol majordomus executions protocol GET /api/v1/executions/protocol majordomus_execution_protocol
executions.report —none POST /api/v1/executions/report —none
executions.start majordomus run POST /api/v1/executions/start majordomus_execution_start
commands.get —none GET /api/v1/command majordomus_command
commands.graph —none GET /api/v1/commands/graph majordomus_command_graph
commands.list —none GET /api/v1/commands majordomus_commands
editors.status —none GET /api/v1/editors majordomus_editors
entity.kinds majordomus entity kinds GET /api/v1/entity/kinds majordomus_kinds
entity.show majordomus entity show GET /api/v1/entity majordomus_entity
mcp.projection —none GET /api/v1/mcp majordomus_mcp
in the Cockpit, of a running server
/cockpit/api API
served by the executable
/api/v1 The capability registry over HTTP
/openapi.json The OpenAPI document of the capability registry
/swagger Swagger UI over the OpenAPI document
/mcp MCP over HTTP for attached clients
/docs The documentation, as this process serves it
/rustdoc The Rust crate's documentation, as rustdoc renders it

Evidence

What is guaranteed

Each claim this feature names, with the status its row declares, the verdict the recorded runs support, and the test that settles it.

Executable use cases

The rules that hold it

  • blocking A web surface is declared once and every web projection is derived from itproject.web-surface-declared-once
  • blocking A web surface is discovered from its producer, never registered twiceproject.web-surface-topology
  • blocking A native command line command exists only with its documentation and its executable examplesproject.native-cli-documented
  • blocking Nothing a client leaves behind locks another client outproject.shared-server-resilience

The decisions behind it

Using it

From the executable's command line

The synopsis of each, as the executable's own help prints it.

Where this page comes from

the file
.ai/repo/features/interfaces.md
the same answer
majordomus product show interfaces

Searches the titles and descriptions of every page this site publishes.