Rozhraní MCP

Co spustitelný soubor v Rustu pod apps/majordomus-cli/ poskytuje klientovi MCP, odkud to pochází a co odmítá. Chování tak, jak je implementováno a testováno; kde se implementace a tento dokument rozcházejí, je chybný dokument a mění se ve stejném commitu jako oprava. Vývojářský detail (architektura, každá volba, schéma druhu) je ve vlastním README.md aplikace.

Co to je

Proces, který klient spouští a který mluví Model Context Protocolem na svém stdin a stdout, obsluhuje AI vrstvu repozitáře (čtení a pojmenované příkazy, které mění stav) a připojuje se k jedinému sdílenému serveru repozitáře: první takový proces v repozitáři naváže loopback HTTP projekci vedle své stdio relace (domovská stránka s výpisem všech povrchů, dokumentace tohoto repozitáře, Swagger UI, dokument OpenAPI, každá routa schopnosti, MCP přes HTTP) a oznámí kde; každý další se k ní připojí.

cargo build --manifest-path apps/majordomus-cli/Cargo.toml
apps/majordomus-cli/target/debug/majordomus mcp --inspect    # what would be served, and every diagnostic
apps/majordomus-cli/target/debug/majordomus mcp              # serve until the client goes; the first one is the server
apps/majordomus-cli/target/debug/majordomus mcp --standalone # this client alone: no port, no lease, no peers
bin/majordomus-mcp                                           # the same, built first when needed: what a client configuration names

Log na stderr to pojmenuje v okamžiku, kdy server běží:

shared server listening on http://127.0.0.1:8741 — 7 surface(s): api http://127.0.0.1:8741/api/v1, cockpit http://127.0.0.1:8741/cockpit, docs http://127.0.0.1:8741/docs, home http://127.0.0.1:8741/, mcp http://127.0.0.1:8741/mcp, openapi http://127.0.0.1:8741/openapi.json, swagger http://127.0.0.1:8741/swagger; the one server of this checkout ...

Není to démon: nic jej nespouští kromě klienta, nic jej nedrží naživu kromě klientů a končí, když zmizí jeho vlastní klient a odejde poslední připojený. Nedrží žádný stav kromě paměti, nepotřebuje databázi a zapisuje jeden soubor: lease pod .ai/local/state/mcp/, lokální polovinou checkoutu, kterou vrstva vyhrazuje pro provozní stav, odstraněný při zastavení serveru. Je to jedna projekce registru schopností spustitelného souboru (CAPABILITIES.md): stejné schopnosti jsou trasy HTTP a příkazy capabilities a každý nástroj a zdroj zde je odvozen ze záznamu registru, žádný není deklarován v kódu MCP. Rozhodnutí je .ai/repo/adrs/0003-shared-mcp-server-peers-and-client-autostart.md.

Jeden server na checkout

Jeden repozitář, každý jeho server

Server obsluhuje checkout. Propojený worktree je vlastní checkout — má manifest, takže má kořen, lease i vlastní server — a do ADR 0035 nic neříkalo, že dva takové servery patří jednomu repozitáři. Nyní indexová trasa (GET /) jmenuje vedle identity samotného checkoutu i git repozitář, ke kterému checkout patří: commit je commit, ze kterého byl odpovídající spustitelný soubor sestaven, celý nebo unknown, a dirty zda jeho strom nesl necommitnuté změny (null, když to sestavení nevědělo) — stejná dvě pole odpovídají GET /api/v1/live a GET /api/v1/ready; stale je null, dokud je spustitelný soubor, ze kterého byl proces načten, stále souborem na disku, a říká proč, jakmile ho přestavba nahradila nebo odstranila — proces pak obsluhuje kód, který už neexistuje, a GET /api/v1/ready odpovídá ready: false se stejným důvodem (I1502); repository_id je checkoutu (otisk jeho kořene, s čím lease sonda porovnává), git_repository_id je repozitáře (otisk adresáře gitu, který sdílí každý worktree; chybí tam, kde se git nedá zeptat), linked_worktree říká, zda jde o primární checkout, a leaseholder říká, zda odpovídající proces je stále tentýž (níže). branch a head jsou větev a commit, z nichž byly obsluhované odpovědi čteny, jak je četl index (I1031). Domovská stránka a shell Swaggeru na /swagger nesou stejnou identitu na jednom řádku vedle svého obsahu; nic z toho není cesta, protože kdo dosáhne socketu, se dozví, který checkout odpověděl, a nikdy kde leží. GET /api/v1/server — nástroj majordomus_server, zdroj majordomus://server — vypisuje každý checkout, který git pro repozitář eviduje, primární první, každý s jeho leasem, stavem jeho serveru a počtem peerů, které drží, a říká, kde stojí server tohoto checkoutu měřeno proti tomu, co by obsluhoval tento spustitelný soubor:

Seznam je to, co volající dostane, když se na nic neptá, a stojí čtení lease a sondu na checkout — na počítači se sty registrovaných worktree sto od každého. Volající, který chce vědět jen o checkoutu, ve kterém je, to řekne — checkouts=this v query stringu, ve vstupu nástroje nebo --checkouts this na příkazové řádce — a toto čtení nevyčísluje žádný jiný checkout, nečte žádný jiný lease a nesonduje žádný jiný server. Výchozí je celý seznam, protože to je odpověď, kterou tato schopnost dávala dříve, než pole existovalo.

Lease samotný je jeden typ, čtený jednou (lease::LeaseDocument, lease::LeaseFile::read): volba, serving jen pro čtení, snímek prostředí a stav ho všechny parsují stejným čtením a nese version serveru vedle spustitelného souboru, z něhož byl spuštěn. .ai/local/state/mcp/server.json je stále místem, kde ho člověk čte pomocí cat; stav je místem, kde ho čte program.

Server, který už není tím serverem

