Buildable

@bldbl/mcp

Offizieller MCP-Client für Buildable – KI-gestützte Entwicklungsplattform, die jedes Projekt baubar macht

Dieses Paket ermöglicht KI-Assistenten (Claude, GPT usw.), mit dem Model Context Protocol (MCP) direkt mit Buildable-Projekten zu arbeiten. KI-Assistenten können Projektkontext abrufen, Aufgaben verwalten, den Fortschritt verfolgen und mit menschlichen Entwicklern kommunizieren.

🌟 Was ist Buildable?

Buildable (bldbl.dev) ist eine KI-gestützte Entwicklungsplattform, die jedes Projekt baubar macht. Sie bietet:

• KI-generierte Baupläne: Umfassende Projekt-Roadmaps mit Implementierungsdetails
• Intelligente Aufgabenverwaltung: Automatisierte Aufgabenaufteilung mit Abhängigkeiten und Prioritäten
• KI-Assistenten-Integration: Direkte Integration mit Claude, GPT und anderen KI-Assistenten
• Echtzeit-Zusammenarbeit: Nahtlose Mensch-KI-Zusammenarbeit an komplexen Projekten
• Fortschrittsverfolgung: Live-Überwachung des Entwicklungsfortschritts und von Blockern

🚀 Funktionen

• Vollständige Projektintegration: Vollständigen Projektkontext, Pläne und Aufgabendetails abrufen
• Autonome Aufgabenverwaltung: Aufgaben starten, Fortschritt aktualisieren und abschließen
• Menschliche Zusammenarbeit: Diskussionen für Fragen und Blocker erstellen
• Echtzeit-Fortschrittsverfolgung: Live-Updates und Statusüberwachung
• Typsichere API: Vollständige TypeScript-Unterstützung mit umfassenden Typdefinitionen
• Claude-Desktop-bereit: CLI-Schnittstelle für nahtlose Claude-Desktop-Integration

📦 Installation

Installation über Smithery

Um @bldbl/mcp automatisch für Claude Desktop über Smithery zu installieren:

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

Manuelle Installation

npm install @bldbl/mcp

🚀 Schnellstart

Schritt 1: MCP-Server installieren

npm install -g @bldbl/mcp

Schritt 2: Buildable-API-Schlüssel besorgen

1. Gehen Sie zu bldbl.dev und erstellen Sie ein Konto
2. Erstellen oder wählen Sie ein Projekt aus
3. Gehen Sie zu Projekteinstellungen → KI-Assistenten → API-Schlüssel generieren

Schritt 3: KI-Assistenten konfigurieren

🤖 Für Claude Desktop:

Fügen Sie dies zu Ihrer Claude-Desktop-Konfigurationsdatei hinzu (~/.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"
      }
    }
  }
}

Minimale Einrichtung – nur die API-URL wird automatisch erkannt.

✨ Für Cursor AI:

Option 1: Ein-Klick-Einrichtung (empfohlen)

1. Gehen Sie zu Ihrem Projekt auf bldbl.dev
2. Navigieren Sie zu Integrationen
3. Klicken Sie auf "Zu Cursor hinzufügen" – Fertig! 🎉

Option 2: Manuelle Konfiguration Fügen Sie dies zu Ihrer Cursor-AI-Konfigurationsdatei hinzu:

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

Minimale Einrichtung – nur die API-URL wird automatisch erkannt.

Schritt 4: KI-gestützte Entwicklung starten!

Sobald die Konfiguration abgeschlossen ist, hat Ihr KI-Assistent Zugriff auf diese leistungsstarken Werkzeuge:

• 🏗️ get_project_context – Gesamte Projektstruktur verstehen
• 📋 get_next_task – Nächste Aufgabe basierend auf Prioritäten finden
• ▶️ start_task – Mit einer bestimmten Aufgabe beginnen
• 📊 update_progress – Detaillierte Fortschrittsaktualisierungen melden
• ✅ complete_task – Aufgaben mit umfassenden Notizen als erledigt markieren
• 💬 create_discussion – Fragen stellen, wenn menschliche Eingabe benötigt wird
• 🔍 health_check – Verbindung zu Buildable überprüfen

💡 Beispiel-KI-Konversation:

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

🔧 Erweiterte Konfiguration

Umgebungsvariablen

3 Umgebungsvariablen werden für eine ordnungsgemäße KI-Assistenten-Verfolgung empfohlen:

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)

Warum die KI-Assistenten-ID wichtig ist: Damit können Sie in Ihrem Projekt-Dashboard nachverfolgen, welcher KI-Assistent welche Arbeit erledigt.

CLI-Nutzung

Sie können den MCP-Server auch direkt ausführen:

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

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

Mehrere Projekte

Um mit mehreren Buildable-Projekten zu arbeiten, erstellen Sie verschiedene MCP-Server-Konfigurationen:

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

BuildPlannerMCPClient

