# Gnexus Book Server

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

## Development

From the repository root:

```bash
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.

Run over stdio:

```bash
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?)`

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.