# BookStack MCP Server for Cursor

A minimal Python MCP (Model Context Protocol) server that allows Cursor AI to manage your BookStack documentation.

## Features

This server provides essential BookStack management tools:

- **List Content**: Browse books, bookshelves, chapters, and pages
- **Search**: Full-text search across all content
- **Page Management**: Create, read, update, and delete pages
- **Book Management**: Create new books
- **Chapter Management**: Create new chapters

## Prerequisites

- Python 3.8 or higher
- BookStack instance with API access
- BookStack API token (ID and Secret)

## Setup

### 1. Install Dependencies

```bash
pip install -r requirements.txt
```

### 2. Configure Environment

First, you need to create an API token in BookStack:

1. Log in to your BookStack instance at http://192.168.1.193:6875
2. Go to your profile → API Tokens
3. Create a new token with appropriate permissions
4. Copy the Token ID and Token Secret

Then create a `.env` file:

```bash
cp .env.example .env
```

Edit `.env` and add your BookStack credentials:

```env
BS_URL=http://192.168.1.193:6875
BS_TOKEN_ID=your_actual_token_id
BS_TOKEN_SECRET=your_actual_token_secret
```

### 3. Test the Server

Run the server directly to test:

```bash
python server.py
```

The server will start and listen for MCP protocol messages via stdio.

## Cursor Integration

To use this MCP server with Cursor, add it to your Cursor MCP settings:

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to **Features** → **Model Context Protocol**
3. Add a new server configuration:

```json
{
  "mcpServers": {
    "bookstack": {
      "command": "python",
      "args": ["/home/borjigin/dev/bookstack-mcp/server.py"],
      "env": {
        "BS_URL": "http://192.168.1.193:6875",
        "BS_TOKEN_ID": "your_token_id",
        "BS_TOKEN_SECRET": "your_token_secret"
      }
    }
  }
}
```

Or use a script wrapper:

```json
{
  "mcpServers": {
    "bookstack": {
      "command": "/home/borjigin/dev/bookstack-mcp/run_server.sh"
    }
  }
}
```

4. Restart Cursor

## Available Tools

Once configured, you can ask Cursor to interact with BookStack:

### Listing Content

- "List all books in BookStack"
- "Show me the chapters in book 5"
- "Find pages with 'API' in the name"

### Searching

- "Search for 'authentication' in BookStack"
- "Find documentation about Docker"

### Reading Content

- "Get the content of page 42"
- "Show me what's in page ID 10"

### Creating Content

- "Create a new book called 'API Documentation'"
- "Create a chapter named 'Getting Started' in book 5"
- "Create a page in book 3 with markdown content..."

### Updating Content

- "Update page 15 to change the title to 'New Title'"
- "Modify page 20's content with this markdown..."

### Deleting Content

- "Delete page 99"

## Tools Reference

### bookstack_list_content
List content entities (books, bookshelves, chapters, pages)
- `entity_type`: "books" | "bookshelves" | "chapters" | "pages"
- `count`: Number of items (default 20)
- `offset`: Pagination offset (default 0)
- `filter_name`: Filter by name substring

### bookstack_search
Search across all content
- `query`: Search query string
- `page`: Page number (default 1)
- `count`: Results per page (default 20)

### bookstack_get_page
Get page details and content
- `page_id`: Page ID

### bookstack_create_page
Create a new page
- `book_id`: Book ID (required)
- `name`: Page title (required)
- `html` or `markdown`: Content (one required)
- `chapter_id`: Optional chapter ID
- `tags`: Optional tags (format: "tag1=value1,tag2=value2")

### bookstack_update_page
Update an existing page
- `page_id`: Page ID (required)
- `name`: New title (optional)
- `html` or `markdown`: New content (optional)
- `tags`: Optional tags

### bookstack_delete_page
Delete a page
- `page_id`: Page ID (required)

### bookstack_create_book
Create a new book
- `name`: Book name (required)
- `description`: Optional description
- `tags`: Optional tags

### bookstack_create_chapter
Create a new chapter
- `book_id`: Book ID (required)
- `name`: Chapter name (required)
- `description`: Optional description
- `tags`: Optional tags

## Troubleshooting

### Connection Issues

If Cursor can't connect to BookStack:
1. Verify BookStack is running: `curl http://192.168.1.193:6875`
2. Check your API tokens are correct
3. Ensure the token has sufficient permissions

### Permission Issues

If you get 403 errors:
- Your API token may lack necessary permissions
- Create a new token with admin or appropriate role permissions

### Server Not Starting

If the Python server won't start:
- Check Python version: `python --version` (must be 3.8+)
- Verify dependencies: `pip list | grep fastmcp`
- Check for errors in the `.env` file

## Development

To extend this server with more tools:

1. Add new functions decorated with `@mcp.tool()`
2. Use the `BookStackClient` for API calls
3. Follow the pattern of existing tools

Example:

```python
@mcp.tool()
async def bookstack_custom_operation(param: str) -> str:
    """Your custom tool description"""
    client = get_client()
    result = await client.request("GET", f"endpoint/{param}")
    return str(result)
```

## API Reference

BookStack API documentation: https://www.bookstackapp.com/docs/api/

## License

This project is open source and available for modification and use.