Official MCP client for Buildable - AI-powered development platform that makes any project buildable 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. Buildable (bldbl.dev) is an AI-powered development plat
Add this skill
npx mdskills install chunkydotdev/bldbl-mcpWell-documented MCP server connecting AI assistants to Buildable's task management platform with comprehensive setup guides
1# @bldbl/mcp23**Official MCP client for Buildable - AI-powered development platform that makes any project buildable**45<a href="https://glama.ai/mcp/servers/@chunkydotdev/bldbl-mcp">6 <img width="380" height="200" src="https://glama.ai/mcp/servers/@chunkydotdev/bldbl-mcp/badge" alt="@bldbl/mcp MCP server" />7</a>89[](https://badge.fury.io/js/@bldbl%2Fmcp)10[](https://opensource.org/licenses/MIT)11[](https://smithery.ai/server/@buildable/bldbl-mcp)1213This 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.1415## 🌟 What is Buildable?1617Buildable (bldbl.dev) is an AI-powered development platform that makes any project buildable. It provides:1819- **AI-Generated Build Plans**: Comprehensive project roadmaps with implementation details20- **Smart Task Management**: Automated task breakdown with dependencies and priorities21- **AI Assistant Integration**: Direct integration with Claude, GPT, and other AI assistants22- **Real-time Collaboration**: Seamless human-AI collaboration on complex projects23- **Progress Tracking**: Live monitoring of development progress and blockers2425## 🚀 Features2627- **Full Project Integration**: Get complete project context, plans, and task details28- **Autonomous Task Management**: Start, update progress, and complete tasks29- **Human Collaboration**: Create discussions for questions and blockers30- **Real-time Progress Tracking**: Live updates and status monitoring31- **Type-Safe API**: Full TypeScript support with comprehensive type definitions32- **Claude Desktop Ready**: CLI interface for seamless Claude Desktop integration3334## 📦 Installation3536### Installing via Smithery3738To install @bldbl/mcp for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@buildable/bldbl-mcp):3940```bash41npx -y @smithery/cli install @buildable/bldbl-mcp --client claude42```4344### Manual Installation45```bash46npm install @bldbl/mcp47```4849## 🚀 Quick Start5051### **Step 1: Install the MCP Server**52```bash53npm install -g @bldbl/mcp54```5556### **Step 2: Get Your Buildable API Key**571. Go to [bldbl.dev](https://bldbl.dev) and create an account582. Create or select a project593. Go to **Project Settings** → **AI Assistants** → **Generate API Key**6061### **Step 3: Configure Your AI Assistant**6263#### **🤖 For Claude Desktop:**64Add this to your Claude Desktop config file (`~/.config/claude/claude_desktop_config.json`):6566```json67{68 "mcpServers": {69 "buildable": {70 "command": "npx",71 "args": ["-y", "@bldbl/mcp"],72 "env": {73 "BUILDABLE_API_KEY": "bp_your_api_key_here",74 "BUILDABLE_PROJECT_ID": "your-project-id",75 "BUILDABLE_AI_ASSISTANT_ID": "claude-desktop"76 }77 }78 }79}80```8182*Minimal setup - only API URL is auto-detected.*8384#### **✨ For Cursor AI:**8586**Option 1: One-Click Setup (Recommended)**871. Go to your project on [bldbl.dev](https://bldbl.dev)882. Navigate to **Integrations**893. Click **"Add to Cursor"** - Done! 🎉9091**Option 2: Manual Configuration**92Add this to your Cursor AI config file:9394```json95{96 "mcpServers": {97 "buildable": {98 "command": "npx",99 "args": ["-y", "@bldbl/mcp"],100 "env": {101 "BUILDABLE_API_KEY": "bp_your_api_key_here",102 "BUILDABLE_PROJECT_ID": "your-project-id",103 "BUILDABLE_AI_ASSISTANT_ID": "cursor-ide"104 }105 }106 }107}108```109110*Minimal setup - only API URL is auto-detected.*111112### **Step 4: Start AI-Powered Development!**113114Once configured, your AI assistant has access to these powerful tools:115116- **🏗️ `get_project_context`** - Understand your entire project structure117- **📋 `get_next_task`** - Find what to work on next based on priorities118- **▶️ `start_task`** - Begin working on a specific task119- **📊 `update_progress`** - Report detailed progress updates120- **✅ `complete_task`** - Mark tasks finished with comprehensive notes121- **💬 `create_discussion`** - Ask questions when you need human input122- **🔍 `health_check`** - Verify connection to Buildable123124### **💡 Example AI Conversation:**125126```127You: "What should I work on next in my project?"128129AI: *calls get_project_context & get_next_task*130 "I see you're building a React dashboard app. The next131 high-priority task is 'Implement user authentication'.132 Should I start working on it?"133134You: "Yes, go ahead!"135136AI: *calls start_task*137 "Perfect! I'm starting the authentication task. I'll use138 NextAuth.js with GitHub OAuth. Let me break this down:139 1. Install dependencies140 2. Set up NextAuth config141 3. Create login/logout components142 4. Add protected routes143144 I'll update you on progress as I work!"145146[AI works and calls update_progress periodically]147148AI: *calls update_progress*149 "Progress update: 75% complete! I've implemented:150 ✅ NextAuth.js configuration151 ✅ GitHub OAuth provider setup152 ✅ Login/logout components153 🔄 Currently working on: Protected route middleware154155 Should I continue with the remaining work?"156```157158## 🔧 Advanced Configuration159160### **Environment Variables**1613 environment variables are recommended for proper AI assistant tracking:162163```bash164export BUILDABLE_API_KEY="bp_your_api_key_here" # Your API key (required)165export BUILDABLE_PROJECT_ID="your-project-id" # Target project (required)166export BUILDABLE_AI_ASSISTANT_ID="my-ai-assistant" # AI Assistant ID (recommended)167168# Optional (has smart default):169# export BUILDABLE_API_URL="https://bldbl.dev/api" # API endpoint (default)170```171172**Why AI Assistant ID matters:** This helps you track which AI assistant is doing what work in your project dashboard.173174### **CLI Usage**175You can also run the MCP server directly:176177```bash178# Install globally and use bldbl command179npm install -g @bldbl/mcp180bldbl181182# Or run with npx (no installation needed)183npx @bldbl/mcp184```185186### **Multiple Projects**187To work with multiple Buildable projects, create different MCP server configs:188189```json190{191 "mcpServers": {192 "buildable-frontend": {193 "command": "npx",194 "args": ["-y", "@bldbl/mcp"],195 "env": {196 "BUILDABLE_API_KEY": "bp_frontend_key_here",197 "BUILDABLE_PROJECT_ID": "frontend-project-id",198 "BUILDABLE_AI_ASSISTANT_ID": "claude-frontend"199 }200 },201 "buildable-backend": {202 "command": "npx",203 "args": ["-y", "@bldbl/mcp"],204 "env": {205 "BUILDABLE_API_KEY": "bp_backend_key_here",206 "BUILDABLE_PROJECT_ID": "backend-project-id",207 "BUILDABLE_AI_ASSISTANT_ID": "claude-backend"208 }209 }210 }211}212```213214## 🛠️ API Reference215216### BuildPlannerMCPClient217218The main client class for interacting with Buildable projects.219220#### Constructor221222```typescript223new BuildPlannerMCPClient(config: BuildPlannerConfig, options?: ClientOptions)224```225226**Config Parameters:**227- `apiUrl`: Buildable API URL (defaults to 'https://bldbl.dev/api')228- `apiKey`: Your Buildable API key (starts with 'bp_')229- `projectId`: Target project ID230- `aiAssistantId`: Unique identifier for your AI assistant231- `timeout`: Request timeout in milliseconds (default: 30000)232233**Options:**234- `retryAttempts`: Number of retry attempts (default: 3)235- `retryDelay`: Delay between retries in ms (default: 1000)236237#### Methods238239##### `getProjectContext(): Promise<ProjectContext>`240Get complete project context including plan, tasks, and recent activity.241242##### `getNextTask(): Promise<NextTaskResponse>`243Get the next recommended task to work on based on dependencies and priority.244245##### `startTask(taskId: string, options?: StartTaskOptions): Promise<StartTaskResponse>`246Start working on a specific task with optional approach and timing estimates.247248##### `updateProgress(taskId: string, progress: ProgressUpdate): Promise<ProgressResponse>`249Update progress on the current task with detailed status information.250251##### `completeTask(taskId: string, completion: CompleteTaskRequest): Promise<CompleteTaskResponse>`252Mark a task as completed with detailed completion information.253254##### `createDiscussion(discussion: CreateDiscussionRequest): Promise<DiscussionResponse>`255Create a discussion/question for human input when you need guidance.256257##### `healthCheck(): Promise<{status: string, timestamp: string}>`258Check connectivity and health of the Buildable API.259260##### `disconnect(): Promise<void>`261Properly disconnect and cleanup the client connection.262263## 🔐 Authentication2642651. **Generate API Key**: Go to your Buildable project → AI Assistant tab → Generate API Key2662. **Secure Storage**: Store your API key securely (environment variables recommended)2673. **Key Format**: API keys start with `bp_` followed by project and random identifiers268269## 🐛 Error Handling270271The client includes comprehensive error handling:272273```typescript274try {275 const context = await client.getProjectContext();276} catch (error) {277 if (error.code === 'UNAUTHORIZED') {278 console.error('Invalid or expired API key');279 } else if (error.code === 'PROJECT_NOT_FOUND') {280 console.error('Project not found or access denied');281 } else {282 console.error('API error:', error.message);283 }284}285```286287## 🔄 Development Workflow288289Typical AI assistant workflow with Buildable:2902911. **Initialize** - Connect to Buildable with API key2922. **Get Context** - Understand the project structure and current state2933. **Find Work** - Get the next priority task2944. **Start Task** - Begin working with approach and estimates2955. **Progress Updates** - Regular progress reports with details2966. **Ask Questions** - Create discussions for blockers or decisions2977. **Complete Task** - Finish with comprehensive completion notes2988. **Repeat** - Continue with next tasks299300## 📊 Usage Statistics301302```typescript303// Get usage statistics for your AI assistant304const stats = await client.getUsageStats();305console.log(`Tasks completed: ${stats.tasksCompleted}`);306console.log(`Average completion time: ${stats.avgCompletionTime}min`);307console.log(`Success rate: ${stats.successRate}%`);308```309310## ⚡ CLI Usage311312Once installed, you can use the CLI in several ways:313314```bash315# Run directly with npx (no installation needed)316npx @bldbl/mcp317318# Or install globally and use the bldbl command319npm install -g @bldbl/mcp320bldbl321322# For Claude Desktop, use the bldbl command in your config323```324325**Environment Variables Required:**326- `BUILDABLE_API_URL` - Your Buildable API URL327- `BUILDABLE_API_KEY` - Your API key (starts with 'bp_')328- `BUILDABLE_PROJECT_ID` - Target project ID329- `BUILDABLE_AI_ASSISTANT_ID` - Unique assistant identifier330331## 🧪 Testing332333The package includes comprehensive test utilities:334335```typescript336import { createTestClient } from '@bldbl/mcp/test';337338// Create a test client with mock responses339const testClient = createTestClient({340 mockProject: {341 id: 'test-project',342 title: 'Test Project'343 }344});345346// Use in your tests347await testClient.startTask('test-task-id');348```349350## 🔗 Links351352- **🌐 Homepage**: [bldbl.dev](https://bldbl.dev)353- **📚 Documentation**: [bldbl.dev/docs](https://bldbl.dev/docs)354- **💬 Community**: [Discord](https://discord.gg/buildable)355- **🐛 Support**: [support@bldbl.dev](mailto:support@bldbl.dev)356- **📦 NPM Package**: [npmjs.com/package/@bldbl/mcp](https://www.npmjs.com/package/@bldbl/mcp)357358## 🏗️ Built With359360- **TypeScript** - Type-safe development361- **Model Context Protocol (MCP)** - Standardized AI assistant communication362- **Node.js** - Runtime environment363- **REST API** - Simple and reliable communication364365## 📄 License366367Copyright © 2025 Buildable Team. All rights reserved.368369This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.370371---372373**Made with ❤️ by the Buildable team**374375*Buildable is a commercial AI-powered development platform. Visit [bldbl.dev](https://bldbl.dev) to get started.*376377## 🆘 Support378379- **Documentation**: [https://bldbl.dev/docs](https://bldbl.dev/docs)380- **Email**: [support@bldbl.dev](mailto:support@bldbl.dev)381- **Website**: [https://bldbl.dev](https://bldbl.dev)382383---384385**Built with ❤️ by the BuildPlanner team**
Full transparency — inspect the skill content before installing.