Buildable

@bldbl/mcp

Buildable の公式 MCP クライアント — あらゆるプロジェクトをビルド可能にする、AI を活用した開発プラットフォーム

このパッケージを使うと、AI アシスタント（Claude、GPT など）が Model Context Protocol（MCP）を通じて、Buildable のプロジェクトを直接操作できます。AI アシスタントはプロジェクトのコンテキストを取得し、タスクを管理して、進捗を追跡し、人間の開発者とコミュニケーションを取ることができます。

🌟 Buildable とは？

Buildable（bldbl.dev）は、あらゆるプロジェクトをビルド可能にする、AI を活用した開発プラットフォームです。次の機能を提供します。

• AI が生成するビルド計画：実装の詳細を含む、包括的なプロジェクトロードマップ
• スマートなタスク管理：依存関係と優先度を考慮した、タスクの自動分割
• AI アシスタントとの連携：Claude、GPT などの AI アシスタントとの直接連携
• リアルタイムのコラボレーション：複雑なプロジェクトでの、人間と AI によるシームレスな共同作業
• 進捗の追跡：開発の進捗や障害をリアルタイムでモニタリング

🚀 機能

• プロジェクトとの完全な連携：プロジェクトのコンテキスト、計画、タスクの詳細をすべて取得
• 自律的なタスク管理：タスクの開始、進捗の更新、完了
• 人間とのコラボレーション：質問や障害について話し合うディスカッションを作成
• リアルタイムの進捗追跡：更新とステータスをリアルタイムで確認
• 型安全な API：包括的な型定義による、TypeScript の完全サポート
• Claude Desktop 対応：Claude Desktop とシームレスに連携できるコマンドラインインターフェース

📦 インストール

Smithery 経由でインストール

Smithery を使って、Claude Desktop 用の @bldbl/mcp を自動的にインストールするには：

npx -y @smithery/cli install @buildable/bldbl-mcp --client claude

手動インストール

npm install @bldbl/mcp

🚀 クイックスタート

ステップ 1：MCP サーバーをインストール

npm install -g @bldbl/mcp

ステップ 2：Buildable API キーを取得

1. bldbl.dev にアクセスして、アカウントを作成します
2. プロジェクトを作成するか、選択します
3. Project Settings → AI Assistants → Generate API Key の順に進みます

ステップ 3：AI アシスタントを設定

🤖 Claude Desktop の場合：

Claude Desktop の設定ファイル（~/.config/claude/claude_desktop_config.json）に、次の内容を追加します。

{
  "mcpServers": {
    "buildable": {
      "command": "npx",
      "args": ["-y", "@bldbl/mcp"],
      "env": {
        "BUILDABLE_API_KEY": "bp_your_api_key_here",
        "BUILDABLE_PROJECT_ID": "your-project-id",
        "BUILDABLE_AI_ASSISTANT_ID": "claude-desktop"
      }
    }
  }
}

最小限の設定です。API URL は自動検出されます。

✨ Cursor AI の場合：

オプション 1：ワンクリックで設定（推奨）

1. bldbl.dev でプロジェクトにアクセスします
2. Integrations に移動します
3. "Add to Cursor" をクリックします。これで完了です！🎉

オプション 2：手動で設定 Cursor AI の設定ファイルに、次の内容を追加します。

{
  "mcpServers": {
    "buildable": {
      "command": "npx",
      "args": ["-y", "@bldbl/mcp"],
      "env": {
        "BUILDABLE_API_KEY": "bp_your_api_key_here",
        "BUILDABLE_PROJECT_ID": "your-project-id",
        "BUILDABLE_AI_ASSISTANT_ID": "cursor-ide"
      }
    }
  }
}

最小限の設定です。API URL は自動検出されます。

ステップ 4：AI を活用した開発を始めましょう！

設定が完了すると、AI アシスタントから次の強力なツールを利用できます。

• 🏗️ get_project_context - プロジェクト全体の構成を把握します
• 📋 get_next_task - 優先度に基づいて、次に取り組むタスクを見つけます
• ▶️ start_task - 特定のタスクに着手します
• 📊 update_progress - 詳細な進捗を報告します
• ✅ complete_task - 詳細なメモを添えて、タスクを完了としてマークします
• 💬 create_discussion - 人間の意見が必要なときに質問します
• 🔍 health_check - Buildable への接続を確認します

