Buildable MCP Server

oficial

Servidor MCP oficial para la plataforma de desarrollo impulsada por IA Buildable. Permite a los asistentes de IA gestionar tareas, realizar un seguimiento del progreso, obtener contexto del proyecto y colaborar con humanos en proyectos de software.

GitHub

Documentación

@bldbl/mcp

Cliente MCP oficial para Buildable: plataforma de desarrollo impulsada por IA que hace que cualquier proyecto sea construible

Este paquete permite a los asistentes de IA (Claude, GPT, etc.) trabajar directamente con proyectos de Buildable usando el Protocolo de Contexto de Modelo (MCP). Los asistentes de IA pueden obtener el contexto del proyecto, gestionar tareas, seguir el progreso y comunicarse con desarrolladores humanos.

🌟 ¿Qué es Buildable?

Buildable (bldbl.dev) es una plataforma de desarrollo impulsada por IA que hace que cualquier proyecto sea construible. Ofrece:

Planes de construcción generados por IA: Hojas de ruta completas del proyecto con detalles de implementación
Gestión inteligente de tareas: Desglose automatizado de tareas con dependencias y prioridades
Integración con asistentes de IA: Integración directa con Claude, GPT y otros asistentes de IA
Colaboración en tiempo real: Colaboración fluida entre humanos e IA en proyectos complejos
Seguimiento del progreso: Monitoreo en vivo del avance del desarrollo y bloqueos

🚀 Características

Integración completa del proyecto: Obtén el contexto completo del proyecto, planes y detalles de las tareas
Gestión autónoma de tareas: Inicia, actualiza el progreso y completa tareas
Colaboración humana: Crea discusiones para preguntas y bloqueos
Seguimiento del progreso en tiempo real: Actualizaciones en vivo y monitoreo del estado
API con seguridad de tipos: Soporte completo de TypeScript con definiciones de tipos exhaustivas
Listo para Claude Desktop: Interfaz de línea de comandos para una integración perfecta con Claude Desktop

📦 Instalación

Instalación a través de Smithery

Para instalar @bldbl/mcp para Claude Desktop automáticamente a través de Smithery:

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

Instalación manual

npm install @bldbl/mcp

🚀 Inicio rápido

Paso 1: Instalar el servidor MCP

npm install -g @bldbl/mcp

Paso 2: Obtén tu clave API de Buildable

Ve a bldbl.dev y crea una cuenta
Crea o selecciona un proyecto
Ve a Configuración del proyecto → Asistentes de IA → Generar clave API

Paso 3: Configura tu asistente de IA

🤖 Para Claude Desktop:

Añade esto a tu archivo de configuración de Claude Desktop (~/.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"
      }
    }
  }
}

Configuración mínima: solo la URL de la API se detecta automáticamente.

✨ Para Cursor AI:

Opción 1: Configuración en un clic (Recomendado)

Ve a tu proyecto en bldbl.dev
Navega a Integraciones
Haz clic en "Añadir a Cursor" - ¡Listo! 🎉

Opción 2: Configuración manual Añade esto a tu archivo de configuración de Cursor AI:

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

Configuración mínima: solo la URL de la API se detecta automáticamente.

Paso 4: ¡Comienza el desarrollo impulsado por IA!

Una vez configurado, tu asistente de IA tiene acceso a estas potentes herramientas:

🏗️ get_project_context - Comprende toda la estructura de tu proyecto
📋 get_next_task - Encuentra en qué trabajar a continuación según las prioridades
▶️ start_task - Comienza a trabajar en una tarea específica
📊 update_progress - Reporta actualizaciones detalladas del progreso
✅ complete_task - Marca tareas como finalizadas con notas completas
💬 create_discussion - Haz preguntas cuando necesites aportes humanos
🔍 health_check - Verifica la conexión con Buildable

💡 Ejemplo de conversación con IA:

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

🔧 Configuración avanzada

Variables de entorno

Se recomiendan 3 variables de entorno para un seguimiento adecuado del asistente de IA:

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)

Por qué importa el ID del asistente de IA: Esto te ayuda a rastrear qué asistente de IA está haciendo qué trabajo en el panel de tu proyecto.

Uso de CLI

También puedes ejecutar el servidor MCP directamente:

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

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

