v3.3.1: strip raw_html in get_page to honor pagination

Large pages were blowing past MCP token caps because BookStack returns
raw_html alongside html/markdown/text and we weren't stripping it,
bypassing the limit/offset pagination on the content field.

Also reorganize README to lead with the plugin marketplace install.

Author: ttpears

.claude/settings.local.json

@@ -14,10 +14,17 @@
       "WebFetch(domain:spec.modelcontextprotocol.io)",
       "WebFetch(domain:modelcontextprotocol.io)",
       "Bash(find:*)",
-      "Bash(grep:*)"
+      "Bash(grep:*)",
+      "WebFetch(domain:www.librechat.ai)",
+      "Bash(gh api *)",
+      "Bash(python3 -m json.tool)",
+      "mcp__plugin_context7_context7__resolve-library-id",
+      "mcp__plugin_context7_context7__query-docs",
+      "Bash(gh repo *)",
+      "WebFetch(domain:bookstack.bassopaolo.com)"
     ],
     "deny": [],
     "ask": [],
     "defaultMode": "acceptEdits"
   }
-}
+}

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-BookStack MCP Server v2.1 — A TypeScript MCP server providing BookStack wiki integration for AI assistants. Published to npm as `bookstack-mcp`. Uses McpServer API with `registerTool()` and Zod schemas with `z.coerce.number()` for broad MCP client compatibility.
+BookStack MCP Server — A TypeScript MCP server providing BookStack wiki integration for AI assistants. Published to npm as `bookstack-mcp`. Uses McpServer API with `registerTool()` and Zod schemas with `z.coerce.number()` for broad MCP client compatibility. Current version is tracked in `package.json`.
 
 ## Build & Development Commands
 
@@ -42,6 +42,7 @@ BOOKSTACK_BASE_URL=https://your-bookstack.com   # Required
 BOOKSTACK_TOKEN_ID=your-token-id                # Required
 BOOKSTACK_TOKEN_SECRET=your-token-secret        # Required
 BOOKSTACK_ENABLE_WRITE=false                    # Optional
+BOOKSTACK_INSECURE_SKIP_TLS_VERIFY=false        # Optional, for self-signed BookStack
 ```
 
 ### TypeScript Configuration
@@ -57,7 +58,24 @@ Published as `bookstack-mcp`. Key package.json fields:
 - `prepare`: runs build (triggers on install from git and before publish)
 - `engines`: `>=18`
 
-To publish: `npm publish` (package is unscoped, no `--access public` needed)
+## Release Process
+
+Releases are fully automated by GitHub Actions — **never run `npm publish` locally**.
+
+1. Bump `version` in `package.json` (semver) in the same PR/commit as the changes you want to ship.
+2. Merge to `main`.
+3. `.github/workflows/ci.yml` runs:
+   - `build` job: `npm ci` + `npm run build` on every push and PR.
+   - `tag` job (main only): if `package.json` version doesn't already have a matching `v${version}` git tag, it creates and pushes one using `RELEASE_PAT` (a PAT is required because the default `GITHUB_TOKEN` cannot trigger downstream workflows).
+4. The pushed tag triggers `.github/workflows/release.yml`, which:
+   - Builds, then upgrades npm to the latest (Node 20 ships npm 10.x; trusted publishing needs ≥ 11.5.1).
+   - Publishes via npm **trusted publishing (OIDC)** with `--provenance` — no `NPM_TOKEN`. The npm CLI exchanges the Actions OIDC token (`id-token: write`) for a short-lived registry token at publish time. This requires the npm package to have a trusted publisher configured pointing at this repo's `release.yml`.
+   - Creates a GitHub Release for the tag with auto-generated notes (`gh release create --generate-notes`).
+
+Notes:
+- Don't tag manually — let the `tag` job do it from the version bump. Manually pushed tags will still trigger `release.yml`, but you bypass the version-changed gate.
+- If `RELEASE_PAT` is missing/expired, the tag never gets pushed and the release silently doesn't happen. Symptom: CI green on main, no new tag, no npm release.
+- Don't add an `NPM_TOKEN` secret — trusted publishing replaces it. Adding one weakens the threat model.
 
 ## Key Implementation Details
 

README.md

@@ -137,7 +137,24 @@ Restart LibreChat after config changes.
 
 ### Claude Code (CLI)
 
-Add the server with `claude mcp add`. Repeat `--env` for each variable, and put all flags **before** the server name; the `--` separator marks the start of the command Claude Code will spawn:
+The recommended path is the `ttpears/claude-plugins` marketplace, which ships this repo's plugin manifest (`.claude-plugin/plugin.json`):
+
+```
+/plugin marketplace add ttpears/claude-plugins
+/plugin install bookstack-mcp@ttpears-plugins
+```
+
+Then set the `BOOKSTACK_*` environment variables in your shell so the plugin's MCP server can authenticate:
+
+```bash
+export BOOKSTACK_BASE_URL=https://your-bookstack.com
+export BOOKSTACK_TOKEN_ID=your-token-id
+export BOOKSTACK_TOKEN_SECRET=your-token-secret
+```
+
+#### Manual install (alternative)
+
+If you'd rather not use the marketplace, register the server directly with `claude mcp add`. Repeat `--env` for each variable, put all flags **before** the server name, and use `--` to mark the start of the command Claude Code will spawn:
 
 ```bash
 claude mcp add bookstack \