💡 AI との会話例：

You: "What should I work on next in my project?"

AI: *calls get_project_context & get_next_task*
    "I see you're building a React dashboard app. The next 
     high-priority task is 'Implement user authentication'. 
     Should I start working on it?"

You: "Yes, go ahead!"

AI: *calls start_task*
    "Perfect! I'm starting the authentication task. I'll use 
     NextAuth.js with GitHub OAuth. Let me break this down:
     1. Install dependencies
     2. Set up NextAuth config  
     3. Create login/logout components
     4. Add protected routes
     
     I'll update you on progress as I work!"

[AI works and calls update_progress periodically]

AI: *calls update_progress*
    "Progress update: 75% complete! I've implemented:
     ✅ NextAuth.js configuration
     ✅ GitHub OAuth provider setup  
     ✅ Login/logout components
     🔄 Currently working on: Protected route middleware
     
     Should I continue with the remaining work?"

🔧 詳細設定

環境変数

AI アシスタントの追跡を適切に行うには、3 つの環境変数を設定することをおすすめします。

export BUILDABLE_API_KEY="bp_your_api_key_here"           # Your API key (required)
export BUILDABLE_PROJECT_ID="your-project-id"             # Target project (required)
export BUILDABLE_AI_ASSISTANT_ID="my-ai-assistant"        # AI Assistant ID (recommended)

# Optional (has smart default):
# export BUILDABLE_API_URL="https://bldbl.dev/api"        # API endpoint (default)

AI Assistant ID が重要な理由： プロジェクトのダッシュボードで、どの AI アシスタントがどの作業を行っているかを追跡できます。

CLI の使用方法

MCP サーバーを直接実行することもできます。

# Install globally and use bldbl command
npm install -g @bldbl/mcp
bldbl

# Or run with npx (no installation needed)
npx @bldbl/mcp

複数のプロジェクト

複数の Buildable プロジェクトを操作するには、異なる MCP サーバー設定を作成します。

{
  "mcpServers": {
    "buildable-frontend": {
      "command": "npx",
      "args": ["-y", "@bldbl/mcp"],
      "env": {
        "BUILDABLE_API_KEY": "bp_frontend_key_here",
        "BUILDABLE_PROJECT_ID": "frontend-project-id",
        "BUILDABLE_AI_ASSISTANT_ID": "claude-frontend"
      }
    },
    "buildable-backend": {
      "command": "npx", 
      "args": ["-y", "@bldbl/mcp"],
      "env": {
        "BUILDABLE_API_KEY": "bp_backend_key_here",
        "BUILDABLE_PROJECT_ID": "backend-project-id",
        "BUILDABLE_AI_ASSISTANT_ID": "claude-backend"
      }
    }
  }
}

🛠️ API リファレンス

BuildPlannerMCPClient

Buildable プロジェクトとやり取りするためのメインクライアントクラスです。

コンストラクター

new BuildPlannerMCPClient(config: BuildPlannerConfig, options?: ClientOptions)

設定パラメーター:

• apiUrl: Buildable API の URL（デフォルトは 'https://bldbl.dev/api'）
• apiKey: Buildable API キー（'bp_' で始まります）
• projectId: 対象のプロジェクト ID
• aiAssistantId: AI アシスタントの一意の識別子
• timeout: リクエストのタイムアウト時間（ミリ秒、デフォルトは 30000）

オプション:

• retryAttempts: 再試行回数（デフォルトは 3）
• retryDelay: 再試行の間隔（ミリ秒、デフォルトは 1000）

メソッド

getProjectContext(): Promise<ProjectContext>

計画、タスク、最近のアクティビティを含むプロジェクトのコンテキスト全体を取得します。

getNextTask(): Promise<NextTaskResponse>

依存関係と優先度に基づいて、次に取り組むことが推奨されるタスクを取得します。

startTask(taskId: string, options?: StartTaskOptions): Promise<StartTaskResponse>

進め方や所要時間の見積もりを任意で指定して、特定のタスクへの作業を開始します。

updateProgress(taskId: string, progress: ProgressUpdate): Promise<ProgressResponse>

詳細なステータス情報を使って、現在のタスクの進捗を更新します。

