Buildable

@bldbl/mcp

Buildable 官方 MCP 客户端——Buildable 是一个 AI 驱动的开发平台，可让任何项目都具备可构建性

此软件包可让 AI 助手（Claude、GPT 等）使用模型上下文协议（MCP）直接处理 Buildable 项目。AI 助手可以获取项目上下文、管理任务、跟踪进度，并与人类开发者交流。

🌟 什么是 Buildable？

Buildable（bldbl.dev）是一个 AI 驱动的开发平台，可让任何项目都具备可构建性。它提供：

• AI 生成的构建计划：包含实施细节的全面项目路线图
• 智能任务管理：自动拆分任务并设置依赖关系和优先级
• AI 助手集成：直接集成 Claude、GPT 和其他 AI 助手
• 实时协作：人类与 AI 无缝协作，共同处理复杂项目
• 进度跟踪：实时监控开发进度和阻塞项

🚀 功能

• 完整项目集成：获取完整的项目上下文、计划和任务详情
• 自主任务管理：开始任务、更新进度并完成任务
• 人类协作：针对问题和阻塞项创建讨论
• 实时进度跟踪：实时更新和状态监控
• 类型安全的 API：全面支持 TypeScript，并提供完整的类型定义
• 已为 Claude Desktop 准备就绪：提供 CLI 接口，可与 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. 前往 项目设置 → 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?"

🔧 高级配置

环境变量

建议设置 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 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 选项卡 → 生成 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');

🔗 链接

• 🌐 主页：bldbl.dev
• 📚 文档：bldbl.dev/docs
• 💬 社区：Discord
• 🐛 支持：[email protected]
• 📦 NPM 软件包：npmjs.com/package/@bldbl/mcp

🏗️ 构建技术

• TypeScript - 类型安全开发
• Model Context Protocol (MCP) - 标准化的 AI 助手通信
• Node.js - 运行环境
• REST API - 简单可靠的通信

📄 许可证

版权所有 © 2025 Buildable 团队。保留所有权利。

本软件为专有机密软件。严禁未经授权进行复制、分发或使用。

---

由 Buildable 团队倾心打造

Buildable 是一个由 AI 驱动的商业开发平台。访问 bldbl.dev 即可开始使用。

🆘 支持

• 文档：https://bldbl.dev/docs
• 电子邮件：[email protected]
• 网站：https://bldbl.dev

---

由 BuildPlanner 团队倾心打造