STARWARCLOUD STARWAR.AI
返回市场
构建蓝图-MCP

构建蓝图-MCP

作者：chunkydotdev9 星标更新：2025-07-04
安装使用来源：spider==github.com

项目介绍

@bldbl/mcp

Buildable 官方MCP客户端 - 基于AI的开发平台，使任何项目均可构建

<a href="https://glama.ai/mcp/servers/@chunkydotdev/bldbl-mcp"> <img width="380" height="200" src="https://gips0.baidu.com/it/u=2060266313,96177592&fm=3081&app=3081&f=PNG?w=760&h=400" alt="@bldbl/mcp MCP服务器" /> </a>

npm版本 MIT许可证 smithery徽章

此包允许AI助手（如Claude、GPT等）通过模型上下文协议（MCP）直接与Buildable项目进行交互。AI助手可以获取项目上下文、管理任务、跟踪进度并与人类开发者沟通。

🌟 什么是Buildable？

Buildable (bldbl.dev) 是一个基于AI的开发平台，使任何项目均可构建。它提供：

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

🚀 功能

  • 完整的项目集成：获取完整的项目上下文、计划和任务详情
  • 自主任务管理：开始、更新进度并完成任务
  • 人机协作：创建讨论以解决疑问和阻碍
  • 实时进度跟踪：实时更新和状态监控
  • 类型安全API：全面的TypeScript支持和类型定义
  • Claude桌面就绪：用于无缝Claude桌面集成的CLI界面

📦 安装

通过Smithery安装

要通过Smithery自动安装@bldbl/mcp到Claude桌面：

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桌面：

在您的Claude桌面配置文件（~/.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对话：

您："我接下来应该在我的项目中做什么？"

AI：*调用get_project_context & get_next_task*
    "我看到您正在构建一个React仪表板应用程序。下一个高优先级任务是'实现用户认证'。我应该开始做这个吗？"

您："是的，去做吧！"

AI：*调用start_task*
    "太好了！我开始处理认证任务。我将使用NextAuth.js与GitHub OAuth。让我分解一下：
     1. 安装依赖项
     2. 设置NextAuth配置
     3. 创建登录/注销组件
     4. 添加受保护的路由
     
     我会在工作时向您报告进度！"

[AI工作并定期调用update_progress]

AI：*调用update_progress*
    "进度更新：已完成75%！我已经实现了：
     ✅ NextAuth.js配置
     ✅ GitHub OAuth提供商设置
     ✅ 登录/注销组件
     🔄 正在处理：受保护的路由中间件
     
     我是否应该继续剩余的工作？"

🔧 高级配置

环境变量

建议设置三个环境变量以正确跟踪AI助手：

export BUILDABLE_API_KEY="bp_your_api_key_here"           # 您的API密钥（必需）
export BUILDABLE_PROJECT_ID="your-project-id"             # 目标项目（必需）
export BUILDABLE_AI_ASSISTANT_ID="my-ai-assistant"        # AI助手ID（推荐）

# 可选（具有智能默认值）：
# export BUILDABLE_API_URL="https://bldbl.dev/api"        # API端点（默认）

为什么AI助手ID重要： 这有助于您在项目仪表板上追踪哪个AI助手在执行什么工作。

CLI使用

您也可以直接运行MCP服务器：

# 全局安装并使用bldbl命令
npm install -g @bldbl/mcp
bldbl

# 或者使用npx运行（无需安装）
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('无效或已过期的API密钥');
  } else if (error.code === 'PROJECT_NOT_FOUND') {
    console.error('未找到项目或无访问权限');
  } else {
    console.error('API错误：', error.message);
  }
}

🔄 开发工作流

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

  1. 初始化 - 使用API密钥连接到Buildable
  2. 获取上下文 - 了解项目结构和当前状态
  3. 查找工作 - 获取下一个优先级任务
  4. 开始任务 - 开始处理，带有方法和时间估计
  5. 进度更新 - 定期报告详细进度
  6. 提问 - 创建讨论以解决阻碍或决策
  7. 完成任务 - 使用详细的完成笔记完成任务
  8. 重复 - 继续处理下一个任务

📊 使用统计

// 获取您的AI助手的使用统计
const stats = await client.getUsageStats();
console.log(`已完成任务数：${stats.tasksCompleted}`);
console.log(`平均完成时间：${stats.avgCompletionTime}分钟`);
console.log(`成功率：${stats.successRate}%`);

⚡ CLI使用

安装后，您可以多种方式使用CLI：

# 直接使用npx运行（无需安装）
npx @bldbl/mcp

# 或全局安装并使用bldbl命令
npm install -g @bldbl/mcp
bldbl

# 对于Claude桌面，在您的配置中使用bldbl命令

所需环境变量：

  • 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';

// 使用模拟响应创建测试客户端
const testClient = createTestClient({
  mockProject: {
    id: 'test-project',
    title: '测试项目'
  }
});

// 在您的测试中使用
await testClient.startTask('test-task-id');

🔗 链接

🏗️ 构建于

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

📄 许可证

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

本软件是专有的且保密的。未经授权的复制、分发或使用严格禁止。

由Buildable团队用心制作

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

🆘 支持

由BuildPlanner团队用心制作