Bldbl MCP

@bldbl/mcp

可构建的官方MCP客户端-人工智能驱动的开发平台，使任何项目都可以构建

](https://badge.fury.io/js/@bldbl%2Fmcp)  ](https://smithery.ai/server/@buildable/bldbl-mcp)

该软件包使AI助手（Claude、GPT等）能够使用模型上下文协议（MCP）直接处理可构建项目。AI助手可以获取项目上下文、管理任务、跟踪进度并与人类开发人员沟通。

🌟 什么是可构建的？

Buildable（bldbl.dev）是一个人工智能驱动的开发平台，可以构建任何项目。它提供：

• 人工智能生成的构建计划：包含实施细节的综合项目路线图
• 智能任务管理：具有依赖关系和优先级的自动任务分解
• AI助手集成：与Claude、GPT和其他AI助手直接集成
• 实时协作：在复杂项目中实现无缝的人工智能协作
• 进度跟踪：实时监测发展进展和阻碍因素

🚀 特性

• 完整的项目集成：获取完整的项目背景、计划和任务详细信息
• 自主任务管理：启动、更新进度和完成任务
• 人类合作：为问题和拦截器创建讨论
• 实时进度跟踪：实时更新和状态监控
• 安全型API：完全支持TypeScript，具有全面的类型定义
• 克劳德桌面就绪：用于无缝集成Claude Desktop的CLI界面

📦 安装

通过Smithery安装

通过以下方式自动安装@bldbl/mcp for Claude Desktop 铁匠铺:

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

手动安装

npm install @bldbl/mcp

🚀 快速开始

步骤1：安装MCP服务器

npm install -g @bldbl/mcp

第2步：获取可构建的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。*

✨ 对于光标AI：

选项1：一键设置（推荐）

1. 转到您的项目 bldbl.dev
2. 导航至 集成
3. 点击 “添加到光标” -完成！ 🎉

选项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。*

第四步：开始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

多个项目

要处理多个可构建项目，请创建不同的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

用于与可构建项目交互的主要客户端类。

构造函数

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

配置参数：

• apiUrl：可构建API URL（默认为“”https://bldbl.dev/api')
• apiKey：您的可构建API密钥（以“bp\_”开头）
• projectId：目标项目ID
• aiAssistantId：您的AI助手的唯一标识符
• timeout：请求超时（毫秒）（默认值：30000）

选项：

• retryAttempts：重试尝试次数（默认值：3）
• retryDelay：重试之间的延迟（毫秒）（默认值：1000）

方法

`getProjectContext(): Promise

`

获取完整的项目上下文，包括计划、任务和最近的活动。

getNextTask(): Promise

根据依赖关系和优先级获取下一个要处理的推荐任务。

startTask(taskId: string, options?: StartTaskOptions): Promise

使用可选方法和时间估计开始处理特定任务。

`updateProgress(taskId: string, progress: ProgressUpdate): Promise

`

使用详细的状态信息更新当前任务的进度。

completeTask(taskId: string, completion: CompleteTaskRequest): Promise

使用详细的完成信息将任务标记为已完成。

createDiscussion(discussion: CreateDiscussionRequest): Promise

当你需要指导时，创建一个讨论/问题供人工输入。

healthCheck(): Promise

检查可构建API的连接和运行状况。

disconnect(): Promise

正确断开并清理客户端连接。

🔐 认证

1. 生成API密钥：转到您的可构建项目→ 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密钥连接到可构建
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 -您的可构建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包:

🏗️ 构建于

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

📄 许可证

版权所有©2025可构建团队。保留所有权利。

该软件是专有和机密的。严禁未经授权的复制、分发或使用。

______________________________________________________________________

由...制作❤️ 由Buildable团队

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

🆘 支持

• 文档: https://bldbl.dev/docs
• 电子邮件: support@bldbl.dev
• 网站: https://bldbl.dev

______________________________________________________________________

内置于❤️ 由BuildPlanner团队提供