BookStack MCP Server

# BookStack MCP Server - Project Overview ## What is This? This is a **Model Context Protocol (MCP) server** that connects Cursor AI to your BookStack documentation system running at http://192.168.1.193:6875. With this server, you can: - Ask Cursor to list, search, create, and update BookStack content - Manage documentation directly from your AI conversations - Automate documentation tasks through natural language ## Architecture ``` ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │ Cursor │ ◄─MCP──►│ Python Server│ ◄─API──►│ BookStack │ │ AI │ │ (FastMCP) │ │ Instance │ └─────────────┘ └──────────────┘ └──────────────┘ │ │ reads ▼ .env file (API credentials) ``` ## Components ### 1. Main Server (`server.py`) - FastMCP-based Python server - Exposes 10 tools for BookStack management - Handles authentication and API communication - Runs as a stdio MCP server ### 2. Configuration (`.env`) - Stores BookStack URL and API credentials - Required for server operation - Not committed to git for security ### 3. Scripts - `run_server.sh` - Launch the server with proper environment - `test_connection.py` - Verify BookStack connectivity and API access - `setup_env.sh` - Interactive .env file creation - `setup.sh` - Full setup automation ### 4. Documentation - `README.md` - Complete usage guide - `QUICKSTART.md` - Fast setup instructions - `PROJECT_OVERVIEW.md` - This file ## MCP Tools Provided ### Content Discovery 1. **bookstack_list_content** - List books, bookshelves, chapters, or pages 2. **bookstack_search** - Full-text search across all content ### Page Operations 3. **bookstack_get_page** - Get page details and content 4. **bookstack_create_page** - Create new pages 5. **bookstack_update_page** - Update existing pages 6. **bookstack_delete_page** - Delete pages ### Organizational Tools 7. **bookstack_create_book** - Create new books 8. **bookstack_create_chapter** - Create new chapters ## Setup Steps ### Quick Setup (5 minutes) ```bash cd /home/borjigin/dev/bookstack-mcp # 1. Dependencies are already installed in venv/ # 2. Get API credentials from BookStack # - Open http://192.168.1.193:6875 # - Go to Profile → API Tokens # - Create a token # 3. Configure environment ./setup_env.sh # OR manually: cp env.template .env nano .env # Add your credentials # 4. Test connection ./test_connection.py # 5. Configure Cursor (see below) ``` ### Cursor Integration Add to Cursor's MCP settings (`~/.config/cursor/mcp_settings.json` or via Settings UI): ```json { "mcpServers": { "bookstack": { "command": "/home/borjigin/dev/bookstack-mcp/run_server.sh" } } } ``` Or with explicit Python path: ```json { "mcpServers": { "bookstack": { "command": "/home/borjigin/dev/bookstack-mcp/venv/bin/python", "args": ["/home/borjigin/dev/bookstack-mcp/server.py"] } } } ``` Restart Cursor after configuration. ## Usage Examples Once configured, talk to Cursor naturally: ### Browsing - "Show me all books in BookStack" - "List the pages in book 5" - "Search for documentation about Docker" ### Creating - "Create a book called 'API Guide'" - "Add a chapter 'Authentication' to book 3" - "Create a page about JWT tokens in chapter 7" ### Updating - "Update page 42 to include this code example..." - "Change the title of page 15 to 'New Title'" ### Reading - "Show me the content of page 100" - "What's in the 'Getting Started' page?" ## File Structure ``` /home/borjigin/dev/bookstack-mcp/ ├── server.py # Main MCP server ├── requirements.txt # Python dependencies ├── .env # Your credentials (create this) ├── env.template # Template for .env ├── venv/ # Python virtual environment │ ├── run_server.sh # Server launcher ├── test_connection.py # Connection tester ├── setup_env.sh # Env setup helper ├── setup.sh # Full setup script │ ├── README.md # Complete guide ├── QUICKSTART.md # Fast start guide ├── PROJECT_OVERVIEW.md # This file ├── cursor-mcp-config.json # Example Cursor config │ └── .gitignore # Git exclusions ``` ## BookStack API Reference The server uses these BookStack API endpoints: - `GET /api/books` - List books - `GET /api/bookshelves` - List bookshelves - `GET /api/chapters` - List chapters - `GET /api/pages` - List pages - `GET /api/pages/{id}` - Get page details - `POST /api/pages` - Create page - `PUT /api/pages/{id}` - Update page - `DELETE /api/pages/{id}` - Delete page - `POST /api/books` - Create book - `POST /api/chapters` - Create chapter - `GET /api/search` - Search content All requests use Token authentication: ``` Authorization: Token {TOKEN_ID}:{TOKEN_SECRET} ``` ## Security Notes 1. **Credentials**: Never commit `.env` to git 2. **Tokens**: Use tokens with minimal required permissions 3. **Network**: Server connects to local network (192.168.1.193) 4. **Transport**: MCP uses stdio, credentials stay local ## Troubleshooting ### Server won't start ```bash # Check Python python --version # Need 3.8+ # Reinstall dependencies rm -rf venv python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` ### Can't connect to BookStack ```bash # Test basic connectivity curl http://192.168.1.193:6875 # Test API curl -H "Authorization: Token YOUR_ID:YOUR_SECRET" \ http://192.168.1.193:6875/api/books ``` ### Cursor doesn't show tools 1. Check Cursor MCP settings are correct 2. Look at Cursor logs (Help → Toggle Developer Tools) 3. Verify server runs: `./test_connection.py` 4. Restart Cursor completely ### Permission errors - API token may lack permissions - Create new token with appropriate role - Admin tokens have full access ## Development To add more tools: ```python @mcp.tool() async def bookstack_your_tool(param: str) -> str: """Tool description for Cursor""" client = get_client() result = await client.request("GET", f"endpoint/{param}") return str(result) ``` The FastMCP framework automatically: - Registers the tool - Generates JSON Schema - Handles input validation - Manages stdio transport ## Resources - **BookStack API Docs**: https://www.bookstackapp.com/docs/api/ - **FastMCP**: https://gofastmcp.com/ - **MCP Protocol**: https://modelcontextprotocol.io/ - **Cursor MCP Guide**: https://docs.cursor.com/context/model-context-protocol ## License Open source - feel free to modify and extend. ## Support Issues? Check: 1. `.env` file has correct credentials 2. BookStack is accessible at http://192.168.1.193:6875 3. Virtual environment is activated 4. Dependencies are installed 5. Cursor MCP settings are correct Still stuck? Run `./test_connection.py` for diagnostics.