bookstack-mcp

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

The repository on GitHub contains the full commit history including all interim work between releases. Pull requests, feature branches, bug fix branches, and in-progress changes are all visible and reviewable before they are merged to main. The repository does not contain only tagged release commits — every commit to main and all open/closed pull requests are publicly accessible.

URL: https://github.com/paradoxbound/bookstack-mcp/commits/main

Repository on GitHub, which uses git. git is distributed.

Every release has a unique version identifier following semantic versioning (e.g. v2.6.1). The version is the single source of truth from packages/stdio/package.json and is applied consistently across all release artefacts:

Git tag: v2.6.1
Docker image tags: :2.6.1, :2.6, :2, :latest
npm package version: 2.6.1
The CI/CD pipeline explicitly prevents overwriting an existing version — if the tag already exists in GHCR the release job fails early.

URL: https://github.com/paradoxbound/bookstack-mcp/releases

Every release is tagged in git using the format vX.Y.Z (e.g. v2.6.1). Tags are created automatically by the CI/CD pipeline after the multi-arch Docker manifest is verified in GHCR — the tag is never created before the release artefacts are confirmed good.

URL: https://github.com/paradoxbound/bookstack-mcp/tags

Non-trivial release notes file in repository: https://github.com/paradoxbound/bookstack-mcp/blob/main/CHANGELOG.md.

There have been no publicly known run-time vulnerabilities with CVE assignments in the project's own code (as distinct from its dependencies). The project's security scanning (CodeQL SAST, npm audit, OSV Scanner, Trivy) has not identified any CVEs in the project's own source code to date. All CVE findings have been in third-party dependencies, which are addressed via Dependabot PRs and tracked in the dependency audit pipeline, not in the project's own release notes.

Bug reports are submitted via GitHub Issues. The process is documented in the README "Feedback and contributing" section, which links directly to the issue tracker. No account beyond a free GitHub registration is required to open an issue.

URL: https://github.com/paradoxbound/bookstack-mcp/issues

The project uses GitHub Issues as its issue tracker. Each issue has a unique number, persistent URL, status (open/closed), labels, and comment thread. Issues are used for bug reports, feature requests, and security disclosures (via the private Security Advisories tracker).

URL: https://github.com/paradoxbound/bookstack-mcp/issues

All bug reports and issues submitted via GitHub Issues have been acknowledged and responded to. The project has an active maintainer who responds to issues. The issue tracker and pull request history demonstrate consistent engagement with reporter submissions.

URL: https://github.com/paradoxbound/bookstack-mcp/issues

All enhancement requests submitted via GitHub Issues and Pull Requests in the last 12 months have been responded to. The project has an active maintainer who engages with feature requests, either implementing them, providing feedback, or explaining why they are out of scope.

URL: https://github.com/paradoxbound/bookstack-mcp/issues

GitHub Issues is a publicly available, permanently searchable archive. Every issue, bug report, comment, and response is stored indefinitely, accessible without login, searchable by keyword, and addressable by a permanent URL. The archive is maintained by GitHub infrastructure and cannot be deleted by the project.

URL: https://github.com/paradoxbound/bookstack-mcp/issues

SECURITY.md at the repository root documents the full vulnerability reporting process, including how to report privately, what information to include, and the response timeline. GitHub also surfaces this file automatically in the "Security" tab and when users open issues.

URL: https://github.com/paradoxbound/bookstack-mcp/blob/main/SECURITY.md

SECURITY.md documents the private reporting channel: GitHub's built-in private vulnerability reporting feature (Security → "Report a vulnerability"), which keeps the report confidential between the reporter and maintainers until disclosure. The URL to report is included directly in the file.

URL: https://github.com/paradoxbound/bookstack-mcp/blob/main/SECURITY.md

SECURITY.md commits to an initial response within 14 days of receiving a vulnerability report, satisfying the criterion by policy. No vulnerability reports have been received in the last 6 months, so there is no response history to evaluate — the policy commitment is sufficient.

URL: https://github.com/paradoxbound/bookstack-mcp/blob/main/SECURITY.md

The project uses standard npm scripts defined in package.json at the repo root. A single npm run build compiles all TypeScript source to dist/ for both packages. No manual steps are required beyond npm install.

URL: https://github.com/paradoxbound/bookstack-mcp/blob/main/package.json

The build system uses npm (the standard Node.js package manager) and TypeScript's tsc compiler — both ubiquitous, industry-standard tools in the JavaScript/TypeScript ecosystem. No custom or obscure build tooling is required.

All build tools are FLOSS: Node.js (MIT), npm (Artistic License 2.0), and TypeScript (Apache 2.0). No proprietary tools are required at any stage of the build.

URL: https://github.com/paradoxbound/bookstack-mcp/blob/main/package.json

The project uses Vitest (MIT licensed, FLOSS) as its test framework, with fast-check (MIT) for property-based fuzz tests. Tests run via npm test from the repo root. How to run the test suite is documented in both CONTRIBUTING.md and CLAUDE.md, and the CI pipeline runs tests automatically on every PR via functional-tests.yml.

URL: https://github.com/paradoxbound/bookstack-mcp/blob/main/CONTRIBUTING.md