@@ -178,17 +195,6 @@ The resulting config entry looks like this (in `.mcp.json` for project scope, or
 
 > **Tip for committed `.mcp.json`:** Claude Code expands `${VAR}` and `${VAR:-default}` references in `.mcp.json` from the surrounding shell. Use that to keep secrets out of git: set `"BOOKSTACK_TOKEN_SECRET": "${BOOKSTACK_TOKEN_SECRET}"` in the file and have each developer export the variable in their shell.
 
-### Claude Code (plugin marketplace)
-
-This repo also ships a Claude Code plugin manifest (`.claude-plugin/plugin.json`). Add the marketplace and install:
-
-```
-/plugin marketplace add ttpears/claude-plugins
-/plugin install bookstack-mcp@ttpears-plugins
-```
-
-Then set the `BOOKSTACK_*` environment variables in your shell so the plugin's MCP server can authenticate.
-
 ## MCP Resources
 
 Books and pages are also exposed as MCP resources, so clients that browse resources (Claude Desktop, MCP Inspector, etc.) can `@`-mention them directly:

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "bookstack-mcp",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "MCP server for BookStack wiki — search, read, create, and manage documentation via AI assistants",
   "type": "module",
   "bin": {

package.json

@@ -207,8 +207,11 @@ export class BookStackClient {
     const nextOffset = offset + slice.length;
     const truncated = nextOffset < totalChars;
 
-    // Strip duplicate large fields from the base page object
-    const { html: _h, markdown: _m, text: _t, ...pageMeta } = page;
+    // Strip duplicate large fields from the base page object. raw_html is the
+    // unprocessed editor source BookStack returns alongside html/markdown/text;
+    // leaving it in would bypass the limit/offset pagination and can blow past
+    // MCP token caps for large pages.
+    const { html: _h, markdown: _m, text: _t, raw_html: _r, ...pageMeta } = page as any;
 
     return {
       ...pageMeta,
@@ -424,9 +427,9 @@ export class BookStackClient {
       ? `${page.text.substring(0, 200)}${page.text.length > 200 ? '...' : ''}`
       : 'No content preview available';
 
-    // List responses from BookStack don't include html/markdown/text, but strip defensively
-    // and never embed full content here — use get_page for that.
-    const { html: _h, markdown: _m, text: _t, ...pageMeta } = page as any;
+    // List responses from BookStack don't include html/markdown/text/raw_html, but strip
+    // defensively and never embed full content here — use get_page for that.
+    const { html: _h, markdown: _m, text: _t, raw_html: _r, ...pageMeta } = page as any;
 
     return {
       ...pageMeta,