bookstack-mcp-server

v1.0.0

Published

5 months ago

MCP server providing comprehensive access to BookStack knowledge management system

0High
0Medium
0Low

pnocera

mcp bookstack api server claude context documentation

BookStack MCP Server

A comprehensive Model Context Protocol (MCP) server providing full access to BookStack's knowledge management capabilities. This server exposes all 47 BookStack API endpoints as MCP tools, enabling seamless integration with Claude and other MCP-compatible AI assistants.

🚀 Features

Complete BookStack Integration

47 MCP Tools covering all BookStack API endpoints
Resource Access for dynamic content retrieval
Real-time Search across all content types
Export Functionality in multiple formats (HTML, PDF, Markdown, Plain Text)
Content Management for books, pages, chapters, shelves, users, and roles

Advanced Capabilities

Rate Limiting with configurable limits and burst protection
Comprehensive Validation using Zod schemas
Error Handling with retry logic and proper error mapping
Context7 Integration for enhanced documentation
Health Monitoring with detailed system checks
Logging with configurable levels and formats

Developer Experience

TypeScript Support with complete type definitions
Hot Reloading during development
Comprehensive Testing with unit and integration tests
Docker Support for easy deployment
Extensive Documentation with examples and guides

📦 Installation

Prerequisites

Node.js 18+ and npm 9+
BookStack instance with API access
API token from BookStack

Quick Start

Clone and Install

git clone <repository-url>
cd bookstack-mcp-server
npm install

Configure Environment

cp .env.example .env
# Edit .env with your BookStack details

Build and Start
```
npm run build
npm start
```

Configuration

Create a .env file with your BookStack configuration:

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

# Server Configuration
LOG_LEVEL=info
VALIDATION_ENABLED=true
CONTEXT7_ENABLED=true

# Rate Limiting
RATE_LIMIT_REQUESTS_PER_MINUTE=60
RATE_LIMIT_BURST_LIMIT=10

🛠️ Available Tools

Books (6 tools)

bookstack_books_list - List all books with filtering
bookstack_books_create - Create new books
bookstack_books_read - Get book details with contents
bookstack_books_update - Update book information
bookstack_books_delete - Delete books (to recycle bin)
bookstack_books_export - Export books in multiple formats

Pages (6 tools)

bookstack_pages_list - List all pages with filtering
bookstack_pages_create - Create new pages with HTML/Markdown
bookstack_pages_read - Get page details with content
bookstack_pages_update - Update page content and metadata
bookstack_pages_delete - Delete pages (to recycle bin)
bookstack_pages_export - Export pages in multiple formats

Chapters (6 tools)

bookstack_chapters_list - List all chapters
bookstack_chapters_create - Create new chapters
bookstack_chapters_read - Get chapter details with pages
bookstack_chapters_update - Update chapter information
bookstack_chapters_delete - Delete chapters
bookstack_chapters_export - Export chapters

Additional Tools

Search - Advanced search across all content
Users & Roles - Complete user management
Attachments & Images - File management
Permissions - Content access control
System Info - Instance information and health
Recycle Bin - Deleted item recovery

🔗 Claude Code Integration

Add to your Claude Code MCP configuration:

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

📚 Usage Examples

List Books

// Use the bookstack_books_list tool
{
  "count": 10,
  "sort": "updated_at",
  "filter": {
    "name": "documentation"
  }
}

Create a Page

// Use the bookstack_pages_create tool
{
  "name": "API Documentation",
  "book_id": 1,
  "html": "<h1>API Guide</h1><p>Complete API documentation...</p>",
  "tags": [
    {"name": "category", "value": "documentation"},
    {"name": "status", "value": "draft"}
  ]
}

Search Content

// Use the bookstack_search tool
{
  "query": "API documentation [page] tag:category=api",
  "count": 20
}

🧪 Development

Scripts

npm run dev          # Start development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm run test         # Run test suite
npm run test:watch   # Run tests in watch mode
npm run lint         # Lint TypeScript code
npm run format       # Format code with Prettier

Project Structure

src/
├── server.ts           # Main MCP server
├── api/
│   └── client.ts       # BookStack API client
├── tools/              # MCP tool implementations
│   ├── books.ts
│   ├── pages.ts
│   └── ...
├── resources/          # MCP resource handlers
├── utils/              # Utilities (logging, errors, rate limiting)
├── validation/         # Zod schemas and validation
├── config/             # Configuration management
└── context7/           # Context7 integration

Testing

# Run all tests
npm test

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

# Run with coverage
npm run test:coverage

🐳 Docker Deployment

Build Image

docker build -t bookstack-mcp-server .

Run Container

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

Docker Compose

version: '3.8'
services:
  bookstack-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      BOOKSTACK_BASE_URL: http://bookstack:8080/api
      BOOKSTACK_API_TOKEN: your-token
    depends_on:
      - bookstack

🔍 Monitoring & Health Checks

Health Endpoint

The server provides health check functionality:

curl http://localhost:3000/health

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"}
  ]
}

Metrics

Request/response times
Error rates
Rate limit status
Memory usage
Tool usage statistics

🛡️ Security

API Token Management

Secure token storage in environment variables
Token validation on startup
Automatic token rotation support (when available)

Rate Limiting

Configurable request limits (default: 60/minute)
Burst protection (default: 10 concurrent)
Automatic backoff on rate limit hits

Input Validation

Comprehensive Zod schema validation
SQL injection prevention
XSS protection for HTML content
File upload validation

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow TypeScript best practices
Add tests for new features
Update documentation
Follow conventional commit messages
Ensure all tests pass

📝 License

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

🆘 Support

Documentation: Implementation Guide
Issues: GitHub Issues
Examples: Example Usage

🎯 Roadmap

Planned Features

[ ] Real-time notifications via WebSockets
[ ] Bulk operations for content management
[ ] Advanced caching strategies
[ ] Metrics dashboard
[ ] Plugin system for custom tools
[ ] Multi-instance BookStack support

Performance Goals

99.9% uptime
<100ms average response time
Support for 1000+ concurrent connections
Memory usage under 512MB

Built with ❤️ for the BookStack community

For more information about BookStack, visit bookstackapp.com