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

The software itself does not implement any cryptography. All cryptographic operations are handled by the underlying platform and dependencies:

HTTPS/TLS — all communication with the BookStack API uses HTTPS via Node.js's native fetch, which delegates to the Node.js TLS stack (OpenSSL). Only publicly standardised protocols (TLS 1.2/1.3) are used.
Authentication — the BookStack token-based authentication scheme transmits credentials over HTTPS in the Authorization header; no custom cryptographic scheme is implemented.
No custom cryptography — the project implements no encryption, hashing, signing, or key derivation of its own. It relies entirely on the TLS provided by Node.js and the BookStack server.
All cryptographic protocols in use (TLS 1.2/1.3, the cipher suites negotiated by OpenSSL) are publicly published and subject to extensive expert review.

The project is an API proxy/MCP server whose primary purpose is not cryptography. It does not implement any cryptographic functions. All cryptographic operations (TLS, cipher negotiation) are performed by Node.js's built-in TLS stack, which is specifically designed for this purpose. No cryptographic algorithms are re-implemented anywhere in the codebase.

The only cryptographic dependency is TLS, provided by Node.js (MIT/Apache licensed) which uses OpenSSL (Apache-2.0 licensed) — both fully FLOSS. There are no proprietary cryptographic libraries or closed-source TLS implementations required anywhere in the stack.

The project implements no cryptographic key management of its own. TLS connections are established by Node.js's native fetch and the underlying OpenSSL stack, which defaults to TLS 1.2/1.3 with key lengths that meet and exceed NIST 2030 minimums (≥2048-bit RSA, ≥256-bit elliptic curve, ≥128-bit symmetric). Weaker key lengths and older protocol versions (SSL 3, TLS 1.0, TLS 1.1) can be disabled via standard Node.js TLS options (--tls-min-v1.2, secureOptions) or at the OpenSSL configuration level — no application-level changes are required. The project itself does not expose any configuration that would allow weaker keys to be selected.

The project uses no broken cryptographic algorithms. No MD4, MD5, single DES, RC4, or Dual_EC_DRBG are used anywhere in the codebase or its dependencies. TLS connections are handled entirely by Node.js/OpenSSL using modern cipher suites (TLS 1.2/1.3). The project does not implement any protocol that would require use of broken algorithms, and there are no known mitigations to document.

The project depends on no cryptographic algorithms with known serious weaknesses. No SHA-1, CBC mode in SSH, or similar weakened algorithms are used. All TLS cipher suite selection is delegated to Node.js/OpenSSL, which in modern versions disables weak algorithms by default and prefers AEAD cipher suites (AES-GCM, ChaCha20-Poly1305) with TLS 1.3.

Perfect forward secrecy is provided by Node.js/OpenSSL's TLS stack, which preferentially negotiates ephemeral key exchange cipher suites (ECDHE, DHE) for all HTTPS connections. This is the default behaviour in modern Node.js (v18+) and requires no application-level configuration. If a long-term private key is later compromised, past session traffic remains protected.

The software does not store passwords. It is an API proxy/MCP server that forwards requests to BookStack using pre-configured API tokens. No user authentication, user accounts, or password storage of any kind is implemented.

The software generates no cryptographic keys or nonces. All cryptographic material (TLS keys, session nonces) is generated internally by Node.js/OpenSSL, which uses a cryptographically secure random number generator. The project code itself makes no calls to any random number generator for security purposes.

The project is distributed via two delivery mechanisms, both of which counter MITM attacks:

npm — published as bookstack-mcp on the npm registry, which is served over HTTPS with TLS certificate validation enforced by the npm client.
GitHub Container Registry (GHCR) — Docker images are published to ghcr.io over HTTPS, with SLSA Level 2 provenance attestations generated by actions/attest-build-provenance on every release, allowing consumers to cryptographically verify the build provenance.
Source code is available via GitHub over HTTPS and SSH. No insecure (plain HTTP) distribution channel is used.

The project does not retrieve cryptographic hashes over HTTP. All GitHub Actions are pinned by commit SHA (not by mutable tag), and all package downloads occur over HTTPS via npm and GitHub's package registry. No hash is fetched over plain HTTP anywhere in the build, CI, or distribution pipeline.

Dependency vulnerabilities are tracked via npm audit (enforced in CI at --audit-level=high) and Trivy container scanning on every release. Dependabot is enabled and automatically opens PRs for vulnerable dependencies. No known unpatched vulnerabilities of medium or higher severity exist in the current release. The VEX document (vex.json) records any CVEs assessed as non-applicable with documented justification.

Critical vulnerabilities are addressed as the highest priority. Dependabot PRs for security updates are reviewed and merged promptly. The security policy in SECURITY.md commits to a remediation timeline of 7 days for critical severity issues and 30 days for high severity issues.

No credentials, tokens, private keys, or secrets have ever been committed to the repository. All sensitive values are passed via environment variables at runtime. GitHub secret scanning is enabled on the repository and would alert on any accidental credential commit. The git history has been reviewed and contains no credential material.

CodeQL static analysis runs on every push to main and on every pull request via the .github/workflows/scorecard.yml workflow (which includes CodeQL via OpenSSF Scorecard) and a dedicated CodeQL workflow. CodeQL analyses the TypeScript source for security vulnerabilities and code quality issues. It is a required status check for merging to main

CodeQL includes a security-and-quality query suite that specifically targets common vulnerability classes relevant to JavaScript/TypeScript, including injection flaws, path traversal, insecure use of cryptography, and prototype pollution. npm audit additionally scans all dependencies for known CVEs on every CI run.

Any medium or higher severity vulnerability identified by CodeQL or npm audit blocks merging (CodeQL is a required PR check; npm audit --audit-level=high is enforced in CI). Confirmed findings are remediated per the timelines documented in SECURITY.md (7 days critical, 30 days high, 60 days medium).

The project includes property-based fuzz tests using fast-check and @fast-check/vitest (packages/core/tests/fuzz.test.ts), which run on every CI build. These tests generate randomised inputs to exercise URL construction, parameter handling, and response parsing logic across a large input space.

The project includes property-based fuzz tests using fast-check and @fast-check/vitest (packages/core/tests/fuzz.test.ts), which run on every CI build. These tests generate randomised inputs to exercise URL construction, parameter handling, and response parsing logic across a large input space.

he project is written entirely in TypeScript/JavaScript, which is a memory-safe language. No C, C++, or other memory-unsafe languages are used.

The fuzz tests run under Vitest with full TypeScript strict-mode checks active. The property-based tests include explicit invariant assertions (e.g. URL format, response structure) that are verified across thousands of generated inputs on every CI run.

Any exploitable vulnerability discovered through fuzz testing or dynamic analysis would be treated as a security finding and remediated per the timelines in SECURITY.md. No such vulnerabilities have been discovered to date.