bookstack-mcp 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 BookStack MCP Server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# BookStack MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives AI assistants full access to your [BookStack](https://www.bookstackapp.com) documentation — search, read, create, and manage content.
+
+## Features
+
+- 17 read-only tools + 8 write tools for complete BookStack API coverage
+- Type-safe input validation with Zod (auto-coerces string/number params for broad client compatibility)
+- Embedded URLs and content previews in all responses
+- Write operations disabled by default for safety
+- Works with Claude Desktop, LibreChat, and any MCP-compatible client
+
+## Quick Start
+
+### Install from npm
+
+```bash
+npx bookstack-mcp
+```
+
+### Or clone and build
+
+```bash
+git clone https://github.com/ttpears/bookstack-mcp.git
+cd bookstack-mcp
+npm install && npm run build
+npm start
+```
+
+### Environment Variables
+
+```env
+BOOKSTACK_BASE_URL=https://your-bookstack.com   # Required
+BOOKSTACK_TOKEN_ID=your-token-id                # Required
+BOOKSTACK_TOKEN_SECRET=your-token-secret        # Required
+BOOKSTACK_ENABLE_WRITE=false                    # Optional, default false
+```
+
+## Client Configuration
+
+### Claude Desktop
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "bookstack": {
+      "command": "npx",
+      "args": ["-y", "bookstack-mcp"],
+      "env": {
+        "BOOKSTACK_BASE_URL": "https://your-bookstack.com",
+        "BOOKSTACK_TOKEN_ID": "your-token-id",
+        "BOOKSTACK_TOKEN_SECRET": "your-token-secret"
+      }
+    }
+  }
+}
+```
+
+### LibreChat
+
+Add to your `librechat.yaml`:
+
+```yaml
+mcpServers:
+  bookstack:
+    command: npx
+    args:
+      - -y
+      - bookstack-mcp
+    env:
+      BOOKSTACK_BASE_URL: "https://your-bookstack.com"
+      BOOKSTACK_TOKEN_ID: "your-token-id"
+      BOOKSTACK_TOKEN_SECRET: "your-token-secret"
+```
+
+Restart LibreChat after config changes.
+
+## Available Tools
+
+### Read Operations (always available)
+
+| Tool | Description |
+|------|-------------|
+| `get_capabilities` | Server capabilities and configuration |
+| `search_content` | Search across all content with filtering |
+| `search_pages` | Search pages with optional book filtering |
+| `get_books` / `get_book` | List or get details of books |
+| `get_pages` / `get_page` | List or get full page content |
+| `get_chapters` / `get_chapter` | List or get chapter details |
+| `get_shelves` / `get_shelf` | List or get shelf details |
+| `get_attachments` / `get_attachment` | List or get attachment details |
+| `export_page` | Export page as HTML, PDF, Markdown, plaintext, or ZIP |
+| `export_book` | Export entire book |
+| `export_chapter` | Export chapter |
+| `get_recent_changes` | Recently updated content |
+
+### Write Operations (requires `BOOKSTACK_ENABLE_WRITE=true`)
+
+| Tool | Description |
+|------|-------------|
+| `create_page` / `update_page` | Create or update pages |
+| `create_shelf` / `update_shelf` / `delete_shelf` | Manage shelves |
+| `create_attachment` / `update_attachment` / `delete_attachment` | Manage attachments |
+
+## BookStack API Setup
+
+1. Log into BookStack as an admin
+2. Go to **Settings > Users > Edit your user**
+3. Ensure the user has **Access System API** permission
+4. In the **API Tokens** section, create a new token
+5. Copy the Token ID and Token Secret
+
+## Security
+
+- Write operations are **disabled by default**
+- Use HTTPS for production instances
+- Store API tokens securely (never commit to git)
+- Consider a dedicated BookStack user with limited permissions
+
+## Development
+
+```bash
+npm run dev          # Hot reload with tsx
+npm run type-check   # Type checking only
+npm run build        # Production build
+```
+
+## License
+
+MIT

package/dist/bookstack-client.js

@@ -0,0 +1,552 @@
+import axios from 'axios';
+export class BookStackClient {
+    client;
+    enableWrite;
+    baseUrl;
+    bookSlugCache = new Map();
+    constructor(config) {
+        this.enableWrite = config.enableWrite || false;
+        this.baseUrl = config.baseUrl;
+        this.client = axios.create({
+            baseURL: `${config.baseUrl}/api`,
+            headers: {
+                'Authorization': `Token ${config.tokenId}:${config.tokenSecret}`,
+                'Content-Type': 'application/json'
+            }
+        });
+    }
+    async getBookSlug(bookId) {
+        // Check cache first
+        if (this.bookSlugCache.has(bookId)) {
+            return this.bookSlugCache.get(bookId);
+        }
+        try {
+            const response = await this.client.get(`/books/${bookId}`);
+            const slug = response.data.slug || String(bookId);
+            this.bookSlugCache.set(bookId, slug);
+            return slug;
+        }
+        catch (error) {
+            // Fallback to ID if book fetch fails
+            return String(bookId);
+        }
+    }
+    // URL generation utilities
+    generateBookUrl(book) {
+        return `${this.baseUrl}/books/${book.slug || book.id}`;
+    }
+    async generatePageUrl(page) {
+        const bookSlug = await this.getBookSlug(page.book_id);
+        return `${this.baseUrl}/books/${bookSlug}/page/${page.slug || page.id}`;
+    }
+    async generateChapterUrl(chapter) {
+        const bookSlug = await this.getBookSlug(chapter.book_id);
+        return `${this.baseUrl}/books/${bookSlug}/chapter/${chapter.slug || chapter.id}`;
+    }
+    generateShelfUrl(shelf) {
+        return `${this.baseUrl}/shelves/${shelf.slug || shelf.id}`;
+    }
+    generateSearchUrl(query) {
+        const encodedQuery = encodeURIComponent(query);
+        return `${this.baseUrl}/search?term=${encodedQuery}`;
+    }
+    // Enhanced response helpers
+    enhanceBookResponse(book) {
+        const lastUpdated = this.formatDate(book.updated_at);
+        const created = this.formatDate(book.created_at);
+        return {
+            ...book,
+            url: this.generateBookUrl(book),
+            direct_link: `[${book.name}](${this.generateBookUrl(book)})`,
+            last_updated_friendly: lastUpdated,
+            created_friendly: created,
+            summary: book.description ? `${book.description.substring(0, 100)}${book.description.length > 100 ? '...' : ''}` : 'No description available',
+            content_info: `Book created ${created}, last updated ${lastUpdated}`
+        };
+    }
+    async enhancePageResponse(page) {
+        const lastUpdated = this.formatDate(page.updated_at);
+        const created = this.formatDate(page.created_at);
+        const contentPreview = page.text ? `${page.text.substring(0, 200)}${page.text.length > 200 ? '...' : ''}` : 'No content preview available';
+        const url = await this.generatePageUrl(page);
+        return {
+            ...page,
+            url,
+            direct_link: `[${page.name}](${url})`,
+            last_updated_friendly: lastUpdated,
+            created_friendly: created,
+            content_preview: contentPreview,
+            content_info: `Page created ${created}, last updated ${lastUpdated}`,
+            word_count: page.text ? page.text.split(' ').length : 0,
+            location: `Book ID ${page.book_id}${page.chapter_id ? `, Chapter ID ${page.chapter_id}` : ''}`
+        };
+    }
+    async enhanceChapterResponse(chapter) {
+        const lastUpdated = this.formatDate(chapter.updated_at);
+        const created = this.formatDate(chapter.created_at);
+        const url = await this.generateChapterUrl(chapter);
+        return {
+            ...chapter,
+            url,
+            direct_link: `[${chapter.name}](${url})`,
+            last_updated_friendly: lastUpdated,
+            created_friendly: created,
+            summary: chapter.description ? `${chapter.description.substring(0, 100)}${chapter.description.length > 100 ? '...' : ''}` : 'No description available',
+            content_info: `Chapter created ${created}, last updated ${lastUpdated}`,
+            location: `In Book ID ${chapter.book_id}`
+        };
+    }
+    enhanceShelfResponse(shelf) {
+        const lastUpdated = this.formatDate(shelf.updated_at);
+        const created = this.formatDate(shelf.created_at);
+        const bookCount = shelf.books?.length || 0;
+        return {
+            ...shelf,
+            url: this.generateShelfUrl(shelf),
+            direct_link: `[${shelf.name}](${this.generateShelfUrl(shelf)})`,
+            last_updated_friendly: lastUpdated,
+            created_friendly: created,
+            summary: shelf.description ? `${shelf.description.substring(0, 100)}${shelf.description.length > 100 ? '...' : ''}` : 'No description available',
+            content_info: `Shelf with ${bookCount} book${bookCount !== 1 ? 's' : ''}, created ${created}, last updated ${lastUpdated}`,
+            book_count: bookCount,
+            books: shelf.books?.map(book => this.enhanceBookResponse(book)),
+            tags_summary: shelf.tags?.length ? `Tagged with: ${shelf.tags.map(t => `${t.name}${t.value ? `=${t.value}` : ''}`).join(', ')}` : 'No tags'
+        };
+    }
+    async enhanceSearchResults(results, originalQuery) {
+        const enhancedResults = await Promise.all(results.map(async (result) => {
+            const url = await this.generateContentUrl(result);
+            return {
+                ...result,
+                url,
+                direct_link: `[${result.name}](${url})`,
+                content_preview: result.preview_content?.content ? `${result.preview_content.content.substring(0, 150)}${result.preview_content.content.length > 150 ? '...' : ''}` : 'No preview available',
+                content_type: result.type.charAt(0).toUpperCase() + result.type.slice(1),
+                location_info: result.book_id ? `In book ID ${result.book_id}${result.chapter_id ? `, chapter ID ${result.chapter_id}` : ''}` : 'Location unknown'
+            };
+        }));
+        return {
+            search_query: originalQuery,
+            search_url: this.generateSearchUrl(originalQuery),
+            summary: `Found ${results.length} results for "${originalQuery}"`,
+            results: enhancedResults
+        };
+    }
+    async generateContentUrl(result) {
+        switch (result.type) {
+            case 'page':
+                if (result.book_id) {
+                    const bookSlug = await this.getBookSlug(result.book_id);
+                    return `${this.baseUrl}/books/${bookSlug}/page/${result.slug || result.id}`;
+                }
+                return `${this.baseUrl}/link/${result.id}`;
+            case 'chapter':
+                if (result.book_id) {
+                    const bookSlug = await this.getBookSlug(result.book_id);
+                    return `${this.baseUrl}/books/${bookSlug}/chapter/${result.slug || result.id}`;
+                }
+                return `${this.baseUrl}/link/${result.id}`;
+            case 'book':
+                return `${this.baseUrl}/books/${result.slug || result.id}`;
+            case 'bookshelf':
+            case 'shelf':
+                return `${this.baseUrl}/shelves/${result.slug || result.id}`;
+            default:
+                return `${this.baseUrl}/link/${result.id}`;
+        }
+    }
+    async searchContent(query, options) {
+        let searchQuery = query;
+        // Use advanced search syntax for type filtering
+        if (options?.type) {
+            searchQuery = `{type:${options.type}} ${query}`.trim();
+        }
+        const params = { query: searchQuery };
+        if (options?.count)
+            params.count = Math.min(options.count, 500); // BookStack max
+        if (options?.offset)
+            params.offset = options.offset;
+        const response = await this.client.get('/search', { params });
+        const results = response.data.data || response.data;
+        return await this.enhanceSearchResults(results, query);
+    }
+    async searchPages(query, options) {
+        let searchQuery = `{type:page} ${query}`.trim();
+        // Add book filtering if specified
+        if (options?.bookId) {
+            searchQuery = `{book_id:${options.bookId}} ${searchQuery}`;
+        }
+        const params = { query: searchQuery };
+        if (options?.count)
+            params.count = Math.min(options.count, 500);
+        if (options?.offset)
+            params.offset = options.offset;
+        const response = await this.client.get('/search', { params });
+        const results = response.data.data || response.data;
+        return await this.enhanceSearchResults(results, query);
+    }
+    async getBooks(options) {
+        const params = {
+            offset: options?.offset || 0,
+            count: Math.min(options?.count || 50, 500)
+        };
+        if (options?.sort)
+            params.sort = options.sort;
+        if (options?.filter)
+            params.filter = JSON.stringify(options.filter);
+        const response = await this.client.get('/books', { params });
+        const data = response.data;
+        return {
+            ...data,
+            data: data.data.map((book) => this.enhanceBookResponse(book))
+        };
+    }
+    async getBook(id) {
+        const response = await this.client.get(`/books/${id}`);
+        return this.enhanceBookResponse(response.data);
+    }
+    async getPages(options) {
+        const params = {
+            offset: options?.offset || 0,
+            count: Math.min(options?.count || 50, 500)
+        };
+        // Build filter object
+        const filter = { ...options?.filter };
+        if (options?.bookId)
+            filter.book_id = options.bookId;
+        if (options?.chapterId)
+            filter.chapter_id = options.chapterId;
+        if (Object.keys(filter).length > 0) {
+            params.filter = JSON.stringify(filter);
+        }
+        if (options?.sort)
+            params.sort = options.sort;
+        const response = await this.client.get('/pages', { params });
+        const data = response.data;
+        return {
+            ...data,
+            data: await Promise.all(data.data.map((page) => this.enhancePageResponse(page)))
+        };
+    }
+    async getPage(id) {
+        const response = await this.client.get(`/pages/${id}`);
+        return await this.enhancePageResponse(response.data);
+    }
+    async getChapters(bookId, offset = 0, count = 50) {
+        const params = { offset, count };
+        if (bookId)
+            params.filter = JSON.stringify({ book_id: bookId });
+        const response = await this.client.get('/chapters', { params });
+        const data = response.data;
+        return {
+            ...data,
+            data: await Promise.all(data.data.map((chapter) => this.enhanceChapterResponse(chapter)))
+        };
+    }
+    async getChapter(id) {
+        const response = await this.client.get(`/chapters/${id}`);
+        return await this.enhanceChapterResponse(response.data);
+    }
+    async createPage(data) {
+        if (!this.enableWrite) {
+            throw new Error('Write operations are disabled. Set BOOKSTACK_ENABLE_WRITE=true to enable.');
+        }
+        const response = await this.client.post('/pages', data);
+        return await this.enhancePageResponse(response.data);
+    }
+    async updatePage(id, data) {
+        if (!this.enableWrite) {
+            throw new Error('Write operations are disabled. Set BOOKSTACK_ENABLE_WRITE=true to enable.');
+        }
+        const response = await this.client.put(`/pages/${id}`, data);
+        return await this.enhancePageResponse(response.data);
+    }
+    async exportPage(id, format) {
+        try {
+            // For binary formats (PDF, ZIP), return BookStack web URL using slugs
+            if (format === 'pdf' || format === 'zip') {
+                // First fetch the page data to get slugs
+                const page = await this.getPage(id);
+                const book = await this.getBook(page.book_id);
+                // Construct the correct web URL with slugs
+                const directUrl = `${this.baseUrl}/books/${book.slug}/page/${page.slug}/export/${format}`;
+                const filename = `${page.slug}.${format}`;
+                const contentType = format === 'pdf' ? 'application/pdf' : 'application/zip';
+                return {
+                    format: format,
+                    filename: filename,
+                    download_url: directUrl,
+                    content_type: contentType,
+                    export_success: true,
+                    page_id: id,
+                    page_name: page.name,
+                    book_name: book.name,
+                    direct_download: true,
+                    note: "This is a direct link to BookStack's web export. You may need to be logged in to BookStack to access it."
+                };
+            }
+            else {
+                // For text formats, fetch the content via API
+                console.error(`Exporting page ${id} as ${format}...`);
+                const response = await this.client.get(`/pages/${id}/export/${format}`);
+                console.error(`Export response status: ${response.status}`);
+                // For text formats, validate and return as string
+                if (!response.data) {
+                    throw new Error(`Empty ${format} content returned from BookStack API`);
+                }
+                console.error(`Text export length: ${response.data.length} characters`);
+                return response.data;
+            }
+        }
+        catch (error) {
+            console.error(`Export error for page ${id}:`, error);
+            throw new Error(`Failed to export page ${id} as ${format}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async exportBook(id, format) {
+        // For binary formats (PDF, ZIP), return BookStack web URL using slug
+        if (format === 'pdf' || format === 'zip') {
+            // First fetch the book data to get slug
+            const book = await this.getBook(id);
+            // Construct the correct web URL with slug
+            const directUrl = `${this.baseUrl}/books/${book.slug}/export/${format}`;
+            const filename = `${book.slug}.${format}`;
+            const contentType = format === 'pdf' ? 'application/pdf' : 'application/zip';
+            return {
+                format: format,
+                filename: filename,
+                download_url: directUrl,
+                content_type: contentType,
+                export_success: true,
+                book_id: id,
+                book_name: book.name,
+                direct_download: true,
+                note: "This is a direct link to BookStack's web export. You may need to be logged in to BookStack to access it."
+            };
+        }
+        // For text formats, fetch the content via API
+        const response = await this.client.get(`/books/${id}/export/${format}`);
+        return response.data;
+    }
+    async exportChapter(id, format) {
+        // For binary formats (PDF, ZIP), return BookStack web URL using slugs
+        if (format === 'pdf' || format === 'zip') {
+            // First fetch the chapter data to get slugs
+            const chapter = await this.getChapter(id);
+            const book = await this.getBook(chapter.book_id);
+            // Construct the correct web URL with both book and chapter slugs
+            const directUrl = `${this.baseUrl}/books/${book.slug}/chapter/${chapter.slug}/export/${format}`;
+            const filename = `${chapter.slug}.${format}`;
+            const contentType = format === 'pdf' ? 'application/pdf' : 'application/zip';
+            return {
+                format: format,
+                filename: filename,
+                download_url: directUrl,
+                content_type: contentType,
+                export_success: true,
+                chapter_id: id,
+                chapter_name: chapter.name,
+                book_name: book.name,
+                direct_download: true,
+                note: "This is a direct link to BookStack's web export. You may need to be logged in to BookStack to access it."
+            };
+        }
+        // For text formats, fetch the content via API
+        const response = await this.client.get(`/chapters/${id}/export/${format}`);
+        return response.data;
+    }
+    async getRecentChanges(options) {
+        const limit = Math.min(options?.limit || 20, 100);
+        const days = options?.days || 30;
+        const type = options?.type || 'all';
+        // Calculate date threshold
+        const dateThreshold = new Date();
+        dateThreshold.setDate(dateThreshold.getDate() - days);
+        const dateFilter = dateThreshold.toISOString().split('T')[0]; // YYYY-MM-DD format
+        // Build search query for recent changes
+        let searchQuery = `{updated_at:>=${dateFilter}}`;
+        if (type !== 'all') {
+            searchQuery = `{type:${type}} ${searchQuery}`;
+        }
+        const params = {
+            query: searchQuery,
+            count: limit,
+            sort: 'updated_at' // Sort by most recently updated
+        };
+        const response = await this.client.get('/search', { params });
+        const results = response.data.data || response.data;
+        // Enhance results with additional context
+        const enhancedResults = await Promise.all(results.map(async (result) => {
+            let contextualInfo = '';
+            let contentPreview = result.preview_content?.content || '';
+            try {
+                // Get additional context based on content type
+                if (result.type === 'page' && result.id) {
+                    const fullPage = await this.client.get(`/pages/${result.id}`);
+                    const pageData = fullPage.data;
+                    contentPreview = pageData.text?.substring(0, 200) || contentPreview;
+                    contextualInfo = `Updated in book: ${pageData.book?.name || 'Unknown Book'}`;
+                    if (pageData.chapter) {
+                        contextualInfo += `, chapter: ${pageData.chapter.name}`;
+                    }
+                }
+                else if (result.type === 'book' && result.id) {
+                    const fullBook = await this.client.get(`/books/${result.id}`);
+                    const bookData = fullBook.data;
+                    contentPreview = bookData.description?.substring(0, 200) || 'No description available';
+                    contextualInfo = `Book with ${bookData.page_count || 0} pages`;
+                }
+                else if (result.type === 'chapter' && result.id) {
+                    const fullChapter = await this.client.get(`/chapters/${result.id}`);
+                    const chapterData = fullChapter.data;
+                    contentPreview = chapterData.description?.substring(0, 200) || 'No description available';
+                    contextualInfo = `Chapter in book: ${chapterData.book?.name || 'Unknown Book'}`;
+                }
+            }
+            catch (error) {
+                // If we can't get additional context, use what we have
+                contextualInfo = `${result.type.charAt(0).toUpperCase() + result.type.slice(1)} content`;
+            }
+            const url = await this.generateContentUrl(result);
+            return {
+                ...result,
+                url,
+                direct_link: `[${result.name}](${url})`,
+                content_preview: contentPreview ? `${contentPreview}${contentPreview.length >= 200 ? '...' : ''}` : 'No preview available',
+                contextual_info: contextualInfo,
+                last_updated: this.formatDate(result.updated_at || result.created_at || ''),
+                change_summary: `${result.type === 'page' ? 'Page' : result.type === 'book' ? 'Book' : 'Chapter'} "${result.name}" was updated`
+            };
+        }));
+        return {
+            search_query: `Recent changes in the last ${days} days (${type})`,
+            date_threshold: dateFilter,
+            search_url: this.generateSearchUrl(searchQuery),
+            total_found: results.length,
+            summary: `Found ${results.length} items updated in the last ${days} days${type !== 'all' ? ` (${type}s only)` : ''}`,
+            results: enhancedResults
+        };
+    }
+    formatDate(dateString) {
+        if (!dateString)
+            return 'Unknown date';
+        const date = new Date(dateString);
+        const now = new Date();
+        const diffInHours = Math.floor((now.getTime() - date.getTime()) / (1000 * 60 * 60));
+        if (diffInHours < 1)
+            return 'Less than an hour ago';
+        if (diffInHours < 24)
+            return `${diffInHours} hours ago`;
+        const diffInDays = Math.floor(diffInHours / 24);
+        if (diffInDays < 7)
+            return `${diffInDays} days ago`;
+        const diffInWeeks = Math.floor(diffInDays / 7);
+        if (diffInWeeks < 4)
+            return `${diffInWeeks} weeks ago`;
+        return date.toLocaleDateString();
+    }
+    // Shelves (Book Collections) Management
+    async getShelves(options) {
+        const params = {
+            offset: options?.offset || 0,
+            count: Math.min(options?.count || 50, 500)
+        };
+        if (options?.sort)
+            params.sort = options.sort;
+        if (options?.filter)
+            params.filter = JSON.stringify(options.filter);
+        const response = await this.client.get('/shelves', { params });
+        const data = response.data;
+        return {
+            ...data,
+            data: data.data.map((shelf) => this.enhanceShelfResponse(shelf))
+        };
+    }
+    async getShelf(id) {
+        const response = await this.client.get(`/shelves/${id}`);
+        return this.enhanceShelfResponse(response.data);
+    }
+    async createShelf(data) {
+        if (!this.enableWrite) {
+            throw new Error('Write operations are disabled. Set BOOKSTACK_ENABLE_WRITE=true to enable.');
+        }
+        const response = await this.client.post('/shelves', data);
+        return this.enhanceShelfResponse(response.data);
+    }
+    async updateShelf(id, data) {
+        if (!this.enableWrite) {
+            throw new Error('Write operations are disabled. Set BOOKSTACK_ENABLE_WRITE=true to enable.');
+        }
+        const response = await this.client.put(`/shelves/${id}`, data);
+        return this.enhanceShelfResponse(response.data);
+    }
+    async deleteShelf(id) {
+        if (!this.enableWrite) {
+            throw new Error('Write operations are disabled. Set BOOKSTACK_ENABLE_WRITE=true to enable.');
+        }
+        const response = await this.client.delete(`/shelves/${id}`);
+        return response.data;
+    }
+    // Attachments Management
+    async getAttachments(options) {
+        const params = {
+            offset: options?.offset || 0,
+            count: Math.min(options?.count || 50, 500)
+        };
+        if (options?.sort)
+            params.sort = options.sort;
+        if (options?.filter)
+            params.filter = JSON.stringify(options.filter);
+        const response = await this.client.get('/attachments', { params });
+        const data = response.data;
+        return {
+            ...data,
+            data: data.data.map((attachment) => ({
+                ...attachment,
+                page_url: `${this.baseUrl}/books/${Math.floor(attachment.uploaded_to / 1000)}/page/${attachment.uploaded_to}`,
+                direct_link: `[${attachment.name}](${this.baseUrl}/attachments/${attachment.id})`
+            }))
+        };
+    }
+    async getAttachment(id) {
+        const response = await this.client.get(`/attachments/${id}`);
+        const attachment = response.data;
+        return {
+            ...attachment,
+            page_url: `${this.baseUrl}/books/${Math.floor(attachment.uploaded_to / 1000)}/page/${attachment.uploaded_to}`,
+            direct_link: `[${attachment.name}](${this.baseUrl}/attachments/${attachment.id})`,
+            download_url: `${this.baseUrl}/attachments/${attachment.id}`
+        };
+    }
+    async createAttachment(data) {
+        if (!this.enableWrite) {
+            throw new Error('Write operations are disabled. Set BOOKSTACK_ENABLE_WRITE=true to enable.');
+        }
+        const response = await this.client.post('/attachments', data);
+        const attachment = response.data;
+        return {
+            ...attachment,
+            page_url: `${this.baseUrl}/books/${Math.floor(attachment.uploaded_to / 1000)}/page/${attachment.uploaded_to}`,
+            direct_link: `[${attachment.name}](${this.baseUrl}/attachments/${attachment.id})`
+        };
+    }
+    async updateAttachment(id, data) {
+        if (!this.enableWrite) {
+            throw new Error('Write operations are disabled. Set BOOKSTACK_ENABLE_WRITE=true to enable.');
+        }
+        const response = await this.client.put(`/attachments/${id}`, data);
+        const attachment = response.data;
+        return {
+            ...attachment,
+            page_url: `${this.baseUrl}/books/${Math.floor(attachment.uploaded_to / 1000)}/page/${attachment.uploaded_to}`,
+            direct_link: `[${attachment.name}](${this.baseUrl}/attachments/${attachment.id})`
+        };
+    }
+    async deleteAttachment(id) {
+        if (!this.enableWrite) {
+            throw new Error('Write operations are disabled. Set BOOKSTACK_ENABLE_WRITE=true to enable.');
+        }
+        const response = await this.client.delete(`/attachments/${id}`);
+        return response.data;
+    }
+}

