Skip to content

setup-guide.md

Latest commit

 

History

History
697 lines (542 loc) · 16.2 KB

setup-guide.md

File metadata and controls

697 lines (542 loc) · 16.2 KB

BookStack MCP Server - Complete Setup & Configuration Guide

📋 Table of Contents

  1. Overview
  2. Prerequisites
  3. BookStack Server Requirements
  4. Installation Methods
  5. Configuration
  6. Authentication Setup
  7. Claude Integration
  8. Advanced Configuration
  9. Development Setup
  10. Deployment Options
  11. Troubleshooting
  12. FAQ

🎯 Overview

The BookStack MCP Server provides comprehensive access to BookStack's knowledge management capabilities through the Model Context Protocol (MCP). This guide covers everything you need to set up and configure the server for optimal performance.

Key Features

  • 47 MCP Tools covering all BookStack API endpoints
  • Resource Access for dynamic content retrieval
  • Rate Limiting with configurable limits
  • Comprehensive Validation using Zod schemas
  • Error Handling with retry logic
  • TypeScript Support with complete type definitions

🔧 Prerequisites

System Requirements

  • Node.js: 18.0.0 or higher
  • npm: 9.0.0 or higher
  • Operating System: Linux, macOS, or Windows
  • Memory: Minimum 512MB RAM (1GB recommended)
  • Storage: 100MB for installation + log storage

Required Services

  • BookStack Instance: Running and accessible
  • BookStack API: Enabled with valid token
  • Network Access: HTTP/HTTPS connection to BookStack

Verify Prerequisites

# Check Node.js version
node --version  # Should be 18.0.0+

# Check npm version
npm --version   # Should be 9.0.0+

# Check system resources
free -h         # Linux/macOS

🏠 BookStack Server Requirements

BookStack Version

  • Recommended: Latest stable version of BookStack
  • API Version: v1 (current)

⚠️ Note: This server uses modern BookStack API features including the system endpoint for health checks. Please ensure you're running a recent version of BookStack.

BookStack Configuration

Your BookStack instance must have:

  1. API Access Enabled

    // In BookStack .env file
API_REQUESTS_PER_MIN=180
API_DEFAULT_ITEM_COUNT=100

  2. API Rate Limits (optional - adjust if needed)

    // In BookStack .env file - adjust based on your usage
API_REQUESTS_PER_MIN=180

  3. User Permissions

    • API user must have appropriate permissions
    • Recommended: Admin role for full access
    • Minimum: View permissions for content areas

API Token Setup

  1. Log into BookStack as admin or privileged user

  2. Navigate to: Profile → API Tokens

  3. Create New Token:

    • Name: mcp-server-token
    • Description: Token for MCP server access
    • Expiry: Set appropriate expiry (optional)

  4. Combine Token Parts: BookStack provides a Token ID and Token Secret

    Important: You need to combine these as {token_id}:{token_secret}

    Example:

    • Token ID: AbCdEf123456
    • Token Secret: xyz789secretkey
    • Final Token: AbCdEf123456:xyz789secretkey

  5. Save Token: Store the combined token securely for configuration

💡 Token Format: The API token must be in the format {token_id}:{token_secret} as shown in BookStack's API documentation.

📦 Installation Methods

Method 1: Global Installation (Recommended)

# Install globally for system-wide access
npm install -g bookstack-mcp-server

# Verify installation
bookstack-mcp-server --version

Method 2: Local Project Installation

# Create project directory
mkdir my-bookstack-mcp
cd my-bookstack-mcp

# Install locally
npm install bookstack-mcp-server

# Or install from source
git clone https://github.com/pnocera/bookstack-mcp-server.git
cd bookstack-mcp-server
npm install
npm run build

Method 3: Development Installation

# Clone repository
git clone https://github.com/pnocera/bookstack-mcp-server.git
cd bookstack-mcp-server

# Install dependencies
npm install

