Library Registry

Summary

The Aetos ecosystem provides internal libraries for the shared concerns of every application. Use them. Writing a private copy of any capability below is a defect.

Each library also exposes its own documentation as an MCP server. An AI agent can read a library's full API by connecting to its MCP and reading docs://index, docs://nav, and docs://modules/{module}.

Catalog

Library	Import	Purpose	Use instead of	MCP
DAG Pipe	`dagpipe`	Deterministic state-transformation DAG engine	hand-rolled orchestration/topological ordering	`:8006`
Hexa	`hexa`	Declarative DI / composition-root tooling	manual wiring, hand-written factories	`:8008`
Mongo Ops	`mongo_ops`	Async MongoDB repositories, cache, populate, transactions	raw Motor CRUD and connection lifecycle	`:8007`
Omniread	`omniread`	Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX)	custom scrapers/parsers	`:8003`
OpenAPI First	`openapi_first`	Spec-first FastAPI bootstrap, client, codegen	decorator routers and hand-written clients	`:8004`
Mail Intake	`mail_intake`	Provider-agnostic read-only email ingestion	Gmail OAuth + MIME parsing	`:8002`
Py JWT	`jwtlib`	JWT auth primitives (register/login/introspect)	password hashing + token code	`:8005`
Doc Forge	`docforge`	Docstring compiler → MkDocs + MCP docs	custom doc generators	`:8001`
Doc Weaver	`doc-weaver`	JSDoc compiler → TypeDoc + MCP docs (React/TS)	custom TypeScript doc generators	`:8010`
React Auth	`react-auth`	JWT-backed React auth UI: provider, login page, profile screens, bearer axios client	hand-rolled auth contexts and token handling in React apps	`:8011`
React OpenAPI	`react-openapi`	Spec-driven React admin UI (CRUD, tables, forms, SSE) derived from an OpenAPI document	per-resource hand-written admin screens	`:8012`
Auth Server	(service)	Central identity service (register/login/me/logout/introspect)	building auth endpoints yourself	spec: `docs://spec`

How to choose

You need to…	Use
persist and query documents	Mongo Ops
compose dependencies	Hexa
run a multi-step transformation	DAG Pipe
read/parse an arbitrary input format	Omniread
expose a contract-first HTTP API	OpenAPI First
ingest email	Mail Intake
authenticate users / verify tokens	Py JWT (+ Auth Server)
generate documentation	Doc Forge
generate React/TypeScript documentation	Doc Weaver
authenticate a React front-end	React Auth (+ Auth Server)
build a React admin UI from an OpenAPI spec	React OpenAPI

Discovery

A single standards MCP exposes find_library(capability), which returns the matching library, its import name, its "use instead of" guidance, and its MCP endpoint (or, for the auth-server service, a spec pointer). It also serves the pinned auth-server OpenAPI contract at docs://spec. Query it before writing any infrastructure.

Publishing & registry auth

Python packages publish to the private index (pip.aetoskia.com, pypiserver) and npm packages to the private registry (npm.aetoskia.com, Verdaccio). Both authenticate against the same htpasswd file (/auth/htpasswd) used by the Docker registry and the Traefik basic-auth middleware; registration is disabled, so the CI credentials (PIP_USERNAME / PIP_PASSWORD, NPM_USERNAME / NPM_PASSWORD) are one and the same account — there is no separate npm user. Verdaccio requires bcrypt htpasswd entries; see 90 – Drone Pipelines for the CI wiring.

Endpoints

Registry	URL	Backend	CI secret
PyPI	`https://pip.aetoskia.com`	pypiserver (`server-pi:6007`)	`PIP_REPO_URL`
npm	`https://npm.aetoskia.com`	Verdaccio (`server-pi:6008`)	`NPM_REPO_URL`

Both are exposed through Traefik on the websecure entrypoint as bare origins — no path, no trailing slash. Set the secret values exactly as above.

npm: scope the registry, never set it globally

Verdaccio here has no uplink / proxy, so it can only serve @aetoskia/* packages. A global registry=https://npm.aetoskia.com in .npmrc would route every dependency — including public transitive deps such as zod-to-json-schema (pulled in by @modelcontextprotocol/sdk) — through Verdaccio, which 404s on anything it does not host. Always scope the registry to the account:

1 2	`@aetoskia:registry=https://npm.aetoskia.com //npm.aetoskia.com/:_auth=<base64(user:password)>`

Public deps then resolve from registry.npmjs.org and only @aetoskia/* hits the private registry. The auth line must be scoped to the host (//host/:_auth=), not a bare _auth= — modern npm rejects the bare form with ERR_INVALID_AUTH. The drone template derives both from the package scope and NPM_REPO_URL automatically; see 90 – Drone Pipelines.

The Drone pipeline runs each commands: list item in a separate shell, so shell variables defined in one item do not survive into the next. Keep the variable definitions and the commands that use them in the same | block.

Verdaccio storage permissions

Verdaccio runs as uid 10001 (verdaccio) inside verdaccio/verdaccio. The storage directory is bind-mounted from the server (/mnt/omnissiah-vault/data/verdaccio/storage); if it is owned by root:root (mode 755) the process cannot write to it and every publish fails with a confusing 404 no such package available (NotFoundError from local-storage). Ensure the directory — and its plugins subdirectory — are owned by 10001:101:

sudo chown -R 10001:101 /mnt/omnissiah-vault/data/verdaccio/storage
docker restart npm-registry

Notes

Hexa is a full library with its own MCP server on :8008: read docs://index, docs://nav, and docs://modules/{module} (e.g. docs://modules/hexa.container) to discover the DI surface — build(cls, *, instances, config) and the PortNode model.
Auth Server is a service, not an importable library: it has no MCP bundle by design. Read its client contract from the pinned OpenAPI document via docs://spec and wire it by declaring a bearerAuth security scheme in the app's own spec (see Auth Integration); py-jwt covers the low-level token path.
Doc Weaver is the TypeScript counterpart to Doc Forge: it reads JSDoc comments and emits a TypeDoc site plus the same doc-forge-shaped MCP bundle for React packages. Its convention is RDFC (the React Doc-forge Convention), the JSDoc parallel to GSDFC.
React Auth and React OpenAPI are front-end libraries (TypeScript, React 18 + MUI + React Router peers), not Python services — they consume the Auth Server and an OpenAPI document rather than serving one. Each ships a wiki, a TypeDoc site and an MCP bundle like every other library above.
Library MCP servers expose documentation resources (not executable tools): they tell an agent the available API surface so it does not invent code.