package/dist/index.js

@@ -0,0 +1,507 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { BookStackClient } from "./bookstack-client.js";
+function getRequiredEnvVar(name) {
+    const value = process.env[name];
+    if (!value) {
+        console.error(`Error: ${name} environment variable is required`);
+        process.exit(1);
+    }
+    return value;
+}
+async function main() {
+    // Load configuration from environment
+    const config = {
+        baseUrl: getRequiredEnvVar('BOOKSTACK_BASE_URL'),
+        tokenId: getRequiredEnvVar('BOOKSTACK_TOKEN_ID'),
+        tokenSecret: getRequiredEnvVar('BOOKSTACK_TOKEN_SECRET'),
+        enableWrite: process.env.BOOKSTACK_ENABLE_WRITE?.toLowerCase() === 'true'
+    };
+    console.error('Initializing BookStack MCP Server...');
+    console.error(`BookStack URL: ${config.baseUrl}`);
+    console.error(`Write operations: ${config.enableWrite ? 'ENABLED' : 'DISABLED'}`);
+    const client = new BookStackClient(config);
+    const server = new McpServer({
+        name: "bookstack-mcp",
+        version: "2.1.0"
+    });
+    // Register read-only tools
+    server.registerTool("get_capabilities", {
+        title: "Get BookStack Capabilities",
+        description: "Get information about available BookStack MCP capabilities and current configuration",
+        inputSchema: {}
+    }, async () => {
+        const capabilities = {
+            server_name: "BookStack MCP Server",
+            version: "2.1.0",
+            write_operations_enabled: config.enableWrite,
+            available_tools: config.enableWrite ? "All tools enabled" : "Read-only tools only",
+            security_note: config.enableWrite
+                ? "⚠️  Write operations are ENABLED - AI can create and modify BookStack content"
+                : "🛡️  Read-only mode - Safe for production use"
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(capabilities, null, 2) }]
+        };
+    });
+    server.registerTool("search_content", {
+        title: "Search BookStack Content",
+        description: "Search across BookStack content with contextual previews and location info",
+        inputSchema: {
+            query: z.string().describe("Search query. Use BookStack advanced search syntax like {type:page} or {book_id:5}"),
+            type: z.enum(["book", "page", "chapter", "bookshelf"]).optional().describe("Filter by content type"),
+            count: z.coerce.number().max(500).optional().describe("Number of results to return (max 500)"),
+            offset: z.coerce.number().optional().describe("Number of results to skip for pagination")
+        }
+    }, async (args) => {
+        const results = await client.searchContent(args.query, {
+            type: args.type,
+            count: args.count,
+            offset: args.offset
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+        };
+    });
+    server.registerTool("search_pages", {
+        title: "Search Pages",
+        description: "Search specifically for pages with optional book filtering",
+        inputSchema: {
+            query: z.string().describe("Search query for pages"),
+            book_id: z.coerce.number().optional().describe("Filter results to pages within a specific book"),
+            count: z.coerce.number().max(500).optional().describe("Number of results to return"),
+            offset: z.coerce.number().optional().describe("Pagination offset")
+        }
+    }, async (args) => {
+        const results = await client.searchPages(args.query, {
+            bookId: args.book_id,
+            count: args.count,
+            offset: args.offset
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+        };
+    });
+    server.registerTool("get_books", {
+        title: "List Books",
+        description: "List available books with advanced filtering and sorting",
+        inputSchema: {
+            offset: z.coerce.number().default(0).describe("Pagination offset"),
+            count: z.coerce.number().max(500).default(50).describe("Number of results to return"),
+            sort: z.string().optional().describe("Sort field (e.g., 'name', '-created_at', 'updated_at')"),
+            filter: z.record(z.any()).optional().describe("Filter criteria")
+        }
+    }, async (args) => {
+        const books = await client.getBooks({
+            offset: args.offset,
+            count: args.count,
+            sort: args.sort,
+            filter: args.filter
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(books, null, 2) }]
+        };
+    });
+    server.registerTool("get_book", {
+        title: "Get Book Details",
+        description: "Get detailed information about a specific book",
+        inputSchema: {
+            id: z.coerce.number().min(1).describe("Book ID")
+        }
+    }, async (args) => {
+        const book = await client.getBook(args.id);
+        return {
+            content: [{ type: "text", text: JSON.stringify(book, null, 2) }]
+        };
+    });
+    server.registerTool("get_pages", {
+        title: "List Pages",
+        description: "List pages with content previews, word counts, and contextual information",
+        inputSchema: {
+            book_id: z.coerce.number().optional().describe("Filter by book ID"),
+            chapter_id: z.coerce.number().optional().describe("Filter by chapter ID"),
+            offset: z.coerce.number().default(0).describe("Pagination offset"),
+            count: z.coerce.number().max(500).default(50).describe("Number of results to return"),
+            sort: z.string().optional().describe("Sort field"),
+            filter: z.record(z.any()).optional().describe("Additional filter criteria")
+        }
+    }, async (args) => {
+        const pages = await client.getPages({
+            bookId: args.book_id,
+            chapterId: args.chapter_id,
+            offset: args.offset,
+            count: args.count,
+            sort: args.sort,
+            filter: args.filter
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(pages, null, 2) }]
+        };
+    });
+    server.registerTool("get_page", {
+        title: "Get Page Content",
+        description: "Get full content of a specific page",
+        inputSchema: {
+            id: z.coerce.number().min(1).describe("Page ID")
+        }
+    }, async (args) => {
+        const page = await client.getPage(args.id);
+        return {
+            content: [{ type: "text", text: JSON.stringify(page, null, 2) }]
+        };
+    });
+    server.registerTool("get_chapters", {
+        title: "List Chapters",
+        description: "List chapters, optionally filtered by book",
+        inputSchema: {
+            book_id: z.coerce.number().optional().describe("Filter by book ID"),
+            offset: z.coerce.number().default(0).describe("Pagination offset"),
+            count: z.coerce.number().default(50).describe("Number of results to return")
+        }
+    }, async (args) => {
+        const chapters = await client.getChapters(args.book_id, args.offset, args.count);
+        return {
+            content: [{ type: "text", text: JSON.stringify(chapters, null, 2) }]
+        };
+    });
+    server.registerTool("get_chapter", {
+        title: "Get Chapter Details",
+        description: "Get details of a specific chapter",
+        inputSchema: {
+            id: z.coerce.number().min(1).describe("Chapter ID")
+        }
+    }, async (args) => {
+        const chapter = await client.getChapter(args.id);
+        return {
+            content: [{ type: "text", text: JSON.stringify(chapter, null, 2) }]
+        };
+    });
+    server.registerTool("export_page", {
+        title: "Export Page",
+        description: "Export a page in various formats (PDF/ZIP provide direct BookStack download URLs)",
+        inputSchema: {
+            id: z.coerce.number().min(1).describe("Page ID"),
+            format: z.enum(["html", "pdf", "markdown", "plaintext", "zip"]).describe("Export format")
+        }
+    }, async (args) => {
+        const content = await client.exportPage(args.id, args.format);
+        // Handle binary formats with direct URLs
+        if (typeof content === 'object' && content.download_url && content.direct_download) {
+            const format = args.format.toUpperCase();
+            return {
+                content: [{
+                        type: "text",
+                        text: `✅ **${format} Export Ready**\n\n` +
+                            `📄 **Page:** ${content.page_name}\n` +
+                            `📚 **Book:** ${content.book_name}\n` +
+                            `📁 **File:** ${content.filename}\n\n` +
+                            `🚀 **Direct Download Link:**\n${content.download_url}\n\n` +
+                            `ℹ️  **Note:** ${content.note}`
+                    }]
+            };
+        }
+        // Handle text formats
+        const text = typeof content === 'string' ? content : JSON.stringify(content, null, 2);
+        return {
+            content: [{ type: "text", text }]
+        };
+    });
+    server.registerTool("export_book", {
+        title: "Export Book",
+        description: "Export an entire book in various formats",
+        inputSchema: {
+            id: z.coerce.number().min(1).describe("Book ID"),
+            format: z.enum(["html", "pdf", "markdown", "plaintext", "zip"]).describe("Export format")
+        }
+    }, async (args) => {
+        const content = await client.exportBook(args.id, args.format);
+        if (typeof content === 'object' && content.download_url) {
+            const format = args.format.toUpperCase();
+            return {
+                content: [{
+                        type: "text",
+                        text: `✅ **${format} Book Export Ready**\n\n` +
+                            `📚 **Book:** ${content.book_name}\n` +
+                            `📁 **File:** ${content.filename}\n\n` +
+                            `🚀 **Direct Download Link:**\n${content.download_url}\n\n` +
+                            `ℹ️  **Note:** ${content.note}`
+                    }]
+            };
+        }
+        const text = typeof content === 'string' ? content : JSON.stringify(content, null, 2);
+        return {
+            content: [{ type: "text", text }]
+        };
+    });
+    server.registerTool("export_chapter", {
+        title: "Export Chapter",
+        description: "Export a chapter in various formats",
+        inputSchema: {
+            id: z.coerce.number().min(1).describe("Chapter ID"),
+            format: z.enum(["html", "pdf", "markdown", "plaintext", "zip"]).describe("Export format")
+        }
+    }, async (args) => {
+        const content = await client.exportChapter(args.id, args.format);
+        if (typeof content === 'object' && content.download_url) {
+            const format = args.format.toUpperCase();
+            return {
+                content: [{
+                        type: "text",
+                        text: `✅ **${format} Chapter Export Ready**\n\n` +
+                            `📖 **Chapter:** ${content.chapter_name}\n` +
+                            `📚 **Book:** ${content.book_name}\n` +
+                            `📁 **File:** ${content.filename}\n\n` +
+                            `🚀 **Direct Download Link:**\n${content.download_url}\n\n` +
+                            `ℹ️  **Note:** ${content.note}`
+                    }]
+            };
+        }
+        const text = typeof content === 'string' ? content : JSON.stringify(content, null, 2);
+        return {
+            content: [{ type: "text", text }]
+        };
+    });
+    server.registerTool("get_recent_changes", {
+        title: "Get Recent Changes",
+        description: "Get recently updated content with contextual previews and change descriptions",
+        inputSchema: {
+            type: z.enum(["all", "page", "book", "chapter"]).default("all").describe("Filter by content type"),
+            limit: z.coerce.number().max(100).default(20).describe("Number of recent items to return"),
+            days: z.coerce.number().default(30).describe("Number of days back to look for changes")
+        }
+    }, async (args) => {
+        const changes = await client.getRecentChanges({
+            type: args.type,
+            limit: args.limit,
+            days: args.days
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(changes, null, 2) }]
+        };
+    });
+    server.registerTool("get_shelves", {
+        title: "List Shelves",
+        description: "List available book shelves (collections) with filtering and sorting",
+        inputSchema: {
+            offset: z.coerce.number().default(0).describe("Pagination offset"),
+            count: z.coerce.number().max(500).default(50).describe("Number of results to return"),
+            sort: z.string().optional().describe("Sort field"),
+            filter: z.record(z.any()).optional().describe("Filter criteria")
+        }
+    }, async (args) => {
+        const shelves = await client.getShelves({
+            offset: args.offset,
+            count: args.count,
+            sort: args.sort,
+            filter: args.filter
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(shelves, null, 2) }]
+        };
+    });
+    server.registerTool("get_shelf", {
+        title: "Get Shelf Details",
+        description: "Get details of a specific book shelf including all books",
+        inputSchema: {
+            id: z.coerce.number().min(1).describe("Shelf ID")
+        }
+    }, async (args) => {
+        const shelf = await client.getShelf(args.id);
+        return {
+            content: [{ type: "text", text: JSON.stringify(shelf, null, 2) }]
+        };
+    });
+    server.registerTool("get_attachments", {
+        title: "List Attachments",
+        description: "List attachments (files and links) with filtering and sorting",
+        inputSchema: {
+            offset: z.coerce.number().default(0).describe("Pagination offset"),
+            count: z.coerce.number().max(500).default(50).describe("Number of results to return"),
+            sort: z.string().optional().describe("Sort field"),
+            filter: z.record(z.any()).optional().describe("Filter criteria")
+        }
+    }, async (args) => {
+        const attachments = await client.getAttachments({
+            offset: args.offset,
+            count: args.count,
+            sort: args.sort,
+            filter: args.filter
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(attachments, null, 2) }]
+        };
+    });
+    server.registerTool("get_attachment", {
+        title: "Get Attachment Details",
+        description: "Get details of a specific attachment including download links",
+        inputSchema: {
+            id: z.coerce.number().min(1).describe("Attachment ID")
+        }
+    }, async (args) => {
+        const attachment = await client.getAttachment(args.id);
+        return {
+            content: [{ type: "text", text: JSON.stringify(attachment, null, 2) }]
+        };
+    });
+    // Register write tools if enabled
+    if (config.enableWrite) {
+        server.registerTool("create_page", {
+            title: "Create Page",
+            description: "Create a new page in BookStack",
+            inputSchema: {
+                name: z.string().describe("Page name"),
+                book_id: z.coerce.number().min(1).describe("Book ID where the page will be created"),
+                chapter_id: z.coerce.number().optional().describe("Optional: Chapter ID if page should be in a chapter"),
+                html: z.string().optional().describe("Optional: HTML content"),
+                markdown: z.string().optional().describe("Optional: Markdown content")
+            }
+        }, async (args) => {
+            const page = await client.createPage({
+                name: args.name,
+                book_id: args.book_id,
+                chapter_id: args.chapter_id,
+                html: args.html,
+                markdown: args.markdown
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(page, null, 2) }]
+            };
+        });
+        server.registerTool("update_page", {
+            title: "Update Page",
+            description: "Update an existing page",
+            inputSchema: {
+                id: z.coerce.number().min(1).describe("Page ID"),
+                name: z.string().optional().describe("Optional: New page name"),
+                html: z.string().optional().describe("Optional: New HTML content"),
+                markdown: z.string().optional().describe("Optional: New Markdown content")
+            }
+        }, async (args) => {
+            const page = await client.updatePage(args.id, {
+                name: args.name,
+                html: args.html,
+                markdown: args.markdown
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(page, null, 2) }]
+            };
+        });
+        server.registerTool("create_shelf", {
+            title: "Create Shelf",
+            description: "Create a new book shelf (collection)",
+            inputSchema: {
+                name: z.string().describe("Shelf name"),
+                description: z.string().optional().describe("Shelf description"),
+                books: z.array(z.coerce.number()).optional().describe("Array of book IDs to add to the shelf"),
+                tags: z.array(z.object({
+                    name: z.string(),
+                    value: z.string()
+                }).strict()).optional().describe("Tags for the shelf")
+            }
+        }, async (args) => {
+            const shelf = await client.createShelf({
+                name: args.name,
+                description: args.description,
+                books: args.books,
+                tags: args.tags
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(shelf, null, 2) }]
+            };
+        });
+        server.registerTool("update_shelf", {
+            title: "Update Shelf",
+            description: "Update an existing book shelf",
+            inputSchema: {
+                id: z.coerce.number().min(1).describe("Shelf ID"),
+                name: z.string().optional().describe("New shelf name"),
+                description: z.string().optional().describe("New shelf description"),
+                books: z.array(z.coerce.number()).optional().describe("Array of book IDs"),
+                tags: z.array(z.object({
+                    name: z.string(),
+                    value: z.string()
+                }).strict()).optional().describe("Tags for the shelf")
+            }
+        }, async (args) => {
+            const shelf = await client.updateShelf(args.id, {
+                name: args.name,
+                description: args.description,
+                books: args.books,
+                tags: args.tags
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(shelf, null, 2) }]
+            };
+        });
+        server.registerTool("delete_shelf", {
+            title: "Delete Shelf",
+            description: "Delete a book shelf (collection)",
+            inputSchema: {
+                id: z.coerce.number().min(1).describe("Shelf ID")
+            }
+        }, async (args) => {
+            const result = await client.deleteShelf(args.id);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+            };
+        });
+        server.registerTool("create_attachment", {
+            title: "Create Attachment",
+            description: "Create a new link attachment to a page",
+            inputSchema: {
+                name: z.string().describe("Attachment name"),
+                uploaded_to: z.coerce.number().min(1).describe("Page ID where attachment will be attached"),
+                link: z.string().describe("URL for link attachment")
+            }
+        }, async (args) => {
+            const attachment = await client.createAttachment({
+                name: args.name,
+                uploaded_to: args.uploaded_to,
+                link: args.link
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(attachment, null, 2) }]
+            };
+        });
+        server.registerTool("update_attachment", {
+            title: "Update Attachment",
+            description: "Update an existing attachment",
+            inputSchema: {
+                id: z.coerce.number().min(1).describe("Attachment ID"),
+                name: z.string().optional().describe("New attachment name"),
+                link: z.string().optional().describe("New URL for link attachment"),
+                uploaded_to: z.coerce.number().optional().describe("Move attachment to different page")
+            }
+        }, async (args) => {
+            const attachment = await client.updateAttachment(args.id, {
+                name: args.name,
+                link: args.link,
+                uploaded_to: args.uploaded_to
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(attachment, null, 2) }]
+            };
+        });
+        server.registerTool("delete_attachment", {
+            title: "Delete Attachment",
+            description: "Delete an attachment",
+            inputSchema: {
+                id: z.coerce.number().min(1).describe("Attachment ID")
+            }
+        }, async (args) => {
+            const result = await client.deleteAttachment(args.id);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+            };
+        });
+    }
+    // Connect via stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("BookStack MCP server running on stdio");
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch(console.error);
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "bookstack-mcp",
+  "version": "2.1.0",
+  "description": "MCP server for BookStack wiki — search, read, create, and manage documentation via AI assistants",
+  "type": "module",
+  "bin": {
+    "bookstack-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/*.js",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "type-check": "tsc --noEmit",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "bookstack",
+    "model-context-protocol",
+    "ai",
+    "wiki",
+    "documentation",
+    "claude",
+    "librechat"
+  ],
+  "author": "ttpears",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ttpears/bookstack-mcp.git"
+  },
+  "homepage": "https://github.com/ttpears/bookstack-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/ttpears/bookstack-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "axios": "^1.6.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "shx": "^0.4.0",
+    "tsx": "^4.6.0",
+    "typescript": "^5.3.0"
+  }
+}