gnexus-book / server /
@Eugene Sukhodolskiy Eugene Sukhodolskiy authored 1 day ago
..
alembic feat(server): add auth schema, sessions and user mirroring 1 day ago
app feat(server): attribute changesets and versions to the acting principal 1 day ago
tests test(server): cover authentication, sessions and webhooks 1 day ago
.env.example feat(server): add auth schema, sessions and user mirroring 1 day ago
README.md docs: record Phase 4 authentication scaffold 1 day ago
alembic.ini feat(server): add PostgreSQL models, migration and read repositories 1 day ago
pyproject.toml feat(server): add auth schema, sessions and user mirroring 1 day ago
README.md

Gnexus Book Server

FastAPI backend and MCP server for reading and maintaining Gnexus Book documentation and inventory.

Development

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

PostgreSQL storage

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
  • The default backend is 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.
  • Documents and inventory are read and written through PostgreSQL. Every write creates immutable versions grouped into a changeset; applying a changeset publishes it. History, version reads, diff, and restore are available in database mode.
  • Validation and freshness use the database when the backend is db.
  • In database mode POST /commit is blocked: applying a changeset is the publish step. commit_changes in MCP is a documented no-op.
  • Database tests use 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 (gnexus-auth)

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.

MCP Server

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-book
  • GNEXUS_BOOK_MCP_TRANSPORT=stdio|sse|streamable-http

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?)
  • 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:

  • Call get_agent_usage_guide() when unsure how to use the knowledge tools.
  • Use MCP before answering questions about hosts, VPS, VMs, networks, domains, routes, services, deployments, GitBucket repositories, or smart-home infrastructure.
  • Use search_docs first for broad lookup, then read_doc, inventory tools, and get_relationships for authoritative context.
  • Use check_freshness when stale information matters.
  • Use write tools to update documentation after discovering relevant new facts.
  • Never store raw passwords, tokens, private keys, recovery codes, session cookies, or secret config values.

Detailed rules: ../90-maintenance/agent-mcp-usage.md.

Useful resources:

  • gnexus-book://docs
  • gnexus-book://agent-guide
  • gnexus-book://inventory
  • gnexus-book://relationships
  • gnexus-book://freshness
  • gnexus-book://validation
  • gnexus-book://git/status

Current API

  • Swagger UI: GET /api-docs
  • GET /health
  • GET /me
  • GET /auth/login
  • GET /auth/callback
  • POST /auth/logout
  • PATCH /me
  • POST /webhooks/gnexus-auth
  • GET /docs
  • GET /docs/read?path=...
  • GET /documents/{path}/history
  • GET /documents/{path}/versions/{version_no}
  • GET /documents/{path}/diff?from=&to=
  • POST /documents/{path}/restore/{version_no}?summary=...
  • GET /search?q=...
  • GET /inventory
  • GET /inventory/{type}
  • GET /inventory/{type}/{id}
  • GET /traffic-routes
  • GET /relationships
  • GET /health/freshness
  • GET /validate
  • GET /changes
  • GET /changes/{id}
  • POST /changes
  • POST /changes/{id}/apply
  • GET /git/status
  • GET /git/diff
  • POST /commit

Inventory parsing requires PyYAML.

Current Limitations

  • 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.
  • Database mode publishes on apply; POST /commit is only available with the file backend.
  • Authentication is gnexus-auth SSO when configured; without client credentials the service runs open for local development.
  • Role-specific publish policy is not implemented yet: any authenticated, non-blocked user may write.
  • MCP personal keys and key revocation on user block are not implemented yet.
  • File-backend POST /commit creates a local Git commit only. It does not push.
  • Commit requests must provide an explicit file list.
  • Validation uses JSON Schema 2020-12 for inventory records in both backends.
  • Search keeps a substring/line-match path for exact response parity; a PostgreSQL full-text index is deferred to a performance phase.

Validation

GET /validate checks:

  • schema validity for schemas/*.json;
  • required Markdown frontmatter;
  • inventory YAML against JSON Schema;
  • inventory docs links;
  • duplicate inventory item IDs;
  • common raw secret assignment patterns in Markdown, YAML, JSON, and dotenv-style files.

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.