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

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:

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:

# 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:

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

8. 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.