1. Rust spustitelný soubor s datově řízeným MCP povrchem jen pro čtení přes stdio
Kontext
Majordomus je nástroj v shellu, který validuje, promítá a vynucuje vrstvu .ai/ repozitáře. Klienti AI, kteří mluví Model Context Protocolem, nástroj v shellu číst nemohou; spouštějí proces a mluví s ním JSON-RPC. Vlastní dokumenty repozitáře „povrch MCP“ odmítly (README „What this is not“, CONTRIBUTING.md, seznam odložených v docs/DESIGN.md, docs/EXTRACTION_REPORT.md) na základě důkazu, že žádný démon, server, databáze ani fronta nevyřešily problém, který souborové mechanismy nevyřešily. Tento důkaz platí; to, proti čemu argumentoval, byla infrastruktura, ne čtenář.
Operátor požadoval plnohodnotný Rust spustitelný soubor, majordomus, jehož první příkaz servíruje vrstvu klientům MCP, přičemž struktura toho, co se servíruje, se odvozuje z dat repozitáře, ne zapisuje do kódu.
Rozhodnutí
- Jeden balíček Rustu,
apps/majordomus-cli/, sestavující binárku pojmenovanoumajordomus, sclappro příkazovou řádku a jedním příkazem,mcp.apps/je nové: spustitelný soubor je produktový povrch, ne pomocník, takže nepatří podscripts/anibin/. - Transport: pouze stdio, jeden proces na klienta, živý tak dlouho, dokud žije roura klienta. Žádný port, démon, stav, databáze ani síť.
- Jen pro čtení a prokázáno: relace nechá
git statusa každý sledovaný blob bajt po bajtu shodný. - Řízeno daty: kořen je nejbližší
.ai/manifest.yaml; manifest jmenuje sekce;.ai/repo/knowledge/sources.yamlmapuje pathspecy na druhy a objevování jde přes index gitu, jak předepisuje smlouva o znalostech; klíčové smlouvy jsou tytéžshare/allow/*.txt, které používá shellový nástroj, vložené při sestavení; spustitelný soubor dodává jeden vlastní deklarativní soubor,schema/kinds.yaml, který říká, jak se každý druh čte. - Čtečka YAML implementuje zdokumentovanou podmnožinu vrstvy, ne obecný YAML, takže oba executables přijímají a odmítají tytéž soubory.
- Žádná knihovna MCP: podmnožina jen pro čtení, kterou server potřebuje, je osm metod, držených v jednom souboru za indexem, aby se do domény nedostal žádný typ třetí strany a knihovna mohla ten soubor později nahradit, aniž by se dotkla discovery či metadat.
- Politika selhání, rozhodnutá jednou: manifest a
sources.yamljsou chyby; jakýkoli jiný soubor, který se nemůže stát objektem, je vyloučen s pojmenovanou diagnostikou a index jedegradeda dál slouží;--strictdegradovaný index odmítne.
Invariant
Rust nese mechanismus: číst formát, validovat klíče proti seznamu, brát identitu z pojmenovaných polí, mluvit protokolem. Repozitář nese znalost: které soubory, které druhy, které klíče. Přidání objektu známého druhu nebo nové třídy známého druhu je změna dat; přidání druhu je záznam schématu plus, když druh potřebuje nový formát nebo pravidlo identity, kód.
Vůči seznamu „Intentionally Absent“, bod po bodu
| seznam odmítá | toto rozhodnutí |
|---|---|
| démon, server, monitor na pozadí | žádný: proces je potomkem klienta a zaniká s ním |
| databáze, fronta, vektorové úložiště | žádná: jeden in-memory index na vyvolání |
| registr nebo katalog pojmenovaných pracovníků | žádné: index drží vlastní deklarované objekty repozitáře, nic svého |
| nález bez příkazu reprodukce | každá diagnostika nese stabilní kód a cestu; mcp --inspect ji reprodukuje |
| vlastní hlášení, kterému se věří bez nezávislé kontroly | test/cases/72_rust_mcp.sh mluví se sestavenou binárkou přes roury v repozitáři, který init napsal |
| číslo napsané tam, kde by ho mohl spočítat příkaz | spustitelný soubor počítá každý počet, který hlásí |
Zamítnuté alternativy
- Rozšířit shellový nástroj o příkaz MCP. Rámování JSON-RPC, serializér JSON a dlouho žijící smyčka nad stdin v bash 3.2 by zopakovaly ručně psaný serializér, který zpráva o extrakci odmítla; hranice přenositelnosti shellového nástroje je silnou stránkou pro hooky a přítěží pro protokolový server.
- Python. Žádný Python není v toolchainu ani CI repozitáře; přidat závislost na interpretu pro jeden příkaz odporuje „nic jiného“ v požadavcích.
- Samostatný produkt MCP nebo démon. Druhý proces s vlastním životním cyklem je infrastruktura, kterou návrh odmítá, a potřeboval by vlastního čtenáře vrstvy.
- Natvrdo zapsaná tabulka nástrojů a zdrojů v Rustu. Rozešla by se s vrstvou při prvním novém pravidlu a je přesně tím druhým zdrojem pravdy, jemuž má
28_no_hardcoded_values.shzabránit. - Crate pro MCP. Oficiální Rust SDK je udržované a fungovalo by; přináší asynchronní runtime, knihovnu schémat a makra pro server, který potřebuje osm metod jen pro čtení, a jeho typy by seděly tam, kde mají být typy domény. Vratné: soubor protokolu je jediné místo, kde žijí tvary na drátě.
- Obecný YAML crate. Přijímá, co vrstva odmítá (kotvy, blokové skaláry), a odmítá, co vrstva přijímá (nekvótovaný skalár nesoucí
:, hodnota začínající zpětným apostrofem); oba programy by se o témž souboru rozcházely. - Jakákoli závislost na Prismatic. Odmítnuto pravidlem clean-room; žádná neexistuje na úrovni kompilace, běhu, nasazení ani provozu.
Důsledky
Pozitivní: jeden executable, který může klient MCP spustit; povrch roste s vrstvou bez změny kódu; každé tvrzení má black-box test; z konstrukce nezávislé na poskytovateli, protože jména poskytovatelů se nikde v kódu neobjevují.
Negativa a přijatá: schema/kinds.yaml, schéma URI zdrojů, názvy nástrojů a diagnostické kódy se stávají kompatibilitním povrchem; spustitelný soubor vkládá share/allow/ a sestaví se proto jen zevnitř tohoto repozitáře; vrstvu nyní čtou dva spustitelné soubory a 72_rust_mcp.sh je kontrola, že se shodují; dokumenty, které MCP povrch odmítaly, nyní rozlišují infrastrukturu (stále odmítnutou) od čtečky přes stdio.
Nevyřešeno, zaznamenáno místo vymyšleno
Hierarchický kontext (kořen README.md, AGENTS.md, soubory poskytovatelů a cokoli může nést podadresář) nemá na master sémantiku slučování. Spustitelný soubor zaznamenává adresář každého dokumentu a nic nekomponuje. Když kontrakt definuje repozitář, spustitelný soubor jej čte z dat jako cokoli jiného.
Strategie testování
Nejprve black-box: přeložený binární soubor se spouští pro CLI, objevování, protokol a sekvenci rozšíření přidat–odebrat–rozbít; index se cvičí přes knihovnu jen kvůli determinismu napříč oběma výčty. test/cases/72_rust_mcp.sh je křížová kontrola proti vlastní kostře shellového nástroje a CI spouští cargo fmt --check, clippy -D warnings a cargo test vedle behaviorální sady.