update

2026-08-16 22:47:26 -07:00
parent b3212235db
commit ca0f89a671
12 changed files with 1431 additions and 0 deletions
@@ -0,0 +1,101 @@
+# Quickstart (Proxmox / LXD container)
+
+Full detail is in `README.md`. This is the short path.
+
+## 0. Where to put this
+
+Unzip **anywhere except `/opt/bookstack-mcp`** — that path is the install
+*target*, and the installer overwrites it. `/opt/src` is a good home:
+
+```bash
+cd /opt/src                       # or wherever you unzipped
+unzip bookstack-mcp.zip
+cd bookstack-mcp
+```
+
+You should now be able to run this with no errors — all three paths must exist:
+
+```bash
+ls pyproject.toml bookstack_mcp/server.py deploy/lxc/install.sh
+```
+
+## 1. Install
+
+Requires Debian 12+ or Ubuntu 24.04+ (Python 3.11 or newer).
+
+```bash
+bash deploy/lxc/install.sh
+```
+
+This creates the `bookstack-mcp` service user, a venv at
+`/opt/bookstack-mcp/venv`, config at `/etc/bookstack-mcp/env`, and a systemd
+unit. Re-run it any time to upgrade; your config file is preserved.
+
+## 2. Get a BookStack API token
+
+Your instance uses OIDC, so the service user never needs to log in:
+
+1. Settings → Roles → create a role with **Access System API**.
+2. Settings → Users → create a user, assign that role.
+3. Edit that user as an admin → **API Tokens** section at the bottom →
+   **Create Token**. Copy the Token ID and Token Secret.
+
+If you have `OIDC_REMOVE_FROM_GROUPS=true`, do not log this user in via SSO —
+group sync will strip the role. See README step 1.
+
+## 3. Configure
+
+```bash
+nano /etc/bookstack-mcp/env
+```
+
+Minimum to get running with Claude Code only:
+
+```ini
+BOOKSTACK_URL=https://wiki.yourdomain.com
+BOOKSTACK_TOKEN_ID=...
+BOOKSTACK_TOKEN_SECRET=...
+BOOKSTACK_READ_ONLY=true
+MCP_AUTH_MODE=token
+MCP_STATIC_TOKENS=<openssl rand -hex 32>
+```
+
+Add claude.ai later by switching to `MCP_AUTH_MODE=oidc+token` and filling in
+the OIDC block — see `deploy/authelia/configuration.snippet.yml`.
+
+## 4. Start
+
+```bash
+systemctl start bookstack-mcp
+systemctl status bookstack-mcp
+journalctl -u bookstack-mcp -f
+```
+
+Verify locally. A 401 with a `www-authenticate` header is the correct answer:
+
+```bash
+curl -i http://127.0.0.1:8080/mcp
+```
+
+## 5. Reverse proxy
+
+Point `https://mcp.yourdomain.com` at this container on **port 8080**.
+
+Three things that will otherwise cost you an evening:
+
+- Proxy the **whole hostname**, not just `/mcp`. OAuth discovery lives at
+  `/.well-known/*` on the domain root.
+- **Disable buffering** (`proxy_buffering off`, long `proxy_read_timeout`).
+  Streamable HTTP holds a stream open.
+- **Bypass Authelia forward-auth** for this host. Claude can't hold session
+  cookies; the MCP server does its own OAuth.
+
+## 6. Connect
+
+```bash
+claude mcp add --transport http bookstack https://mcp.yourdomain.com/mcp \
+  --header "Authorization: Bearer YOUR_STATIC_TOKEN" --scope user
+```
+
+For claude.ai: Settings → Connectors → Add custom connector →
+`https://mcp.yourdomain.com/mcp`. Requires `MCP_AUTH_MODE=oidc+token`.