Buildable MCP Server

officiel

Serveur MCP officiel pour la plateforme de développement alimentée par l'IA Buildable. Permet aux assistants IA de gérer des tâches, suivre l'avancement, obtenir le contexte du projet et collaborer avec des humains sur des projets logiciels.

GitHub

Documentation

@bldbl/mcp

Client MCP officiel pour Buildable - Plateforme de développement propulsée par l'IA qui rend tout projet constructible

Ce package permet aux assistants IA (Claude, GPT, etc.) de travailler directement avec les projets Buildable en utilisant le Model Context Protocol (MCP). Les assistants IA peuvent obtenir le contexte du projet, gérer les tâches, suivre la progression et communiquer avec les développeurs humains.

🌟 Qu'est-ce que Buildable ?

Buildable (bldbl.dev) est une plateforme de développement propulsée par l'IA qui rend tout projet constructible. Elle offre :

Plans de construction générés par l'IA : Feuilles de route complètes du projet avec détails d'implémentation
Gestion intelligente des tâches : Décomposition automatisée des tâches avec dépendances et priorités
Intégration d'assistants IA : Intégration directe avec Claude, GPT et d'autres assistants IA
Collaboration en temps réel : Collaboration humain-IA transparente sur des projets complexes
Suivi de progression : Surveillance en direct de l'avancement du développement et des blocages

🚀 Fonctionnalités

Intégration complète du projet : Obtenez le contexte complet du projet, les plans et les détails des tâches
Gestion autonome des tâches : Démarrez, mettez à jour la progression et terminez les tâches
Collaboration humaine : Créez des discussions pour les questions et les blocages
Suivi de progression en temps réel : Mises à jour en direct et surveillance du statut
API sécurisée par typage : Support TypeScript complet avec définitions de types exhaustives
Prêt pour Claude Desktop : Interface CLI pour une intégration transparente avec Claude Desktop

📦 Installation

Installation via Smithery

Pour installer @bldbl/mcp pour Claude Desktop automatiquement via Smithery :

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

Installation manuelle

npm install @bldbl/mcp

🚀 Démarrage rapide

Étape 1 : Installer le serveur MCP

npm install -g @bldbl/mcp

Étape 2 : Obtenir votre clé API Buildable

Allez sur bldbl.dev et créez un compte
Créez ou sélectionnez un projet
Allez dans Paramètres du projet → Assistants IA → Générer une clé API

Étape 3 : Configurer votre assistant IA

🤖 Pour Claude Desktop :

Ajoutez ceci à votre fichier de configuration 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"
      }
    }
  }
}

Configuration minimale - seule l'URL de l'API est détectée automatiquement.

✨ Pour Cursor AI :

Option 1 : Configuration en un clic (Recommandée)

Allez sur votre projet sur bldbl.dev
Naviguez vers Intégrations
Cliquez sur "Ajouter à Cursor" - Terminé ! 🎉

Option 2 : Configuration manuelle Ajoutez ceci à votre fichier de configuration 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"
      }
    }
  }
}

Configuration minimale - seule l'URL de l'API est détectée automatiquement.

Étape 4 : Lancez le développement propulsé par l'IA !

Une fois configuré, votre assistant IA a accès à ces outils puissants :

🏗️ get_project_context - Comprendre toute la structure de votre projet
📋 get_next_task - Trouver sur quoi travailler ensuite selon les priorités
▶️ start_task - Commencer à travailler sur une tâche spécifique
📊 update_progress - Rapporter des mises à jour de progression détaillées
✅ complete_task - Marquer les tâches comme terminées avec des notes complètes
💬 create_discussion - Poser des questions lorsque vous avez besoin d'une intervention humaine
🔍 health_check - Vérifier la connexion à Buildable

💡 Exemple de conversation 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?"

🔧 Configuration avancée

Variables d'environnement

3 variables d'environnement sont recommandées pour un suivi correct de l'assistant 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)

Pourquoi l'ID de l'assistant IA est important : Cela vous aide à suivre quel assistant IA fait quel travail dans le tableau de bord de votre projet.

Utilisation en CLI

Vous pouvez également exécuter le serveur MCP directement :

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

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

Projets multiples

