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

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);
    }
  );
}

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

Follow architecture patterns - Use modular tool organization
Implement safety controls - Add validation and access checks
Add comprehensive error handling - Include specific error codes
Use input validation - Zod schemas for all parameters
Format responses consistently - Use utility functions
Add tests - Cover new functionality thoroughly
Update documentation - Keep README current

License

This project is part of the FluentBoards ecosystem.