FluentBoards MCP服务器
FluentBoards项目管理系统的综合模型上下文协议（MCP）服务器，具有高级安全功能和板聚焦模式。
概述
此MCP服务器通过安全的模块化架构为AI代理提供对FluentBoards功能的完全访问。它使AI助手能够以编程方式管理板、任务、评论和标签，同时提供高级安全控制和专注的工作流程。
主要特点
✨ 板聚焦模式 -简化特定董事会的运营\ 🛡️ 删除安全控制 -对破坏性操作进行精细控制\ 🔧 模块化架构 -干净、可维护的代码结构\ 📊 API全面覆盖 -完整的FluentBoard功能\ 🎯 动态工具注册 -上下文感知工具可用性
建筑
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配置模式
1.全板模式（默认）
访问所有板和全板管理功能。
WORDPRESS_URL=https://your-site.local
WORDPRESS_USERNAME=your-username
WORDPRESS_APP_PASSWORD=your-app-password
# No BOARD_ID set2.板聚焦模式🎯
精简运营，专注于特定的董事会。自动禁用电路板操作工具。
WORDPRESS_URL=https://your-site.local
WORDPRESS_USERNAME=your-username
WORDPRESS_APP_PASSWORD=your-app-password
BOARD_ID=14 # Focus on board 14可用工具
工具可用性取决于您的配置模式：
调试工具（始终可用）
debug_test-测试服务器连接和API状态
董事会管理（仅限全董事会模式）
list_boards-列出所有带页码的板create_board-创建具有类型验证的新板delete_board-永久删除板（安全控制）
董事会运营（始终可用，按重点范围）
get_board-获取特定的电路板详细信息create_stage-在棋盘上创建新关卡
任务管理（始终可用，按焦点范围）
list_tasks-在板中列出任务get_task-通过评论/附件获取详细的任务信息create_task-创建具有丰富格式的新任务update_task-更新现有任务change_task_status-在阶段之间移动任务delete_task-永久删除任务（安全控制）
评论管理（始终可用，按焦点范围）
add_comment-为带有通知的任务添加评论/回复
标签管理（始终可用，按焦点范围）
add_label-为任务添加标签remove_label-从任务中删除标签edit_label-编辑标签属性（标题、颜色）create_label-使用自定义颜色创建新标签delete_label-永久删除标签（安全控制）
板聚焦模式🎯
当 BOARD_ID 已配置，服务器进入 板聚焦模式:
什么变化：
- 删除电路板操作工具 (
list_boards,create_board,delete_board) - 所有操作都有范围 仅限聚焦板
- 刀具数量减少 从~14到~11个工具
- 防止意外跨板操作的安全
示例用法：
# 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删除操作安全🛡️
⚠️ 重要： 删除操作包括 默认情况下禁用 为了安全。
安全配置
# 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)安全等级
级别1：不删除（默认-最安全）
ENABLE_DELETES=false所有删除工具都会返回安全错误。
级别2：确认后选择性删除
ENABLE_DELETES=true
REQUIRE_DELETE_CONFIRMATION=true
ALLOWED_DELETE_TYPES=task,label只允许删除任务和标签，需要确认。
级别3：确认后完全删除
ENABLE_DELETES=true
REQUIRE_DELETE_CONFIRMATION=true
ALLOWED_DELETE_TYPES=board,task,label允许所有删除，需要确认。
第四级：无限制（不推荐）
ENABLE_DELETES=true
REQUIRE_DELETE_CONFIRMATION=false
ALLOWED_DELETE_TYPES=board,task,label使用删除操作
启用后，删除操作需要确认：
// 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安装和设置
先决条件
- FluentBoards WordPress插件 -MCP服务器直接连接到FluentBoards REST API
- WordPress应用程序密码 -用于安全身份验证
- 无需额外的WordPress插件
1.安装依赖项
npm install2.构建服务器
npm run build3.配置环境
全板模式：
WORDPRESS_URL=https://your-site.local
WORDPRESS_USERNAME=your-username
WORDPRESS_APP_PASSWORD=your-app-password板聚焦模式：
WORDPRESS_URL=https://your-site.local
WORDPRESS_USERNAME=your-username
WORDPRESS_APP_PASSWORD=your-app-password
BOARD_ID=144.配置MCP客户端
光标(~/.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"
}
}
}
}克劳德桌面：
{
"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"
}
}
}
}完整配置参考
# 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发展
建筑
npm run build测试
# 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添加新工具
- 在适当的模块中创建工具：
// 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);
}
);
}- 在主服务器中注册：
// src/index.ts
import { registerExampleTools } from './tools/example.js';
registerExampleTools(server);API集成
MCP服务器连接 直接 到FluentBoards WordPress REST API：
- 基本URL:
{WORDPRESS_URL}/wp-json/fluent-boards/v2 - 身份验证： WordPress应用程序密码（安全，内置）
- 连接： 直接HTTPS（无需代理）
- 格式： JSON请求/响应
- 速率限制： 由WordPress处理
无需代理插件
MCP服务器使用WordPress的本地REST API和应用程序密码验证。 不需要额外的WordPress插件 以使MCP服务器正常工作。
响应格式
所有工具均返回标准化的MCP响应：
{
"content": [
{
"type": "text",
"text": "{\n \"board\": {\n \"id\": 14,\n \"title\": \"My Board\"\n }\n}"
}
]
}文本格式功能
服务器自动格式化文本内容：
- ✅ 适当的划线标记
- ✅ 标题格式(
##) - ✅ 列表格式(
-并编号） - ✅ 复选框格式(
[ ]和[x]) - ✅ 状态指示器(
✅,❌) - ✅ HTML实体解码
错误处理
针对特定错误类型的全面错误处理：
API错误
{
"error": "API request failed",
"status": 404,
"message": "Board not found"
}安全错误
{
"error": "Delete operation not allowed",
"reason": "Delete operations are disabled",
"code": "DELETES_DISABLED"
}板焦点错误
{
"error": "Operation outside board focus scope",
"reason": "Operations are focused on board 14",
"code": "OUT_OF_FOCUS"
}故障排除
刀具计数更改
- 预期： 在聚焦模式之间切换时，刀具计数会发生变化
- 所有董事会： 约14种可用工具
- 董事会重点： 约11个可用工具（已移除电路板操作工具）
连接问题
# 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/"权限问题
- 确保WordPress用户具有FluentBoards访问权限
- 验证应用程序密码是否正确生成
- 检查WordPress REST API是否已启用
- 确保FluentBoards插件处于活动状态
- 无需安装代理插件
未来的增强功能
- 📊 性能监控和指标
- 🔄 用于频繁访问数据的缓存层
- 🪝 Webhook支持实时更新
- 📦 批量操作以提高效率
- 📎 文件上传和附件管理
- 🔍 高级搜索和过滤
- 📈 报告和分析工具
- 🔐 增强的身份验证方法
贡献
- 遵循架构模式 -使用模块化工具组织
- 实施安全控制 -添加验证和访问检查
- 添加全面的错误处理 -包括特定错误代码
- 使用输入验证 -所有参数的Zod模式
- 一致地格式化响应 -使用实用功能
- 添加测试 -全面覆盖新功能
- 更新文档 -保持README最新
许可证
该项目是FluentBoards生态系统的一部分。