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

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:

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

Agent usage policy:

• 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://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 /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 can create pending change records under 90-maintenance/pending-changes/.
• POST /changes/{id}/apply can apply kind=doc and kind=inventory-item changes after validation.
• No authentication yet.
• 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 files.

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.