Skip to main content
Glama

@bldbl/mcp

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

npm version License: 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

Related MCP server: Autodesk Build MCP Server

๐Ÿš€ 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

  1. Go to bldbl.dev and create an account

  2. Create or select a project

  3. 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)

  1. Go to your project on bldbl.dev

  2. Navigate to Integrations

  3. 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

  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

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

๐Ÿ—๏ธ 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

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 to get started.

๐Ÿ†˜ Support


Built with โค๏ธ by the BuildPlanner team

Available Tools

7 tools
complete_taskD
ParametersJSON Schema
NameRequiredDescriptionDefault
completion_notesYesNotes about task completion
documentation_updatedNoWhether documentation was updated
files_modifiedNoList of files that were modified
task_idYesThe ID of the task to complete
testing_completedNoWhether testing was completed
time_spentNoTotal time spent in minutes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_discussionD
ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesDetailed question or discussion content
tagsNoTags to categorize the discussion
titleYesTitle of the discussion/question
urgencyNoUrgency level of the question

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_next_taskD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_project_contextD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

health_checkD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_taskD
ParametersJSON Schema
NameRequiredDescriptionDefault
approachNoOptional approach or strategy for the task
estimated_durationNoEstimated duration in minutes
notesNoOptional notes about the task
task_idYesThe ID of the task to start

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_progressD
ParametersJSON Schema
NameRequiredDescriptionDefault
challengesNoAny challenges or blockers encountered
completed_stepsNoList of completed steps
current_stepNoCurrent step being worked on
files_modifiedNoList of files that were modified
notesNoAdditional notes
progressYesProgress percentage (0-100)
status_updateYesBrief status update message
task_idYesThe ID of the task being updated
time_spentNoTime spent in minutes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv1.0.0
    • First observedcomplete_task
    • First observedcreate_discussion
    • First observedget_next_task
    • First observedget_project_context
    • First observedhealth_check
    • First observedstart_task
    • First observedupdate_progress

TDQS

C2/5.0
Disambiguation4/5

The tools have distinct purposes with minimal overlap: 'complete_task' and 'start_task' are clearly different lifecycle stages, while 'get_next_task', 'get_project_context', and 'update_progress' serve unique informational or update functions. However, 'create_discussion' might be ambiguous in relation to task management, as it could overlap with task-related communication.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case, such as 'complete_task', 'create_discussion', and 'get_next_task'. This uniformity makes the tool set predictable and easy to understand, with no deviations in naming conventions.

Tool Count5/5

With 7 tools, the count is well-scoped for a task or project management server. It covers core operations like starting, completing, and tracking tasks, along with auxiliary functions like health checks and discussions, without being overly sparse or bloated.

Completeness3/5

The tool set covers basic task lifecycle (start, complete, progress update) and project context, but lacks obvious operations like listing tasks, updating task details, or deleting tasks. This creates minor gaps that agents might need to work around, though core workflows are partially supported.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    C
    maintenance
    A Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.
    9
    MIT
  • -
    license
    Not graded
    quality
    Not graded
    maintenance
    A Model Context Protocol server implementation for Autodesk Construction Cloud Build that enables AI assistants to manage construction issues, RFIs, submittals, photos, forms, and costs through natural language.
    -
  • A
    license
    Not graded
    quality
    C
    maintenance
    A comprehensive Model Context Protocol toolkit that transforms AI assistants into autonomous agents capable of executing real-world tasks across filesystems, web requests, Git workflows, databases, system commands, and AI integrations.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/chunkydotdev/bldbl-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server