Businessmap MCP

🚀 BusinessMap MCP Server

BusinessMap MCP Serverは、BusinessMap (Kanbanize) との統合を目的としたModel Context Protocolサーバーです。ワークスペース、ボード、カード、サブタスク、親子関係、成果、カスタムフィールドなど、BusinessMapのプロジェクト管理機能に包括的にアクセスできます。

🚀 クイックスタート

このセクションでは、BusinessMap MCP Serverのインストール、設定、使用方法について説明します。

✨ 主な機能

高度なカード管理

• カード、サブタスク、関係に対する完全なCRUD操作
• 完全なグラフトラバーサルを備えた親子カード階層
• 詳細な進捗監視のための成果追跡と履歴
• クロスプロジェクト依存関係のためのリンクカード管理
• 柔軟なワークフローのためのカスタムフィールドとタイプのサポート

包括的なボード操作

• 検索機能を備えたマルチワークスペースボード管理
• ワークフローカスタマイズのための列とレーン（スイムレーン）操作
• 詳細なメタデータを備えたボード構造分析

ワークフローインテリジェンス

• 構成可能な列セットを備えたサイクルタイム分析
• パフォーマンス最適化のための有効サイクルタイム追跡
• 強化されたレポートのためのカスタムフィールド統合

エンタープライズ機能

• 安全なデータ探索のための読み取り専用モード
• 詳細なエラーメッセージを備えた堅牢なエラーハンドリング
• リトライロジックを備えた自動接続検証
• コンテナ化デプロイのためのDockerサポート

📦 インストール

NPXを使用する場合（推奨）

グローバルにインストールすることなく、npxを使用してBusinessMap MCPサーバーを直接実行できます。

npx @edicarlos.lds/businessmap-mcp

グローバルインストール

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

📚 ドキュメント

設定

環境変数

サーバーには以下の環境変数が必要です。

• 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. 開発/テスト用に、BusinessMapの資格情報を含む.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

⚠️ 重要提示

Claude DesktopとともにMCPサーバーとして使用する場合は、.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のツールを提供します。

開発

開発環境のセットアップ

# 依存関係をインストールする
npm install

# 開発モードで実行する
npm run dev

# 変更を監視する
npm run watch

# 本番用にビルドする
npm run build

# テストを実行する
npm test

# コードをlintする
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: add new feature
fix: resolve bug
docs: update documentation
refactor: improve code structure

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