Múltiples proyectos

Para trabajar con múltiples proyectos de Buildable, crea diferentes configuraciones de servidor MCP:

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

🛠️ Referencia de la API

BuildPlannerMCPClient

La clase cliente principal para interactuar con proyectos de Buildable.

Constructor

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

Parámetros de configuración:

apiUrl: URL de la API de Buildable (por defecto 'https://bldbl.dev/api')
apiKey: Tu clave API de Buildable (comienza con 'bp_')
projectId: ID del proyecto objetivo
aiAssistantId: Identificador único para tu asistente de IA
timeout: Tiempo de espera de solicitud en milisegundos (por defecto: 30000)

Opciones:

retryAttempts: Número de intentos de reintento (por defecto: 3)
retryDelay: Retraso entre reintentos en ms (por defecto: 1000)

Métodos

`getProjectContext(): Promise<ProjectContext>`

Obtén el contexto completo del proyecto, incluyendo el plan, las tareas y la actividad reciente.

`getNextTask(): Promise<NextTaskResponse>`

Obtén la siguiente tarea recomendada para trabajar según las dependencias y la prioridad.

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

Comienza a trabajar en una tarea específica con un enfoque opcional y estimaciones de tiempo.

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

Actualiza el progreso de la tarea actual con información detallada del estado.

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

Marca una tarea como completada con información detallada de finalización.

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

Crea una discusión/pregunta para recibir aportes humanos cuando necesites orientación.

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

Verifica la conectividad y el estado de la API de Buildable.

`disconnect(): Promise<void>`

Desconecta y limpia correctamente la conexión del cliente.

🔐 Autenticación

Generar clave API: Ve a tu proyecto de Buildable → pestaña Asistente de IA → Generar clave API
Almacenamiento seguro: Guarda tu clave API de forma segura (se recomiendan variables de entorno)
Formato de clave: Las claves API comienzan con bp_ seguido de identificadores de proyecto y aleatorios

🐛 Manejo de errores

El cliente incluye un manejo integral de errores:

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

🔄 Flujo de trabajo de desarrollo

Flujo de trabajo típico del asistente de IA con Buildable:

Inicializar - Conectarse a Buildable con la clave API
Obtener contexto - Comprender la estructura del proyecto y el estado actual
Encontrar trabajo - Obtener la siguiente tarea prioritaria
Comenzar tarea - Empezar a trabajar con enfoque y estimaciones
Actualizaciones de progreso - Informes regulares de progreso con detalles
Hacer preguntas - Crear discusiones para bloqueos o decisiones
Completar tarea - Finalizar con notas completas de finalización
Repetir - Continuar con las siguientes tareas

📊 Estadísticas de uso

// 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}%`);

⚡ Uso de CLI

Una vez instalado, puedes usar la CLI de varias maneras:

# 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

Variables de entorno requeridas:

BUILDABLE_API_URL - Tu URL de la API de Buildable
BUILDABLE_API_KEY - Tu clave API (comienza con 'bp_')
BUILDABLE_PROJECT_ID - ID del proyecto objetivo
BUILDABLE_AI_ASSISTANT_ID - Identificador único del asistente

🧪 Pruebas

El paquete incluye utilidades de prueba integrales:

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

🔗 Enlaces

🌐 Página principal: bldbl.dev
📚 Documentación: bldbl.dev/docs
💬 Comunidad: Discord
🐛 Soporte: [email protected]
📦 Paquete NPM: npmjs.com/package/@bldbl/mcp

🏗️ Construido con

TypeScript - Desarrollo con seguridad de tipos
Protocolo de Contexto de Modelo (MCP) - Comunicación estandarizada con asistentes de IA
Node.js - Entorno de ejecución
API REST - Comunicación simple y confiable

📄 Licencia

Este software es propietario y confidencial. La copia, distribución o uso no autorizados están estrictamente prohibidos.

Hecho con ❤️ por el equipo de Buildable

Buildable es una plataforma de desarrollo comercial impulsada por IA. Visita bldbl.dev para comenzar.

🆘 Soporte

Documentación: https://bldbl.dev/docs
Correo electrónico: [email protected]
Sitio web: https://bldbl.dev

Construido con ❤️ por el equipo de BuildPlanner