BookStack MCP Server

# Installation Summary ## ✅ What Has Been Created Your BookStack MCP Server is now set up at: ``` /home/borjigin/dev/bookstack-mcp/ ``` ### Components Installed 1. **Python MCP Server** (`server.py`) - FastMCP-based server with 10 BookStack tools - Ready to connect to http://192.168.1.193:6875 2. **Virtual Environment** (`venv/`) - Isolated Python 3.12 environment - All dependencies installed (fastmcp, httpx, python-dotenv) 3. **Configuration Files** - `env.template` - Configuration template - `.gitignore` - Security exclusions 4. **Helper Scripts** - `run_server.sh` - Launch server - `test_connection.py` - Test setup - `setup_env.sh` - Create .env interactively - `setup.sh` - Automated setup 5. **Documentation** - `README.md` - Complete guide - `QUICKSTART.md` - Quick start - `PROJECT_OVERVIEW.md` - Architecture overview - `cursor-mcp-config.json` - Example config ## 🎯 Next Steps (2 minutes) ### Step 1: Get BookStack API Token 1. Open http://192.168.1.193:6875 in your browser 2. Log in to BookStack 3. Click your profile picture → **Edit Profile** 4. Go to **API Tokens** tab 5. Click **Create Token** 6. Give it a name like "Cursor MCP" 7. **Copy both Token ID and Token Secret** ### Step 2: Configure Environment Option A - Interactive (recommended): ```bash cd /home/borjigin/dev/bookstack-mcp ./setup_env.sh ``` Option B - Manual: ```bash cd /home/borjigin/dev/bookstack-mcp cp env.template .env nano .env ``` Edit to add your credentials: ```env BS_URL=http://192.168.1.193:6875 BS_TOKEN_ID=your_actual_token_id_here BS_TOKEN_SECRET=your_actual_token_secret_here ``` ### Step 3: Test Connection ```bash ./test_connection.py ``` You should see: ``` ✅ BookStack is reachable ✅ API authentication successful! ✅ All tests passed! ``` ### Step 4: Configure Cursor #### Option A: Edit Settings File Edit `~/.config/cursor/mcp_settings.json`: ```json { "mcpServers": { "bookstack": { "command": "/home/borjigin/dev/bookstack-mcp/run_server.sh" } } } ``` #### Option B: Use Cursor Settings UI 1. Open Cursor 2. Press `Ctrl + ,` (Settings) 3. Search for "MCP" 4. Click **Add Server** 5. Configure: - **Name**: `bookstack` - **Command**: `/home/borjigin/dev/bookstack-mcp/venv/bin/python` - **Args**: `/home/borjigin/dev/bookstack-mcp/server.py` ### Step 5: Restart Cursor Close and reopen Cursor completely. ### Step 6: Test in Cursor Open a new chat and try: ``` "List all books in my BookStack" ``` or ``` "Search for 'docker' in BookStack" ``` If Cursor responds with BookStack data, **you're all set!** 🎉 ## 📊 System Status ``` Location: /home/borjigin/dev/bookstack-mcp/ Python: 3.12 (venv activated) FastMCP: 2.13.1 ✅ httpx: 0.28.1 ✅ BookStack URL: http://192.168.1.193:6875 Status: Ready for configuration ``` ## 🛠 Tools Available Once configured, Cursor can use these tools: | Tool | Purpose | |------|---------| | `bookstack_list_content` | List books, shelves, chapters, pages | | `bookstack_search` | Full-text search | | `bookstack_get_page` | Read page content | | `bookstack_create_page` | Create new pages | | `bookstack_update_page` | Update existing pages | | `bookstack_delete_page` | Delete pages | | `bookstack_create_book` | Create new books | | `bookstack_create_chapter` | Create new chapters | ## 🔧 Troubleshooting ### Server won't start ```bash ./test_connection.py ``` This will diagnose the issue. ### Can't connect to BookStack ```bash curl http://192.168.1.193:6875 ``` ### Permission denied on scripts ```bash chmod +x *.sh *.py ``` ### Dependencies missing ```bash source venv/bin/activate pip install -r requirements.txt ``` ## 📚 Documentation - Quick Start: `cat QUICKSTART.md` - Full Guide: `cat README.md` - Architecture: `cat PROJECT_OVERVIEW.md` ## 🎯 Quick Commands ```bash # Test connection ./test_connection.py # Run server manually ./run_server.sh # Or with venv source venv/bin/activate python server.py # Recreate environment ./setup_env.sh # Check status ls -la .env # Should exist after setup ``` ## 💡 Usage Examples After Cursor integration, try: **Browsing:** - "Show me all books" - "List pages in book 3" - "Find documentation about authentication" **Creating:** - "Create a book named 'DevOps Guide'" - "Add a chapter 'Docker Basics' to book 5" - "Create a new page about Kubernetes in chapter 2" **Updating:** - "Update page 42 with this content: ..." - "Change the title of page 15" **Reading:** - "Show me page 100" - "What's in the Getting Started page?" ## ✨ What Makes This Special 1. **Minimal Setup**: Only essential dependencies 2. **Secure**: Credentials stay local in .env 3. **Fast**: Direct API access, no middleware 4. **Natural**: Talk to Cursor naturally about your docs 5. **Isolated**: Virtual environment prevents conflicts ## 🚀 You're Ready! Your BookStack MCP Server is installed and ready. Just: 1. ✅ Get API token from BookStack 2. ✅ Run `./setup_env.sh` 3. ✅ Test with `./test_connection.py` 4. ✅ Configure Cursor 5. ✅ Start documenting! --- **Need help?** Run `./test_connection.py` for diagnostics. **Want more details?** Read `README.md` or `QUICKSTART.md`.