@bldbl/mcp

Official MCP client for Buildable - AI-powered development platform that makes any project buildable

![npm version](https://badge.fury.io/js/@bldbl%2Fmcp) ![License: MIT](https://opensource.org/licenses/MIT) ![smithery badge](https://smithery.ai/server/@buildable/bldbl-mcp)

This package enables AI assistants (Claude, GPT, etc.) to work directly with Buildable projects using the Model Context Protocol (MCP). AI assistants can get project context, manage tasks, track progress, and communicate with human developers.

🌟 What is Buildable?

Buildable (bldbl.dev) is an AI-powered development platform that makes any project buildable. It provides:

AI-Generated Build Plans: Comprehensive project roadmaps with implementation details
Smart Task Management: Automated task breakdown with dependencies and priorities
AI Assistant Integration: Direct integration with Claude, GPT, and other AI assistants
Real-time Collaboration: Seamless human-AI collaboration on complex projects
Progress Tracking: Live monitoring of development progress and blockers

🚀 Features

Full Project Integration: Get complete project context, plans, and task details
Autonomous Task Management: Start, update progress, and complete tasks
Human Collaboration: Create discussions for questions and blockers
Real-time Progress Tracking: Live updates and status monitoring
Type-Safe API: Full TypeScript support with comprehensive type definitions
Claude Desktop Ready: CLI interface for seamless Claude Desktop integration

📦 Installation

Installing via Smithery

To install @bldbl/mcp for Claude Desktop automatically via Smithery:

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

Manual Installation

npm install @bldbl/mcp

🚀 Quick Start

Step 1: Install the MCP Server

npm install -g @bldbl/mcp

Step 2: Get Your Buildable API Key

Go to bldbl.dev and create an account
Create or select a project
Go to Project Settings → AI Assistants → Generate API Key

Step 3: Configure Your AI Assistant

🤖 For Claude Desktop:

Add this to your Claude Desktop config file (~/.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"
      }
    }
  }
}

Minimal setup - only API URL is auto-detected.

✨ For Cursor AI:

Option 1: One-Click Setup (Recommended)

Go to your project on bldbl.dev
Navigate to Integrations
Click "Add to Cursor" - Done! 🎉

Option 2: Manual Configuration Add this to your Cursor AI config file:

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

Minimal setup - only API URL is auto-detected.

Step 4: Start AI-Powered Development!

Once configured, your AI assistant has access to these powerful tools:

🏗️ get_project_context - Understand your entire project structure
📋 get_next_task - Find what to work on next based on priorities
▶️ start_task - Begin working on a specific task
📊 update_progress - Report detailed progress updates
✅ complete_task - Mark tasks finished with comprehensive notes
💬 create_discussion - Ask questions when you need human input
🔍 health_check - Verify connection to Buildable

💡 Example AI Conversation:

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

🔧 Advanced Configuration

Environment Variables

3 environment variables are recommended for proper AI assistant tracking:

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)

Why AI Assistant ID matters: This helps you track which AI assistant is doing what work in your project dashboard.

CLI Usage

You can also run the MCP server directly:

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

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

Multiple Projects

To work with multiple Buildable projects, create different MCP server configs:

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

BuildPlannerMCPClient

The main client class for interacting with Buildable projects.

Constructor

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

Config Parameters:

apiUrl: Buildable API URL (defaults to 'https://bldbl.dev/api')
apiKey: Your Buildable API key (starts with 'bp_')
projectId: Target project ID
aiAssistantId: Unique identifier for your AI assistant
timeout: Request timeout in milliseconds (default: 30000)

Options:

retryAttempts: Number of retry attempts (default: 3)
retryDelay: Delay between retries in ms (default: 1000)

Methods

`getProjectContext(): Promise<ProjectContext>`

Get complete project context including plan, tasks, and recent activity.

`getNextTask(): Promise<NextTaskResponse>`

Get the next recommended task to work on based on dependencies and priority.

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

Start working on a specific task with optional approach and timing estimates.

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

Update progress on the current task with detailed status information.

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

Mark a task as completed with detailed completion information.

`createDiscussion(discussion: CreateDiscussionRequest): Promise<DiscussionResponse>`

Create a discussion/question for human input when you need guidance.

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

Check connectivity and health of the Buildable API.

`disconnect(): Promise<void>`

Properly disconnect and cleanup the client connection.

🔐 Authentication

Generate API Key: Go to your Buildable project → AI Assistant tab → Generate API Key
Secure Storage: Store your API key securely (environment variables recommended)
Key Format: API keys start with bp_ followed by project and random identifiers

🐛 Error Handling

The client includes comprehensive error handling:

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

🔄 Development Workflow

Typical AI assistant workflow with Buildable:

Initialize - Connect to Buildable with API key
Get Context - Understand the project structure and current state
Find Work - Get the next priority task
Start Task - Begin working with approach and estimates
Progress Updates - Regular progress reports with details
Ask Questions - Create discussions for blockers or decisions
Complete Task - Finish with comprehensive completion notes
Repeat - Continue with next tasks

📊 Usage Statistics

// 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 Usage

Once installed, you can use the CLI in several ways:

# 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

Environment Variables Required:

BUILDABLE_API_URL - Your Buildable API URL
BUILDABLE_API_KEY - Your API key (starts with 'bp_')
BUILDABLE_PROJECT_ID - Target project ID
BUILDABLE_AI_ASSISTANT_ID - Unique assistant identifier

🧪 Testing

The package includes comprehensive test utilities:

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

🔗 Links

🌐 Homepage: bldbl.dev
📚 Documentation: bldbl.dev/docs
💬 Community: Discord
🐛 Support: support@bldbl.dev
📦 NPM Package: npmjs.com/package/@bldbl/mcp

🏗️ Built With

TypeScript - Type-safe development
Model Context Protocol (MCP) - Standardized AI assistant communication
Node.js - Runtime environment
REST API - Simple and reliable communication

📄 License

This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.

---

Made with ❤️ by the Buildable team

Buildable is a commercial AI-powered development platform. Visit bldbl.dev to get started.

🆘 Support

Documentation: https://bldbl.dev/docs
Email: support@bldbl.dev
Website: https://bldbl.dev

---

Built with ❤️ by the BuildPlanner team

bldbl-mcp