Buildable MCP Server

chính thức

Máy chủ MCP chính thức cho nền tảng phát triển hỗ trợ AI Buildable. Cho phép trợ lý AI quản lý tác vụ, theo dõi tiến độ, lấy ngữ cảnh dự án và cộng tác với con người trong các dự án phần mềm.

GitHub
12

Tài liệu

@bldbl/mcp

MCP client chính thức cho Buildable - Nền tảng phát triển ứng dụng AI giúp mọi dự án trở nên khả thi

@bldbl/mcp MCP server

npm version License: MIT smithery badge

Gói này cho phép các trợ lý AI (Claude, GPT, v.v.) làm việc trực tiếp với các dự án Buildable bằng Giao thức Ngữ cảnh Mô hình (MCP). Trợ lý AI có thể lấy ngữ cảnh dự án, quản lý tác vụ, theo dõi tiến độ và giao tiếp với nhà phát triển.

🌟 Buildable là gì?

Buildable (bldbl.dev) là nền tảng phát triển ứng dụng AI giúp mọi dự án trở nên khả thi. Nó cung cấp:

  • Kế hoạch Xây dựng do AI Tạo ra: Lộ trình dự án toàn diện với chi tiết triển khai
  • Quản lý Tác vụ Thông minh: Phân rã tác vụ tự động với các phụ thuộc và ưu tiên
  • Tích hợp Trợ lý AI: Tích hợp trực tiếp với Claude, GPT và các trợ lý AI khác
  • Cộng tác Thời gian Thực: Cộng tác liền mạch giữa người và AI trong các dự án phức tạp
  • Theo dõi Tiến độ: Giám sát trực tiếp tiến độ phát triển và các điểm nghẽn

🚀 Tính năng

  • Tích hợp Dự án Đầy đủ: Lấy ngữ cảnh dự án, kế hoạch và chi tiết tác vụ hoàn chỉnh
  • Quản lý Tác vụ Tự chủ: Bắt đầu, cập nhật tiến độ và hoàn thành tác vụ
  • Cộng tác với Con người: Tạo thảo luận cho các câu hỏi và điểm nghẽn
  • Theo dõi Tiến độ Thời gian Thực: Cập nhật trực tiếp và giám sát trạng thái
  • API An toàn Kiểu: Hỗ trợ TypeScript đầy đủ với định nghĩa kiểu toàn diện
  • Sẵn sàng cho Claude Desktop: Giao diện CLI để tích hợp liền mạch với Claude Desktop

📦 Cài đặt

Cài đặt qua Smithery

Để cài đặt @bldbl/mcp cho Claude Desktop tự động qua Smithery:

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

Cài đặt Thủ công

npm install @bldbl/mcp

🚀 Bắt đầu Nhanh

Bước 1: Cài đặt MCP Server

npm install -g @bldbl/mcp

Bước 2: Lấy Khóa API Buildable của Bạn

  1. Truy cập bldbl.dev và tạo tài khoản
  2. Tạo hoặc chọn một dự án
  3. Vào Cài đặt Dự án → Trợ lý AI → Tạo Khóa API

Bước 3: Cấu hình Trợ lý AI của Bạn

🤖 Cho Claude Desktop:

Thêm phần này vào tệp cấu hình Claude Desktop của bạn (~/.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"
      }
    }
  }
}

Thiết lập tối thiểu - chỉ URL API được tự động phát hiện.

✨ Cho Cursor AI:

Tùy chọn 1: Thiết lập Một cú Nhấp (Khuyến nghị)

  1. Vào dự án của bạn trên bldbl.dev
  2. Điều hướng đến Tích hợp
  3. Nhấp "Thêm vào Cursor" - Xong! 🎉

Tùy chọn 2: Cấu hình Thủ công Thêm phần này vào tệp cấu hình Cursor AI của bạn:

{
  "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"
      }
    }
  }
}

Thiết lập tối thiểu - chỉ URL API được tự động phát hiện.

Bước 4: Bắt đầu Phát triển với AI!

Sau khi cấu hình, trợ lý AI của bạn có quyền truy cập vào các công cụ mạnh mẽ sau:

  • 🏗️ get_project_context - Hiểu toàn bộ cấu trúc dự án của bạn
  • 📋 get_next_task - Tìm việc cần làm tiếp theo dựa trên ưu tiên
  • ▶️ start_task - Bắt đầu làm việc trên một tác vụ cụ thể
  • 📊 update_progress - Báo cáo cập nhật tiến độ chi tiết
  • ✅ complete_task - Đánh dấu tác vụ đã hoàn thành với ghi chú toàn diện
  • 💬 create_discussion - Đặt câu hỏi khi bạn cần đầu vào từ con người
  • 🔍 health_check - Xác minh kết nối đến Buildable

💡 Ví dụ Hội thoại 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?"

🔧 Cấu hình Nâng cao

Biến Môi trường

Khuyến nghị 3 biến môi trường để theo dõi trợ lý AI đúng cách:

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)

Tại sao ID Trợ lý AI quan trọng: Điều này giúp bạn theo dõi trợ lý AI nào đang làm công việc gì trong bảng điều khiển dự án của bạn.

Sử dụng CLI

Bạn cũng có thể chạy trực tiếp MCP server:

# Install globally and use bldbl command
npm install -g @bldbl/mcp
bldbl

# Or run with npx (no installation needed)
npx @bldbl/mcp

