Buildable MCP Server

官方

Buildable AI驱动开发平台的官方MCP服务器。使AI助手能够管理任务、跟踪进度、获取项目上下文，并与人类在软件项目上进行协作。

GitHub

文档

@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 就绪：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 密钥

前往 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);
  }
}

🔄 开发工作流

使用 Buildable 的典型 AI 助手工作流：

初始化 - 使用 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
🐛 支持：[email protected]
📦 NPM 包：npmjs.com/package/@bldbl/mcp

🏗️ 技术栈

TypeScript - 类型安全开发
模型上下文协议（MCP） - 标准化的 AI 助手通信
Node.js - 运行时环境
REST API - 简单可靠的通信

📄 许可证

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

由 Buildable 团队用 ❤️ 制作

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

🆘 支持

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

由 BuildPlanner 团队用 ❤️ 构建