@chunkydotdev/bldbl-mcp/README.md

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

# @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.svg)](https://badge.fury.io/js/@bldbl%2Fmcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
npm install @bldbl/mcp
```

## 🔧 Quick Start

### **Local Development Setup**

For testing with localhost during development:

```typescript
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**

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

const client = createBuildPlannerClient({
  apiUrl: 'https://bldbl.dev',  // Production API
  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

```bash
npm install -g bldbl-mcp-client
```

Or run directly with npx:
```bash
npx bldbl-mcp-client
```

### 2. Configure Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "buildable": {
      "command": "bldbl",
      "args": [],
      "env": {
        "BUILDABLE_API_URL": "https://bldbl.dev/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

```typescript
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)
- `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:

```typescript
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

```typescript
// 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:

```bash
# 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:

```typescript
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](https://bldbl.dev)
- **📚 Documentation**: [bldbl.dev/docs](https://bldbl.dev/docs)
- **💬 Community**: [Discord](https://discord.gg/buildable)
- **🐛 Support**: [support@bldbl.dev](mailto:support@bldbl.dev)
- **📦 NPM Package**: [npmjs.com/package/@bldbl/mcp](https://www.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

## 📈 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/sdk@1.12.1

### 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

## 📄 License

Copyright © 2025 Buildable Team. All rights reserved.

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](https://bldbl.dev) to get started.*

## 🆘 Support

- **Documentation**: [https://bldbl.dev/docs](https://bldbl.dev/docs)
- **Email**: [support@bldbl.dev](mailto:support@bldbl.dev)
- **Website**: [https://bldbl.dev](https://bldbl.dev)

---

**Built with ❤️ by the BuildPlanner team**