Buildable MCP Server

oficial

Servidor MCP oficial para a plataforma de desenvolvimento com IA Buildable. Permite que assistentes de IA gerenciem tarefas, acompanhem o progresso, obtenham contexto do projeto e colaborem com humanos em projetos de software.

GitHub

Documentação

@bldbl/mcp

Cliente MCP oficial para Buildable - plataforma de desenvolvimento com IA que torna qualquer projeto construível

Este pacote permite que assistentes de IA (Claude, GPT, etc.) trabalhem diretamente com projetos Buildable usando o Model Context Protocol (MCP). Os assistentes de IA podem obter contexto do projeto, gerenciar tarefas, acompanhar o progresso e se comunicar com desenvolvedores humanos.

🌟 O que é Buildable?

Buildable (bldbl.dev) é uma plataforma de desenvolvimento com IA que torna qualquer projeto construível. Ela oferece:

Planos de Construção Gerados por IA: Roteiros abrangentes do projeto com detalhes de implementação
Gerenciamento Inteligente de Tarefas: Divisão automatizada de tarefas com dependências e prioridades
Integração com Assistentes de IA: Integração direta com Claude, GPT e outros assistentes de IA
Colaboração em Tempo Real: Colaboração perfeita entre humanos e IA em projetos complexos
Acompanhamento de Progresso: Monitoramento ao vivo do progresso do desenvolvimento e bloqueios

🚀 Funcionalidades

Integração Completa com o Projeto: Obtenha contexto completo do projeto, planos e detalhes das tarefas
Gerenciamento Autônomo de Tarefas: Inicie, atualize o progresso e conclua tarefas
Colaboração Humana: Crie discussões para perguntas e bloqueios
Acompanhamento de Progresso em Tempo Real: Atualizações ao vivo e monitoramento de status
API com Tipagem Segura: Suporte completo a TypeScript com definições de tipo abrangentes
Pronto para Claude Desktop: Interface CLI para integração perfeita com o Claude Desktop

📦 Instalação

Instalando via Smithery

Para instalar @bldbl/mcp para Claude Desktop automaticamente via Smithery:

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

Instalação Manual

npm install @bldbl/mcp

🚀 Início Rápido

Passo 1: Instale o Servidor MCP

npm install -g @bldbl/mcp

Passo 2: Obtenha sua Chave de API do Buildable

Acesse bldbl.dev e crie uma conta
Crie ou selecione um projeto
Vá para Configurações do Projeto → Assistentes de IA → Gerar Chave de API

Passo 3: Configure seu Assistente de IA

🤖 Para Claude Desktop:

Adicione isto ao seu arquivo de configuração do 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"
      }
    }
  }
}

Configuração mínima - apenas a URL da API é detectada automaticamente.

✨ Para Cursor AI:

Opção 1: Configuração com Um Clique (Recomendado)

Vá para o seu projeto em bldbl.dev
Navegue até Integrações
Clique em "Adicionar ao Cursor" - Pronto! 🎉

Opção 2: Configuração Manual Adicione isto ao seu arquivo de configuração do 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"
      }
    }
  }
}

Configuração mínima - apenas a URL da API é detectada automaticamente.

Passo 4: Comece o Desenvolvimento com IA!

Uma vez configurado, seu assistente de IA tem acesso a estas ferramentas poderosas:

🏗️ get_project_context - Entenda toda a estrutura do seu projeto
📋 get_next_task - Encontre no que trabalhar em seguida com base nas prioridades
▶️ start_task - Comece a trabalhar em uma tarefa específica
📊 update_progress - Relate atualizações detalhadas de progresso
✅ complete_task - Marque tarefas como concluídas com notas abrangentes
💬 create_discussion - Faça perguntas quando precisar de contribuição humana
🔍 health_check - Verifique a conexão com o Buildable

💡 Exemplo de Conversa com 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?"

🔧 Configuração Avançada

Variáveis de Ambiente

3 variáveis de ambiente são recomendadas para o rastreamento adequado do assistente 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 que o ID do Assistente de IA é importante: Isso ajuda você a rastrear qual assistente de IA está fazendo qual trabalho no painel do seu projeto.

Uso da CLI