Tests are invoked via npm test — the standard convention for Node.js/TypeScript projects. Any developer familiar with the ecosystem will know to run this without consulting documentation.

URL: https://github.com/paradoxbound/bookstack-mcp/blob/main/package.json

Code coverage is tracked via Codecov and currently stands at ~80% line coverage. Tests include credential-free unit tests (mocked fetch, all public API methods), property-based fuzz tests, and functional integration tests against a live BookStack instance.

URL: https://codecov.io/gh/paradoxbound/bookstack-mcp

The project uses GitHub Actions CI on every pull request and post-merge push. The functional-tests workflow runs npm run type-check, npm run build, and npm run test:coverage (92 unit tests + fuzz tests + functional integration tests) on every PR. Code coverage is uploaded to Codecov on each run. No code reaches main without passing all automated checks.

CONTRIBUTING.md requires that any new public API method or MCP tool must include a corresponding unit test in packages/core/tests/api-methods.test.ts and, where applicable, a functional test in read-tools.test.ts or write-tools.test.ts. This is enforced through code review on all PRs.

Recent PRs demonstrate adherence: PR #99 and PR #101 added packages/core/tests/api-methods.test.ts (92 tests covering all public API methods including uploadAttachment, exportPage, exportBook, exportChapter, and all CRUD operations) alongside the corresponding implementation. PR #101 also extended read-tools.test.ts with PDF export functional tests. All new functionality in the codebase has corresponding tests.

The test requirement for new functionality is documented in CONTRIBUTING.md under "Requirements for acceptable contributions" (requirement 7), which is presented to all contributors when they open a pull request.

The project uses TypeScript with strict: true in tsconfig.json, which enables strictNullChecks, noImplicitAny, strictFunctionTypes, and all other strict-mode checks. This serves as both a compiler warning system and a safe language mode. TypeScript's type checker runs on every build (npm run type-check) and in CI.

ll TypeScript compiler errors and warnings are treated as build failures — tsc exits non-zero on any type error. The type-check step runs in CI and blocks merging if any warnings are present. The codebase currently compiles with zero warnings.

tsconfig.json uses "strict": true which is the maximum strictness level available in TypeScript. No // @ts-ignore or // @ts-nocheck suppressions exist in the production source code (src/). The project intentionally avoids loosening any strict-mode checks.

The project has a single primary developer who is familiar with secure software design principles, including the Saltzer and Schroeder principles, as demonstrated by their application throughout the project:

Economy of mechanism — the server has no runtime dependencies beyond the MCP SDK and Zod; the API client uses native fetch with no abstraction layers, keeping the attack surface minimal and the codebase auditable.
Fail-safe defaults — write operations are disabled by default (BOOKSTACK_ENABLE_WRITE=false); the server starts in read-only mode unless explicitly opted in via environment variable.
Complete mediation — every write operation is gated behind the enableWrite flag check at tool registration time; there is no path to invoke a write tool without the flag being set.
Open design — security relies on token credentials (not obscurity); the full source is publicly available on GitHub under MIT licence.
Separation of privilege — the BookStack API itself requires a token ID and token secret together; neither alone is sufficient.
Least privilege — the server only requests the API scopes it needs; the BOOKSTACK_ENABLE_WRITE flag allows deployments to further restrict to read-only access.
Least common mechanism — each client instance is isolated; there is no shared mutable state between requests.
Psychological acceptability — the tool names and descriptions are human-readable and follow the principle of least astonishment; the write-gate default prevents accidental data modification.
Limited attack surface — documented in SECURITY.md (attack surface analysis section); the server accepts no inbound network connections (stdio transport only), has no web UI, and exposes no ports.
Input validation with allowlists — all MCP tool inputs are validated against Zod schemas before being passed to the API client; invalid inputs are rejected at the boundary.

he primary developer is familiar with the common vulnerability classes relevant to this type of software (an API proxy/MCP server that handles credentials and makes authenticated HTTP requests) and the mitigations applied:

Credential exposure — API tokens are passed only via environment variables, never hardcoded or logged. The server writes to stderr only (not stdout, which carries the MCP protocol), preventing accidental token leakage into protocol output.
Injection attacks (command/prompt injection) — the server does not execute shell commands or construct dynamic queries; all API calls use structured parameters passed directly to the BookStack REST API. MCP tool inputs are validated via Zod schemas before use.
Broken access control — write operations are disabled by default and require explicit opt-in (BOOKSTACK_ENABLE_WRITE=true). There is no way to invoke a write tool without the flag being set at startup.
Insecure dependencies / supply chain — dependencies are tracked via npm audit (enforced in CI at --audit-level=high), pinned GitHub Actions are used by commit hash, and Trivy container scanning runs on every release. A VEX document (vex.json) records non-applicable CVE suppressions.
Sensitive data exposure — no credentials, tokens, or personally identifiable information are written to logs, stored on disk, or returned in API responses beyond what BookStack itself returns.
Unvalidated input — all MCP tool inputs pass through Zod schema validation at the tool boundary before being forwarded to the BookStack API; unexpected input is rejected before any processing occurs.
Denial of service via unbounded requests — the client implements retry logic with Retry-After header support and a maximum of 3 retries for 429 responses, preventing runaway request loops.
These mitigations are documented in SECURITY.md (threat model and attack surface sections).