Buildable MCP Server

официальный

Official MCP server for Buildable AI-powered development platform. Enables AI assistants to manage tasks, track progress, get project context, and collaborate with humans on software projects.

GitHub

Документация

@bldbl/mcp

Официальный MCP-клиент для Buildable — платформы разработки на базе ИИ, которая делает любой проект реализуемым

Этот пакет позволяет ИИ-ассистентам (Claude, GPT и др.) напрямую работать с проектами Buildable, используя Model Context Protocol (MCP). ИИ-ассистенты могут получать контекст проекта, управлять задачами, отслеживать прогресс и общаться с разработчиками-людьми.

🌟 Что такое Buildable?

Buildable (bldbl.dev) — это платформа разработки на базе ИИ, которая делает любой проект реализуемым. Она предоставляет:

Планы сборки, созданные ИИ: Комплексные дорожные карты проекта с деталями реализации
Умное управление задачами: Автоматическая разбивка задач с зависимостями и приоритетами
Интеграция с ИИ-ассистентами: Прямая интеграция с Claude, GPT и другими ИИ-ассистентами
Совместная работа в реальном времени: Бесшовное сотрудничество человека и ИИ над сложными проектами
Отслеживание прогресса: Живой мониторинг хода разработки и блокирующих факторов

🚀 Возможности

Полная интеграция с проектом: Получение полного контекста проекта, планов и деталей задач
Автономное управление задачами: Запуск, обновление прогресса и завершение задач
Сотрудничество с человеком: Создание обсуждений для вопросов и блокирующих факторов
Отслеживание прогресса в реальном времени: Живые обновления и мониторинг статуса
Типобезопасный API: Полная поддержка TypeScript с исчерпывающими определениями типов
Готовность к Claude Desktop: Интерфейс командной строки для бесшовной интеграции с Claude Desktop

📦 Установка

Установка через Smithery

Чтобы установить @bldbl/mcp для Claude Desktop автоматически через Smithery:

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

Ручная установка

npm install @bldbl/mcp

🚀 Быстрый старт

Шаг 1: Установите MCP-сервер

npm install -g @bldbl/mcp

Шаг 2: Получите ваш API-ключ Buildable

Перейдите на bldbl.dev и создайте аккаунт
Создайте или выберите проект
Перейдите в Настройки проекта → ИИ-ассистенты → Сгенерировать API-ключ

Шаг 3: Настройте вашего ИИ-ассистента

🤖 Для Claude Desktop:

Добавьте это в конфигурационный файл 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"
      }
    }
  }
}

Минимальная настройка — только URL API определяется автоматически.

✨ Для Cursor AI:

Вариант 1: Настройка в один клик (рекомендуется)

Перейдите в ваш проект на bldbl.dev
Перейдите в раздел Интеграции
Нажмите «Добавить в Cursor» — Готово! 🎉

Вариант 2: Ручная настройка Добавьте это в конфигурационный файл 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"
      }
    }
  }
}

Минимальная настройка — только URL API определяется автоматически.

Шаг 4: Начните разработку на базе ИИ!

После настройки ваш ИИ-ассистент получит доступ к этим мощным инструментам:

🏗️ get_project_context — Понять всю структуру вашего проекта
📋 get_next_task — Найти, над чем работать дальше, исходя из приоритетов
▶️ start_task — Начать работу над конкретной задачей
📊 update_progress — Сообщать подробные обновления о прогрессе
✅ complete_task — Отмечать задачи как выполненные с исчерпывающими заметками
💬 create_discussion — Задавать вопросы, когда требуется вклад человека
🔍 health_check — Проверить соединение с Buildable

💡 Пример разговора с ИИ:

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

🔧 Расширенная настройка

Переменные окружения

Для корректного отслеживания ИИ-ассистента рекомендуется использовать 3 переменные окружения:

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)

Почему важен идентификатор ИИ-ассистента: Это помогает отслеживать, какой ИИ-ассистент выполняет какую работу на панели вашего проекта.

Использование CLI

Вы также можете запустить MCP-сервер напрямую:

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

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

Несколько проектов

