danieliser/fluent-boards-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.

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.

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:

# 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

# 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)

ENABLE_DELETES=false

All delete tools return safety errors.

Level 2: Selective Deletes with Confirmation

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

ENABLE_DELETES=true
REQUIRE_DELETE_CONFIRMATION=true
ALLOWED_DELETE_TYPES=board,task,label

All deletions allowed, confirmation required.

Level 4: Unrestricted (Not Recommended)

ENABLE_DELETES=true
REQUIRE_DELETE_CONFIRMATION=false
ALLOWED_DELETE_TYPES=board,task,label

Using Delete Operations

When enabled, delete operations require confirmation:

// 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

npm install

2. Build the Server

npm run build

3. Configure Environment

All Boards Mode:

WORDPRESS_URL=https://your-site.local
WORDPRESS_USERNAME=your-username
WORDPRESS_APP_PASSWORD=your-app-password

Board Focus Mode:

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):

{
  "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:

{
  "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

# 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

npm run build

Testing

# 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:

// 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:

// 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:

{
  "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

{
  "error": "API request failed",
  "status": 404,
  "message": "Board not found"
}

Safety Errors

{
  "error": "Delete operation not allowed",
  "reason": "Delete operations are disabled",
  "code": "DELETES_DISABLED"
}

Board Focus Errors

{
  "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

# 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.