# Build project
npm run build

# Run development server
npm run dev

⚙️ Configuration

Environment Variables

Create a .env file in your project directory:

# BookStack API Configuration
BOOKSTACK_BASE_URL=http://localhost:8080/api
BOOKSTACK_API_TOKEN=your-api-token-here
BOOKSTACK_TIMEOUT=30000

# Server Configuration
SERVER_NAME=bookstack-mcp-server
SERVER_VERSION=1.0.0
SERVER_PORT=3000

# Rate Limiting
RATE_LIMIT_REQUESTS_PER_MINUTE=60
RATE_LIMIT_BURST_LIMIT=10

# Validation
VALIDATION_ENABLED=true
VALIDATION_STRICT_MODE=false

# Logging
LOG_LEVEL=info
LOG_FORMAT=pretty

# Context7 Integration
CONTEXT7_ENABLED=true
CONTEXT7_LIBRARY_ID=/bookstack/bookstack
CONTEXT7_CACHE_TTL=3600

# Security
CORS_ENABLED=true
CORS_ORIGIN=*
HELMET_ENABLED=true

# Development
NODE_ENV=development
DEBUG=false

Configuration Options Explained

BookStack Settings

  • BOOKSTACK_BASE_URL: Full URL to BookStack API endpoint

    • Format: http://yourserver.com/api
    • Include /api suffix
    • Use HTTPS in production

  • BOOKSTACK_API_TOKEN: API token from BookStack

    • Generate in BookStack admin panel
    • Keep secure and rotate regularly

  • BOOKSTACK_TIMEOUT: Request timeout in milliseconds

    • Default: 30000 (30 seconds)
    • Increase for slow networks

Rate Limiting

  • RATE_LIMIT_REQUESTS_PER_MINUTE: Maximum requests per minute

    • Default: 60
    • Adjust based on BookStack limits

  • RATE_LIMIT_BURST_LIMIT: Concurrent request limit

    • Default: 10
    • Prevents overwhelming BookStack

Logging

  • LOG_LEVEL: Logging verbosity

    • Options: error, warn, info, debug
    • Use info for production

  • LOG_FORMAT: Log output format

    • Options: json, pretty
    • Use json for production logs

Validation

  • VALIDATION_ENABLED: Enable input validation

    • Default: true
    • Always keep enabled

  • VALIDATION_STRICT_MODE: Strict validation mode

    • Default: false
    • Enable for additional safety

🔐 Authentication Setup

BookStack User Setup

  1. Create Service Account (recommended)

    Email: mcp-service@yourcompany.com
Name: MCP Service Account
Role: Admin (or custom role with required permissions)

  2. Generate API Token

    • Login as service account
    • Go to Profile → API Tokens
    • Create token with descriptive name
    • Important: Combine the Token ID and Token Secret as {token_id}:{token_secret}
    • Store the combined token securely

Token Security

  • Storage: Use environment variables or secure vault
  • Rotation: Implement regular token rotation
  • Monitoring: Monitor token usage and access

Permission Requirements

The API user needs these minimum permissions:

  • Books: View, Create, Update, Delete
  • Pages: View, Create, Update, Delete
  • Chapters: View, Create, Update, Delete
  • Shelves: View, Create, Update, Delete
  • Users: View (for user management tools)
  • System: View (for system info tools)

🎨 Claude Integration

Claude Desktop Integration

Add to your Claude Desktop configuration:

Method 1: Manual Configuration

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "bookstack": {
      "command": "bookstack-mcp-server",
      "env": {
        "BOOKSTACK_BASE_URL": "http://localhost:8080/api",
        "BOOKSTACK_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Method 2: Using Claude CLI

# Add server configuration
claude mcp add bookstack bookstack-mcp-server \
  --env BOOKSTACK_BASE_URL=http://localhost:8080/api \
  --env BOOKSTACK_API_TOKEN=your-api-token-here

# Verify configuration
claude mcp list

Claude Code Integration

For Claude Code MCP support:

# Add as MCP server
claude mcp add-json bookstack '{
  "type": "stdio",
  "command": "npx",
  "args": ["bookstack-mcp-server"],
  "env": {
    "BOOKSTACK_BASE_URL": "http://localhost:8080/api",
    "BOOKSTACK_API_TOKEN": "your-api-token-here"
  }
}'

Configuration File Locations

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json
  • Linux: ~/.config/claude/claude_desktop_config.json

🔧 Advanced Configuration

Custom Configuration Files

Create config.json for complex setups:

{
  "bookstack": {
    "baseUrl": "https://docs.company.com/api",
    "apiToken": "${BOOKSTACK_API_TOKEN}",
    "timeout": 45000,
    "retryAttempts": 3,
    "retryDelay": 1000
  },
  "server": {
    "name": "company-bookstack-mcp",
    "version": "1.0.0",
    "port": 3000
  },
  "rateLimit": {
    "requestsPerMinute": 120,
    "burstLimit": 20
  },
  "logging": {
    "level": "info",
    "format": "json",
    "logFile": "/var/log/bookstack-mcp.log"
  },
  "features": {
    "enableMetrics": true,
    "enableHealthCheck": true,
    "enableDocumentation": true
  }
}

Production Configuration

For production deployments:

# Production Environment Variables
NODE_ENV=production
DEBUG=false
LOG_LEVEL=warn
LOG_FORMAT=json

# Security
CORS_ORIGIN=https://yourapp.com
HELMET_ENABLED=true

# Performance
RATE_LIMIT_REQUESTS_PER_MINUTE=180
RATE_LIMIT_BURST_LIMIT=30

# Monitoring
ENABLE_METRICS=true
METRICS_PORT=9090
HEALTH_CHECK_PORT=9091

Multiple BookStack Instances

For multiple BookStack instances:

{
  "instances": [
    {
      "name": "production",
      "baseUrl": "https://docs.company.com/api",
      "apiToken": "${PROD_API_TOKEN}",
      "priority": 1
    },
    {
      "name": "staging",
      "baseUrl": "https://staging-docs.company.com/api",
      "apiToken": "${STAGING_API_TOKEN}",
      "priority": 2
    }
  ]
}

🛠️ Development Setup

Development Environment

# Clone repository
git clone https://github.com/pnocera/bookstack-mcp-server.git
cd bookstack-mcp-server

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env

# Start development server
npm run dev

Development Scripts

# Development server with hot reload
npm run dev

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Clean build directory
npm run clean

Testing Configuration

# Run specific test file
npm test -- books.test.ts

# Run tests in watch mode
npm run test:watch

# Debug tests
npm run test:debug

🚀 Deployment Options

Systemd Service (Linux)

Create /etc/systemd/system/bookstack-mcp.service:

[Unit]
Description=BookStack MCP Server
After=network.target

[Service]
Type=simple
User=bookstack-mcp
WorkingDirectory=/opt/bookstack-mcp
ExecStart=/usr/bin/node /opt/bookstack-mcp/dist/server.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
EnvironmentFile=/opt/bookstack-mcp/.env

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable bookstack-mcp
sudo systemctl start bookstack-mcp
sudo systemctl status bookstack-mcp

Docker Deployment

Create Dockerfile:

FROM node:18-alpine

# Create app directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy source code
COPY dist ./dist
COPY .env.example .env

# Expose port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (res) => process.exit(res.statusCode === 200 ? 0 : 1))"

# Start server
CMD ["node", "dist/server.js"]

Build and run:

# Build image
docker build -t bookstack-mcp-server .

# Run container
docker run -d \
  --name bookstack-mcp \
  -p 3000:3000 \
  -e BOOKSTACK_BASE_URL=http://bookstack:8080/api \
  -e BOOKSTACK_API_TOKEN=your-token \
  bookstack-mcp-server

🔍 Troubleshooting

Common Issues

1. Connection Refused

Error: ECONNREFUSED connecting to BookStack

Solutions:

  • Verify BookStack is running and accessible
  • Check BOOKSTACK_BASE_URL is correct
  • Ensure /api suffix is included in URL
  • Test API access: curl -H "Authorization: Token YOUR_TOKEN" http://localhost:8080/api/docs

2. Authentication Failed

Error: 401 Unauthorized or 403 Forbidden

Solutions:

  • Verify API token is correct and not expired
  • Check user permissions in BookStack
  • Ensure token has required scopes
  • Test token: curl -H "Authorization: Token YOUR_TOKEN" http://localhost:8080/api/users

3. Rate Limit Exceeded

Error: 429 Too Many Requests

Solutions:

  • Reduce RATE_LIMIT_REQUESTS_PER_MINUTE
  • Increase RATE_LIMIT_BURST_LIMIT
  • Check BookStack rate limits
  • Implement request queuing

4. Validation Errors

Error: Configuration validation failed

Solutions:

  • Check all required environment variables are set
  • Verify URL format (must include protocol)
  • Ensure numeric values are valid
  • Review configuration schema

5. Memory Issues

Error: JavaScript heap out of memory

Solutions:

  • Increase Node.js memory: node --max-old-space-size=4096 dist/server.js
  • Reduce concurrent connections
  • Enable response streaming
  • Check for memory leaks

Debug Mode

Enable debug logging:

# Set debug environment
export DEBUG=true
export LOG_LEVEL=debug

# Run with debug output
npm run dev

Health Checks

Monitor server health:

# Check server status
curl http://localhost:3000/health

# Expected response
{
  "status": "healthy",
  "checks": [
    {"name": "bookstack_connection", "healthy": true},
    {"name": "tools_loaded", "healthy": true, "message": "47 tools loaded"},
    {"name": "resources_loaded", "healthy": true, "message": "12 resources loaded"}
  ]
}

Log Analysis

Check logs for issues:

# View recent logs
tail -f /var/log/bookstack-mcp.log

# Search for errors
grep -i error /var/log/bookstack-mcp.log

# Filter by timestamp
grep "2024-01-01" /var/log/bookstack-mcp.log

Performance Monitoring

Monitor performance metrics:

# Check memory usage
ps aux | grep bookstack-mcp

# Monitor network connections
netstat -an | grep :3000

# Check file descriptors
lsof -p $(pgrep -f bookstack-mcp)

❓ FAQ

Q: Can I use this with BookStack SaaS?

A: Yes, if your BookStack SaaS provider supports API access. Contact your provider for API endpoint and token generation.

Q: Does this support multiple BookStack instances?

A: Currently, one instance per server. For multiple instances, run multiple MCP servers with different configurations.

Q: What's the difference between tools and resources?

A: Tools are active functions (create, update, delete). Resources are passive data access (read-only content).

Q: How do I backup my configuration?

A: Back up your .env file and any custom configuration files. Store API tokens securely.

Q: Can I customize the available tools?

A: Yes, you can disable specific tools by modifying the source code or using feature flags.

Q: How do I migrate from an older version?

A:

  1. Backup current configuration
  2. Update to new version
  3. Compare configuration schemas
  4. Test all integrations
  5. Update Claude integration if needed

Q: Is there a GUI for configuration?

A: Currently no GUI is available. Configuration is done through environment variables and config files.

Q: How do I contribute to the project?

A:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

Q: What's the performance impact?

A: Minimal. The server uses connection pooling and efficient caching. Typical memory usage is 50-100MB.

Q: Can I use this in production?

A: Yes, it's designed for production use. Follow the production configuration guidelines and implement proper monitoring.

📞 Support

📝 License

This project is licensed under the MIT License. See the LICENSE file for details.

Built with ❤️ for the BookStack community