Businessmap Mcp

Businessmap Mcp

管理 TypeScript

🚀 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
  1. 安装依赖：
npm install
  1. 创建 .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 客户端配置中设置环境变量。

  1. 构建项目：
npm run build
  1. 启动服务器：
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
  1. 手动测试连接：
chmod +x scripts/test-connection.sh
./scripts/test-connection.sh
  1. 常见问题：
  • 无效的 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: 改进代码结构
  1. 在提交 PR 之前确保所有测试通过：
npm test
npm run test:npx

📄 许可证

本项目采用 MIT 许可证。

支持

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

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

相关项目

默认排序 时间排序

0 个评论

« 上一篇
Teamwork Mcp 2j9
下一篇 »
Kelvin6365_plane Mcp Server
  • 0 关注
  • 0 收藏，115 浏览
  • system 提出于 2025-10-07 11:18

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »