FastAPI backend and MCP server for reading and maintaining Gnexus Book documentation and inventory.
From the repository root:
cd server python3 -m venv .venv . .venv/bin/activate pip install -e ".[dev]" uvicorn app.main:app --reload --host 127.0.0.1 --port 8080
The read path can be served from PostgreSQL instead of files:
# From the repository root: start a local development cluster on 127.0.0.1:5433 ./scripts/dev-db.sh start cd server export GNEXUS_BOOK_DATABASE_URL="$(../scripts/dev-db.sh url)" .venv/bin/alembic upgrade head .venv/bin/python -m app.storage.cli import --replace .venv/bin/python -m app.storage.cli parity GNEXUS_BOOK_STORAGE_BACKEND=db .venv/bin/python -m uvicorn app.main:app --port 3005
file; set GNEXUS_BOOK_STORAGE_BACKEND=db to use PostgreSQL.import --replace re-imports the current repository; parity compares file and database read results and exits non-zero on a difference.scripts/backup-db.sh writes a custom-format dump to the off-host NFS by default; scripts/restore-db.sh requires GNEXUS_BOOK_RESTORE_YES=1 before replacing data.db.POST /commit is blocked: applying a changeset is the publish step. commit_changes in MCP is a documented no-op.GNEXUS_BOOK_TEST_DATABASE_URL (default postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book_test) and are skipped when PostgreSQL is unavailable.Authentication is disabled unless the gnexus-auth client is configured. When the following variables are present, the service guards every route except /health, /me, /auth/*, and /webhooks/gnexus-auth*:
GNEXUS_BOOK_AUTH_CLIENT_ID GNEXUS_BOOK_AUTH_CLIENT_SECRET GNEXUS_BOOK_AUTH_BASE_URL GNEXUS_BOOK_AUTH_REDIRECT_URI GNEXUS_BOOK_AUTH_WEBHOOK_SECRET GNEXUS_BOOK_AUTH_SESSION_COOKIE # default gnb_session GNEXUS_BOOK_AUTH_COOKIE_SECURE # default true for https redirect URIs GNEXUS_BOOK_AUTH_SESSION_TTL_SECONDS # default 604800
Endpoints:
GET /me — {auth_enabled, user, locale, locale_effective}; returns user: null when there is no session.GET /auth/login — redirects to gnexus-auth with OAuth PKCE.GET /auth/callback — exchanges the code, mirrors the sub user, and sets an httpOnly session cookie.POST /auth/logout — revokes the session and clears the cookie.PATCH /me — stores the per-user locale override (en, uk, ru, or empty).POST /webhooks/gnexus-auth and /webhooks/gnexus-auth/ — HMAC-verified gnexus-auth events, idempotent by event id.Sessions are stored as SHA-256 hashes in user_sessions. Webhook signatures follow gnexus-auth's t=<timestamp>,v1=<hmac> scheme over <timestamp>.<body>.
Current Phase 4 scope: user mirroring, sessions, /me, webhook handling, and actor attribution on changesets/versions. Role-specific publish policy and MCP key revocation on user block arrive with Phase 5.
The MCP server exposes the same repository, inventory, validation, pending-change, and Git commit logic through MCP tools and resources.
It should be treated by AI agents as infrastructure memory. Agents should consult it proactively for infrastructure-specific work rather than waiting for the user to explicitly ask them to "look in the knowledge base".
Run over stdio:
cd server .venv/bin/python -m app.mcp_server
Optional environment:
GNEXUS_BOOK_REPO_ROOT=/path/to/gnexus-bookGNEXUS_BOOK_MCP_TRANSPORT=stdio|sse|streamable-httpCore tools:
get_agent_usage_guide()search_docs(query)read_doc(path)list_docs()list_inventory(inventory_type?)get_inventory_item(inventory_type, item_id)get_relationships()validate_repository()check_freshness()git_status()git_diff(files?)propose_doc_change(path, content, summary, reason?)propose_inventory_item_change(inventory_type, item_id, patch, summary, reason?, mode?)apply_pending_change(change_id)commit_changes(summary, files, details?)update_doc(path, content, summary, reason?)document_history(path)document_version(path, version_no)document_diff(path, from_version?, to_version?)restore_document_version(path, version_no, summary?)Agent usage policy:
get_agent_usage_guide() when unsure how to use the knowledge tools.search_docs first for broad lookup, then read_doc, inventory tools, and get_relationships for authoritative context.check_freshness when stale information matters.Detailed rules: ../90-maintenance/agent-mcp-usage.md.
Useful resources:
gnexus-book://docsgnexus-book://agent-guidegnexus-book://inventorygnexus-book://relationshipsgnexus-book://freshnessgnexus-book://validationgnexus-book://git/statusGET /api-docsGET /healthGET /meGET /auth/loginGET /auth/callbackPOST /auth/logoutPATCH /mePOST /webhooks/gnexus-authGET /docsGET /docs/read?path=...GET /documents/{path}/historyGET /documents/{path}/versions/{version_no}GET /documents/{path}/diff?from=&to=POST /documents/{path}/restore/{version_no}?summary=...GET /search?q=...GET /inventoryGET /inventory/{type}GET /inventory/{type}/{id}GET /traffic-routesGET /relationshipsGET /health/freshnessGET /validateGET /changesGET /changes/{id}POST /changesPOST /changes/{id}/applyGET /git/statusGET /git/diffPOST /commitInventory parsing requires PyYAML.
POST /changes creates pending change records in the file backend or changesets in the database backend.POST /changes/{id}/apply applies kind=doc and kind=inventory-item changes transactionally after validation.POST /commit is only available with the file backend.POST /commit creates a local Git commit only. It does not push.GET /validate checks:
schemas/*.json;docs links;Inventory includes broad records for hosts, services, domains, traffic routes, endpoints, integrations, projects, databases, backups, networks, hardware, and virtual machines.
POST /changes/{id}/apply and POST /commit both rely on validation to block unsafe repository states.