Buildable MCP Server

공식

Buildable AI 기반 개발 플랫폼의 공식 MCP 서버입니다. AI 어시스턴트가 작업을 관리하고, 진행 상황을 추적하며, 프로젝트 컨텍스트를 얻고, 소프트웨어 프로젝트에서 인간과 협업할 수 있도록 지원합니다.

GitHub
12

문서

@bldbl/mcp

Buildable 공식 MCP 클라이언트 - 모든 프로젝트를 빌드 가능하게 만드는 AI 기반 개발 플랫폼

@bldbl/mcp MCP server

npm version License: MIT smithery badge

이 패키지를 사용하면 AI 어시스턴트(Claude, GPT 등)가 모델 컨텍스트 프로토콜(MCP)을 통해 Buildable 프로젝트와 직접 작업할 수 있습니다. AI 어시스턴트는 프로젝트 컨텍스트를 가져오고, 작업을 관리하며, 진행 상황을 추적하고, 인간 개발자와 소통할 수 있습니다.

🌟 Buildable이란?

Buildable(bldbl.dev)은 모든 프로젝트를 빌드 가능하게 만드는 AI 기반 개발 플랫폼입니다. 다음을 제공합니다:

  • AI 생성 빌드 계획: 구현 세부 사항이 포함된 종합적인 프로젝트 로드맵
  • 스마트 작업 관리: 종속성과 우선순위가 포함된 자동화된 작업 분할
  • AI 어시스턴트 통합: Claude, GPT 및 기타 AI 어시스턴트와의 직접 통합
  • 실시간 협업: 복잡한 프로젝트에서의 원활한 인간-AI 협업
  • 진행 상황 추적: 개발 진행 상황 및 차단 요소에 대한 실시간 모니터링

🚀 기능

  • 완전한 프로젝트 통합: 전체 프로젝트 컨텍스트, 계획 및 작업 세부 정보 획득
  • 자율 작업 관리: 작업 시작, 진행 상황 업데이트 및 완료
  • 인간 협업: 질문 및 차단 요소에 대한 토론 생성
  • 실시간 진행 상황 추적: 실시간 업데이트 및 상태 모니터링
  • 타입 안전 API: 포괄적인 타입 정의를 갖춘 완전한 TypeScript 지원
  • Claude Desktop 준비 완료: 원활한 Claude Desktop 통합을 위한 CLI 인터페이스

📦 설치

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?"

🔧 고급 구성

환경 변수

적절한 AI 어시스턴트 추적을 위해 3개의 환경 변수가 권장됩니다:

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: 재시도 간 지연 시간(ms) (기본값: 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('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');

🔗 링크

🏗️ 사용 기술

  • TypeScript - 타입 안전 개발
  • 모델 컨텍스트 프로토콜(MCP) - 표준화된 AI 어시스턴트 통신
  • Node.js - 런타임 환경
  • REST API - 간단하고 안정적인 통신

📄 라이선스

Copyright © 2025 Buildable Team. 모든 권리 보유.

이 소프트웨어는 독점적이며 기밀입니다. 무단 복사, 배포 또는 사용은 엄격히 금지됩니다.

Buildable 팀이 ❤️를 담아 제작

Buildable은 상용 AI 기반 개발 플랫폼입니다. 시작하려면 bldbl.dev를 방문하세요.

🆘 지원

BuildPlanner 팀이 ❤️를 담아 제작