# 📚 BookStack MCP Server

[![TypeScript](https://img.shields.io/badge/TypeScript-5.8.3-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> 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](https://github.com/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

```bash
# 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)
```bash
# Production-ready containerized deployment
docker-compose up --build -d

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

#### Option B: Local Development
```bash
# 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`):

```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
| Variable | Description | Required | Example |
|----------|-------------|----------|---------|
| `BOOKSTACK_URL` | BookStack instance URL | ✅ | `https://wiki.company.com` |
| `BOOKSTACK_API_TOKEN_ID` | API Token ID from BookStack | ✅ | `abc123def456` |
| `BOOKSTACK_API_TOKEN_SECRET` | API Token Secret from BookStack | ✅ | `xyz789uvw012` |

### 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```bash
# Scale across multiple nodes
docker stack deploy -c docker-compose.yml bookstack-mcp
```

#### Kubernetes
```yaml
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
```bash
# Development with auto-reload
npm run watch

# Type checking
npx tsc --noEmit

# Debug with MCP Inspector
npm run inspector
```

---

## 🐛 Debugging & Troubleshooting

### MCP Inspector
```bash
# Launch debugging interface
npm run inspector
# Access via browser at provided URL
```

### Common Issues

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

#### Container Issues
```bash
# 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](https://dknox.dev)
- 📧 [Email](mailto:derron.knox@gmail.com)
- 💼 [LinkedIn](https://www.linkedin.com/in/dknox86/)

---

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