| .. | |||
| alembic | 1 day ago | ||
| app | 1 day ago | ||
| tests | 1 day ago | ||
| .env.example | 1 day ago | ||
| README.md | 1 day ago | ||
| alembic.ini | 1 day ago | ||
| pyproject.toml | 1 day ago | ||
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.python -m app.storage.cli migrate --replace --manifest /tmp/report.json imports the file repository, validates the database, verifies the content manifest, and reconciles documents, search, inventory, relationships, validation and freshness. It exits non-zero on any discrepancy.
For a rehearsed or real cutover use the scripts:
# Rehearsal / cutover against a target database GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://USER@HOST:PORT/gnexus_book \ ./scripts/cutover-db.sh --replace # Verify that the file backend is still readable for rollback ./scripts/rollback-cutover.sh
cutover-db.sh applies migrations, imports, verifies, reconciles and writes an off-host dump. It does not switch the running service: set GNEXUS_BOOK_STORAGE_BACKEND=db (and the database URL) in server/.env, then restart the backend and MCP units. The systemd units load server/.env through EnvironmentFile, and the Git checkout remains untouched as the rollback source. See ../30-runbooks/cutover-postgres.md for the full procedure.
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".
Production agents use streamable HTTP at /mcp-protocol/ with a personal mcp_* key:
cd server GNEXUS_BOOK_MCP_HOST=0.0.0.0 GNEXUS_BOOK_MCP_PORT=8001 .venv/bin/python -m app.mcp_http
python -m app.mcp_server still runs stdio for local development and tests; SSE is a legacy fallback only. GNEXUS_BOOK_MCP_TRANSPORT=streamable-http delegates to the same guarded HTTP app.
Environment:
GNEXUS_BOOK_REPO_ROOT=/path/to/gnexus-bookGNEXUS_BOOK_MCP_TRANSPORT=stdio|sse|streamable-httpGNEXUS_BOOK_MCP_HOST, GNEXUS_BOOK_MCP_PORTGNEXUS_BOOK_MCP_TOKEN — optional static break-glass token, never a fallback for personal keysGNEXUS_BOOK_MCP_REQUEST_RATE_LIMIT — per-key requests per minute (default 300)GNEXUS_BOOK_INTERNAL_KEY_SECRET, GNEXUS_BOOK_INTERNAL_ALLOWLIST — provisioning API protectionmcp_tokens stores only a SHA-256 hash and a tail hint; one active key per (user_id, consumer), revocation is revoked_at.is_user; it changes actor_kind from agent to user while keeping the key label and via=mcp.scopes without write) key receives {"error": 403, ...} as data.Session-protected key management:
GET /mcp-keys (admins may pass ?all=true)POST /mcp-keys — plaintext returned oncePOST /mcp-keys/{key_id}/rotateDELETE /mcp-keys/{key_id}Service-to-service provisioning (not exposed through nginx; requires X-Service-Key/Bearer service secret and allowlisted source):
POST /internal/keysGET /internal/keys?user_id=&consumer=POST /internal/keys/{key_id}/rotateDELETE /internal/keys/{key_id}Core 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?, is_user?)propose_inventory_item_change(inventory_type, item_id, patch, summary, reason?, mode?, is_user?)apply_pending_change(change_id, is_user?)commit_changes(summary, files, details?, is_user?)update_doc(path, content, summary, reason?, is_user?)document_history(path)document_version(path, version_no)document_diff(path, from_version?, to_version?)restore_document_version(path, version_no, summary?, is_user?)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/logoutGET /mcp-keysPOST /mcp-keysPOST /mcp-keys/{key_id}/rotateDELETE /mcp-keys/{key_id}POST /internal/keysGET /internal/keysPOST /internal/keys/{key_id}/rotateDELETE /internal/keys/{key_id}PATCH /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.read and write; finer-grained scopes are not implemented.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.