Lease lze převzít, i když proces, který ho držel, stále běží a je zdravý — protože jeho spustitelný soubor byl nahrazen rebuildem, což volba čte jako „servíruje kód, který už není na disku“, nebo protože je to starší release než volící klient. Instalátor ukládá každý release do vlastního adresáře, takže upgrade mění cestu spustitelného souboru a kontrola rebuildu to nikdy nevidí; kontrola releasu ano. Rozhoduje jediný verdikt (lease::version_verdict) pro volbu, serve ensure i server.status, řadící releasy podle precedence sémantického verzování definované release::version::Version, takže server na 1.0.0-alpha.1 je novější než 0.29.0 a starší než 1.0.0-alpha.2 a 1.0.0:

Starší klient nikdy nepřevezme novější server, takže dva releasy vedle sebe nebojují o lease: drží ho novější (I2163). Nahrazený proces se nezabíjí. Drží svůj socket, svou nástěnku peerů a generaci vrstvy, kterou načetl, a obsluhuje relace, které už měl, dokud neskončí. Je to záměrné: klient uprostřed odpovědi nemá přijít o svůj server proto, že někdo spustil cargo build.

Co nesmí dělat, je dál být tím serverem. Od okamžiku, kdy jeho vlastní čtečka zjistí, že lease už nenese jeho token:

tests/mesh_lease_retirement.rs dokazuje převzetí se skutečnými servery: vyřazený proces stále odpovídá svému připojenému klientovi MCP, přestane se účastnit meshe a nástupce se synchronizuje se vzdáleným runtime bez opakovaných opětovných připojení.

Server příliš starý na to, aby odpověděl na třetí otázku, sonda přijme. Na tom endpointu jej nelze odlišit od aktuálního a jeho odmítnutí by bylo horším selháním: živý server považovaný za mrtvý se převezme, a tak se stane, že jeden checkout má dva.

Bylo to změřeno dřív, než to bylo napsáno: 2026-09-10 měl tento repozitář dva servery, jeden lease, a relace, jejíž prostředí nesla starší adresu, četla nástěnku peerů s jedním peerem, zatímco nástěnka, kterou sdíleli všichni ostatní, měla dva.

Čtyři významy slova „připraveno“

Tento spustitelný soubor odpovídá „ready“ čtyřikrát a audit, který podnítil ADR 0035, počítal tři z nich za nehodu (docs/ENTRY_AUDIT.md, příčina 5). Nejsou to jedna otázka špatně rozdělená: jsou to čtyři otázky o čtyřech subjektech a sloučení kterýchkoli dvou by ztratilo to jediné, co ten čtenář potřebuje. Každá je zde pojmenována se svým vlastníkem, aby další čtenář nemusel znovu objevovat, na kterou se dívá.

Čtěte sloupec shora dolů a žebříček je jasný: třetí se ptá, zda je socket otevřený, čtvrtý, zda proces za ním patří tomuto checkoutu, ze souboru na disku, v tomto buildu. Zastaralý server odpoví na třetí a selže na čtvrtém, což je přesně třída, která tento repozitář už stála den.

health.report nese čtvrtý a jen čtvrtý. První je pro každý povrch zvlášť a patří na stránku, která povrchy vykresluje; druhý je výrok o procesu, který report vyřizuje, a ten nemůže být nepravdivý tam, kde report vzniká; a třetí nerozezná živý server od socketu, který drží někdo jiný. Kontrola deleguje na capability::builtin::server::standing_at — stejné čtení, ze kterého odpovídá server.status — takže report o zdraví a stav nemohou říct dvě různá slova o jednom leasu.

Zajištění serveru a jeho zastavení

majordomus serve status [--checkouts this|repository] [--format json]
                                            where this checkout's server stands, and every server of the repository
majordomus serve ensure [--idle S] [--wait S] [--port P]
                                            a ready server for this checkout, started if it must be
majordomus serve stop [--wait S]            end the server this checkout's lease names

serve ensure přečte lease a vyzkouší server, který jmenuje, přesně jako volba, a konverguje: ready se vytiskne a nic se nespustí; na starting se čeká; absent a stale spustí server jako vlastní proces — tento spustitelný soubor, serve --fallback --idle S, jeho log na .ai/local/state/mcp/server.log, ve vlastní skupině procesů, aby přežil shell, který o něj požádal — a čekají, až je připraven; outdated spustí server jen tehdy, když by volba lease převzala (tentýž spustitelný soubor, vyměněný na disku, nebo starší release než tento spustitelný soubor) a jinak se hlásí s nápravou, protože server jiného buildu, který odpovídá, tento příkaz nekončí. Spuštěno dvakrát nespustí podruhé nic; spuštěno třemi shelly najednou nechá volba jeden ze tří serverů navázat a ostatní ustoupí. Volání je omezeno --wait; server, který se včas nepřipravil, se hlásí se stavem, jehož dosáhl, a exit kódem 10.

Server, který ensure spustí, nemá vlastního klienta. Skončí, když ho --idle sekund (ve výchozím stavu patnáct minut) nic nepoužilo — není připojena žádná relace MCP, nebyl zodpovězen žádný požadavek HTTP a není otevřen žádný živý kanál /events, takže člověk, který čte Cockpit nebo volá REST API, si server, který používá, ponechá (I2131) — což zachovává linii ADR 0003 — žádný proces bez klienta — platnou v čase, ne v každém okamžiku: vstup agenta má server dlužen před prvním připojením a checkout, ve kterém nikdo nepracuje, žádný nedrží.

serve stop pošle signál serveru, který jmenuje lease, pokud tento server odpovídá za tento checkout, a čeká, až lease toho serveru zmizí — dokument, který přečetl, podle jeho tokenu, nejen cesta — a pak až proces skončí. SIGTERM, který pošle, je uspořádané zastavení, ne kill: server dá připojeným peerům dvě sekundy na odchod, zavře jejich relace a epizody, které nesly, zavře své listenery (rozpracovaná odpověď se dokončí první), uvolní svůj lease a vyprázdní mesh. Soubor odstraní jen proces, jehož token soubor stále nese: každé odstranění a každé přepsání lease ho znovu čte pod zámkem vedle něj (.ai/local/state/mcp/server.lock), takže server zastavený těsně poté, co byl jeho lease převzat, nechá lease svého nástupce na pokoji. serve pak skončí s exit 0 vlastním návratem; zastavení, které nedoběhne do osmi sekund, nebo druhý SIGTERM ho přesto ukončí. serve ensure stále čekající ve volbě převezme uvolněnou cestu během milisekund, takže čekání na cestu by hlásilo server, který se nezastavil, ačkoli už se zastavil; převzetí se místo toho pojmenuje v odpovědi. Lease, který jmenuje server jiného checkoutu, nebo takový, který neodpovídá, se ponechá na pokoji a řekne se to; nic zde nezabíjí proces, který nebyl vyžádán jménem.

