Buildable MCP Server

公式

Buildable AI搭載開発プラットフォームの公式MCPサーバー。AIアシスタントがタスクの管理、進捗の追跡、プロジェクトコンテキストの取得、ソフトウェアプロジェクトでの人間とのコラボレーションを可能にします。

GitHub
12

ドキュメント

@bldbl/mcp

Buildable 公式 MCP クライアント - あらゆるプロジェクトをビルド可能にする AI 駆動開発プラットフォーム

@bldbl/mcp MCP server

npm version License: MIT smithery badge

このパッケージにより、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 統合のための CLI インターフェース

📦 インストール

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. プロジェクト設定 → AI アシスタント → API キーを生成 に移動

ステップ 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. 統合 に移動
  3. 「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 アシスタント 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 アシスタントタブ → API キーを生成
  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');

🔗 リンク

🏗️ 使用技術

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

📄 ライセンス

Copyright © 2025 Buildable Team. All rights reserved.

このソフトウェアは独自の機密情報です。許可されていないコピー、配布、使用は固く禁じられています。

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

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

🆘 サポート

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