Businessmap MCP

🚀 BusinessMap MCP Server

BusinessMap MCP Server 是一个用于集成 BusinessMap（Kanbanize）的模型上下文协议（MCP）服务器。它提供了对 BusinessMap 项目管理功能的全面访问，涵盖工作区、看板、卡片、子任务、父子关系、成果、自定义字段等多个方面。

🚀 快速开始

你可以使用以下两种方式快速启动 BusinessMap MCP 服务器：

通过 NPX（推荐）

无需全局安装，直接使用 npx 运行：

npx @edicarlos.lds/businessmap-mcp

全局安装

npm install -g @edicarlos.lds/businessmap-mcp

✨ 主要特性

高级卡片管理

• 对卡片、子任务和关系进行完整的 CRUD 操作。
• 支持父子卡片层级结构，并具备完整的图遍历功能。
• 跟踪成果和历史记录，便于详细的进度监控。
• 管理关联卡片，处理跨项目依赖关系。
• 支持自定义字段和类型，实现灵活的工作流。

全面的看板操作

• 支持多工作区的看板管理，并具备搜索功能。
• 可对列和泳道进行操作，自定义工作流。
• 分析看板结构，提供详细的元数据。

工作流智能

• 进行周期时间分析，支持可配置的列集。
• 跟踪有效周期时间，优化性能。
• 集成自定义字段，增强报告功能。

企业级特性

• 支持只读模式，安全地探索数据。
• 强大的错误处理机制，提供详细的错误信息。
• 自动验证连接，具备重试逻辑。
• 支持 Docker 容器化部署。

📦 安装指南

环境变量配置

服务器需要以下环境变量：

• BUSINESSMAP_API_TOKEN：你的 BusinessMap API 令牌
• BUSINESSMAP_API_URL：你的 BusinessMap API URL（例如：https://your-account.kanbanize.com/api/v2）
• BUSINESSMAP_READ_ONLY_MODE：设置为 "true" 启用只读模式，"false" 允许修改（可选，默认为 "false"）
• BUSINESSMAP_DEFAULT_WORKSPACE_ID：设置 BusinessMap 工作区 ID（可选）

Claude Desktop 配置

在 claude_desktop_config.json 文件中添加以下配置： 使用 NPX：

{
  "mcpServers": {
    "Businessmap": {
      "command": "npx",
      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
      "env": {
        "BUSINESSMAP_API_TOKEN": "your_token_here",
        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
        "BUSINESSMAP_READ_ONLY_MODE": "false", // 可选
        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1" // 可选
      }
    }
  }
}

使用全局安装：

{
  "mcpServers": {
    "Businessmap": {
      "command": "businessmap-mcp",
      "env": {
        "BUSINESSMAP_API_TOKEN": "your_token_here",
        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
        "BUSINESSMAP_READ_ONLY_MODE": "false", // 可选
        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1" // 可选
      }
    }
  }
}

其他 MCP 客户端

对于其他 MCP 客户端，使用适合你的客户端的配置格式，确保指定以下内容：

• 命令：npx @edicarlos.lds/businessmap-mcp（如果全局安装，则使用 businessmap-mcp）
• 环境变量：BUSINESSMAP_API_TOKEN、BUSINESSMAP_API_URL，可选的 BUSINESSMAP_READ_ONLY_MODE、BUSINESSMAP_DEFAULT_WORKSPACE_ID

手动设置

1. 克隆仓库：

git clone https://github.com/edicarloslds/businessmap-mcp.git
cd businessmap-mcp

2. 安装依赖：

npm install

3. 创建 .env 文件，用于开发/测试时存储你的 BusinessMap 凭证：

BUSINESSMAP_API_TOKEN=your_token_here
BUSINESSMAP_API_URL=https://your-account.kanbanize.com/api/v2
BUSINESSMAP_READ_ONLY_MODE=false
BUSINESSMAP_DEFAULT_WORKSPACE_ID=1

⚠️ 重要提示

当作为 MCP 服务器与 Claude Desktop 一起使用时，不需要 .env 文件。而是直接在 MCP 客户端配置中设置环境变量。

4. 构建项目：

npm run build

5. 启动服务器：

npm start

💻 使用示例

BusinessMap MCP 服务器提供了以下工具：

工作区管理

• list_workspaces - 获取所有工作区
• get_workspace - 获取工作区详情
• create_workspace - 创建新的工作区

看板管理

• list_boards - 列出工作区中的看板
• search_board - 按 ID 或名称搜索看板
• get_current_board_structure - 获取看板的完整当前结构，包括工作流、列、泳道和配置
• create_board - 创建新的看板（非只读模式下）
• get_columns - 获取看板的所有列
• get_lanes - 获取看板的所有泳道
• get_lane - 获取特定泳道的详情
• create_lane - 创建新的泳道（非只读模式下）