Nhiều Dự án

Để làm việc với nhiều dự án Buildable, tạo các cấu hình MCP server khác nhau:

{
  "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"
      }
    }
  }
}

🛠️ Tham khảo API

BuildPlannerMCPClient

Lớp client chính để tương tác với các dự án Buildable.

Constructor

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

Tham số Cấu hình:

  • apiUrl: URL API Buildable (mặc định là 'https://bldbl.dev/api')
  • apiKey: Khóa API Buildable của bạn (bắt đầu bằng 'bp_')
  • projectId: ID dự án mục tiêu
  • aiAssistantId: Định danh duy nhất cho trợ lý AI của bạn
  • timeout: Thời gian chờ yêu cầu tính bằng mili giây (mặc định: 30000)

Tùy chọn:

  • retryAttempts: Số lần thử lại (mặc định: 3)
  • retryDelay: Độ trễ giữa các lần thử lại tính bằng ms (mặc định: 1000)

Phương thức

getProjectContext(): Promise<ProjectContext>

Lấy ngữ cảnh dự án hoàn chỉnh bao gồm kế hoạch, tác vụ và hoạt động gần đây.

getNextTask(): Promise<NextTaskResponse>

Lấy tác vụ được khuyến nghị tiếp theo để làm dựa trên phụ thuộc và ưu tiên.

startTask(taskId: string, options?: StartTaskOptions): Promise<StartTaskResponse>

Bắt đầu làm việc trên một tác vụ cụ thể với cách tiếp cận và ước tính thời gian tùy chọn.

updateProgress(taskId: string, progress: ProgressUpdate): Promise<ProgressResponse>

Cập nhật tiến độ trên tác vụ hiện tại với thông tin trạng thái chi tiết.

completeTask(taskId: string, completion: CompleteTaskRequest): Promise<CompleteTaskResponse>

Đánh dấu một tác vụ là đã hoàn thành với thông tin hoàn thành chi tiết.

createDiscussion(discussion: CreateDiscussionRequest): Promise<DiscussionResponse>

Tạo một cuộc thảo luận/câu hỏi cho đầu vào từ con người khi bạn cần hướng dẫn.

healthCheck(): Promise<{status: string, timestamp: string}>

Kiểm tra kết nối và tình trạng của API Buildable.

disconnect(): Promise<void>

Ngắt kết nối và dọn dẹp kết nối client đúng cách.

🔐 Xác thực

  1. Tạo Khóa API: Vào dự án Buildable của bạn → tab Trợ lý AI → Tạo Khóa API
  2. Lưu trữ An toàn: Lưu trữ khóa API của bạn một cách an toàn (khuyến nghị dùng biến môi trường)
  3. Định dạng Khóa: Khóa API bắt đầu bằng bp_ theo sau là dự án và định danh ngẫu nhiên

🐛 Xử lý Lỗi

Client bao gồm xử lý lỗi toàn diện:

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

🔄 Quy trình Phát triển

Quy trình làm việc điển hình của trợ lý AI với Buildable:

  1. Khởi tạo - Kết nối với Buildable bằng khóa API
  2. Lấy Ngữ cảnh - Hiểu cấu trúc dự án và trạng thái hiện tại
  3. Tìm Việc - Lấy tác vụ ưu tiên tiếp theo
  4. Bắt đầu Tác vụ - Bắt đầu làm việc với cách tiếp cận và ước tính
  5. Cập nhật Tiến độ - Báo cáo tiến độ thường xuyên với chi tiết
  6. Đặt Câu hỏi - Tạo thảo luận cho các điểm nghẽn hoặc quyết định
  7. Hoàn thành Tác vụ - Kết thúc với ghi chú hoàn thành toàn diện
  8. Lặp lại - Tiếp tục với các tác vụ tiếp theo

📊 Thống kê Sử dụng

// 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}%`);

⚡ Sử dụng CLI

Sau khi cài đặt, bạn có thể sử dụng CLI theo nhiều cách:

# 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

Biến Môi trường Yêu cầu:

  • BUILDABLE_API_URL - URL API Buildable của bạn
  • BUILDABLE_API_KEY - Khóa API của bạn (bắt đầu bằng 'bp_')
  • BUILDABLE_PROJECT_ID - ID dự án mục tiêu
  • BUILDABLE_AI_ASSISTANT_ID - Định danh trợ lý duy nhất

🧪 Kiểm thử

Gói bao gồm các tiện ích kiểm thử toàn diện:

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

🔗 Liên kết

🏗️ Được Xây dựng Bằng

  • TypeScript - Phát triển an toàn kiểu
  • Giao thức Ngữ cảnh Mô hình (MCP) - Giao tiếp trợ lý AI chuẩn hóa
  • Node.js - Môi trường thời gian chạy
  • REST API - Giao tiếp đơn giản và đáng tin cậy

📄 Giấy phép

Bản quyền © 2025 Buildable Team. Đã đăng ký bản quyền.

Phần mềm này là độc quyền và bảo mật. Sao chép, phân phối hoặc sử dụng trái phép bị nghiêm cấm.

Được tạo bằng ❤️ bởi đội ngũ Buildable

Buildable là nền tảng phát triển ứng dụng AI thương mại. Truy cập bldbl.dev để bắt đầu.

🆘 Hỗ trợ

Được xây dựng bằng ❤️ bởi đội ngũ BuildPlanner