Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
85 lines (59 loc) · 2.86 KB

CONTRIBUTING.md

File metadata and controls

85 lines (59 loc) · 2.86 KB
Raw

Contributing to BookStack MCP

Thank you for your interest in contributing!

Getting started

git clone https://github.com/paradoxbound/bookstack-mcp.git
cd bookstack-mcp
npm install
npm run build
npm run type-check

Project structure

  • packages/core/ — BookStack API client and shared types (no runtime dependencies)
  • packages/stdio/ — MCP server with stdio transport

Developer Certificate of Origin (DCO)

All commits must include a Signed-off-by line asserting that you are legally authorised to make the contribution under the project's MIT License (see the Developer Certificate of Origin).

Sign off automatically with:

git commit -s -m "your commit message"

This adds Signed-off-by: Your Name <your@email.com> to the commit message. A CI check enforces this on every pull request.

To fix unsigned commits before opening a PR:

git rebase --signoff HEAD~<number-of-commits>

Making changes

  1. Fork the repository and create a branch from main
  2. Make your changes
  3. Ensure npm run type-check and npm run build pass
  4. If you have a BookStack instance available, run npm test with the required environment variables (see below)
  5. Sign off all commits (see DCO section above)
  6. Open a pull request against main

Running tests

Unit and fuzz tests run without a BookStack instance:

npm test

Functional tests require a live BookStack instance:

export TEST_BOOKSTACK_URL=https://your-bookstack.example.com
export TEST_BOOKSTACK_TOKEN_ID=your-token-id
export TEST_BOOKSTACK_TOKEN_SECRET=your-token-secret
npm test

Reporting security vulnerabilities

Please do not open a public issue for security vulnerabilities. Use the process described in SECURITY.md.

Requirements for acceptable contributions

All pull requests must meet these requirements before they will be merged:

  1. DCO sign-off — every commit must have a Signed-off-by line (see above)
  2. Type-check passes — npm run type-check must succeed with no errors
  3. Build passes — npm run build must succeed
  4. Tests pass — npm test must pass (unit and fuzz tests run without credentials; functional tests require a live BookStack instance)
  5. No new HIGH/CRITICAL vulnerabilities — npm audit --audit-level=high must pass
  6. Code style — follow the conventions below
  7. Tests for new functionality — if you add a new public API method or MCP tool, include a corresponding unit test in packages/core/tests/api-methods.test.ts and, where applicable, a functional test in tests/read-tools.test.ts or tests/write-tools.test.ts

Code style

  • TypeScript strict mode
  • Native fetch only — no axios or other HTTP clients
  • Zod schemas for all MCP tool inputs
  • Error handling via error.status / error.response (not axios patterns)