Newer
Older
gnexus-book / server / README.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 1 day ago 5 KB docs: record Phase 2 completion

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 uses the database when the backend is db. Freshness still reads files until Phase 3.
  • 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.

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 /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.
  • No authentication 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.
  • Freshness reports still read the file backend until Phase 3.

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.