FluentBoards MCP Server

# FluentBoards MCP Server A comprehensive Model Context Protocol (MCP) server for FluentBoards project management system with advanced safety features and board focus mode. ## Overview This MCP server provides AI agents with full access to FluentBoards functionality through a secure, modular architecture. It enables AI assistants to manage boards, tasks, comments, and labels programmatically while offering advanced safety controls and focused workflows. ## Key Features ✨ **Board Focus Mode** - Streamline operations for a specific board 🛡️ **Delete Safety Controls** - Granular control over destructive operations 🔧 **Modular Architecture** - Clean, maintainable code structure 📊 **Comprehensive API Coverage** - Full FluentBoards functionality 🎯 **Dynamic Tool Registration** - Context-aware tool availability ## Architecture ``` src/ ├── config/ # Configuration management with safety controls ├── utils/ # Utilities (formatting, validation, safety) ├── api/ # API client and HTTP handling ├── types/ # TypeScript types and Zod schemas ├── tools/ # MCP tool implementations │ ├── boards.ts # Board management (conditional registration) │ ├── tasks.ts # Task management tools │ ├── comments.ts # Comment management tools │ ├── labels.ts # Label management tools │ └── debug.ts # Debug and testing tools └── index.ts # Main server entry point ``` ## Configuration Modes ### 1. All Boards Mode (Default) Access to all boards and full board management capabilities. ```env WORDPRESS_URL=https://your-site.local WORDPRESS_USERNAME=your-username WORDPRESS_APP_PASSWORD=your-app-password # No BOARD_ID set ``` ### 2. Board Focus Mode 🎯 Streamlined operations focused on a specific board. Automatically disables board manipulation tools. ```env WORDPRESS_URL=https://your-site.local WORDPRESS_USERNAME=your-username WORDPRESS_APP_PASSWORD=your-app-password BOARD_ID=14 # Focus on board 14 ``` ## Available Tools Tool availability depends on your configuration mode: ### Debug Tools (Always Available) - `debug_test` - Test server connectivity and API status ### Board Management (All Boards Mode Only) - `list_boards` - List all boards with pagination - `create_board` - Create new boards with type validation - `delete_board` - Delete boards permanently (safety controlled) ### Board Operations (Always Available, Scoped by Focus) - `get_board` - Get specific board details - `create_stage` - Create new stages in boards ### Task Management (Always Available, Scoped by Focus) - `list_tasks` - List tasks in a board - `get_task` - Get detailed task information with comments/attachments - `create_task` - Create new tasks with rich formatting - `update_task` - Update existing tasks - `change_task_status` - Move tasks between stages - `delete_task` - Delete tasks permanently (safety controlled) ### Comment Management (Always Available, Scoped by Focus) - `add_comment` - Add comments/replies to tasks with notifications ### Label Management (Always Available, Scoped by Focus) - `add_label` - Add labels to tasks - `remove_label` - Remove labels from tasks - `edit_label` - Edit label properties (title, colors) - `create_label` - Create new labels with custom colors - `delete_label` - Delete labels permanently (safety controlled) ## Board Focus Mode 🎯 When `BOARD_ID` is configured, the server enters **Board Focus Mode**: ### What Changes: - **Board manipulation tools are removed** (`list_boards`, `create_board`, `delete_board`) - **All operations are scoped** to the focused board only - **Tool count reduces** from ~14 to ~11 tools - **Safety from accidental cross-board operations** ### Example Usage: ```bash # Set focus to board 14 export BOARD_ID=14 # Available operations (all scoped to board 14): get_board(board_id: 14) # ✅ Works get_board(board_id: 15) # ❌ Blocked create_task(board_id: 14, ...) # ✅ Works create_task(board_id: 15, ...) # ❌ Blocked # Not available in focus mode: list_boards() # ❌ Tool not registered create_board(...) # ❌ Tool not registered delete_board(...) # ❌ Tool not registered ``` ## Delete Operation Safety 🛡️ ⚠️ **IMPORTANT:** Delete operations are **disabled by default** for safety. ### Safety Configuration ```env # Core safety settings ENABLE_DELETES=false # Master switch (default: false) REQUIRE_DELETE_CONFIRMATION=true # Require confirmation (default: true) ALLOWED_DELETE_TYPES=task,label # Allowed types (default: none) ``` ### Safety Levels **Level 1: No Deletes (Default - Safest)** ```env ENABLE_DELETES=false ``` All delete tools return safety errors. **Level 2: Selective Deletes with Confirmation** ```env ENABLE_DELETES=true REQUIRE_DELETE_CONFIRMATION=true ALLOWED_DELETE_TYPES=task,label ``` Only task and label deletions allowed, confirmation required. **Level 3: Full Deletes with Confirmation** ```env ENABLE_DELETES=true REQUIRE_DELETE_CONFIRMATION=true ALLOWED_DELETE_TYPES=board,task,label ``` All deletions allowed, confirmation required. **Level 4: Unrestricted (Not Recommended)** ```env ENABLE_DELETES=true REQUIRE_DELETE_CONFIRMATION=false ALLOWED_DELETE_TYPES=board,task,label ``` ### Using Delete Operations When enabled, delete operations require confirmation: ```typescript // Valid confirmation formats: delete_task(board_id: 1, task_id: 5, confirm_delete: true) delete_task(board_id: 1, task_id: 5, confirm_delete: "yes") delete_task(board_id: 1, task_id: 5, confirm_delete: "confirm") // Without confirmation (when required): delete_task(board_id: 1, task_id: 5) // ❌ Safety error ``` ## Installation & Setup ### Prerequisites - **FluentBoards WordPress Plugin** - The MCP server connects directly to FluentBoards REST API - **WordPress Application Password** - For secure authentication - **No additional WordPress plugins required** ### 1. Install Dependencies ```bash npm install ``` ### 2. Build the Server ```bash npm run build ``` ### 3. Configure Environment **All Boards Mode:** ```env WORDPRESS_URL=https://your-site.local WORDPRESS_USERNAME=your-username WORDPRESS_APP_PASSWORD=your-app-password ``` **Board Focus Mode:** ```env WORDPRESS_URL=https://your-site.local WORDPRESS_USERNAME=your-username WORDPRESS_APP_PASSWORD=your-app-password BOARD_ID=14 ``` ### 4. Configure MCP Client **Cursor (`~/.cursor/mcp.json`):** ```json { "mcpServers": { "fluent-boards": { "command": "node", "args": ["/path/to/mcp-server-app/dist/index.js"], "env": { "WORDPRESS_URL": "https://your-site.local", "WORDPRESS_USERNAME": "your-username", "WORDPRESS_APP_PASSWORD": "your-app-password", "BOARD_ID": "14" } } } } ``` **Claude Desktop:** ```json { "mcpServers": { "fluent-boards": { "command": "node", "args": ["/path/to/mcp-server-app/dist/index.js"], "env": { "WORDPRESS_URL": "https://your-site.local", "WORDPRESS_USERNAME": "your-username", "WORDPRESS_APP_PASSWORD": "your-app-password" } } } } ``` ## Complete Configuration Reference ```env # Required: WordPress connection WORDPRESS_URL=https://your-site.local WORDPRESS_USERNAME=your-username WORDPRESS_APP_PASSWORD=your-app-password # Optional: Board focus mode BOARD_ID=14 # Enable board focus mode # Optional: Delete operation safety ENABLE_DELETES=false # Enable delete operations REQUIRE_DELETE_CONFIRMATION=true # Require confirmation parameter ALLOWED_DELETE_TYPES=task,label # Comma-separated: board,task,label ``` ## Development ### Building ```bash npm run build ``` ### Testing ```bash # Run integration tests npm test # Run specific integration test npx ts-node tests/integration.test.ts # Run development/debugging scripts (see scripts/README.md) npx ts-node scripts/testing/test-connection.ts npx ts-node scripts/testing/test-admin-create.ts ``` ### Adding New Tools 1. **Create tool in appropriate module:** ```typescript // src/tools/example.ts export function registerExampleTools(server: McpServer) { server.tool( "example_tool", "Description of the tool", { board_id: z.number().int().positive().describe("Board ID"), param1: z.string().describe("Parameter description"), }, async (args) => { const { board_id, param1 } = args; // Validate board access in focus mode const accessCheck = validateBoardAccess(board_id); if (!accessCheck.allowed) { return formatResponse(createBoardFocusError(accessCheck)); } // Implementation const response = await api.get(`/endpoint/${board_id}`); return formatResponse(response.data); } ); } ``` 2. **Register in main server:** ```typescript // src/index.ts import { registerExampleTools } from './tools/example.js'; registerExampleTools(server); ``` ## API Integration The MCP server connects **directly** to the FluentBoards WordPress REST API: - **Base URL:** `{WORDPRESS_URL}/wp-json/fluent-boards/v2` - **Authentication:** WordPress Application Password (secure, built-in) - **Connection:** Direct HTTPS (no proxy required) - **Format:** JSON requests/responses - **Rate Limiting:** Handled by WordPress ### No Proxy Plugin Required The MCP server uses WordPress's native REST API and Application Password authentication. **No additional WordPress plugins are needed** for the MCP server to function. ## Response Format All tools return standardized MCP responses: ```json { "content": [ { "type": "text", "text": "{\n \"board\": {\n \"id\": 14,\n \"title\": \"My Board\"\n }\n}" } ] } ``` ## Text Formatting Features The server automatically formats text content: - ✅ Proper line breaks for markdown - ✅ Header formatting (`##`) - ✅ List formatting (`-` and numbered) - ✅ Checkbox formatting (`[ ]` and `[x]`) - ✅ Status indicators (`✅`, `❌`) - ✅ HTML entity decoding ## Error Handling Comprehensive error handling with specific error types: ### API Errors ```json { "error": "API request failed", "status": 404, "message": "Board not found" } ``` ### Safety Errors ```json { "error": "Delete operation not allowed", "reason": "Delete operations are disabled", "code": "DELETES_DISABLED" } ``` ### Board Focus Errors ```json { "error": "Operation outside board focus scope", "reason": "Operations are focused on board 14", "code": "OUT_OF_FOCUS" } ``` ## Troubleshooting ### Tool Count Changes - **Expected:** Tool count changes when switching between focus modes - **All Boards:** ~14 tools available - **Board Focus:** ~11 tools available (board manipulation tools removed) ### Connection Issues ```bash # Test server connectivity npm run test # Test direct FluentBoards API access curl -u "username:app-password" "https://your-site.local/wp-json/fluent-boards/v2/projects/list-of-boards" # Test WordPress REST API is working curl "https://your-site.local/wp-json/" ``` ### Permission Issues - Ensure WordPress user has FluentBoards access - Verify Application Password is correctly generated - Check WordPress REST API is enabled - Ensure FluentBoards plugin is active - No proxy plugin installation required ## Future Enhancements - 📊 Performance monitoring and metrics - 🔄 Caching layer for frequently accessed data - 🪝 Webhook support for real-time updates - 📦 Bulk operations for efficiency - 📎 File upload and attachment management - 🔍 Advanced search and filtering - 📈 Reporting and analytics tools - 🔐 Enhanced authentication methods ## Contributing 1. **Follow architecture patterns** - Use modular tool organization 2. **Implement safety controls** - Add validation and access checks 3. **Add comprehensive error handling** - Include specific error codes 4. **Use input validation** - Zod schemas for all parameters 5. **Format responses consistently** - Use utility functions 6. **Add tests** - Cover new functionality thoroughly 7. **Update documentation** - Keep README current ## License This project is part of the FluentBoards ecosystem.