Pour travailler avec plusieurs projets Buildable, créez différentes configurations de serveur 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"
      }
    }
  }
}

🛠️ Référence API

BuildPlannerMCPClient

La classe cliente principale pour interagir avec les projets Buildable.

Constructeur

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

Paramètres de configuration :

apiUrl : URL de l'API Buildable (par défaut 'https://bldbl.dev/api')
apiKey : Votre clé API Buildable (commence par 'bp_')
projectId : ID du projet cible
aiAssistantId : Identifiant unique pour votre assistant IA
timeout : Délai d'expiration de la requête en millisecondes (par défaut : 30000)

Options :

retryAttempts : Nombre de tentatives de réessai (par défaut : 3)
retryDelay : Délai entre les réessais en ms (par défaut : 1000)

Méthodes

`getProjectContext(): Promise<ProjectContext>`

Obtenir le contexte complet du projet incluant le plan, les tâches et l'activité récente.

`getNextTask(): Promise<NextTaskResponse>`

Obtenir la prochaine tâche recommandée sur laquelle travailler en fonction des dépendances et de la priorité.

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

Commencer à travailler sur une tâche spécifique avec une approche et des estimations de temps optionnelles.

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

Mettre à jour la progression de la tâche en cours avec des informations de statut détaillées.

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

Marquer une tâche comme terminée avec des informations de complétion détaillées.

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

Créer une discussion/question pour une intervention humaine lorsque vous avez besoin de conseils.

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

Vérifier la connectivité et la santé de l'API Buildable.

`disconnect(): Promise<void>`

Se déconnecter proprement et nettoyer la connexion cliente.

🔐 Authentification

Générer une clé API : Allez dans votre projet Buildable → onglet Assistant IA → Générer une clé API
Stockage sécurisé : Stockez votre clé API en toute sécurité (variables d'environnement recommandées)
Format de la clé : Les clés API commencent par bp_ suivi d'identifiants de projet et aléatoires

🐛 Gestion des erreurs

Le client inclut une gestion complète des erreurs :

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

🔄 Flux de travail de développement

Flux de travail typique d'un assistant IA avec Buildable :

Initialiser - Se connecter à Buildable avec la clé API
Obtenir le contexte - Comprendre la structure du projet et l'état actuel
Trouver du travail - Obtenir la prochaine tâche prioritaire
Démarrer la tâche - Commencer à travailler avec une approche et des estimations
Mises à jour de progression - Rapports de progression réguliers avec détails
Poser des questions - Créer des discussions pour les blocages ou les décisions
Terminer la tâche - Finir avec des notes de complétion complètes
Répéter - Continuer avec les tâches suivantes

📊 Statistiques d'utilisation

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

⚡ Utilisation en CLI

Une fois installé, vous pouvez utiliser la CLI de plusieurs façons :

# 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 d'environnement requises :

BUILDABLE_API_URL - Votre URL d'API Buildable
BUILDABLE_API_KEY - Votre clé API (commence par 'bp_')
BUILDABLE_PROJECT_ID - ID du projet cible
BUILDABLE_AI_ASSISTANT_ID - Identifiant unique de l'assistant

🧪 Tests

Le package inclut des utilitaires de test complets :

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

🔗 Liens

🌐 Page d'accueil : bldbl.dev
📚 Documentation : bldbl.dev/docs
💬 Communauté : Discord
🐛 Support : [email protected]
📦 Package NPM : npmjs.com/package/@bldbl/mcp

🏗️ Construit avec

TypeScript - Développement sécurisé par typage
Model Context Protocol (MCP) - Communication standardisée des assistants IA
Node.js - Environnement d'exécution
API REST - Communication simple et fiable

📄 Licence

Ce logiciel est propriétaire et confidentiel. La copie, la distribution ou l'utilisation non autorisée est strictement interdite.

Fait avec ❤️ par l'équipe Buildable

Buildable est une plateforme de développement commerciale propulsée par l'IA. Visitez bldbl.dev pour commencer.

🆘 Support

Documentation : https://bldbl.dev/docs
Email : [email protected]
Site web : https://bldbl.dev

Construit avec ❤️ par l'équipe BuildPlanner