Kdo volá ensure. Volá ho startovní událost providera (session.ensure_server_on_start v politice, ve výchozím stavu zapnuto): jediný okamžik, kdy je dlužen server, který ještě nikdo nespustil, je příchod agenta, a briefing, který událost zapíše, nese jeden řádek — Shared server: ready http://127.0.0.1:8741 pid 123 — aby pracovník věděl už před prvním voláním nástroje, zda nástěnka, kterou má číst, existuje. Událost nikdy nesestavuje spustitelný soubor: chybějící nebo starší než jeho zdroje se v tom řádku pojmenuje a nechá být, protože hook není místo pro spouštění kompilátoru a server ze zastaralého kódu by odpovídal stromem ze včerejška. Launcher klienta MCP (bin/majordomus-mcp) konverguje vždy stejně přes volbu; shell vstupující do repozitáře (.envrc) je informován a není obsloužen, protože project.envrc-is-an-adapter zakazuje vstupnímu hooku cokoli spouštět a shell není klient.

Oznámení přežije server, kterému bylo učiněno. Most vidí každý rámec, který jeho klient pošle, takže si drží argumenty posledního oznámení, které server přijal, a řekne je znovu, kamkoli klient dopadne dál: po opětovném připojení, jakmile je relace znovu otevřena; po převzetí na nástěnku serveru, kterým se stal vlastní proces mostu. Worker, který oznámil jednou, je na nástěnce každého serveru, který ho obsluhuje, aniž by musel oznamovat znovu; pokyn oznámit znovu po opětovném připojení zůstává v bootstrapu pro jediný případ, který most nepokryje: klient, jehož vlastní proces je serverem a restartuje se.

Před čím volba nyní chrání. Vlastník udržuje své lease mladé, zatímco se vrstva načítá (Lease::keep_alive), takže studený start pomalejší než odklad vazby se nikdy nepovažuje za opuštěný; převzetí odstraní jen soubor, který posoudilo, nikdy ten, který mezitím dorazil, a dva voliči, kteří posoudili jedno lease jako zastaralé, skončí s právě jedním lease, protože každý před odstraněním znovu přečte soubor pod zámkem vedle něj; vlastník, jehož lease bylo převzato během vazby, odmítne publikovat a degraduje, místo aby přepsal adresu vítěze, a publikuje přes vlastní dočasný soubor, synchronizovaný před přejmenováním; a server, jehož lease je později převzato, je přestane nárokovat — nic, co dělá při odchodu, se nedotkne souboru, který patří někomu jinému — po dobu odkladu zaneprázdněnosti obsluhuje peery, které má, každého z nich předá aktuálnímu serveru a skončí. Čtečka samotného serveru také zapomíná relace HTTP, které přestaly pingovat, na každé cestě, a ne jen když vlastník čeká na odchod peerů, takže mrtvý peer nikdy nezůstane attached na nástěnce.

Rozhraní pojmenovává stroj

Lokální server se váže na loopback. Tato výchozí hodnota se nehýbe: vrstva, její diagnostika, její peeři a dva nástroje, které odpovídají o .ai/local/, nejsou pro každého hostitele v síti, ve které se notebook zrovna nachází.

Jeden stroj může chtít být dosažitelný — druhý stroj se připojující přes LAN, peer meshe vytáčející se dovnitř, telefon otevírající Cockpit — a do 0.14 byl jediný způsob, jak to říct, majordomus serve --host 0.0.0.0, psané ručně. To trvalo přesně tak dlouho jako proces: serve ensure, což spouští start relace a vstup do shellu, spouští server vůbec bez hostitele, takže příští zastavení z nečinnosti nebo příští relace vrátily checkout na loopback bez jediného slova a serve status celou dobu hlásilo desired 127.0.0.1.

Rozhraní se tedy čte z jednoho místa, které dědí každý starter:

export MAJORDOMUS_HTTP_HOST=0.0.0.0     # every interface; or one address of this machine

Z toho, že je to proměnná a ne nastavení, plynou čtyři věci:

• Patří stroji, nikdy repozitáři. Nic sledovaného ho nemůže nastavit. Klíč v .ai/repo/policy.yaml by způsobil, že by každý klon veřejného repozitáře naslouchal v jakékoli síti, ve které se probudí.
• Příkazová řádka vyhrává, prázdná hodnota není hodnota a hodnota, kterou nelze nikam navázat, odmítne start a pojmenuje adresu.
• Varování platí. Vazba zvolená proměnnou stále loguje, že každý hostitel dosahující na rozhraní může číst vrstvu; řádek logu před ním říká, že adresu pojmenovala proměnná, takže vazba není nikdy nevysledovatelná. Jen objekt deploymentu deklaruje expozici a jen deklarovaná je tichá.
• server.status odpovídá za prostředí, ve kterém se ptá. desired.host je to, co by server spuštěný z toho prostředí navázal, takže adresa, kterou server naváže, a adresa, kterou stav nazývá žádoucí, jsou jedno rozlišení (cli::resolve_http_host) a nemohou se rozcházet. Běžící server odpovídá serve status a odpovídá za prostředí, v němž byl spuštěn.

Nastavte to tam, kde to uvidí každý, kdo cokoli spouští — ve vlastním startovacím souboru shellu (~/.zshenv, ~/.profile). .envrc.local je pro jednoho z nich příliš pozdě: .envrc vyhodnotí majordomus-env enter, což zajistí server, dříve než načte .envrc.local, takže server, který spustí první cd, by proměnnou neměl, zatímco vše spuštěné z toho shellu poté by ji mělo.