Die Hauptclient-Klasse für die Interaktion mit Buildable-Projekten.

Konstruktor

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

Konfigurationsparameter:

• apiUrl: Buildable-API-URL (Standard: 'https://bldbl.dev/api')
• apiKey: Ihr Buildable-API-Schlüssel (beginnt mit 'bp_')
• projectId: Zielprojekt-ID
• aiAssistantId: Eindeutige Kennung für Ihren KI-Assistenten
• timeout: Anforderungs-Timeout in Millisekunden (Standard: 30000)

Optionen:

• retryAttempts: Anzahl der Wiederholungsversuche (Standard: 3)
• retryDelay: Verzögerung zwischen Wiederholungen in ms (Standard: 1000)

Methoden

getProjectContext(): Promise<ProjectContext>

Vollständigen Projektkontext einschließlich Plan, Aufgaben und letzter Aktivität abrufen.

getNextTask(): Promise<NextTaskResponse>

Nächste empfohlene Aufgabe basierend auf Abhängigkeiten und Priorität abrufen.

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

Mit einer bestimmten Aufgabe beginnen, mit optionalen Ansatz- und Zeitschätzungen.

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

Fortschritt der aktuellen Aufgabe mit detaillierten Statusinformationen aktualisieren.

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

Aufgabe mit detaillierten Abschlussinformationen als erledigt markieren.

createDiscussion(discussion: CreateDiscussionRequest): Promise<DiscussionResponse>

Diskussion/Frage für menschliche Eingabe erstellen, wenn Sie Anleitung benötigen.

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

Konnektivität und Zustand der Buildable-API überprüfen.

disconnect(): Promise<void>

Client-Verbindung ordnungsgemäß trennen und bereinigen.

🔐 Authentifizierung

1. API-Schlüssel generieren: Gehen Sie zu Ihrem Buildable-Projekt → KI-Assistenten-Tab → API-Schlüssel generieren
2. Sichere Speicherung: Bewahren Sie Ihren API-Schlüssel sicher auf (Umgebungsvariablen empfohlen)
3. Schlüsselformat: API-Schlüssel beginnen mit bp_, gefolgt von Projekt- und Zufallskennungen

🐛 Fehlerbehandlung

Der Client enthält umfassende Fehlerbehandlung:

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

🔄 Entwicklungsworkflow

Typischer KI-Assistenten-Workflow mit Buildable:

1. Initialisieren – Mit API-Schlüssel mit Buildable verbinden
2. Kontext abrufen – Projektstruktur und aktuellen Zustand verstehen
3. Arbeit finden – Nächste priorisierte Aufgabe abrufen
4. Aufgabe starten – Mit Ansatz und Schätzungen beginnen
5. Fortschrittsaktualisierungen – Regelmäßige Fortschrittsberichte mit Details
6. Fragen stellen – Diskussionen für Blocker oder Entscheidungen erstellen
7. Aufgabe abschließen – Mit umfassenden Abschlussnotizen beenden
8. Wiederholen – Mit nächsten Aufgaben fortfahren

📊 Nutzungsstatistiken

// 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-Nutzung

Nach der Installation können Sie die CLI auf verschiedene Arten nutzen:

# 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

Erforderliche Umgebungsvariablen:

• BUILDABLE_API_URL – Ihre Buildable-API-URL
• BUILDABLE_API_KEY – Ihr API-Schlüssel (beginnt mit 'bp_')
• BUILDABLE_PROJECT_ID – Zielprojekt-ID
• BUILDABLE_AI_ASSISTANT_ID – Eindeutige Assistentenkennung

🧪 Tests

Das Paket enthält umfassende Test-Dienstprogramme:

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

🔗 Links

• 🌐 Homepage: bldbl.dev
• 📚 Dokumentation: bldbl.dev/docs
• 💬 Community: Discord
• 🐛 Support: support@bldbl.dev
• 📦 NPM-Paket: npmjs.com/package/@bldbl/mcp

🏗️ Erstellt mit

• TypeScript – Typsichere Entwicklung
• Model Context Protocol (MCP) – Standardisierte KI-Assistenten-Kommunikation
• Node.js – Laufzeitumgebung
• REST-API – Einfache und zuverlässige Kommunikation

📄 Lizenz

Copyright © 2025 Buildable Team. Alle Rechte vorbehalten.

Diese Software ist proprietär und vertraulich. Unbefugtes Kopieren, Verteilen oder Verwenden ist strengstens untersagt.

---

Mit ❤️ vom Buildable-Team erstellt

Buildable ist eine kommerzielle KI-gestützte Entwicklungsplattform. Besuchen Sie bldbl.dev, um loszulegen.

🆘 Support

• Dokumentation: https://bldbl.dev/docs
• E-Mail: support@bldbl.dev
• Website: https://bldbl.dev

---

Mit ❤️ vom BuildPlanner-Team erstellt