Derron-Knox/bookstack-mcp-server

📚 BookStack MCP Server

A professional-grade Model Context Protocol (MCP) server that seamlessly bridges AI assistants with BookStack knowledge management systems. Transform your documentation workflows with intelligent automation.

Created by Derron Knox | Showcasing enterprise-level software architecture and best practices

🚀 Overview

This TypeScript-based MCP server provides a robust, production-ready interface for AI assistants to interact with BookStack instances. Designed with enterprise scalability, security, and maintainability in mind, it demonstrates advanced software engineering principles and modern development practices.

✨ Key Features

• 🛡️ Enterprise Security: Token-based authentication with secure credential management
• 🏗️ Modular Architecture: Clean separation of concerns with TypeScript interfaces
• 🔄 Comprehensive CRUD Operations: Full lifecycle management of BookStack content
• 🐳 Container-Ready: Production-optimized Docker setup with multi-stage builds
• ⚡ High Performance: Optimized API calls with proper error handling and timeouts
• 📋 Type Safety: Full TypeScript implementation with strict type checking
• 🔍 Smart Search: Advanced content discovery and filtering capabilities
• 📖 Intelligent Resolution: Name-to-ID resolution for user-friendly operations

🛠️ Available Tools

Page Management

• create_page - Create new pages with HTML/Markdown content
• get_page_content - Retrieve page content by ID or name
• update_page - Modify existing pages (content, location, metadata)
• delete_page - Remove pages from BookStack

Content Discovery

• search_items - Search across shelves, books, chapters, and pages
• list_books - Enumerate books with filtering and pagination
• list_shelves - Browse shelf collections with advanced options

Book Management

• read_book - Get details of a specific book by ID or name
• create_book - Create a new book
• update_book - Modify existing books (content, metadata)
• delete_book - Remove books from BookStack

Advanced Features

• Flexible Targeting: Use either IDs or names for all operations
• Context-Aware Resolution: Automatic name-to-ID conversion
• Hierarchical Navigation: Support for book/chapter/page relationships
• Metadata Management: Tags, priorities, and organizational features

🏃‍♂️ Quick Start

Prerequisites

• Node.js 20+
• Docker & Docker Compose (for containerized deployment)
• BookStack instance with API access
• BookStack API tokens (Token ID & Secret)

1. Environment Setup

# Clone and configure
git clone <repository-url>
cd bookstack/
cp .env.example .env

# Configure your BookStack credentials
cat > .env << EOF
BOOKSTACK_URL="https://your-bookstack-instance.com"
BOOKSTACK_API_TOKEN_ID="your_token_id_here"
BOOKSTACK_API_TOKEN_SECRET="your_token_secret_here"
EOF

2. Installation Options

Option A: Docker Deployment (Recommended)

# Production-ready containerized deployment
docker-compose up --build -d

# Monitor logs
docker-compose logs -f bookstack-mcp-server

Option B: Local Development

# Install dependencies
npm install

# Development with hot reload
npm run watch

# Production build
npm run build
npm start

3. Integration with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bookstack-mcp-server": {
      "command": "node",
      "args": ["/path/to/bookstack/build/index.js"],
      "env": {
        "BOOKSTACK_URL": "https://your-bookstack-instance.com",
        "BOOKSTACK_API_TOKEN_ID": "your_token_id",
        "BOOKSTACK_API_TOKEN_SECRET": "your_token_secret"
      }
    }
  }
}

🏗️ Architecture & Best Practices

Project Structure

bookstack/
├── src/
│   ├── types.ts              # TypeScript interface definitions
│   ├── utils/
│   │   ├── validation.ts     # Input validation & sanitization
│   │   └── api.ts           # API utilities & helper functions
│   ├── tools/
│   │   ├── definitions.ts    # Tool schema definitions
│   │   └── handlers.ts      # Business logic implementations
│   └── index.ts             # Main server & orchestration
├── build/                   # Compiled JavaScript output
├── Dockerfile              # Multi-stage container build
├── docker-compose.yml      # Production deployment config
└── package.json            # Dependencies & scripts

Engineering Principles Demonstrated

🎯 Clean Architecture

• Separation of Concerns: Distinct layers for validation, business logic, and API interaction
• Dependency Injection: Modular design with clear interfaces
• Single Responsibility: Each module has one well-defined purpose

🔒 Security First

