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.

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

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

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.
In BookStack, create hermes-btd as a non-admin local user.
Apply Shelf/Book permissions first, then enable the user permission Access system API.
While logged in as hermes-btd, create a named, expiry-bounded API token. Copy its ID and secret once into local .env.
Create a project-local environment and install the MCP SDK:

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

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

# 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

Run local tests before any live probe:

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

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

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.