completeTask(taskId: string, completion: CompleteTaskRequest): Promise<CompleteTaskResponse>

詳細な完了情報を添えて、タスクを完了としてマークします。

createDiscussion(discussion: CreateDiscussionRequest): Promise<DiscussionResponse>

指針が必要な場合に、人間からの入力を求めるためのディスカッションや質問を作成します。

healthCheck(): Promise<{status: string, timestamp: string}>

Buildable API への接続と稼働状態を確認します。

disconnect(): Promise<void>

クライアント接続を適切に切断し、後処理を行います。

🔐 認証

1. API キーを生成する：Buildable プロジェクト → AI Assistant タブ → Generate API Key の順に移動します
2. 安全に保管する：API キーを安全に保管します（環境変数の使用を推奨）
3. キー形式：API キーは bp_ に続いてプロジェクト識別子とランダムな識別子が並びます

🐛 エラー処理

クライアントには包括的なエラー処理が含まれています。

try {
  const context = await client.getProjectContext();
} catch (error) {
  if (error.code === 'UNAUTHORIZED') {
    console.error('Invalid or expired API key');
  } else if (error.code === 'PROJECT_NOT_FOUND') {
    console.error('Project not found or access denied');
  } else {
    console.error('API error:', error.message);
  }
}

🔄 開発ワークフロー

Buildable を使った一般的な AI アシスタントのワークフロー：

1. 初期化 - API キーを使って Buildable に接続します
2. コンテキストを取得 - プロジェクトの構造と現在の状態を把握します
3. 作業を見つける - 次の優先タスクを取得します
4. タスクを開始 - 進め方と見積もりを設定して作業を始めます
5. 進捗を更新 - 詳細な進捗を定期的に報告します
6. 質問する - 作業の妨げとなる問題や判断についてディスカッションを作成します
7. タスクを完了 - 詳細な完了メモを添えて作業を終えます
8. 繰り返す - 次のタスクに進みます

📊 使用統計

// Get usage statistics for your AI assistant
const stats = await client.getUsageStats();
console.log(`Tasks completed: ${stats.tasksCompleted}`);
console.log(`Average completion time: ${stats.avgCompletionTime}min`);
console.log(`Success rate: ${stats.successRate}%`);

⚡ CLI の使用方法

インストール後は、CLI をいくつかの方法で使用できます。

# Run directly with npx (no installation needed)
npx @bldbl/mcp

# Or install globally and use the bldbl command
npm install -g @bldbl/mcp
bldbl

# For Claude Desktop, use the bldbl command in your config

必要な環境変数:

• BUILDABLE_API_URL - Buildable API の URL
• BUILDABLE_API_KEY - API キー（'bp_' で始まります）
• BUILDABLE_PROJECT_ID - 対象のプロジェクト ID
• BUILDABLE_AI_ASSISTANT_ID - アシスタントの一意の識別子

🧪 テスト

このパッケージには、包括的なテストユーティリティが含まれています。

import { createTestClient } from '@bldbl/mcp/test';

// Create a test client with mock responses
const testClient = createTestClient({
  mockProject: {
    id: 'test-project',
    title: 'Test Project'
  }
});

// Use in your tests
await testClient.startTask('test-task-id');

🔗 リンク

• 🌐 ホームページ: bldbl.dev
• 📚 ドキュメント: bldbl.dev/docs
• 💬 コミュニティ: Discord
• 🐛 サポート: [email protected]
• 📦 NPM パッケージ: npmjs.com/package/@bldbl/mcp

🏗️ 使用技術

• TypeScript - 型安全な開発
• Model Context Protocol (MCP) - AI アシスタント向けの標準化された通信
• Node.js - ランタイム環境
• REST API - シンプルで信頼性の高い通信

📄 ライセンス

Copyright © 2025 Buildable Team. All rights reserved.

このソフトウェアは独占的かつ機密性の高いものです。無断での複製、配布、使用は固く禁じられています。

---

Buildable チームが ❤️ を込めて制作

Buildable は、商用の AI 搭載開発プラットフォームです。利用を開始するには、bldbl.dev にアクセスしてください。

🆘 サポート

• ドキュメント：https://bldbl.dev/docs
• メール：[email protected]
• ウェブサイト：https://bldbl.dev

---

BuildPlanner チームが ❤️ を込めて制作