Buildable

官方

Buildable AI 開發平台的官方 MCP 伺服器，讓 AI 助手能夠管理任務、追蹤進度、取得專案背景資訊，並與人類協作進行軟體專案。

GitHub

你可以用 Buildable MCP 做什麼？

取得完整專案背景 — 透過 get_project_context 擷取專案計畫、任務與近期活動。
尋找下一個優先任務 — 請 AI 呼叫 get_next_task，根據相依性與優先順序識別應處理的項目。
開始並追蹤任務 — 透過 start_task 開始執行特定任務，並使用 update_progress 回報階段性進度。
完成任務 — 使用 complete_task 將任務標記為完成，並附上詳細的完成備註。
請求人工輸入 — 透過 create_discussion 為阻礙事項或決策建立討論。
驗證連線狀態 — 使用 health_check 檢查 Buildable API 的連線狀態。

文件

@bldbl/mcp

Buildable 官方 MCP 用戶端 - 讓任何專案都可被建構的 AI 驅動開發平台

此套件讓 AI 助理（Claude、GPT 等）能透過模型上下文協定 (MCP) 直接與 Buildable 專案協作。AI 助理可以取得專案上下文、管理任務、追蹤進度，並與人類開發者溝通。

🌟 什麼是 Buildable？

Buildable (bldbl.dev) 是一個 AI 驅動的開發平台，讓任何專案都可被建構。它提供：

AI 生成的建構計畫：包含實作細節的全面專案路線圖
智慧任務管理：自動化任務分解，包含相依性與優先順序
AI 助理整合：直接整合 Claude、GPT 及其他 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 金鑰

前往 bldbl.dev 並建立帳戶
建立或選擇一個專案
前往 專案設定 → 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：一鍵設定（建議）

前往您在 bldbl.dev 上的專案
導覽至整合
點擊 「新增至 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?"

🔧 進階設定

環境變數

建議使用 3 個環境變數以正確追蹤 AI 助理：

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>`

正確地中斷連線並清理用戶端。

🔐 驗證

產生 API 金鑰：前往您的 Buildable 專案 → AI 助理分頁 → 產生 API 金鑰
安全儲存：安全地儲存您的 API 金鑰（建議使用環境變數）
金鑰格式：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);
  }
}

🔄 開發工作流程

AI 助理與 Buildable 協作的典型工作流程：

初始化 - 使用 API 金鑰連線至 Buildable
取得上下文 - 了解專案結構與目前狀態
尋找工作 - 取得下一個優先任務
開始任務 - 附帶方法與預估開始工作
進度更新 - 定期回報包含細節的進度
提出問題 - 針對阻礙或決策建立討論
完成任務 - 附上全面的完成筆記來結束任務
重複 - 繼續處理下一個任務

📊 使用統計

// 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
🐛 支援：support@bldbl.dev
📦 NPM 套件：npmjs.com/package/@bldbl/mcp

🏗️ 使用技術建構

TypeScript - 型別安全的開發
模型上下文協定 (MCP) - 標準化的 AI 助理通訊
Node.js - 執行環境
REST API - 簡單且可靠的通訊

📄 授權條款

此軟體為專有且機密。未經授權的複製、散佈或使用均嚴格禁止。

由 Buildable 團隊用 ❤️ 打造

Buildable 是一個商業 AI 驅動開發平台。前往 bldbl.dev 開始使用。

🆘 支援

文件：https://bldbl.dev/docs
電子郵件：support@bldbl.dev
網站：https://bldbl.dev

由 BuildPlanner 團隊用 ❤️ 打造