Для работы с несколькими проектами Buildable создайте разные конфигурации 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"
      }
    }
  }
}

🛠️ Справочник API

BuildPlannerMCPClient

Основной класс клиента для взаимодействия с проектами Buildable.

Конструктор

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

Параметры конфигурации:

apiUrl: URL API Buildable (по умолчанию 'https://bldbl.dev/api')
apiKey: Ваш API-ключ Buildable (начинается с 'bp_')
projectId: Идентификатор целевого проекта
aiAssistantId: Уникальный идентификатор вашего ИИ-ассистента
timeout: Тайм-аут запроса в миллисекундах (по умолчанию: 30000)

Опции:

retryAttempts: Количество попыток повтора (по умолчанию: 3)
retryDelay: Задержка между повторами в мс (по умолчанию: 1000)

Методы

`getProjectContext(): Promise<ProjectContext>`

Получить полный контекст проекта, включая план, задачи и недавнюю активность.

`getNextTask(): Promise<NextTaskResponse>`

Получить следующую рекомендованную задачу для работы на основе зависимостей и приоритета.

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

Начать работу над конкретной задачей с опциональным подходом и оценкой времени.

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

Обновить прогресс по текущей задаче с подробной информацией о статусе.

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

Отметить задачу как выполненную с подробной информацией о завершении.

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

Создать обсуждение/вопрос для получения вклада человека, когда требуется руководство.

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

Проверить связь и работоспособность API Buildable.

`disconnect(): Promise<void>`

Корректно отключиться и очистить соединение клиента.

🔐 Аутентификация

Сгенерируйте API-ключ: Перейдите в ваш проект Buildable → вкладка ИИ-ассистент → Сгенерировать API-ключ
Безопасное хранение: Храните ваш API-ключ безопасно (рекомендуются переменные окружения)
Формат ключа: API-ключи начинаются с bp_, за которым следуют идентификаторы проекта и случайные идентификаторы

🐛 Обработка ошибок

Клиент включает комплексную обработку ошибок:

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

🔄 Рабочий процесс разработки

Типичный рабочий процесс ИИ-ассистента с Buildable:

Инициализация — Подключение к Buildable с помощью API-ключа
Получение контекста — Понимание структуры проекта и текущего состояния
Поиск работы — Получение следующей приоритетной задачи
Запуск задачи — Начало работы с подходом и оценками
Обновления прогресса — Регулярные отчеты о прогрессе с деталями
Вопросы — Создание обсуждений для блокирующих факторов или решений
Завершение задачи — Завершение с исчерпывающими заметками о выполнении
Повтор — Продолжение со следующими задачами

📊 Статистика использования

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

После установки вы можете использовать CLI несколькими способами:

# 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

Необходимые переменные окружения:

BUILDABLE_API_URL — URL вашего API Buildable
BUILDABLE_API_KEY — Ваш API-ключ (начинается с 'bp_')
BUILDABLE_PROJECT_ID — Идентификатор целевого проекта
BUILDABLE_AI_ASSISTANT_ID — Уникальный идентификатор ассистента

🧪 Тестирование

Пакет включает комплексные утилиты для тестирования:

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

🔗 Ссылки

🌐 Домашняя страница: bldbl.dev
📚 Документация: bldbl.dev/docs
💬 Сообщество: Discord
🐛 Поддержка: [email protected]
📦 Пакет NPM: npmjs.com/package/@bldbl/mcp

🏗️ Создано с помощью

TypeScript — Типобезопасная разработка
Model Context Protocol (MCP) — Стандартизированное взаимодействие ИИ-ассистентов
Node.js — Среда выполнения
REST API — Простое и надежное взаимодействие

📄 Лицензия

Это программное обеспечение является собственностью и конфиденциально. Несанкционированное копирование, распространение или использование строго запрещено.

Сделано с ❤️ командой Buildable

Buildable — это коммерческая платформа разработки на базе ИИ. Посетите bldbl.dev, чтобы начать.

🆘 Поддержка

Документация: https://bldbl.dev/docs
Email: [email protected]
Веб-сайт: https://bldbl.dev

Создано с ❤️ командой BuildPlanner