Už běžící server si ponechá adresu, na kterou se navázal. Po nastavení proměnné majordomus serve stop a příští serve ensure — nebo příští relace — ho zvedne na pojmenovaném rozhraní.

Na tomto povrchu nejsou žádné účty ani tokeny, takže požadavek se posuzuje podle toho, odkud přišel (ADR 0126). Navázání mimo loopback poskytne každému dosažitelnému hostiteli povrch pro čtení a nic víc: požadavek z adresy, která není loopback, spustí schopnost jen tehdy, když schopnost čte (effect: read) nebo když je jejím vstupem podepsaná zpráva, kterou handler ověří proti politice důvěry — link.hello, link.sync a register meshe. Každá jiná trasa a každý nástroj MCP, který něco mění, odpoví volajícímu forbidden (HTTP 403) dříve, než se spustí jeho handler, včetně executions.start, který by jinak spustil libovolnou schopnost. Rozhodnutí se činí na každý požadavek, ne na relaci: id relace MCP je jméno, nikoli důkaz. Čtení se stále poskytuje celé síti, nešifrovaně; chcete-li zapisovat z jiného počítače, připojte se k loopback serveru přes SSH tunel (ssh -L 8741:127.0.0.1:8741 <machine>), jehož požadavky přicházejí z loopbacku.

Požadavek z loopbacku musí tento server pojmenovat adresou nebo localhost: požadavek, který jmenuje jiného hostitele, se odmítne forbidden dřív, než odpoví kterýkoli povrch, včetně čtení, protože přesně to posílá stránka, jejíž doména byla přinucena překládat na tento stroj (DNS rebinding). Požadavek z jiného hostitele smí stroj pojmenovat tak, jak jej zná. /swagger se servíruje s Content-Security-Policy, která připouští jen jeho připnuté soubory z CDN, jejichž integritní hashe stránka jmenuje, a jeho jediný inline skript.

Čím se spor posuzuje

O tom, který proces vlastní lease, rozhodují čtyři čísla a pátým zůstává vlastník schopen odpovídat. Jsou deklarována v bloku server: souboru .ai/repo/policy.yaml a čtou se jednou při otevření repozitáře: mcp i serve je čtou před první volbou, takže hodnoty níže jsou ty, které používá každá volba v procesu (I2129); dříve byla hodnota přečtená před politikou po celý život procesu zkompilovaným výchozím.

Do 2026-09-15 byly všechny zkompilované konstanty v apps/majordomus-cli/src/lease.rs: neměnné bez přebuildování, nikde neuvedené tam, kde by to čtenář hledal, a neviditelné pro každou projekci — přitom probe_timeout je přesně to číslo, které rozhoduje, zda živý vlastník drží, co vlastní. To je rozhodnutí o tom, jak je repozitář dozorován, nikoli implementační detail.

Schéma (share/schemas/majordomus/policy/policy.v1.schema.json) vlastní blok s additionalProperties: false, takže překlepnuté časování je odmítnuto místo čtení jako chybějící; test/cases/354_a_lease_contest_is_judged_by_a_declaration.sh to drží a lease::Timings::from_policy nese doc test dokazující, že deklarovaná hodnota je ta, která se používá, a že klíč, který politika vynechá, si drží svou konstantu. Dodané hodnoty jsou konstanty, které nahradily, takže jejich deklarace nezměnila chování — záměrně: změna způsobu, jak se soutěž posuzuje, má být vidět jako změna, a ne dorazit uvnitř refaktoringu.

Spuštění z klienta

Kořen tohoto repozitáře nese konfiguraci, kterou čte každý klient, všechny jmenují stejný launcher, takže první klient, který repozitář otevře, se stane serverem a ostatní se připojí:

The provider rows are the providers whose declaration names a client configuration; the whole set, with what each reads and where it keeps its scratch checkouts, is docs/generated/providers.md, generated from the same declaration.

bin/majordomus-mcp sestaví spustitelný soubor, když chybí nebo je starší než jeho zdroje (MAJORDOMUS_BUILD_PROFILE=release pro release build; MAJORDOMUS_BIN jmenuje spustitelný soubor a nikdy nebuilduje; MAJORDOMUS_NO_BUILD=1 odmítne sestavit a skončí s exit 12 s příkazem ke spuštění), nastaví MAJORDOMUS_SHARE na share/ distribuce vedle něj, nezapisuje nic na stdout a předá každý argument majordomus mcp. Klient nečeká na build. mcp je jediný příkaz, který klient spustí a pak na něj čeká, a klient, který nedostane handshake, hlásí server jako selhavší a pokračuje bez něj. Takže když tento checkout nemá spustitelný soubor ke spuštění, nebo takový, který nemůže přebuildovat — není cargo, je méně volného místa než práh buildu (MAJORDOMUS_MIN_FREE_MB, výchozí 5120), build selhal — bin/majordomus-mcp místo toho spustí nainstalovaný release (MAJORDOMUS_INSTALLED_BIN, výchozí majordomus v ~/.local/bin, kam jej dává install.sh) a na stderr řekne, který release a proč. Zastaralý spustitelný soubor, který lze přebuildovat, se přebuilduje jako dříve, MAJORDOMUS_MCP_BUILD=1 způsobí, že mcp builduje jako každý jiný příkaz, a každý jiný příkaz stále končí s exit 12, když nemá co spustit: záložní řešení je pro klienta, který by jinak byl odmítnut, nikdy způsob, jak nehlášeně spustit jiný release. Soubor uvnitř repozitáře se nikdy nebere za nainstalovaný release, ani takový, který neodpovídá na --version. ADR 0172; případ je test/cases/3177_a_client_always_gets_a_server.sh.

just mcp, just serve a just inspect v kořeni dělají totéž pro člověka; just docs-ui otevře Swagger UI běžícího serveru. Tentýž dokument, s tagy, příklady a stavy, je referencí API na webu na /docs/api/ a servíruje se surový na /openapi.json webu; instrukce initialize, OpenAPI info a GET / se otevírají jedním shrnutím z about.rs (CAPABILITIES.md).

Relace, která začíná připojením