Você também pode executar o servidor MCP diretamente:

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

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

Múltiplos Projetos

Para trabalhar com múltiplos projetos Buildable, crie diferentes configurações 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"
      }
    }
  }
}

🛠️ Referência da API

BuildPlannerMCPClient

A classe cliente principal para interagir com projetos Buildable.

Construtor

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

Parâmetros de Configuração:

apiUrl: URL da API Buildable (padrão é 'https://bldbl.dev/api')
apiKey: Sua chave de API Buildable (começa com 'bp_')
projectId: ID do projeto alvo
aiAssistantId: Identificador único para seu assistente de IA
timeout: Tempo limite da requisição em milissegundos (padrão: 30000)

Opções:

retryAttempts: Número de tentativas de repetição (padrão: 3)
retryDelay: Atraso entre repetições em ms (padrão: 1000)

Métodos

`getProjectContext(): Promise<ProjectContext>`

Obter contexto completo do projeto, incluindo plano, tarefas e atividade recente.

`getNextTask(): Promise<NextTaskResponse>`

Obter a próxima tarefa recomendada para trabalhar com base em dependências e prioridade.

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

Começar a trabalhar em uma tarefa específica com abordagem opcional e estimativas de tempo.

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

Atualizar o progresso na tarefa atual com informações de status detalhadas.

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

Marcar uma tarefa como concluída com informações detalhadas de conclusão.

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

Criar uma discussão/pergunta para contribuição humana quando você precisar de orientação.

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

Verificar conectividade e saúde da API Buildable.

`disconnect(): Promise<void>`

Desconectar e limpar adequadamente a conexão do cliente.

🔐 Autenticação

Gerar Chave de API: Vá para seu projeto Buildable → aba Assistente de IA → Gerar Chave de API
Armazenamento Seguro: Armazene sua chave de API com segurança (variáveis de ambiente recomendadas)
Formato da Chave: As chaves de API começam com bp_ seguido por identificadores de projeto e aleatórios

🐛 Tratamento de Erros

O cliente inclui tratamento abrangente de erros:

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

🔄 Fluxo de Trabalho de Desenvolvimento

Fluxo de trabalho típico do assistente de IA com Buildable:

Inicializar - Conectar ao Buildable com a chave de API
Obter Contexto - Entender a estrutura do projeto e o estado atual
Encontrar Trabalho - Obter a próxima tarefa prioritária
Iniciar Tarefa - Começar a trabalhar com abordagem e estimativas
Atualizações de Progresso - Relatórios regulares de progresso com detalhes
Fazer Perguntas - Criar discussões para bloqueios ou decisões
Concluir Tarefa - Finalizar com notas abrangentes de conclusão
Repetir - Continuar com as próximas tarefas

📊 Estatí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 da CLI

Uma vez instalado, você pode usar a CLI de várias maneiras:

# 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

Variáveis de Ambiente Necessárias:

BUILDABLE_API_URL - Sua URL da API Buildable
BUILDABLE_API_KEY - Sua chave de API (começa com 'bp_')
BUILDABLE_PROJECT_ID - ID do projeto alvo
BUILDABLE_AI_ASSISTANT_ID - Identificador único do assistente

🧪 Testes

O pacote inclui utilitários de teste abrangentes:

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

🌐 Página Inicial: bldbl.dev
📚 Documentação: bldbl.dev/docs
💬 Comunidade: Discord
🐛 Suporte: [email protected]
📦 Pacote NPM: npmjs.com/package/@bldbl/mcp

🏗️ Construído Com

TypeScript - Desenvolvimento com tipagem segura
Model Context Protocol (MCP) - Comunicação padronizada com assistentes de IA
Node.js - Ambiente de execução
API REST - Comunicação simples e confiável

📄 Licença

Este software é proprietário e confidencial. Cópia, distribuição ou uso não autorizado é estritamente proibido.

Feito com ❤️ pela equipe Buildable

Buildable é uma plataforma comercial de desenvolvimento com IA. Visite bldbl.dev para começar.

🆘 Suporte

Documentação: https://bldbl.dev/docs
Email: [email protected]
Website: https://bldbl.dev

Construído com ❤️ pela equipe BuildPlanner