# BookStack BTD MCP adapter

Read-only local stdio MCP adapter for the BookStack REST API. This project is deliberately separate from the BookStack deployment repository and does not open an HTTP port.

```text
Hermes
  → local stdio subprocess: bookstack-mcp
    → BookStack REST API with Token authentication
      → BookStack BTD pilot / final UGM subpath
```

## Security model

- Use a dedicated BookStack user: `hermes-btd`, never an Admin account.
- Grant it read access only to the intended `Publik` and specific `Terbatas` content.
- Do not grant `Rahasia / Privat` access.
- Create an API token from that account and store its ID and secret only in local `.env`.
- This adapter registers **no create, update, delete, user, role, permission, attachment, export, audit-log, or token-management tools**.
- BookStack access permissions are the source-of-truth security boundary. MCP tool scope is defense in depth.

## Available MCP tools

```text
list_shelves / get_shelf
list_books   / get_book
list_chapters / get_chapter
list_pages    / get_page
search_knowledge
```

BookStack's official REST API does not expose a References/backlinks endpoint. The adapter intentionally does not claim a `get_references` tool.

## Setup after BookStack is deployed

1. Ensure the Hermes runtime can reach BookStack. A private NUC LAN IP must be reachable from the machine running Hermes; browser access elsewhere is not enough.
2. In BookStack, create `hermes-btd` as a non-admin local user.
3. Apply Shelf/Book permissions first, then enable the user permission **Access system API**.
4. While logged in as `hermes-btd`, create a named, expiry-bounded API token. Copy its ID and secret once into local `.env`.
5. Create a project-local environment and install the MCP SDK:

```bash
cd /Users/wayeien/Documents/bookstack-mcp
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
cp .env.example .env
chmod 600 .env
```

6. Edit only the local `.env`. Use the exact canonical base URL without trailing slash:

```dotenv
# Current LAN pilot: first establish a Mac → NUC SSH tunnel:
# ssh -N -L 127.0.0.1:18603:10.14.7.239:8603 magangbtd@10.14.7.239
# Then keep the API token on the Mac and send it only through that tunnel.
BOOKSTACK_URL=http://127.0.0.1:18603/bookstack

# Later UGM HTTPS example
# BOOKSTACK_URL=https://<host-UGM>/bookstack
```

7. Run local tests before any live probe:

```bash
.venv/bin/python -m unittest discover -s tests -v
```

8. Once network reachability and a least-privilege API token are verified, register with Hermes:

```bash
hermes mcp add bookstack-btd \
  --command /Users/wayeien/Documents/bookstack-mcp/.venv/bin/python \
  --args /Users/wayeien/Documents/bookstack-mcp/run_bookstack_mcp.py
hermes mcp test bookstack-btd
```

Approve only the displayed read-only tools during registration. Start a new Hermes session after successful registration.

## Tests

Tests mock the BookStack API and verify:

- canonical base URL and UGM subpath preservation;
- BookStack `Authorization: Token <id>:<secret>` header format;
- URL encoding/search pagination;
- JSON error payload handling;
- environment placeholder rejection;
- read-only MCP tool delegation.

They do not prove LAN/API reachability or actual BookStack account permissions. Those require a deployed BookStack instance and `hermes-btd` token.

## Source contract

Implemented against BookStack `v26.05.3` API routes (`/api/shelves`, `/books`, `/chapters`, `/pages`, `/search`) and token format defined in the upstream source. No direct database access is used.