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