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