• Environment Variable Management: Secure credential handling
• Input Validation: Comprehensive argument sanitization
• Error Boundaries: Proper exception handling without information leakage

🚀 Production Readiness

• Container Optimization: Multi-stage Docker builds for minimal image size
• Health Checks: Built-in container health monitoring
• Graceful Shutdown: Proper signal handling for clean termination
• Comprehensive Logging: Structured error reporting and debugging

📊 Code Quality

• TypeScript Strict Mode: Full type safety with comprehensive interfaces
• Modular Design: Reusable components with clear APIs
• Error Handling: Robust exception management with user-friendly messages

🔧 Configuration Options

Environment Variables

Docker Configuration

• Health Checks: 30-second intervals with 3 retry attempts
• Log Rotation: 10MB max file size, 5 file retention
• Security: Non-root user execution
• Resource Optimization: Multi-stage builds for production efficiency

🔍 Usage Examples

Creating Content

// Create a page in a specific book
await createPage({
  name: "API Documentation",
  markdown: "# API Guide\n\nComprehensive API documentation...",
  book_name: "Development Guides",
  tags: [
    { name: "category", value: "api" },
    { name: "priority", value: "high" }
  ]
});

Content Discovery

// Search across all content types
await searchItems({
  query: "kubernetes deployment",
  count: 20
});

// Find pages by context
await getPageContent({
  page_name: "Deployment Guide",
  book_name: "Infrastructure Documentation"
});

Content Management

// Update page with new content
await updatePage({
  page_name: "Getting Started",
  book_name: "User Manual",
  markdown: "# Updated Getting Started Guide\n...",
  tags: [{ name: "status", value: "updated" }]
});

🚀 Deployment Options

Production Deployment

Docker Swarm

# Scale across multiple nodes
docker stack deploy -c docker-compose.yml bookstack-mcp

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: bookstack-mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: bookstack-mcp-server
  template:
    metadata:
      labels:
        app: bookstack-mcp-server
    spec:
      containers:
      - name: bookstack-mcp-server
        image: bookstack-mcp-server:latest
        env:
        - name: BOOKSTACK_URL
          valueFrom:
            secretKeyRef:
              name: bookstack-credentials
              key: url

Development Workflow

# Development with auto-reload
npm run watch

# Type checking
npx tsc --noEmit

# Debug with MCP Inspector
npm run inspector

🐛 Debugging & Troubleshooting

MCP Inspector

# Launch debugging interface
npm run inspector
# Access via browser at provided URL

Common Issues

Connection Problems

# Verify BookStack accessibility
curl -H "Authorization: Token $BOOKSTACK_API_TOKEN_ID:$BOOKSTACK_API_TOKEN_SECRET" \
     "$BOOKSTACK_URL/api/books"

Container Issues

# Check container health
docker-compose ps
docker-compose logs bookstack-mcp-server

# Restart with fresh build
docker-compose down && docker-compose up --build

📋 Dependencies

Production Dependencies

• @modelcontextprotocol/sdk: ^0.6.0 - MCP protocol implementation
• axios: ^1.9.0 - HTTP client for BookStack API

Development Dependencies

• typescript: ^5.3.3 - Type-safe JavaScript development
• @types/node: ^20.11.24 - Node.js type definitions

System Requirements

• Node.js: 20+ (LTS recommended)
• Memory: 256MB minimum, 512MB recommended
• Storage: 100MB for application, additional for logs

🎯 Professional Showcase

This project demonstrates expertise in:

Backend Development

• RESTful API integration and design
• Microservices architecture patterns
• Error handling and resilience patterns

DevOps & Infrastructure

• Containerization with Docker
• Production deployment strategies
• Configuration management
• Health monitoring and observability

Software Engineering

• Clean code principles
• Design patterns (Strategy, Factory, Dependency Injection)
• Test-driven development mindset
• Documentation and maintainability

Modern JavaScript/TypeScript

• Advanced TypeScript features
• Async/await patterns
• ES2022+ modern syntax
• Node.js best practices

🤝 Contributing

This project welcomes contributions! Areas for enhancement:

• Unit test coverage expansion
• Additional BookStack API endpoints
• Performance optimizations
• Enhanced error recovery

📞 Contact

Derron Knox - Software Engineer & Solutions Architect

• 🌐 Portfolio
• 📧
• 💼 LinkedIn

This project exemplifies enterprise-grade software development practices, demonstrating proficiency in modern web technologies, cloud-native development, and scalable system architecture.