Hook může jen přidat kontext; nic než první zpráva nezačne tah. Takže relace, která je pouze otevřena, dostane briefing a čeká, až člověk něco napíše, a dokud někdo nenapíše, není na nástěnce (ADR 0156, ADR 0172). share/shell/session-start.sh to pro Claude Code uzavírá: načtený z ~/.bashrc nebo ~/.zshrc obalí holé claude tak, že uvnitř repozitáře s vrstvou .ai/ je první zpráva majordomus prompt render session-start — vlastní prompt repozitáře (.ai/repo/prompts/session-start.md): řekni, jak jsi připojen, přečti nástěnku, najdi práci, která je dlužná, zkontroluj kolize, oznam a pak pracuj uvnitř rozsahu úlohy a vše drž lokální. Jakýkoli argument je vlastní argument člověka a předává se dál, stejně jako běh mimo dozorovaný repozitář, s MAJORDOMUS_NO_AUTOSTART=1, nebo když se prompt nedá vykreslit. Prompt je prompt repozitáře, takže jeho změna je commit a aktualizuje se každý checkout, který jej stáhne; soubor se dodává v share/ release a aktualizuje se s ním. test/cases/3221_a_bare_session_start_joins_the_cluster.sh to dokazuje v bash a zsh. Není nainstalován za vás: instalátor se nedotýká ničeho mimo svůj prefix (docs/DISTRIBUTION.md), takže načtení souboru je jediný řádek, který člověk přidá.

Claude in the browser

Three Claude surfaces meet a browser. Only one of them reaches this server today, and the other two must not be made to look as if they did:

A tunnel from the public internet to the loopback server would give a vendor's requests the loopback caller's right to change the repository (ADR 0126 judges a caller by its address), so none is set up. The side panel and the chat reach the mesh when a vendor caller has a listener of its own that authenticates it and serves reads only (I3285, which covers a claude.ai custom connector as well as a ChatGPT one), and the hosted hub serves the mesh over TLS to an authenticated caller only (the owner's decision of 2026-10-21: TLS first, then the hub, and no anonymous caller reads the mesh). Until then a side-panel session reads what is published: https://majordomus.dev and its /ui/, a snapshot built without a running mesh, which is why it says the mesh is not observed. To work on the live mesh from a page, drive the page from Claude Code.

Set it up once, per person rather than per repository:

• In Claude Code run /chrome and choose Enabled by default. It is a user setting: Claude Code ignores CLAUDE_CODE_ENABLE_CFC in a project's settings ("a project can't turn on Claude in Chrome", Claude Code documentation, code.claude.com/docs/en/chrome), so this repository does not try.
• Sign the extension in to the claude.ai organization that /status names in Claude Code. Claude Code needs a claude.ai login (Pro, Max, Team, Enterprise); an API key or a setup-token keeps the bridge off.
• The first enable writes the native messaging host — on macOS ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json, which runs claude --chrome-native-host — and Chrome finds it after a restart.

Every browser action still passes the extension's own per-site permissions; a rule in .claude/settings.json does not lift them, and this repository pre-approves no browser tool.

When it does not connect — list_connected_browsers answers an empty list, or a browser tool says "Browser extension is not connected":

1. The extension is not running, or it is signed in to another account or organization than /status names. Sign it in again with that organization.
2. /chrome → Reconnect extension, then restart Chrome and Claude Code.
3. An organization IP allowlist that blocks bridge.claudeusercontent.com blocks the bridge (Claude Code documentation, code.claude.com/docs/en/network-config).
4. A JavaScript dialog open in a controlled tab stops every later browser event until a person dismisses it.

The mesh half is diagnosed as always, from the same session: majordomus mesh doctor, and majordomus_peers for the board.

Peery

Každá relace je peer: vlastní stdio klient serveru, každý přemostěný majordomus mcp a každý klient mluvící přímo /mcp. Peer je pojmenován tím, co jeho klient poslal v initialize (clientInfo.name a version: claude-code, codex, gemini-cli, nebo jak se klient sám nazývá), číslován p1, p2, ... v pořadí připojení, s transportem, kdy se připojil a kdy byl naposledy viděn. instructions výsledku initialize řeknou klientovi URL serveru, jeho vlastní id peeru a každého dalšího peera s tím, co oznámil, před prvním voláním nástroje.

Oznámení je jeden řádek záměru a cesty relativní k repozitáři, kterých se peer chystá dotknout. Nástěnka žije v paměti serveru a zmizí s procesem; peers.announce je druhu command, protože mění tuto paměť, a klientům MCP se oznamuje jako ne read-only. Přes prosté HTTP není žádný volající, takže POST /api/v1/peers/announce se odmítne (422) a GET /api/v1/peers odpovídá bez caller.

Nástěnka patří repozitáři (ADR 0044)

Server servíruje checkout, takže repozitář, na němž se pracuje přes linked worktree, má jednu nástěnku na worktree — a až do ADR 0044 odpovídal peers.list jednou z nich, zatímco bootstrap v CLAUDE.md a AGENTS.md říkal každému workeru, že viděl repozitář. Změřeno 2026-09-11: sedm živých serverů, jeden git_repository_id, sedm nástěnek, devět agentů napříč šedesáti worktree, z nichž každý četl nástěnku, která držela jen jeho.

peers.list nyní sbírá. Vyjmenuje checkouty, které git registruje, a přečte zápůjčku každého — týmiž čtečkami, jaké používá server.status — vlastní nástěnku vezme z paměti tohoto procesu a každého dalšího checkoutu, jehož server odpovídá, se zeptá na jeho vlastní nástěnku samotnou (checkouts=this). Ten parametr drží sběr hluboký jeden skok: server dotázaný na this nevyjmenovává žádný checkout a nezkouší žádný server, takže se nikdy nemůže zeptat zpět. Bez něj není žádné opakování, protože server příliš starý na to, aby parametr znal, by odpověděl celou svou nástěnkou a cyklus je jediné selhání, které to mít nesmí; takový checkout se místo toho hlásí jako nepřečtený s důvodem.

Id peera je pozice na jedné nástěnce, přidělená v pořadí připojení a po opětovném připojení přidělená znovu — relace, která byla dnes ráno p3, je p1, jakmile se její most znovu připojí. Nic podle něj nesmí korelovat pracovníka v čase; checkout, který peer nese, je trvalá polovina jeho identity. Oznámení rovněž patří spojení: most zopakuje poslední oznámení svého klienta po opětovném připojení nebo převzetí a pracovník, jehož proces mostu je nahrazen, oznamuje znovu.

Stojí jedno čtení lease na registrovaný checkout, jednu sondu na checkout, jehož lease pojmenovává adresu, a jeden round trip na server, který odpoví. V tomto repozitáři 2026-09-11 — 118 registrovaných checkoutů, 7 živých serverů — trvalo vyčíslení a sondování, které server.status už provádí, 3,0 s wall.

Claim se zodpovídá, nejen zaznamenává. peers.announce porovná rozsah, který dostane, se všemi ostatními oznámeními a vrátí peery, jejichž claimy se s ním setkávají, s dvojicemi cest, které se setkávají: dva claimy se setkávají, když jsou stejné nebo je jeden uvnitř druhého (apps obsahuje apps/majordomus-cli; app ne, protože claim je cesta, ne prefix řetězce). peers.list hlásí tytéž kolize napříč celou nástěnkou, každou dvojici jednou. Stále to není vynucování, ani check --overlap shellového nástroje, které hlásí rozsahy úloh jiných worktree a končí s 0. Odmítá rozsah vlastní úlohy z start --scope, při check, při finish a v hooku pre-push — ale kolize je nyní známa v okamžiku svého vzniku, a ne objevena později v historii větve.

Nástěnka dosáhne i na workera, který o ni nikdy nepožádá. Čtení bylo dobrovolné a dobrovolná spolupráce selhala: relace se ohlásila, její transport se obnovil pod novým id peera a osm dalších ji tři hodiny nevidělo; dvě relace postavily týž subsystém, protože se ani jedna nepodívala. Proto majordomus context — příkaz, který bootstrap nařizuje každému workerovi spustit před prací — nese sekci PEERS mezi GIT a TASK: kdo další je připojen, co si každý z nich nárokuje a konkrétně které z těch nároků se dotýkají rozsahu aktuální úlohy. Čte lease sdíleného serveru (který je vázán na repozitář, takže jej linked worktree najde přes --git-common-dir v primárním checkoutu) a ptá se GET /api/v1/peers. Nápověda nikdy nenese zátěž: bez lease, bez jq či curl, se serverem, který neodpoví do dvou sekund, nebo s nástěnkou, na které nikdo není, zůstane context přesně takový, jaký byl, protože repozitář s jediným workerem nesmí dostat sekci o tom, že je sám. test/cases/106_context_peers.sh to celé drží.

Oznámení přežije spojení, které ho učinilo. Relace, která se znovu připojila, dřív mlčky ztratila vše, co řekla, sama sobě i všem ostatním; nástěnka nyní drží oznámení odešlého peera a vypisuje ho s attached: false, takže to, na čem relace řekla, že pracuje, přežije přerušený socket. Peer, který nikdy neoznámil, nezanechá nic, uchovává se nejnovějších 32 odešlých peerů, aby server, který běžel celý den, nebyl muzeum, a připojený peer se nikdy nevyhodí, aby se uvolnilo místo pro toho, kdo odešel. count z peers.list jsou skutečně připojení peeři; pole peers je delší, když nástěnka drží to, co kdo řekl, než odešel.

Epizody

Peer je spojení. Epizoda je posezení práce a pro klienta bez vlastních hooků poskytovatele je spojení jediné, co může nakreslit její hranici (ADR 0103). Do té doby bylo kreslení hranice pod modelem zapojeno jen pro Claude Code a tvrzení repozitáře, že to dělá, bylo tvrzením o jednom dodavateli.

stateDiagram-v2
  [*] --> Attached: initialize, a peer attaches and no episode opens
  Attached --> Open: episodes.attach opens the episode, or resumes this client's own
  Open --> Open: every message is the episode's heartbeat
  Open --> Detached: the connection goes, detached and not closed
  Detached --> Open: episodes.attach again resumes the same episode under a new peer id
  Open --> Closed: episodes.detach closes it deliberately into a session record
  Detached --> Closed: no reconnect in 15 minutes, the reaper closes it as interrupted
  Open --> Closed: the server stops, closed as shutdown
  Detached --> Closed: the server stops, closed as shutdown
  Closed --> [*]

initialize nic neotevírá. Klient, který otevře server jen proto, aby přečetl jedno pravidlo, není pracovník a nezanechá žádný záznam; attach je volání, které provede klient, který ví, že chce epizodu. To je také to, co drží záruku, kterou drží test/cases/90_mcp_shared_server.sh — obsluha repozitář vůbec nemění.

Identita patří klientovi, nikdy ne id peera. external_id je to, čemu klient trvale říká sezení, ve kterém je — id jeho konverzace nebo vlákna — a jeho celým úkolem je přežít opětovné připojení. Id peera se přiděluje na připojení a je pokaždé, když se klient vrátí, jiný řetězec; považovat jej za trvalé je to, co udělalo relaci neviditelnou pro osm dalších po tři hodiny dne 2026-09-09.

Přerušené spojení se odpojí; nezavře se. Zmizení klienta řídí dvoje hodiny a odpovídají na dvě otázky. SESSION_IDLE_TIMEOUT (90 s) rozhoduje, kdy se socket zapomene. episodes::REATTACH_GRACE (15 minut) rozhoduje, kdy je práce u konce. Čtenář logů uvidí spojení vyklizené dlouho před epizodou, kterou neslo, a je to záměr.

Nic zde nezapisuje záznam relace. Nástěnka spouští majordomus capture session --provider generic --event start|end — stejný příkaz, který spouští shim hooku poskytovatele, se stejným tvarem payloadu, přes stejný čtecí kód — a hlásí, co řekl, doslova, v poli repository epizody. Druhý zapisovač záznamu, který už hooky zapisují, by byla opakovaná sémantická definice, kterou CAPABILITIES.md zakazuje. Vlastní úložiště repozitáře je také to, co epizodu obnoví po restartu serveru: zabitý server nezapíše žádnou koncovou událost, epizoda zůstane otevřená v .ai/local/state/sessions-open/ a další attach pod stejnou identitou je session start --if-open keep, který ji zachová.

Zachycení surového promptu tu není a je deklarováno, že není. MCP server dostává initialize, volání nástrojů a oznámení; prompt osoby mezi nimi není nikdy, v žádné verzi protokolu. share/providers.yaml říká prompts: none pro generického poskytovatele, s tímto zdůvodněním v poli důkazů, a pod prompts neexistuje hodnota connection, po které by kdokoli mohl sáhnout. Co každý poskytovatel umí a kde to bylo ověřeno, je majordomus product providers a majordomus capture status.

Co rozhoduje o tom, co se obsluhuje

Program nejmenuje žádný soubor repozitáře kromě dvou konvencí, které vrstva sama dokumentuje, .ai/manifest.yaml a sources.yaml v sekci knowledge, a jak se který druh čte, zjišťuje za běhu z distribuce nástroje. Zbytek jsou data:

Důsledky, na které se repozitář může spolehnout:

• nové pravidlo, prompt, profil, milník, úkol, tvrzení nebo dokument se servíruje, jakmile jej git add vloží do stagingového indexu, bez změny spustitelného souboru a bez restartu: staging přesune soubor, který server sleduje, takže příští požadavek přestaví vrstvu (project.the-server-sees-the-current-tree);
• nová třída v sources.yaml pojmenovávající známý druh nebo nový druh se schématem pod .ai/repo/knowledge/ se servíruje stejně;
• .ai/local/ se nikdy neservíruje, ať je sledován, či ne;
• čtené YAML je podmnožina, kterou definuje SCHEMAS.md, takže soubor, který shell nástroj odmítne, se odmítne i zde, se jmenovaným stejným řádkem.

Zdroje

URI se rozřeší jednou, jednou funkcí, ať se na něj ptá kdokoli: resources/read, nástroj majordomus_get i GET /api/v1/object odpovídají na stejné URI stejně. URI, které registr nezná, se na žádném z nich nenajde. majordomus://repository je dotaz (repository.info) s expozicí zdroje: přečtený jako zdroj je to report jako text JSON; přečtený přes majordomus_get je to report jako data (answer) se stejným textem vedle (content). Registr odmítne dotaz vystavený jako zdroj, jehož vstup cokoli vyžaduje, protože čtení nic nedodá.

Objekt má také adresu, kterou URI není: majordomus://rule/project.x@1 je identita a /cockpit/objects/rule/project-x-1 je to, kam je čtenář poslán. Adresa se odvozuje z druhu a identity jednou funkcí, takže existuje pro každý objekt a je stejná na každé ploše; majordomus_entity odpovídá na obě podoby a majordomus_kinds hlásí všechny dvě identity jednoho druhu, které se redukují na jednu adresu. majordomus_entity také jmenuje veřejnou stránku dokumentace objektu (documentation: projekce, route, url, nebo reason, jeho druh není publikován), čtenou z site/data/publication.toml repozitáře a base_url webu — null, když repozitář žádnou publikaci nedeklaruje.

Identita jsou identitní pole druhu spojená pomocí @ — majordomus.scope-integrity@1 pro pravidlo, continue pro prompt, implementation pro profil, M001 pro milník — nebo, u druhu bez identitních polí (politika, dokument), cesta relativní k repozitáři. Každý vypsaný zdroj nese _meta.majordomus s druhem, identitou a proveniencí: cesta, adresář, třída, která jej objevila, sekce manifestu, pod kterou spadá, a jeho velikost.

Nástroje

Tabulka výše je základní sada, ne celek: seznam nástrojů je projekce registru schopností, roste s každým složeným modulem a seznam v próze, který by tvrdil úplnost, by byl příště nepravdivý. majordomus_capabilities a docs/generated/capabilities.md jsou odvozená, úplná reference; to, co je napsáno zde, je to, co čtenář potřebuje před jejím otevřením.

Relace a kontinuita

Dva z nástrojů odpovídají o .ai/local/ — polovině vrstvy, která jmenuje tento stroj — a jsou důvodem, proč se server váže na rozhraní loopback. Servírují se a nikdy nepublikují: žádný generátor je nezapisuje do docs/generated/ a žádná stránka webu žádný z nich nenese.

První odpovídá na otázku workera a ostatní na otázky operátora, což je jiná otázka, ne nadmnožina: continuity.state následuje state/session-current.yaml a tento ukazatel je symlink, který přesměruje nejnovější startovní událost. CONTINUITY.md obsahuje model a celou cestu.

Popsaná projekce

mcp.projection — nástroj majordomus_mcp, zdroj majordomus://mcp, trasa GET /api/v1/mcp, stránka Cockpitu /cockpit/mcp a první řádky majordomus mcp --inspect — odpovídá na to, co by tento dokument jinak musel vypisovat a ručně udržovat pravdivé:

majordomus mcp --inspect    # its lines beginning server, protocol, effect, writes and client are this answer
curl -s http://127.0.0.1:8741/api/v1/mcp | jq '{server, protocol_versions, effects, writers, clients}'
curl -s 'http://127.0.0.1:8741/api/v1/mcp?effect=repository_mutation' | jq '.tools[].name'

Nic v tom není vlastním seznamem, takže se nemůže rozejít s tools/list: schopnost, která získá nástroj, je v odpovědi, na stránce Cockpitu i v generované referenci při dalším požadavku, aniž by se upravil jiný soubor.

Co smí nástroj měnit

Anotace nástroje se nepíší v kódu MCP: jsou to klasifikované nápovědy schopnosti (ExecutionPolicy::hints), které vyplývají z jejího efektu, a efekt samotný nese _meta.majordomus.effect.

Klasifikace je konzervativní ve směru, který volající přežije: nic, co něco mění, se neohlašuje jako bezpečné k opakování, protože žádný handler nedeklaroval, že druhé volání je prázdná operace, a cokoli, co zapisuje repozitář, se ohlašuje jako schopné přepsat nebo odstranit. openWorldHint je všude false, protože žádný handler nesahá za hranice stroje: pozorování forge a konzultace poradce jsou příkazy, které spouští člověk, ne schopnosti. Které nástroje zapisují repozitář, není nikdy seznam v tomto dokumentu: jmenují je instrukce initialize, odvozené z registru, a také majordomus mcp --inspect. Každý nástroj nese kanonické id v _meta.majordomus.id a své inputSchema a outputSchema z kanonických schémat. Odmítnuté volání je výsledek s isError: true, důvodem jako textem a kategorií jako jedním slovem v _meta.majordomus.error.code — invalid_input, not_found, refused nebo forbidden, stejným slovem, jakým odpovídá trasa HTTP jako error.code, protože obojí čte z téže chyby. Odmítnutý výsledek nenese structuredContent: výstupní schéma popisuje úspěch. Neznámý nástroj, metoda nebo zdroj je chyba protokolu.

Chování při selhání

Každý řádek jmenuje selhání, co klient pozoruje a co to dokazuje: testy, které ho řídí, nebo uvedené omezení, které říká, proč to nedělá nic. Řádek bez obojího, nebo takový, který cituje test či případ, jenž tento strom nemá, test/cases/3056_every_failure_class_names_its_proof.sh odmítne.

Dva soubory jednoho druhu, které si nárokují jednu identitu, jsou oba vyloučeny a oba pojmenovány, jak vyžaduje smlouva pravidel. Nic se neopravuje, nedoplňuje výchozími hodnotami ani nepřepisuje.

Záměrně neposkytováno

• Prompty MCP. Prompt assety repozitáře vykreslují {{CONTEXT}} z lokálního stavu checkoutu, který vlastní nástroj shellu; servírované nevykreslené by vypadaly jako hotové. Jsou to zdroje (majordomus://prompt/<name>), nikoli prompty.
• Hierarchie bootstrap souborů. Kořenový README.md, AGENTS.md a další soubory providerů se servírují jako dokumenty se zaznamenaným adresářem; nic je nesloučí ani neseřadí, protože repozitář nedefinuje žádnou sémantiku slučování. Zaznamenáno v .ai/repo/adrs/0001-rust-cli-and-stdio-mcp.md.
• Mutace repozitáře, která není schopností. Nástroj zapisuje do repozitáře jen tehdy, když jeho schopnost deklaruje .writes_repository(); handler je ten, který dosahuje trasa HTTP a příkazový řádek, takže odmítnutí tam je stejné odmítnutí zde a MCP nepřidává žádného vlastního zapisovatele.
• Odběry, oznámení o změně seznamu a stream iniciovaný serverem na /mcp (tento server nic neposílá bez vyzvání). HTTP projekci téhož registru poskytuje sdílený server a majordomus serve; viz CAPABILITIES.md.
• Trvalá koordinace. Nástěnka peerů je paměť jednoho procesu a sesbíraná nástěnka je čtení několika z nich v okamžiku dotazu: na čem peer pracuje napříč relacemi a stroji, to je záznam úlohy a rozsah nástroje shellu, ne tohle. Větev pushnutá před začátkem relace nenese žádné oznámení a jejím claimem není o nic méně; čtečkou pro ni je scripts/collision-check.

Co to dokazuje

test/cases/72_rust_mcp.sh sestaví exekutor a mluví s ním přes roury uvnitř repozitáře, který napsal init nástroje shellu, a čte majordomus://repository přes nástroj a čtení zdroje, aby viděl jednu odpověď; 76_capabilities_projections.sh přečte jednu schopnost zpět přes každé rozhraní; 90_mcp_shared_server.sh spustí dva klienty přes bin/majordomus-mcp v takovém repozitáři a ověří, že oba obsluhuje jeden server, že každý vidí druhého, že lease přichází a odchází se serverem a že tři konfigurace klientů jmenují launcher. Vlastní sada crate (cargo test --manifest-path apps/majordomus-cli/Cargo.toml) pokrývá příkazovou řádku, výběr kořene, kontrakt metadat, determinismus, kolečko protokolem, stdout jen protokolu, nemutaci, sekvenci přidat–odebrat–rozbít u externího rozšíření a v tests/mcp_shared.rs sdílený server nad skutečnými rourami a sockety: volbu, most, relace /mcp, záložní port, odkládání serve, --standalone, převzetí po zabití, opětovné připojení, zamítnutí, když přebírající nemůže obsluhovat, převzetí poškozeného, cizího, prázdného nebo opuštěného lease, dva klienty startující ve stejný okamžik, nezapisovatelný adresář lease degradující na samostatnou relaci, SIGTERM zastavující server v pořadí a nezanechávající žádný lease (tests/lease_holder.rs: signál po převzetí šetřící lease nástupce a serve stop uzavírající epizody serveru a končící 0), poškozený provoz na /mcp a průhlednost mostu: přemostěná relace a restartovaný server odpovídají bajt po bajtu tak, jak odpověděl první server. Doktrína za tabulkou selhání je pravidlo project.shared-server-resilience. tests/server_status.rs drží případ dvou worktrees a případ zastaralého lease; tests/health_server.rs drží kontrolu server z health.report proti skutečnému serveru, checkoutu, který nikdo neobsluhuje, a lease jmenujícímu adresu, na které nikdo neodpovídá, a ověřuje, že kontrola a status říkají o jednom lease jedno slovo. test/cases/992_the_local_bind_is_the_machines_to_name.sh drží rozhraní: loopback, když žádné nic nejmenuje, proměnná následovaná serve, serverem, který spouští serve ensure, a tím, který volí mcp, vítězný příznak, ignorovaná prázdná hodnota, zachované varování, shodující se desired.host a nenavazatelná adresa zamítnutá bez lease; 85_deployment_bind.sh drží vedle toho deklarovanou adresu. tests/hot_path.rs pošle stovky rámců a vyžaduje nezměněné startovní čítače (majordomus_perf); majordomus bench změří čas každého nástroje přes skutečný podřízený proces (CAPABILITIES.md). Tvrzení jsou v CLAIMS.yaml pod mcp-, hot-path-no-rebuild a benchmark-coverage-derived.