bldbl-mcp-client

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.

🌟 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

npm install bldbl-mcp-client

🔧 Quick Start

Local Development Setup

For testing with localhost during development:

import { createBuildPlannerClient } from 'bldbl-mcp-client';

const client = createBuildPlannerClient({
  apiUrl: 'http://localhost:3000/api',  // ← Local development server
  apiKey: 'bp_your_api_key_here',
  projectId: 'your-project-id',
  aiAssistantId: 'local-dev-assistant'
});

// Test connection
try {
  const health = await client.healthCheck();
  console.log('✅ Connected to local Buildable:', health);
  
  // Get project context
  const context = await client.getProjectContext();
  console.log('📋 Project:', context.project.title);
} catch (error) {
  console.error('❌ Connection failed:', error);
}

Production Usage

import { createBuildPlannerClient } from 'bldbl-mcp-client';

const client = createBuildPlannerClient({
  apiUrl: 'https://buildplanner.ai/api',  // or your Buildable instance
  apiKey: 'bp_your_api_key_here',
  projectId: 'your-project-id',
  aiAssistantId: 'my-ai-assistant'
});

// Get project context
const context = await client.getProjectContext();
console.log('Project:', context.project.title);

// Get next task to work on
const nextTask = await client.getNextTask();
if (nextTask.task) {
  console.log('Next task:', nextTask.task.title);
  
  // Start the task
  const started = await client.startTask(nextTask.task.id, {
    approach: 'Test-driven development',
    estimated_duration: 120, // 2 hours
    notes: 'Starting with unit tests'
  });
  
  // Update progress
  await client.updateProgress(nextTask.task.id, {
    progress: 25,
    status_update: 'Completed initial setup and tests',
    completed_steps: ['Set up test environment', 'Created base test files'],
    current_step: 'Implementing core functionality',
    time_spent: 30
  });
  
  // Complete the task
  await client.completeTask(nextTask.task.id, {
    completion_notes: 'Task completed successfully',
    files_modified: ['src/components/Button.tsx', 'tests/Button.test.tsx'],
    testing_completed: true,
    documentation_updated: true,
    time_spent: 120
  });
}

// Create a discussion for human input
await client.createDiscussion({
  topic: 'API Design Question',
  message: 'Should we use REST or GraphQL for this API? I need guidance on the trade-offs.',
  context: {
    current_task_id: nextTask.task?.id,
    urgency: 'medium'
  }
});

🤖 Claude Desktop Integration

Perfect for integrating with Claude Desktop for AI-powered development:

1. Install the Package

npm install -g bldbl-mcp-client

Or run directly with npx:

npx bldbl-mcp-client

2. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "buildable": {
      "command": "bldbl",
      "args": [],
      "env": {
        "BUILDABLE_API_URL": "https://buildplanner.ai/api",
        "BUILDABLE_API_KEY": "bp_your_api_key_here",
        "BUILDABLE_PROJECT_ID": "your-project-id",
        "BUILDABLE_AI_ASSISTANT_ID": "claude-desktop",
        "BUILDABLE_LOG_LEVEL": "info"
      }
    }
  }
}

3. Start Using with Claude

I need to work on my project. Can you get the project context and show me what I should work on next?

Claude will now have access to these tools:

• get_project_context - Get complete project information
• get_next_task - Find the next recommended task
• start_task - Begin working on a task
• update_progress - Track progress with detailed updates
• complete_task - Mark tasks as finished
• create_discussion - Ask questions or raise concerns
• get_connection_status - Check AI assistant connection

