bookstack-mcp

All workflows declare permissions: read-all at the top level, establishing read-only as the baseline for every job. Individual jobs that require write access (e.g. pushing to GHCR, creating git tags) override only the specific permissions they need at the job level. GitHub Actions honours the most restrictive scope when no job-level override is present, so any task without explicit permissions inherits the read-all baseline rather than the default broad token permissions.

Every release is tagged with a unique semantic version identifier (e.g. v2.5.6) derived from the version field in packages/stdio/package.json. The CI/CD pipeline (docker-publish.yml) reads this value at merge time, asserts the version tag does not already exist in the registry, and creates the git tag only after the multi-arch Docker manifest is verified. Attempting to release a version that already exists in GHCR causes the pipeline to fail, enforcing uniqueness.

Each release produces a GitHub Release (automated via the merge job in docker-publish.yml) with notes extracted from the corresponding ## [X.Y.Z] section of CHANGELOG.md. The changelog follows the Keep a Changelog format and documents changes under categorised headings: Added, Fixed, Security, Dependencies, and Changed. See the v2.5.6 release as an example.

The build pipeline uses npm ci — the standardized, deterministic install command for Node.js/npm projects. npm ci installs exclusively from package-lock.json, ensuring exact, reproducible dependency versions across all CI runs. This is the npm-recommended practice for automated environments over npm install.

Docker images are published to GHCR with SLSA Level 2 provenance attestations generated by actions/attest-build-provenance during each post-merge build. The attestation records the builder identity, source commit SHA, and a signed manifest of the image digests, anchored to the GitHub Actions OIDC token. The attestation is stored in the repository's attestation log and can be verified with gh attestation verify.

Dependencies are declared in packages/core/package.json and packages/stdio/package.json and locked in package-lock.json. All installs use npm ci for reproducible builds. Updates are automated via Dependabot (weekly schedule for npm, GitHub Actions, and Docker base image). Vulnerability tracking uses npm audit on every CI build, OSV Scanner, and Trivy image scanning. See the Dependency Management section in README.md.

Build instructions are documented in README.md under "Quick Start" (prerequisites: Node.js 18+, npm; steps: npm install, npm run build) and in CONTRIBUTING.md under "Getting started". Required dependencies are listed in packages/core/package.json and packages/stdio/package.json. The project has no system-level library requirements beyond Node.js and npm.

MAINTAINERS.md in the repository root lists all project members with access to sensitive resources (GitHub repo admin, GHCR registry, GitHub Actions secrets). The project has a single maintainer: @paradoxbound. No manually stored secrets exist — the only credential used by CI is the auto-provisioned GITHUB_TOKEN

MAINTAINERS.md describes the project's single Maintainer role held by @paradoxbound, with responsibilities covering repository administration, release management (approving and merging PRs, triggering the release pipeline), and ownership of sensitive resources (GitHub repo, GHCR registry, Actions secrets).

CONTRIBUTING.md in the repository root provides a contribution guide covering: repository setup and build steps, project structure, the pull request workflow (fork → branch from main → pass type-check and build → open PR), how to run tests, security vulnerability reporting, and the code style requirements (TypeScript strict mode, native fetch only, Zod schemas for inputs, specific error handling patterns). These constitute the requirements for acceptable contributions.

All pull requests are checked by a GitHub Actions DCO workflow (dco.yml) that fails if any commit lacks a Signed-off-by: line. The DCO sign-off check is required before merging. Contributors are instructed to use git commit -s in CONTRIBUTING.md. This implements the Developer Certificate of Origin, asserting legal authorisation to contribute under the MIT License.

GitHub branch protection on main requires all status checks to pass before merging. The required checks are: test (functional-tests.yml), build-and-push (docker-publish.yml), and pre-merge-cd-check (docker-publish.yml). "Do not allow bypassing the above settings" is enabled, preventing administrators from merging without passing checks. Bypasses are therefore explicit and require removing branch protection rules, which is itself a logged, auditable action.

The functional-tests.yml workflow runs on every pull request targeting main and on every push to main. It executes npm run build, npm run type-check, and npm test (the full vitest suite including unit tests, fuzz tests, and where credentials are available, functional tests against a live BookStack instance). This check is a required status check — PRs cannot merge unless it passes.

The README Architecture section documents all actors (MCP client, bookstack-mcp server, BookStack API client, BookStack instance, operator) in a table, and includes an ASCII data flow diagram showing the complete request/response path through the system — from MCP client through stdio transport, Zod validation, the BookStack HTTP client, and back. Key design decisions (native fetch, write-gate, Zod schemas, stdio transport, monorepo split) are also documented.

The README documents all external software interfaces: the MCP tool interface (45 tools listed with descriptions), the environment variable configuration interface, the BookStack REST API dependency (with authentication format), and the stdio transport interface as consumed by each supported MCP client (Claude Desktop and LibreChat).

SECURITY.md contains a Security Assessment section documenting six threats with severity ratings (HIGH/MEDIUM/LOW) and existing mitigations: API credential exposure, unintended write operations, prompt injection via BookStack content, insecure transport (now enforced at startup), supply chain compromise, and SSRF via BOOKSTACK_BASE_URL.

SECURITY.md documents a coordinated vulnerability disclosure policy: reporters use GitHub's private Security Advisory feature, can expect acknowledgement within 7 days and a patch or mitigation within 30 days where feasible, and will be credited in the advisory unless they request otherwise.

SECURITY.md directs reporters to use GitHub's private Security Advisory feature (https://github.com/paradoxbound/bookstack-mcp/security/advisories/new), which routes directly to the maintainer without public disclosure. The README also links to SECURITY.md via the Security Considerations section.

SECURITY.md states that once a fix is released, the GitHub Security Advisory will be published publicly and a CVE requested where appropriate, and that security fixes are recorded in CHANGELOG.md under the relevant release.