卡片管理

基本卡片操作

• list_cards - 从看板获取卡片，支持可选过滤器
• get_card - 获取卡片的详细信息
• get_card_size - 获取特定卡片的大小/点数
• create_card - 创建新的卡片
• move_card - 将卡片移动到不同的列/泳道
• update_card - 更新卡片属性
• set_card_size - 设置特定卡片的大小/点数

卡片评论

• get_card_comments - 获取特定卡片的所有评论
• get_card_comment - 获取特定评论的详情

卡片自定义字段和类型

• get_card_custom_fields - 获取特定卡片的所有自定义字段
• get_card_types - 获取所有可用的卡片类型

卡片成果和历史记录

• get_card_outcomes - 获取特定卡片的所有成果
• get_card_history - 获取特定卡片成果的历史记录

卡片关系

• get_card_linked_cards - 获取特定卡片的所有关联卡片

卡片子任务

• get_card_subtasks - 获取特定卡片的所有子任务
• get_card_subtask - 获取特定子任务的详情
• create_card_subtask - 为卡片创建新的子任务

卡片父子关系

• get_card_parents - 获取特定卡片的所有父卡片列表
• get_card_parent - 检查卡片是否为给定卡片的父卡片
• add_card_parent - 将卡片设置为给定卡片的父卡片
• remove_card_parent - 移除子卡片与父卡片之间的关联
• get_card_parent_graph - 获取包括其父卡片在内的父卡片列表

自定义字段管理

• get_custom_field - 按 ID 获取特定自定义字段的详情

工作流和周期时间分析

• get_workflow_cycle_time_columns - 获取工作流的周期时间列
• get_workflow_effective_cycle_time_columns - 获取工作流的有效周期时间列

用户管理

• list_users - 获取所有用户
• get_user - 获取用户详情
• get_current_user - 获取当前登录用户的详情

系统

• health_check - 检查 API 连接
• get_api_info - 获取 API 信息

工具总结

BusinessMap MCP 服务器提供了 7 个类别共 42 个工具：

• 工作区管理：3 个工具
• 看板管理：9 个工具
• 卡片管理：22 个工具（分为 6 个子类别）
• 自定义字段管理：1 个工具
• 工作流和周期时间分析：2 个工具
• 用户管理：3 个工具
• 系统：2 个工具

🔧 技术细节

开发环境设置

# 安装依赖
npm install

# 以开发模式运行
npm run dev

# 监听文件变化
npm run watch

# 为生产环境构建
npm run build

# 运行测试
npm test

# 代码检查
npm run lint

Docker 支持

# 构建 Docker 镜像
npm run docker:build

# 使用 Docker Compose 运行
npm run docker:up

# 查看日志
npm run docker:logs

# 停止容器
npm run docker:down

故障排除

连接问题

服务器在启动时会自动验证连接。如果遇到连接问题：

1. 检查环境变量：

echo $BUSINESSMAP_API_URL
echo $BUSINESSMAP_API_TOKEN

2. 手动测试连接：

chmod +x scripts/test-connection.sh
./scripts/test-connection.sh

3. 常见问题：

• 无效的 API URL：确保你的 URL 遵循 https://your-account.kanbanize.com/api/v2 格式。
• 无效的 API 令牌：验证你的令牌具有必要的权限。

启动过程

服务器在初始化时会执行以下步骤：

1. 配置验证 - 检查所有必需的环境变量。
2. API 连接验证 - 测试连接，最多重试 3 次。
3. 身份验证检查 - 验证 API 令牌权限。
4. 服务器启动 - 仅在连接成功后启动 MCP 服务器。

如果连接失败，服务器将显示详细的错误信息并自动重试。

发布过程

本项目使用自动化发布流程。详细文档请参阅 RELEASE_PROCESS.md。 快速开始：

# 预览发布说明
npm run preview:release

# 发布新版本（交互式）
npm run publish

发布过程会自动执行以下操作：

• 提升版本号（补丁/次要/主要）
• 从提交记录生成发布说明
• 创建 GitHub 标签和发布版本
• 发布到 NPM

贡献代码

1. 遵循常规提交格式，以便生成更好的发布说明：

feat: 添加新功能
fix: 修复 bug
docs: 更新文档
refactor: 改进代码结构

2. 在提交 PR 之前确保所有测试通过：

npm test
npm run test:npx

📄 许可证

本项目采用 MIT 许可证。

支持

如果你遇到问题或有疑问：

1. 查看 Issues 页面。
2. 查阅 BusinessMap API 文档。
3. 验证你的环境配置。
4. 提交包含详细信息的新问题。

相关项目

• Model Context Protocol - 官方 MCP 文档
• BusinessMap API Documentation - 官方 API 参考
• MCP TypeScript SDK - 官方 MCP SDK