🛠️ 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 (e.g., 'https://buildplanner.ai/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)
• enableRealTimeUpdates: Enable real-time event streaming (default: false)
• logLevel: Logging level - 'debug' | 'info' | 'warn' | 'error' (default: 'info')

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

1. Generate API Key: Go to your Buildable project → AI Assistant tab → Generate API Key
2. Secure Storage: Store your API key securely (environment variables recommended)
3. 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:

1. Initialize - Connect to Buildable with API key
2. Get Context - Understand the project structure and current state
3. Find Work - Get the next priority task
4. Start Task - Begin working with approach and estimates
5. Progress Updates - Regular progress reports with details
6. Ask Questions - Create discussions for blockers or decisions
7. Complete Task - Finish with comprehensive completion notes
8. 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-client

# Or install globally and use the bldbl command
npm install -g bldbl-mcp-client
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-client/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: docs.bldbl.dev
• 💬 Community: Discord
• 🐛 Issues: GitHub Issues
• 📦 NPM Package: npmjs.com/package/bldbl-mcp-client

🏗️ Built With

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

📈 Changelog

v1.6.0 (2025-01-11)

• 🚀 MAJOR FIX: Complete rewrite using proper @modelcontextprotocol/sdk
• ✅ Standards Compliant: Now uses official MCP SDK instead of custom JSON-RPC
• 🛠️ Better Tool Definitions: Proper Zod schema validation for all tools
• 🔧 Improved Stability: More reliable MCP protocol implementation
• 📚 Updated Dependencies: Latest @modelcontextprotocol/[email protected]

v1.5.0 (2025-01-11)

• ✨ New Feature: Automatic AI connection tracking
• 🤖 Auto-Connect: MCP client now creates AI connection record on initialization
• 📡 Connection Management: New connect() method for explicit connection management
• 🔗 Integration Ready: Full AI assistant monitoring and status tracking

v1.2.3 (2025-01-10)

• 🐛 Critical Fix: Disabled ALL logging in MCP mode to prevent JSON-RPC pollution
• 🔧 Enhanced: Complete stdout/stderr silence for proper MCP protocol compliance
• ✅ Zero Interference: No console output that could corrupt the JSON-RPC stream

v1.2.2 (2025-01-10)

• 🐛 Fixed: Removed all console output that was polluting JSON-RPC stream
• 🔧 Improved: Better error handling without console interference
• ✅ MCP Compliance: Now fully compliant with JSON-RPC 2.0 protocol

v1.2.1 (2025-01-10)

• 🐛 Fixed: Proper JSON-RPC 2.0 protocol implementation
• 🔧 Improved: MCP standard compliance for tool calls
• ⚡ Enhanced: Better error handling with standard JSON-RPC error codes

v1.2.0

• 🔧 CRITICAL FIX: Proper MCP Protocol: Fixed CLI to use correct JSON-RPC 2.0 format
• ✅ MCP Compatibility: Now properly handles initialize and tools/call methods
• 🐛 Fixed Cursor Integration: Resolves "Unknown tool: undefined" and validation errors
• 📝 Added proper JSON-RPC error codes and responses
• ⚡ Enhanced error handling and protocol compliance

v1.1.0

• 🔄 BREAKING: Updated environment variables to use BUILDABLE_* prefix instead of BUILDPLANNER_*
• 🏷️ New environment variables:
  • BUILDABLE_API_URL (was BUILDPLANNER_API_URL)
  • BUILDABLE_API_KEY (was BUILDPLANNER_API_KEY)
  • BUILDABLE_PROJECT_ID (was BUILDPLANNER_PROJECT_ID)
  • BUILDABLE_AI_ASSISTANT_ID (was BUILDPLANNER_AI_ASSISTANT_ID)
  • BUILDABLE_LOG_LEVEL (was BUILDPLANNER_LOG_LEVEL)
• 📝 Updated all documentation and examples
• 🏗️ Consistent branding with "Buildable" throughout

v1.0.3

• 📚 Enhanced CLI documentation: Added comprehensive usage instructions
• ⚡ Better command examples and environment variable explanations

v1.0.2

• 🔧 Fixed CLI executable: Added bin field to package.json
• ⚡ Now works with npx bldbl-mcp-client and bldbl commands
• 📚 Updated documentation with correct CLI usage

v1.0.1

• 📝 Enhanced README: Comprehensive documentation improvements
• 🏷️ Added npm badges and better structure
• 🌟 Added "What is Buildable" section

v1.0.0

• ✨ Initial release
• 🚀 Full MCP client implementation
• 🤖 Claude Desktop integration
• 📝 Comprehensive TypeScript types
• 🧪 Complete test suite
• 📚 Full documentation

🤝 Contributing

We welcome contributions! Please see our contributing guide for details.

📄 License

MIT License - see LICENSE for details.

Made with ❤️ by the Buildable team

🆘 Support

• Documentation: https://docs.buildplanner.ai
• Issues: GitHub Issues
• Email: [email protected]

Built with ❤️ by the BuildPlanner team