Vibe Coder

Um servidor MCP avançado para roteamento semântico, geração de código, fluxos de trabalho e desenvolvimento assistido por IA.

GitHub
103
Experimente este MCPPatrocinado

Documentação

Vibe Coder MCP Server

npm version npm downloads npm total downloads GitHub release Node.js Version License GitHub stars

O Vibe Coder é um servidor MCP (Model Context Protocol) projetado para turbinar seu assistente de IA (como Cursor, Cline AI ou Claude Desktop) com ferramentas poderosas para desenvolvimento de software. Ele ajuda com pesquisa, planejamento, geração de requisitos, criação de projetos iniciais e muito mais!

🆕 Novidades na Versão 0.3.5

🎉 Última Versão - CLI Aprimorado, REPL e Extração de Parâmetros

Principais Melhorias:

  • ✨ Revisão Completa do Hybrid Matcher: Todas as 15 ferramentas MCP agora possuem extração abrangente de parâmetros
  • 🚀 Experiência CLI/REPL: Confirmações interativas, verificação de status de tarefas com progresso visual
  • 🔧 Correção de Bugs Críticos: O task-list-generator gera automaticamente histórias de usuário, conversas de múltiplas etapas funcionam perfeitamente
  • 📊 Melhor Correspondência de Ferramentas: Abordagem multi-estratégia (palavras-chave 35%, padrões 30%, semântica 15%, LLM 20%)
  • ⚡ Modo Estrito TypeScript: Zero tipos any, toda tipagem explícita, qualidade de código de nível de produção

Melhorias na Experiência do Usuário:

  • Correspondências de baixa confiança agora solicitam confirmação do usuário
  • Indicadores visuais de progresso para tarefas de longa duração
  • Saída mais limpa com filtragem de logs JSON no modo interativo
  • Persistência de sessão entre comandos
  • Mensagens de erro aprimoradas e feedback de validação

Versões Anteriores Notáveis

Versão 0.3.1 - Instalação Global e Sincronização

  • Corrigidos problemas de sincronização de versão global/local
  • Processo de build limpo aprimorado para instalações
  • Fluxo de empacotamento melhorado para publicação no NPM

Versão 0.2.8 - Modo Interativo do CLI

  • Corrigida a persistência de configuração no modo interativo
  • Detecção aprimorada da raiz do projeto para usuários do CLI
  • Configuração sensível ao contexto melhorada

Versão 0.2.3 - REPL Interativo e Assistente de Configuração

  • Modo REPL Interativo com interface estilo chat e persistência de sessão
  • Assistente de Configuração Aprimorado com detecção automática de primeira execução
  • Modelos de Configuração em src/config-templates/
  • Melhorias de Desempenho com uso otimizado de memória
  • Binário CLI Unificado - comando único vibe para todas as operações

🚀 Início Rápido

# Install globally (recommended)
npm install -g vibe-coder-mcp@latest

# Run setup wizard on first use
vibe --setup

# Or use instantly with npx (no installation)
npx vibe-coder-mcp@latest --setup

O assistente de configuração irá:

  1. ✅ Configurar sua chave de API do OpenRouter
  2. ✅ Configurar diretórios do projeto
  3. ✅ Criar arquivos de configuração a partir de modelos
  4. ✅ Validar seu ambiente
  5. ✅ Deixá-lo pronto para usar todos os recursos!

📦 Instalação

npm version npm downloads

# Recommended: Install globally for the 'vibe' command
npm install -g vibe-coder-mcp@latest

# Or run instantly without installation
npx vibe-coder-mcp@latest

Métodos de Instalação

Instalação Global (Recomendada)

npm install -g vibe-coder-mcp@latest

# Use the 'vibe' command anywhere
vibe                                    # Start MCP server
vibe "create a PRD for a todo app"     # CLI mode
vibe --interactive                     # Interactive REPL mode
vibe --setup                           # Setup wizard

Execução Rápida com npx

# No installation needed
npx vibe-coder-mcp@latest
npx vibe-coder-mcp@latest "research React best practices"

Instalação Local no Projeto

npm install vibe-coder-mcp
npx vibe-coder-mcp "map the codebase structure"

Uso pela Linha de Comando

# MCP Server Mode (for Claude Desktop, Cursor, etc.)
vibe                                    # Start with stdio transport
vibe --sse                             # Start with Server-Sent Events

# CLI Mode - Natural Language Commands
vibe "research modern JavaScript frameworks"
vibe "create a PRD for an e-commerce platform"
vibe "map the codebase structure" --json
vibe "generate user stories for auth system"

# Interactive REPL Mode
vibe --interactive                     # Chat interface with context retention

# Configuration
vibe --setup                           # Run setup wizard
vibe --help                            # Show all options
vibe --version                         # Show version

Recursos do Modo Interativo:

  • Conversa estilo chat com retenção de contexto
  • Execução de ferramentas ao vivo com indicadores de progresso
  • Persistência de sessão e histórico
  • Suporte a renderização de Markdown
  • Múltiplos temas e personalização
  • Comandos de barra para ações rápidas

🎯 Integração com Clientes MCP (Claude Desktop, Cursor, Cline AI)

Guia Rápido de Integração

O Vibe-Coder MCP integra-se perfeitamente com qualquer cliente compatível com MCP. Veja como configurá-lo:

Opção 1: Usando NPX (Recomendada)

No diálogo de configuração do servidor do seu cliente MCP:

  • Nome do Servidor: vibe-coder-mcp
  • Comando/URL: npx
  • Argumentos: vibe-coder-mcp
  • Variáveis de Ambiente:
    • OPENROUTER_API_KEY: Sua chave de API do OpenRouter (obrigatória)
    • VIBE_PROJECT_ROOT: /path/to/your/project (obrigatória)
    • LOG_LEVEL: info (opcional)
    • NODE_ENV: production (opcional)

Opção 2: Instalação Global

# First install globally
npm install -g vibe-coder-mcp

Em seguida, configure:

  • Comando/URL: vibe
  • Argumentos: (deixe vazio)
  • Variáveis de Ambiente: As mesmas da Opção 1

Opção 3: Node com Caminho Completo

  • Comando/URL: node
  • Argumentos: /path/to/node_modules/vibe-coder-mcp/build/index.js
  • Variáveis de Ambiente: As mesmas da Opção 1

Configuração Específica para Claude Desktop

Para usuários do Claude Desktop, adicione isto ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "vibe-coder-mcp": {
      "command": "npx",
      "args": ["vibe-coder-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key",
        "VIBE_PROJECT_ROOT": "/path/to/your/project",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Veja example_claude_desktop_config.json para um exemplo completo.

Ferramentas Disponíveis Após a Integração

Após a configuração, seu cliente MCP terá acesso a:

  • vibe-task-manager: Gerenciamento de tarefas nativo de IA com metodologia RDD
  • research-manager: Pesquisa aprofundada usando integração com Perplexity
  • map-codebase: Análise avançada de base de código (35+ linguagens)
  • curate-context: Curadoria inteligente de contexto para desenvolvimento com IA
  • generate-prd: Gerador de documento de requisitos de produto
  • generate-user-stories: Gerador de histórias de usuário
  • generate-task-list: Gerador de lista de tarefas
  • generate-fullstack-starter-kit: Ferramenta de scaffolding de projetos
  • run-workflow: Execução de fluxos de trabalho em múltiplas etapas

Testando Sua Integração

Após a configuração, teste perguntando ao seu assistente de IA:

  • "Use o vibe para pesquisar as melhores práticas do React"
  • "Mapeie a base de código deste projeto"
  • "Gere um PRD para um aplicativo de gerenciamento de tarefas"

🆕 Configuração Unificada da Raiz do Projeto

Configuração Zero para Usuários do CLI

# Automatic project detection - just run from your project!
cd /path/to/your/project
vibe "map the codebase structure"

Configuração Simples para Clientes MCP

{
  "env": {
    "OPENROUTER_API_KEY": "your_key_here",
    "VIBE_PROJECT_ROOT": "/path/to/your/project"
  }
}
  • Uma Variável: VIBE_PROJECT_ROOT substitui múltiplas configurações de diretório
  • Detecção Automática: O CLI detecta automaticamente a raiz do projeto
  • Compatível com Versões Anteriores: Variáveis legadas ainda são suportadas

🔧 Configuração de Ambiente

Obrigatório: Você precisa de uma chave de API do OpenRouter para usar o Vibe Coder MCP.

Obtenha Sua Chave de API do OpenRouter

  1. Visite openrouter.ai
  2. Crie uma conta se você não tiver uma
  3. Navegue até a seção de Chaves de API
  4. Crie uma nova chave de API e copie-a

Configure as Variáveis de Ambiente

Opção 1: Usando o Assistente de Configuração (Recomendado para v0.2.3+)

# Run the interactive setup wizard
vibe --setup

# The wizard will:
# • Configure your OpenRouter API key
# • Set up project directories
# • Create configuration files
# • Validate your setup

Opção 2: Variáveis de Ambiente

# Set your OpenRouter API key
export OPENROUTER_API_KEY="your_api_key_here"

# Optional: Set custom directories
export VIBE_CODER_OUTPUT_DIR="/path/to/output/directory"
export VIBE_PROJECT_ROOT="/path/to/your/project"

# Legacy variables (still supported for backward compatibility)
export CODE_MAP_ALLOWED_DIR="/path/to/your/source/code"
export VIBE_TASK_MANAGER_READ_DIR="/path/to/your/project"

Opção 3: Crie um arquivo .env (modelos fornecidos na v0.2.3+) Crie um arquivo .env no seu diretório de trabalho (ou copie de src/config-templates/.env.template):

# Required: Your OpenRouter API key
OPENROUTER_API_KEY="your_api_key_here"

# Optional: Unified project root configuration
VIBE_CODER_OUTPUT_DIR="/path/to/output/directory"
VIBE_PROJECT_ROOT="/path/to/your/project"
VIBE_USE_PROJECT_ROOT_AUTO_DETECTION="true"

# Legacy variables (still supported for backward compatibility)
CODE_MAP_ALLOWED_DIR="/path/to/your/source/code"  
VIBE_TASK_MANAGER_READ_DIR="/path/to/your/project"

# Optional: Other settings
OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
GEMINI_MODEL="google/gemini-2.5-flash-preview-05-20"

Configuração de Diretórios (Unificada e Simplificada)

🆕 Configuração Unificada (Recomendada)

  • VIBE_PROJECT_ROOT: Variável única para todas as operações do projeto (detecção automática habilitada por padrão para CLI)
  • VIBE_USE_PROJECT_ROOT_AUTO_DETECTION: Habilita a detecção automática da raiz do projeto para usuários do CLI (padrão: "true")
  • VIBE_CODER_OUTPUT_DIR: Onde os arquivos gerados são salvos (padrão: ./VibeCoderOutput/)

Configuração Legada (Ainda Suportada)

  • CODE_MAP_ALLOWED_DIR: Limite de segurança para análise de código (fallback se VIBE_PROJECT_ROOT não estiver definido)
  • VIBE_TASK_MANAGER_READ_DIR: Limite de segurança para operações do gerenciador de tarefas (fallback se VIBE_PROJECT_ROOT não estiver definido)

Benefícios da Detecção Automática:

  • Configuração Zero: Usuários do CLI obtêm detecção automática da raiz do projeto
  • Sensível ao Contexto: Comportamento diferente para uso via CLI vs cliente MCP
  • Fallbacks Inteligentes: Cadeia de resolução com 5 prioridades garante operação confiável

🔌 Configuração do Cliente MCP

Configure seu assistente de IA para conectar-se ao Vibe Coder MCP:

Para Clientes MCP Cursor AI / Windsurf / VS Code

Adicione isto às suas configurações MCP (geralmente em settings.json):

{
  "mcpServers": {
    "vibe-coder-mcp": {
      "command": "npx",
      "args": ["vibe-coder-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Para Claude Desktop

Adicione isto ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "vibe-coder-mcp": {
      "command": "npx",
      "args": ["vibe-coder-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here",
        "VIBE_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

💻 Guia de Uso do CLI

O Vibe Coder inclui uma interface de linha de comando poderosa com múltiplos modos para interação direta com todas as ferramentas.

Assistente de Configuração Interativo (Aprimorado na v0.2.3)

# First-time setup (runs automatically on first use)
vibe --setup

# Features:
# • Smart first-run detection
# • OS-specific configuration paths
# • Non-interactive mode for CI/CD
# • Configuration validation
# • Backup system for existing configs

# Reconfigure existing installation
vibe --reconfigure

Modo REPL Interativo (NOVO na v0.2.3!)

# Start interactive chat session
vibe --interactive

# Or with alias
vibe -i

# Resume a previous session
vibe --resume <session-id>

Recursos do REPL:

  • 🎯 Interface de Chat: Fluxo de conversa natural com retenção de contexto
  • 📝 Entrada Multilinha: Use """ para mensagens multilinha
  • 🎨 Temas: Múltiplos temas de cores com o comando /theme
  • 💾 Gerenciamento de Sessão: Capacidades de salvamento automático e retomada
  • 📊 Renderização de Markdown: Formatação de texto rico nas respostas
  • ⚡ Progresso ao Vivo: Feedback de execução em tempo real
  • 🔧 Comandos de Barra: Ações rápidas como /tools, /history, /save
  • 🎮 Auto-completar: Completar com Tab para comandos e ferramentas

Exemplos de Comandos do CLI

Pesquisa e Análise

vibe "research modern React patterns and best practices"
vibe "analyze current trends in microservices architecture"
vibe "research security best practices for Node.js APIs"

Planejamento de Projeto

vibe "create a PRD for an e-commerce platform with user authentication"
vibe "generate user stories for authentication system"
vibe "create development tasks from user stories"

Análise e Geração de Código

vibe "map the codebase structure"
vibe "create context for implementing authentication"
vibe "generate a fullstack starter kit for e-commerce"
vibe "create coding standards for TypeScript projects"

Gerenciamento de Tarefas

vibe "create a new project for building a todo app"
vibe "list all my projects"
vibe "show project status for MyApp"
vibe "create high priority task for implementing OAuth"

Opções do CLI

# Output formats
vibe "research React hooks" --json
vibe "create PRD for todo app" --yaml

# Verbosity control
vibe "create project MyApp" --verbose
vibe "research Node.js patterns" --quiet

# Interactive REPL mode (NEW!)
vibe --interactive
vibe -i

# Session management (NEW!)
vibe --resume <session-id>
vibe --list-sessions

Comandos do REPL Interativo (v0.2.3+)

Uma vez no modo interativo (vibe --interactive), use estes comandos:

# Help and navigation
/help              # Show available commands
/tools             # List all MCP tools
/status            # Show session status

# Session management
/save              # Save current session
/sessions          # List saved sessions
/export [file]     # Export session to markdown

# Conversation control
/clear             # Clear conversation history
/history           # Show conversation history

# Customization
/theme             # Change color theme
/markdown          # Toggle markdown rendering
/config            # Manage configuration

# Exit
/quit or /exit     # Exit interactive mode

Organização de Arquivos

Os arquivos gerados são organizados automaticamente em VibeCoderOutput/:

VibeCoderOutput/
├── research/                    # Research reports
├── prd-generator/              # Product requirements
├── user-stories-generator/     # User stories
├── task-list-generator/        # Development tasks
├── fullstack-starter-kit-generator/  # Project templates
├── map-codebase/              # Code analysis
├── vibe-task-manager/         # Task management data
└── workflow-runner/           # Workflow outputs

🔄 Guia de Migração (v0.2.3)

Mudanças de Quebra

Nenhuma! A versão 0.2.3 é totalmente compatível com versões anteriores. Todas as configurações e fluxos de trabalho existentes continuam funcionando.

Melhorias Técnicas

  • Arquitetura CLI unificada com ponto de entrada único
  • Melhor tratamento de erros e recuperação
  • Limpeza de recursos aprimorada
  • Segurança de tipos aprimorada em toda a base de código
  • Prevenção de vazamentos de memória em sessões de longa duração
  • Otimização do Pipeline CI/CD:
    • Execução 70% mais rápida (~3 minutos vs ~10 minutos)
    • Focado em verificações essenciais: type-check, lint, build
    • Testes unitários movidos para o fluxo de desenvolvimento local
    • Veja o Guia CI/CD para detalhes
  • Uso de memória otimizado para bases de código grandes
  • Experiência de primeira execução mais rápida com detecção inteligente

📚 Configuração de Desenvolvimento (Avançado)

Se você quiser contribuir para o desenvolvimento ou executar a partir do código-fonte, siga o guia de configuração detalhado abaixo.

Visão Geral e Recursos

O Vibe Coder MCP integra-se com clientes compatíveis com MCP para fornecer as seguintes capacidades:

🚀 Arquitetura Principal

  • Suporte a Quatro Transportes: Protocolos de transporte stdio, SSE, WebSocket e HTTP para máxima compatibilidade com clientes
  • Alocação Dinâmica de Portas: Gerenciamento inteligente de portas com resolução de conflitos e degradação graciosa
  • Roteamento Semântico de Requisições: Roteia requisições de forma inteligente usando correspondência semântica baseada em embeddings com fallbacks de pensamento sequencial
  • Arquitetura de Registro de Ferramentas: Gerenciamento centralizado de ferramentas com ferramentas de auto-registro
  • Protocolo de Comunicação Unificado: Coordenação de agentes em todos os mecanismos de transporte com notificações em tempo real
  • Gerenciamento de Estado de Sessão: Mantém o contexto entre requisições dentro das sessões

🧠 Gerenciamento de Tarefas Nativo de IA

  • Vibe Task Manager: Gerenciamento de tarefas pronto para produção com 99,9% de taxa de sucesso em testes e integração abrangente (Funcional, mas ativamente em aprimoramento)
  • Processamento de Linguagem Natural: 21 intenções suportadas com reconhecimento multi-estratégia (correspondência de padrões + fallback LLM)
  • Design de Decomposição Recursiva (RDD): Decomposição inteligente de projetos em tarefas atômicas
  • Orquestração de Agentes: Coordenação multi-agente com mapeamento de capacidades, balanceamento de carga e sincronização de status em tempo real
  • Suporte Multi-Transporte para Agentes: Integração completa nos transportes stdio, SSE, WebSocket e HTTP
  • Integração de Armazenamento Real: Política de zero código mock - todas as integrações de produção
  • Integração de Análise de Artefatos: Integração perfeita com as saídas do Gerador de PRD e do Gerador de Lista de Tarefas
  • Persistência de Sessão: Rastreamento de sessão aprimorado com gatilhos de fluxo de orquestração
  • CLI Abrangente: Interface de linha de comando em linguagem natural com funcionalidade extensa

🔍 Análise Avançada de Código e Curadoria de Contexto

  • Ferramenta Code Map: Suporte a mais de 35 linguagens de programação com otimização de redução de tokens de 95-97%
  • Ferramenta de Curadoria de Contexto: Detecção de projetos agnóstica de linguagem com precisão de 95%+ em mais de 35 linguagens
  • Cache Inteligente de Codemaps: Sistema de cache configurável que reutiliza codemaps recentes para otimizar o desempenho do fluxo de trabalho
  • Resolução Aprimorada de Imports: Integração de terceiros para mapeamento preciso de dependências
  • Descoberta de Arquivos com Múltiplas Estratégias: 4 estratégias paralelas para análise abrangente
  • Otimização de Memória: Cache sofisticado e gerenciamento de recursos
  • Limites de Segurança: Validação separada de caminhos de leitura/escrita para operações seguras

📋 Suíte de Pesquisa e Planejamento

  • Ferramenta de Pesquisa: Pesquisa aprofundada usando Perplexity Sonar via OpenRouter
  • Curadoria de Contexto: Análise inteligente de base de código com pipeline de fluxo de trabalho em 8 fases e cache inteligente de codemaps para desenvolvimento orientado por IA
  • Geradores de Documentos: PRDs (prd-generator), histórias de usuário (user-stories-generator), listas de tarefas (task-list-generator), regras de desenvolvimento (rules-generator)
  • Scaffolding de Projetos: Kits iniciais full-stack (fullstack-starter-kit-generator) com geração dinâmica de templates
  • Execução de Fluxos de Trabalho: Sequências predefinidas de chamadas de ferramentas definidas em workflows.json

⚡ Desempenho e Confiabilidade

  • Execução Assíncrona: Processamento baseado em jobs com acompanhamento de status em tempo real
  • Desempenho Otimizado: Tempos de resposta <200ms, uso de memória <400MB
  • Testes Abrangentes: Taxa de sucesso de 99,9% em mais de 2.100 testes com validação completa de integração
  • Pronto para Produção: Zero implementações mock, integrações reais de serviços
  • Tratamento Aprimorado de Erros: Recuperação avançada de erros com nova tentativa automática, escalonamento e análise de padrões
  • Gerenciamento Dinâmico de Portas: Alocação inteligente de portas com resolução de conflitos e degradação graciosa
  • Monitoramento em Tempo Real: Monitoramento de saúde do agente, rastreamento de execução de tarefas e análises de desempenho

(Consulte as seções "Documentação Detalhada das Ferramentas" e "Detalhes dos Recursos" abaixo para mais informações)

Guia de Configuração para Desenvolvimento

Para desenvolvedores que desejam executar a partir do código-fonte ou contribuir com o projeto.

Etapa 1: Pré-requisitos

  1. Verifique a Versão do Node.js:

    • Abra um terminal ou prompt de comando.
    • Execute node -v
    • Certifique-se de que a saída mostre v20.0.0 ou superior (obrigatório).
    • Se não estiver instalado ou estiver desatualizado: Baixe de nodejs.org.

  2. Verifique a Instalação do Git:

    • Abra um terminal ou prompt de comando.
    • Execute git --version
    • Se não estiver instalado: Baixe de git-scm.com.

  3. Obtenha a Chave de API do OpenRouter:

    • Visite openrouter.ai
    • Crie uma conta se você não tiver uma.
    • Navegue até a seção de Chaves de API.
    • Crie uma nova chave de API e copie-a.
    • Mantenha esta chave à mão para a Etapa 4.

Etapa 2: Obtenha o Código

  1. Crie um Diretório de Projeto (opcional):

    • Abra um terminal ou prompt de comando.
    • Navegue até onde você deseja armazenar o projeto: 
      cd ~/Documents     # Example: Change to your preferred location

  2. Clone o Repositório:

    • Execute: 
      git clone https://github.com/freshtechbro/vibe-coder-mcp.git
      (Ou use a URL do seu fork, se aplicável)

  3. Navegue até o Diretório do Projeto:

    • Execute: 
      cd vibe-coder-mcp

Etapa 3: Execute o Script de Configuração

Escolha o script apropriado para o seu sistema operacional:

Para Windows:

  1. No seu terminal (ainda no diretório vibe-coder-mcp), execute: 
    setup.bat
  2. Aguarde o script concluir (ele instalará as dependências, compilará o projeto e criará os diretórios necessários).
  3. Se você vir alguma mensagem de erro, consulte a seção de Solução de Problemas abaixo.

Para macOS ou Linux:

  1. Torne o script executável: 
    chmod +x setup.sh
  2. Execute o script: 
    ./setup.sh
  3. Aguarde o script concluir.
  4. Se você vir alguma mensagem de erro, consulte a seção de Solução de Problemas abaixo.

O script executa as seguintes ações:

  • Verifica a versão do Node.js (v20+ obrigatório)
  • Instala todas as dependências via npm
  • Cria os subdiretórios VibeCoderOutput/ necessários
  • Compila o projeto TypeScript
  • Cria configuração a partir de templates se não estiver presente (v0.2.3+)
  • Define permissões executáveis (em sistemas Unix)

Nota: O processo de configuração agora é mais rápido (v0.2.3+) com instalação otimizada de dependências e processo de compilação simplificado.

Etapa 4: Configure as Variáveis de Ambiente

Novo na v0.2.3: Templates de configuração são fornecidos em src/config-templates/ para facilitar a configuração.

Opção A: Use o Assistente de Configuração (Recomendado)

vibe --setup

O assistente irá guiá-lo pela configuração e criar todos os arquivos necessários.

Opção B: Configuração Manual

  1. Copie os templates (se ainda não foi feito pelo script de configuração):

    cp src/config-templates/.env.template .env
cp src/config-templates/llm_config.template.json llm_config.json
cp src/config-templates/mcp-config.template.json mcp-config.json

  2. Edite o arquivo .env com sua configuração:

    # OpenRouter Configuration (REQUIRED)
OPENROUTER_API_KEY="your_actual_api_key_here"

# Optional configurations
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
GEMINI_MODEL=google/gemini-2.5-flash-preview-05-20

# Project directories (optional - auto-detected for CLI users)
VIBE_PROJECT_ROOT=/path/to/your/project
VIBE_CODER_OUTPUT_DIR=/path/to/output

  3. Configure o Diretório de Saída (Opcional):

    • Para alterar onde os arquivos gerados são salvos (o padrão é VibeCoderOutput/ dentro do projeto), adicione esta linha ao seu arquivo .env: 
      VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
    • Substitua o caminho pelo seu caminho absoluto preferido. Use barras normais (/) para caminhos. Se esta variável não for definida, o diretório padrão (VibeCoderOutput/) será usado.

  4. 🆕 Configure a Raiz Unificada do Projeto (Recomendado):

    • Para configurar a nova raiz unificada do projeto, adicione esta linha ao seu arquivo .env: 
      VIBE_PROJECT_ROOT=/path/to/your/project/root
    • Substitua o caminho pelo caminho absoluto do diretório raiz do seu projeto.
    • Benefícios: Variável de configuração única para todas as ferramentas (Code Map Generator, Task Manager, Context Curator)
    • Detecção Automática: Para usuários de CLI, a raiz do projeto é detectada automaticamente a partir do diretório de trabalho atual
    • Compatibilidade Retroativa: Variáveis legadas ainda são suportadas se você preferir configurações separadas

  5. Configuração Legada de Diretórios (Opcional):

    • Se você preferir configurações separadas de diretórios, ainda pode usar as variáveis originais: 
      CODE_MAP_ALLOWED_DIR=/path/to/your/source/code/directory
VIBE_TASK_MANAGER_READ_DIR=/path/to/your/project/source/directory
    • Nota: Essas variáveis funcionam como fallback se VIBE_PROJECT_ROOT não estiver definido
    • Segurança: Todas as variáveis funcionam com a implementação estrita de segurança do sistema de arquivos

  6. Revise Outras Configurações (Opcional):

    • Você pode adicionar outras variáveis de ambiente suportadas pelo servidor, como LOG_LEVEL (por exemplo, LOG_LEVEL=debug) ou NODE_ENV (por exemplo, NODE_ENV=development).

  7. Salve o Arquivo .env.

Etapa 5: Integre com Seu Assistente de IA (Configurações MCP)

Esta etapa crucial conecta o Vibe Coder ao seu assistente de IA adicionando sua configuração ao arquivo de configurações MCP do cliente.

5.1: Localize o Arquivo de Configurações MCP do Seu Cliente

A localização varia dependendo do seu assistente de IA:

  • Cursor AI / Windsurf / RooCode (baseado em VS Code):

    1. Abra o aplicativo.
    2. Abra a Paleta de Comandos (Ctrl+Shift+P ou Cmd+Shift+P).
    3. Digite e selecione Preferences: Open User Settings (JSON).
    4. Isso abre seu arquivo settings.json onde o objeto mcpServers deve residir.

  • Cline AI (Extensão do VS Code):

    • Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
    • macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
    • Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
    • (Nota: Se estiver usando VS Code padrão em vez de Cursor, substitua Cursor por Code no caminho)

  • Claude Desktop:

    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

5.2: Adicione a Configuração do Vibe Coder

  1. Abra o arquivo de configurações identificado acima em um editor de texto.

  2. Encontre o objeto JSON "mcpServers": { ... }. Se ele não existir, talvez seja necessário criá-lo (certifique-se de que o arquivo geral permaneça como JSON válido). Por exemplo, um arquivo vazio pode se tornar {"mcpServers": {}}.

  3. Adicione o seguinte bloco de configuração dentro das chaves {} do objeto mcpServers. Se outros servidores já estiverem listados, adicione uma vírgula , após a chave de fechamento } do servidor anterior antes de colar este bloco.

    // This is the unique identifier for this MCP server instance within your client's settings
"vibe-coder-mcp": {
  // Specifies the command used to execute the server. Should be 'node' if Node.js is in your system's PATH
  "command": "node",
  // Provides the arguments to the 'command'. The primary argument is the absolute path to the compiled server entry point
  // !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
  "args": ["/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/build/index.js"],
  // Sets the current working directory for the server process when it runs
  // !! IMPORTANT: Replace with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows !!
  "cwd": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
  // Defines the communication transport protocol between the client and server
  "transport": "stdio",
  // Environment variables to be passed specifically to the Vibe Coder server process when it starts
  // API Keys should be in the .env file, NOT here
  "env": {
    // Absolute path to the LLM configuration file used by Vibe Coder
    // !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
    "LLM_CONFIG_PATH": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/llm_config.json",
    // Sets the logging level for the server
    "LOG_LEVEL": "debug",
    // Specifies the runtime environment
    "NODE_ENV": "production",
    // Directory where Vibe Coder tools will save their output files
    // !! IMPORTANT: Replace with the actual absolute path on YOUR system !!
    "VIBE_CODER_OUTPUT_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/VibeCoderOutput",
    // 🆕 Unified project root for all tools (recommended)
    // This single variable configures all tools with the same project boundary
    "VIBE_PROJECT_ROOT": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP",
    // Legacy variables (optional - used as fallbacks if VIBE_PROJECT_ROOT not set)
    "CODE_MAP_ALLOWED_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP/src",
    "VIBE_TASK_MANAGER_READ_DIR": "/Users/username/Documents/Dev Projects/Vibe-Coder-MCP"
  },
  // A boolean flag to enable (false) or disable (true) this server configuration
  "disabled": false,
  // A list of tool names that the MCP client is allowed to execute automatically
  "autoApprove": [
    "research",
    "rules-generator",
    "user-stories-generator",
    "task-list-generator",
    "prd-generator",
    "fullstack-starter-kit-generator",
    "refactor-code",
    "git-summary",
    "run-workflow",
    "map-codebase"
  ]
}

  4. CRÍTICO: Substitua todos os caminhos placeholder (como /path/to/your/vibe-coder-mcp/...) pelos caminhos absolutos corretos no seu sistema onde você clonou o repositório. Use barras normais / para caminhos, mesmo no Windows (por exemplo, C:/Users/YourName/Projects/vibe-coder-mcp/build/index.js). Caminhos incorretos são o motivo mais comum de falha na conexão do servidor.

  5. Salve o arquivo de configurações.

  6. Feche e reinicie completamente seu aplicativo de assistente de IA (Cursor, VS Code, Claude Desktop, etc.) para que as alterações tenham efeito.

Etapa 6: Teste Sua Configuração

  1. Inicie Seu Assistente de IA:

    • Reinicie completamente o aplicativo do seu assistente de IA.

  2. Teste um Comando Simples:

    • Digite um comando de teste como: Research modern JavaScript frameworks

  3. Verifique a Resposta Adequada:

    • Se estiver funcionando corretamente, você deve receber uma resposta de pesquisa.
    • Se não, consulte a seção de Solução de Problemas abaixo.

Integração com Agentes de IA

O sistema MCP do Vibe Coder inclui instruções abrangentes de sistema projetadas para ajudar agentes de IA e clientes MCP a aproveitar efetivamente todo o ecossistema. Essas instruções fornecem orientação detalhada sobre o uso de ferramentas, padrões de integração e melhores práticas.

Arquivo de Instruções do Sistema

O arquivo VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md contém orientação abrangente para agentes de IA sobre como usar o ecossistema MCP do Vibe Coder de forma eficaz. Este arquivo deve ser integrado ao seu ambiente de desenvolvimento de IA para treinar seus agentes no uso ideal das ferramentas.

Integração Específica por Plataforma

Claude Desktop

Coloque as instruções do sistema nas instruções do sistema ou instruções personalizadas do seu projeto:

  1. Abra o Claude Desktop
  2. Navegue até as configurações do projeto
  3. Adicione o conteúdo de VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md ao campo de instruções do sistema
  4. Salve e reinicie o Claude Desktop

ChatGPT

Adicione as instruções do sistema às suas instruções personalizadas ou configurações do projeto:

  1. Abra as configurações do ChatGPT
  2. Navegue até instruções personalizadas ou configuração do projeto
  3. Cole o conteúdo de VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
  4. Salve a configuração

Extensões do VS Code (Cline, Roo Coder, Augment)

Integre as instruções do sistema na configuração da sua extensão:

  1. Cline: Coloque na seção de instruções do sistema ou memórias
  2. Roo Coder: Adicione às instruções do sistema ou à pasta de regras
  3. Augment: Coloque nas instruções do sistema ou memórias
  4. Outros forks do VS Code: Coloque nas instruções do sistema ou na pasta de regras com a configuração "sempre ativo"

Clientes MCP Gerais

Para outros clientes compatíveis com MCP:

  1. Localize a configuração de instruções do sistema ou regras
  2. Adicione o conteúdo de VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
  3. Defina como "sempre ativo" ou "persistente" se a opção estiver disponível
  4. Reinicie o cliente para aplicar as alterações

Principais Benefícios da Integração

  • Conhecimento Abrangente de Ferramentas: Os agentes aprendem sobre todas as 15+ ferramentas disponíveis e suas capacidades
  • Orquestração de Fluxos de Trabalho: Orientação sobre como encadear ferramentas para fluxos de trabalho complexos de desenvolvimento
  • Protocolo de Polling de Jobs: Instruções críticas para lidar corretamente com operações assíncronas
  • Melhores Práticas: Estratégias de otimização de desempenho e tratamento de erros
  • Padrões de Integração: Fluxos de trabalho comuns para pesquisa, planejamento e implementação

Exemplos de Uso

Uma vez integrados, seus agentes de IA serão capazes de:

# Research-driven development
"Research modern React patterns, then create a PRD and generate user stories"

# Complete project setup
"Set up a new e-commerce project with React frontend and Node.js backend"

# Context-aware development
"Analyze this codebase and suggest improvements with implementation tasks"

# Multi-agent coordination
"Register frontend and backend agents, then distribute authentication tasks"

Verificação

Para verificar a integração bem-sucedida:

  1. Pergunte ao seu agente de IA sobre as ferramentas disponíveis do Vibe Coder
  2. Solicite um fluxo de trabalho que use múltiplas ferramentas em sequência
  3. Verifique se o agente segue os protocolos adequados de polling de jobs
  4. Confirme se as saídas são salvas nos diretórios corretos

🎯 Arquitetura CLI Unificada (v0.2.3+)

A nova CLI unificada (unified-cli.ts) fornece um ponto de entrada único para todas as operações do Vibe Coder:

flowchart TD
    Start[vibe command] --> Detect{First Run?}
    Detect -->|Yes| Setup[Setup Wizard]
    Detect -->|No| Parse[Parse Arguments]
    
    Setup --> Config[Save Configuration]
    Config --> Parse
    
    Parse --> Mode{Mode?}
    Mode -->|--interactive| REPL[Interactive REPL]
    Mode -->|"message"| CLI[CLI Execution]
    Mode -->|none| MCP[MCP Server]
    Mode -->|--setup| Setup
    
    REPL --> Session[Session Management]
    Session --> Chat[Chat Interface]
    Chat --> Tools[Tool Execution]
    
    CLI --> Router[Hybrid Router]
    Router --> Tools
    
    MCP --> Transport{Transport?}
    Transport -->|stdio| Stdio[Stdio Server]
    Transport -->|sse| SSE[SSE Server]

Benefícios da CLI Unificada:

  • Binário único para todas as operações (vibe)
  • Interface de comando consistente
  • Gerenciamento compartilhado de configuração
  • Alternância perfeita de modos
  • Melhor utilização de recursos

Arquitetura do Projeto

O servidor MCP Vibe Coder segue uma arquitetura modular em TypeScript ESM com suporte a transporte duplo e um ecossistema abrangente de ferramentas:

flowchart TD
    subgraph "Core Architecture"
        Init[index.ts] --> Config[Configuration Loader]
        Config --> Transport{Transport Type}
        Transport --> |stdio| StdioTransport[Stdio Transport]
        Transport --> |sse| SSETransport[SSE Transport]
        StdioTransport --> Server[MCP Server]
        SSETransport --> Server
        Server --> ToolReg[Tool Registry]
        ToolReg --> InitEmbed[Initialize Embeddings]
        InitEmbed --> Ready[Server Ready]
    end

    subgraph "Request Processing"
        Req[Client Request] --> SessionMgr[Session Manager]
        SessionMgr --> Router[Hybrid Router]
        Router --> Semantic[Semantic Matcher]
        Router --> Sequential[Sequential Thinking]
        Semantic --> |High Confidence| Execute[Tool Execution]
        Sequential --> |Fallback| Execute
        Execute --> JobMgr[Job Manager]
        JobMgr --> Response[Response to Client]
    end

    subgraph "Tool Ecosystem"
        Execute --> Research[Research Tool]
        Execute --> TaskMgr[Vibe Task Manager]
        Execute --> CodeMap[Code Map Tool]
        Execute --> FullStack[Fullstack Generator]
        Execute --> PRDGen[PRD Generator]
        Execute --> UserStories[User Stories Generator]
        Execute --> TaskList[Task List Generator]
        Execute --> Rules[Rules Generator]
        Execute --> Workflow[Workflow Runner]
    end

    subgraph "Support Services"
        JobMgr --> AsyncJobs[Async Job Processing]
        Execute --> FileOps[File Operations]
        Execute --> LLMHelper[LLM Integration]
        Execute --> ErrorHandler[Error Handling]
        Execute --> StateManager[Session State]
    end

    subgraph "Configuration & Security"
        Config --> LLMConfig[LLM Config Mapping]
        Config --> MCPConfig[MCP Tool Config]
        Config --> EnvVars[Environment Variables]
        FileOps --> SecurityBoundary[Security Boundaries]
        SecurityBoundary --> ReadOps[Read Operations]
        SecurityBoundary --> WriteOps[Write Operations]
    end

Estrutura de Diretórios

vibe-coder-mcp/
├── .env                              # Environment configuration
├── .env.example                      # Environment template
├── llm_config.json                   # LLM model mappings
├── mcp-config.json                   # MCP tool configurations
├── package.json                      # Project dependencies
├── README.md                         # This documentation
├── VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md  # System prompt documentation
├── setup.bat                         # Windows setup script
├── setup.sh                          # macOS/Linux setup script
├── tsconfig.json                     # TypeScript configuration
├── vitest.config.ts                  # Vitest (testing) configuration
├── workflows.json                    # Workflow definitions
├── build/                            # Compiled JavaScript (after build)
├── docs/                             # Additional documentation
│   ├── map-codebase/                # Code Map Tool docs
│   ├── handover/                     # Development handover docs
│   └── *.md                          # Various documentation files
├── VibeCoderOutput/                  # Tool output directory
│   ├── research/                    # Research reports
│   ├── rules-generator/              # Development rules
│   ├── prd-generator/                # Product requirements
│   ├── user-stories-generator/       # User stories
│   ├── task-list-generator/          # Task lists
│   ├── fullstack-starter-kit-generator/  # Project templates
│   ├── map-codebase/                # Code maps and diagrams
│   ├── vibe-task-manager/            # Task management data
│   └── workflow-runner/              # Workflow outputs
└── src/                              # Source code
    ├── index.ts                      # Entry point
    ├── logger.ts                     # Logging configuration (Pino)
    ├── server.ts                     # MCP server setup
    ├── services/                     # Core services
    │   ├── routing/                  # Semantic routing system
    │   │   ├── embeddingStore.ts     # Embedding management
    │   │   ├── hybridMatcher.ts      # Hybrid routing logic
    │   │   └── toolRegistry.ts       # Tool registry
    │   ├── sse-notifier/             # SSE notification system
    │   ├── JobManager.ts             # Async job management
    │   └── ToolService.ts            # Tool execution service
    ├── tools/                        # MCP Tools
    │   ├── index.ts                  # Tool registration
    │   ├── sequential-thinking.ts    # Fallback routing
    │   ├── map-codebase/            # Code analysis tool
    │   │   ├── cache/                # Memory management
    │   │   ├── grammars/             # Tree-sitter grammars
    │   │   ├── importResolvers/      # Import resolution adapters
    │   │   └── *.ts                  # Core implementation
    │   ├── fullstack-starter-kit-generator/  # Project scaffolding
    │   ├── prd-generator/            # PRD creation
    │   ├── research/                # Research tool
    │   ├── rules-generator/          # Rule generation
    │   ├── task-list-generator/      # Task list generation
    │   ├── user-stories-generator/   # User story generation
    │   ├── vibe-task-manager/        # AI-native task management
    │   │   ├── __tests__/            # Comprehensive test suite
    │   │   ├── cli/                  # Command-line interface
    │   │   ├── core/                 # Core algorithms
    │   │   ├── integrations/         # Tool integrations
    │   │   ├── prompts/              # LLM prompts (YAML)
    │   │   ├── services/             # Business logic services
    │   │   ├── types/                # TypeScript definitions
    │   │   └── utils/                # Utility functions
    │   └── workflow-runner/          # Workflow execution engine
    ├── types/                        # TypeScript type definitions
    └── utils/                        # Shared utilities
        ├── configLoader.ts           # Configuration management
        ├── errors.ts                 # Error handling
        └── llmHelper.ts              # LLM integration helpers

Sistema de Roteamento Semântico

O Vibe Coder utiliza uma abordagem sofisticada de roteamento para selecionar a ferramenta certa para cada solicitação:

flowchart TD
    Start[Client Request] --> Process[Process Request]
    Process --> Hybrid[Hybrid Matcher]

    subgraph "Primary: Semantic Routing"
        Hybrid --> Semantic[Semantic Matcher]
        Semantic --> Embeddings[Query Embeddings]
        Embeddings --> Tools[Tool Embeddings]
        Tools --> Compare[Compare via Cosine Similarity]
        Compare --> Score[Score & Rank Tools]
        Score --> Confidence{High Confidence?}
    end

    Confidence -->|Yes| Registry[Tool Registry]

    subgraph "Fallback: Sequential Thinking"
        Confidence -->|No| Sequential[Sequential Thinking]
        Sequential --> LLM[LLM Analysis]
        LLM --> ThoughtChain[Thought Chain]
        ThoughtChain --> Extraction[Extract Tool Name]
        Extraction --> Registry
    end

    Registry --> Executor[Execute Tool]
    Executor --> Response[Return Response]

Padrão de Registro de Ferramentas

O Registro de Ferramentas é um componente central para gerenciar definições e execução de ferramentas:

flowchart TD
    subgraph "Tool Registration (at import)"
        Import[Import Tool] --> Register[Call registerTool]
        Register --> Store[Store in Registry Map]
    end

    subgraph "Tool Definition"
        Def[ToolDefinition] --> Name[Tool Name]
        Def --> Desc[Description]
        Def --> Schema[Zod Schema]
        Def --> Exec[Executor Function]
    end

    subgraph "Server Initialization"
        Init[server.ts] --> Import
        Init --> GetAll[getAllTools]
        GetAll --> Loop[Loop Through Tools]
        Loop --> McpReg[Register with MCP Server]
    end

    subgraph "Tool Execution"
        McpReg --> ExecTool[executeTool Function]
        ExecTool --> GetTool[Get Tool from Registry]
        GetTool --> Validate[Validate Input]
        Validate -->|Valid| ExecFunc[Run Executor Function]
        Validate -->|Invalid| ValidErr[Return Validation Error]
        ExecFunc -->|Success| SuccessResp[Return Success Response]
        ExecFunc -->|Error| HandleErr[Catch & Format Error]
        HandleErr --> ErrResp[Return Error Response]
    end

Processo de Pensamento Sequencial

O mecanismo de Pensamento Sequencial fornece roteamento de fallback baseado em LLM:

flowchart TD
    Start[Start] --> Estimate[Estimate Number of Steps]
    Estimate --> Init[Initialize with System Prompt]
    Init --> First[Generate First Thought]
    First --> Context[Add to Context]
    Context --> Loop{Needs More Thoughts?}

    Loop -->|Yes| Next[Generate Next Thought]
    Next -->|Standard| AddStd[Add to Context]
    Next -->|Revision| Rev[Mark as Revision]
    Next -->|New Branch| Branch[Mark as Branch]
    Rev --> AddRev[Add to Context]
    Branch --> AddBranch[Add to Context]
    AddStd --> Loop
    AddRev --> Loop
    AddBranch --> Loop

    Loop -->|No| Extract[Extract Final Solution]
    Extract --> End[End With Tool Selection]

    subgraph "Error Handling"
        Next -->|Error| Retry[Retry with Simplified Request]
        Retry -->|Success| AddRetry[Add to Context]
        Retry -->|Failure| FallbackEx[Extract Partial Solution]
        AddRetry --> Loop
        FallbackEx --> End
    end

Gerenciamento de Estado de Sessão

flowchart TD
    Start[Client Request] --> SessionID[Extract Session ID]
    SessionID --> Store{State Exists?}

    Store -->|Yes| Retrieve[Retrieve Previous State]
    Store -->|No| Create[Create New State]

    Retrieve --> Context[Add Context to Tool]
    Create --> NoContext[Execute Without Context]

    Context --> Execute[Execute Tool]
    NoContext --> Execute

    Execute --> SaveState[Update Session State]
    SaveState --> Response[Return Response to Client]

    subgraph "Session State Structure"
        State[SessionState] --> PrevCall[Previous Tool Call]
        State --> PrevResp[Previous Response]
        State --> Timestamp[Timestamp]
    end

Mecanismo de Execução de Fluxos de Trabalho

O sistema de Fluxos de Trabalho permite sequências de múltiplas etapas:

flowchart TD
    Start[Client Request] --> Parse[Parse Workflow Request]
    Parse --> FindFlow[Find Workflow in workflows.json]
    FindFlow --> Steps[Extract Steps]

    Steps --> Loop[Process Each Step]
    Loop --> PrepInput[Prepare Step Input]
    PrepInput --> ExecuteTool[Execute Tool via Registry]
    ExecuteTool --> SaveOutput[Save Step Output]
    SaveOutput --> NextStep{More Steps?}

    NextStep -->|Yes| MapOutput[Map Output to Next Input]
    MapOutput --> Loop

    NextStep -->|No| FinalOutput[Prepare Final Output]
    FinalOutput --> End[Return Workflow Result]

    subgraph "Input/Output Mapping"
        MapOutput --> Direct[Direct Value]
        MapOutput --> Extract[Extract From Previous]
        MapOutput --> Transform[Transform Values]
    end

Configuração de Fluxos de Trabalho

Os fluxos de trabalho são definidos no arquivo workflows.json localizado no diretório raiz do projeto. Este arquivo contém sequências predefinidas de chamadas de ferramentas que podem ser executadas com um único comando.

Localização e Estrutura do Arquivo

  • O arquivo workflows.json deve ser colocado no diretório raiz do projeto (mesmo nível do package.json)
  • O arquivo segue esta estrutura: 
    {
  "workflows": {
    "workflowName1": {
      "description": "Description of what this workflow does",
      "inputSchema": {
        "param1": "string",
        "param2": "string"
      },
      "steps": [
        {
          "id": "step1_id",
          "toolName": "tool-name",
          "params": {
            "param1": "{workflow.input.param1}"
          }
        },
        {
          "id": "step2_id",
          "toolName": "another-tool",
          "params": {
            "paramA": "{workflow.input.param2}",
            "paramB": "{steps.step1_id.output.content[0].text}"
          }
        }
      ],
      "output": {
        "summary": "Workflow completed message",
        "details": ["Output line 1", "Output line 2"]
      }
    }
  }
}

Modelos de Parâmetros

Os parâmetros das etapas do fluxo de trabalho suportam strings de modelo que podem referenciar:

  • Entradas do fluxo de trabalho: {workflow.input.paramName}
  • Saídas de etapas anteriores: {steps.stepId.output.content[0].text}

Acionando Fluxos de Trabalho

Use a ferramenta run-workflow com:

Run the newProjectSetup workflow with input {"productDescription": "A task manager app"}

Documentação Detalhada das Ferramentas

Cada ferramenta no diretório src/tools/ inclui documentação abrangente em seu próprio arquivo README.md. Esses arquivos cobrem:

  • Visão geral e propósito da ferramenta
  • Especificações de entrada/saída
  • Diagramas de fluxo de trabalho (Mermaid)
  • Exemplos de uso
  • Prompts de sistema utilizados
  • Detalhes de tratamento de erros

Consulte esses READMEs individuais para informações aprofundadas:

  • src/tools/fullstack-starter-kit-generator/README.md
  • src/tools/prd-generator/README.md
  • src/tools/research/README.md
  • src/tools/rules-generator/README.md
  • src/tools/task-list-generator/README.md
  • src/tools/user-stories-generator/README.md
  • src/tools/workflow-runner/README.md
  • src/tools/map-codebase/README.md

Categorias de Ferramentas

Ferramentas de Análise e Informação

  • Ferramenta de Mapa de Código (map-codebase): Escaneia uma base de código para extrair informações semânticas (classes, funções, comentários) e gera um mapa Markdown legível com diagramas Mermaid ou uma representação JSON estruturada com caminhos de arquivo absolutos para importações e informações aprimoradas de propriedades de classe.
  • Ferramenta de Curadoria de Contexto (curate-context): Análise inteligente de base de código e curadoria de pacotes de contexto com pipeline de fluxo de trabalho de 8 fases, cache inteligente de codemap, detecção de projeto independente de linguagem com suporte a mais de 35 linguagens de programação e descoberta de arquivos com múltiplas estratégias para tarefas de desenvolvimento orientadas por IA.
  • Ferramenta de Pesquisa (research): Realiza pesquisas aprofundadas sobre tópicos técnicos usando Perplexity Sonar, fornecendo resumos e fontes.

Ferramentas de Planejamento e Documentação

  • Gerador de Regras (rules-generator): Cria regras e diretrizes de desenvolvimento específicas do projeto.
  • Gerador de PRD (prd-generator): Gera documentos abrangentes de requisitos de produto.
  • Gerador de Histórias de Usuário (user-stories-generator): Cria histórias de usuário detalhadas com critérios de aceitação.
  • Gerador de Lista de Tarefas (task-list-generator): Constrói listas estruturadas de tarefas de desenvolvimento com dependências.

Ferramenta de Estruturação de Projetos

  • Gerador de Kit Inicial Fullstack (fullstack-starter-kit-generator): Cria kits iniciais de projeto personalizados com tecnologias de frontend/backend especificadas, incluindo scripts básicos de configuração e configuração.

Fluxo de Trabalho e Orquestração

  • Executor de Fluxos de Trabalho (run-workflow): Executa sequências predefinidas de chamadas de ferramentas para tarefas comuns de desenvolvimento.

Armazenamento de Arquivos Gerados

Por padrão, as saídas das ferramentas geradoras são armazenadas para referência histórica no diretório VibeCoderOutput/ dentro do projeto. Este local pode ser substituído definindo a variável de ambiente VIBE_CODER_OUTPUT_DIR no seu arquivo .env ou na configuração do assistente de IA.

Limites de Segurança para Operações de Leitura e Escrita

Por razões de segurança, as ferramentas MCP do Vibe Coder mantêm limites de segurança separados para operações de leitura e escrita com uma abordagem de segurança por padrão:

  • Operações de Leitura:

    • Ferramenta de Mapa de Código: Apenas lê de diretórios explicitamente autorizados através da variável de ambiente CODE_MAP_ALLOWED_DIR
    • Gerenciador de Tarefas Vibe: Apenas lê de diretórios autorizados através da variável de ambiente VIBE_TASK_MANAGER_READ_DIR (padrão para process.cwd())
    • Modo de Segurança: O Gerenciador de Tarefas Vibe usa o modo de segurança 'estrito' por padrão, que impede o acesso a diretórios do sistema como /private/var/spool/postfix/, /System/ e outros caminhos não autorizados
    • Segurança do Sistema de Arquivos: Aplicação abrangente de lista negra e verificação de permissões previnem erros EACCES e acesso não autorizado a arquivos

  • Operações de Escrita: Todos os arquivos de saída são gravados no diretório VIBE_CODER_OUTPUT_DIR (ou seus subdiretórios). Essa separação garante que as ferramentas só possam gravar em locais de saída designados, protegendo seu código-fonte de modificações acidentais.

  • Implementação de Segurança: O sistema de segurança do sistema de arquivos inclui:

    • Gerenciamento Adaptativo de Tempo Limite: Previne que operações fiquem pendentes indefinidamente com nova tentativa e cancelamento inteligentes
    • Validação de Caminhos: Validação abrangente de todos os caminhos de arquivo antes do acesso
    • Verificação de Permissões: Verificação proativa de permissões para prevenir erros de acesso
    • Proteção de Diretórios do Sistema: Lista negra integrada de diretórios do sistema que nunca devem ser acessados

Exemplo de estrutura (local padrão):

VibeCoderOutput/
  ├── research/                # Research reports
  │   └── TIMESTAMP-QUERY-research.md
  ├── rules-generator/          # Development rules
  │   └── TIMESTAMP-PROJECT-rules.md
  ├── prd-generator/            # PRDs
  │   └── TIMESTAMP-PROJECT-prd.md
  ├── user-stories-generator/   # User stories
  │   └── TIMESTAMP-PROJECT-user-stories.md
  ├── task-list-generator/      # Task lists
  │   └── TIMESTAMP-PROJECT-task-list.md
  ├── fullstack-starter-kit-generator/  # Project templates
  │   └── TIMESTAMP-PROJECT/
  ├── map-codebase/            # Code maps and diagrams
  │   └── TIMESTAMP-code-map/
  └── workflow-runner/          # Workflow outputs
      └── TIMESTAMP-WORKFLOW/

Instruções de Sistema para Clientes MCP

Para desempenho ideal com assistentes de IA e clientes MCP, use as instruções abrangentes de sistema fornecidas em VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md. Este documento contém orientações detalhadas para:

  • Padrões de uso específicos de ferramentas e melhores práticas
  • Estruturas de comandos em linguagem natural
  • Diretrizes de consulta de trabalhos assíncronos
  • Fluxos de integração e exemplos
  • Tratamento de erros e solução de problemas

Como Usar as Instruções de Sistema

Para Claude Desktop:

  1. Abra as configurações do Claude Desktop
  2. Navegue até "Instruções Personalizadas" ou "Prompt de Sistema"
  3. Copie todo o conteúdo de VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
  4. Cole no campo de instruções personalizadas
  5. Salve as configurações

Para Augment:

  1. Acesse as configurações/preferências do Augment
  2. Encontre "Instruções Personalizadas" ou "Configuração do Sistema"
  3. Copie e cole as instruções de sistema
  4. Aplique as alterações

Para Claude Code/Windsurf/Outros Clientes MCP:

  1. Localize a configuração de instruções personalizadas ou prompt de sistema
  2. Copie o conteúdo de VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md
  3. Cole no campo apropriado
  4. Salve/aplique a configuração

Benefícios de Usar as Instruções de Sistema:

  • Taxa de sucesso de operação de ferramentas acima de 98%
  • Reconhecimento ideal de comandos em linguagem natural
  • Tratamento adequado de trabalhos assíncronos
  • Orquestração eficiente de fluxos de trabalho
  • Menos erros e melhor solução de problemas

Exemplos de Uso

Via CLI (Linha de Comando Direta)

# Research and analysis
vibe "research modern JavaScript frameworks"
vibe "create development rules for a mobile banking application"

# Project planning
vibe "generate a PRD for a task management application"
vibe "generate user stories for an e-commerce website"
vibe "create a task list for a weather app based on user stories"

# Code generation and analysis
vibe "create a starter kit for a React/Node.js blog application with user authentication"
vibe "map the codebase structure" --json
vibe "curate context for adding authentication to my React app"

# Task management
vibe "create a new project for building a todo app"
vibe "list all my projects"
vibe "show status of my React project"

# Workflow automation
vibe "run workflow newProjectSetup with input {\"projectName\": \"my-new-app\"}"

Via Cliente MCP (Integração com Assistente de IA)

Interaja com as ferramentas através do seu assistente de IA conectado:

  • Pesquisa: Research modern JavaScript frameworks
  • Gerar Regras: Create development rules for a mobile banking application
  • Gerar PRD: Generate a PRD for a task management application
  • Gerar Histórias de Usuário: Generate user stories for an e-commerce website
  • Gerar Lista de Tarefas: Create a task list for a weather app based on [user stories]
  • Pensamento Sequencial: Think through the architecture for a microservices-based e-commerce platform
  • Kit Inicial Fullstack: Create a starter kit for a React/Node.js blog application with user authentication
  • Executar Fluxo de Trabalho: Run workflow newProjectSetup with input { "projectName": "my-new-app", "description": "A simple task manager" }
  • Mapear Base de Código: Generate a code map for the current project, map-codebase path="./src" ou Generate a JSON representation of the codebase structure with output_format="json"
  • Curadoria de Contexto: Curate context for adding authentication to my React app, Generate context package for refactoring the user service ou Analyze this codebase for performance optimization opportunities
  • Gerenciador de Tarefas Vibe: Create a new project for building a todo app, List all my projects, Run task authentication-setup, What's the status of my React project?

Gerenciador de Tarefas Vibe - Gerenciamento de Tarefas Nativo para IA

O Gerenciador de Tarefas Vibe é um sistema abrangente de gerenciamento de tarefas projetado especificamente para agentes de IA e fluxos de trabalho de desenvolvimento. Ele fornece decomposição inteligente de projetos, processamento de comandos em linguagem natural e integração perfeita com outras ferramentas do Vibe Coder.

Status: Funcional e pronto para produção com taxa de sucesso de teste de 99,9%, mas ativamente aprimorado com novos recursos e melhorias.

Principais Recursos

  • Processamento de Linguagem Natural: Entende comandos como "Crie um projeto para construir um aplicativo React" ou "Mostre-me todas as tarefas pendentes"
  • Design de Decomposição Recursiva (RDD): Quebra automaticamente projetos complexos em tarefas atômicas e executáveis
  • Integração de Análise de Artefatos: Importa perfeitamente arquivos PRD de VibeCoderOutput/prd-generator/ e listas de tarefas de VibeCoderOutput/generated_task_lists/
  • Persistência de Sessão: Rastreamento aprimorado de sessão com gatilhos de fluxo de trabalho de orquestração para operações confiáveis de múltiplas etapas
  • CLI Abrangente: Interface completa de linha de comando com processamento de linguagem natural e comandos estruturados
  • Orquestração de Agentes: Coordena múltiplos agentes de IA para execução paralela de tarefas
  • Pronto para Integração: Funciona perfeitamente com a Ferramenta de Mapa de Código, Ferramenta de Pesquisa e outras ferramentas
  • Armazenamento de Arquivos: Todos os dados do projeto armazenados em VibeCoderOutput/vibe-task-manager/ seguindo convenções estabelecidas

Exemplos de Início Rápido

# Project Management
"Create a new project for building a todo app with React and Node.js"
"List all my projects"
"Show me the status of my web app project"

# Task Management
"Create a high priority task for implementing user authentication"
"List all pending tasks for the todo-app project"
"Run the database setup task"

# Project Analysis (Enhanced with Intelligent Lookup)
"Decompose my React project into development tasks"
"Decompose PID-TODO-APP-REACT-001 into tasks"  # Using project ID
"Decompose \"Todo App with React\" into tasks"  # Using exact name
"Decompose todo into tasks"  # Using partial name (fuzzy matching)
"Refine the authentication task to include OAuth support"
"What's the current progress on my mobile app?"

🎯 Recursos Aprimorados de Busca de Projetos

  • Análise Inteligente: Detecta automaticamente IDs de projeto, nomes ou correspondências parciais
  • Validação Abrangente: Valida a prontidão do projeto antes da decomposição
  • Mensagens de Erro Aprimoradas: Fornece orientação acionável com projetos disponíveis e exemplos de uso
  • Múltiplos Formatos de Entrada: Suporta IDs de projeto, nomes entre aspas, nomes parciais e correspondência difusa
  • Pontuação de Confiança: Mostra níveis de confiança de análise para melhor feedback ao usuário

Estrutura de Comandos

O Gerenciador de Tarefas Vibe suporta tanto comandos estruturados quanto linguagem natural:

Comandos Estruturados:

  • vibe-task-manager create project "Name" "Description" --options
  • vibe-task-manager list projects --status pending
  • vibe-task-manager run task task-id --force
  • vibe-task-manager status project-id --detailed

Linguagem Natural (Recomendado):

  • "Crie um projeto para [descrição]"
  • "Mostre-me todos os projetos [status]"
  • "Execute a tarefa [nome da tarefa]"
  • "Qual é o status de [projeto]?"
  • "Analise arquivos PRD para [nome do projeto]" (NOVO)
  • "Importe lista de tarefas de [caminho do arquivo]" (NOVO)
  • "Analise todos os PRDs e crie projetos automaticamente" (NOVO)

Para documentação completa, consulte src/tools/vibe-task-manager/README.md e as instruções de sistema em VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md.

Status de Implementação e Métricas de Desempenho

Status Atual do Epic

O projeto MCP Vibe Coder segue uma abordagem de desenvolvimento baseada em epics com rastreamento abrangente:

gantt
    title Vibe Coder MCP Development Progress
    dateFormat  YYYY-MM-DD
    section Core Infrastructure
    Tool Registry & Routing    :done, epic1, 2024-01-01, 2024-02-15
    MCP Server Implementation  :done, epic2, 2024-01-15, 2024-03-01
    Async Job Management       :done, epic3, 2024-02-15, 2024-03-15

    section Tool Development
    Research & Planning Tools  :done, epic4, 2024-02-01, 2024-04-01
    Code Map Tool              :done, epic5, 2024-03-01, 2024-05-15
    Vibe Task Manager Core     :done, epic6, 2024-04-01, 2024-06-15

    section Advanced Features
    Performance Optimization   :active, epic7, 2024-06-01, 2024-07-15
    Security Implementation    :epic8, 2024-07-01, 2024-08-15
    Analytics & Monitoring     :epic9, 2024-07-15, 2024-09-01

Resumo de Conclusão dos Epics

  • Epic 1-5: ✅ Concluído (100% - Infraestrutura principal e ferramentas básicas)
  • Epic 6.1: ✅ Concluído (98,3% de taxa de sucesso de teste - Integração Profunda de Ferramentas MCP)
  • Epic 6.2: 🔄 Em Andamento (Otimização de Desempenho - 75% concluído)
  • Epic 7.1: 📋 Planejado (Implementação de Segurança - Pronto para implementação)
  • Epic 8: 📋 Planejado (Análise Avançada e Monitoramento - Projetado)

Metas de Desempenho e Métricas Atuais (v0.2.3)

MétricaMetaAtualStatus
Taxa de Sucesso de Testes98%+99,9%✅ Excedida
Tempo de Resposta (Operações de Tarefa)<200ms<150ms✅ Excedido
Tempo de Resposta (Operações Síncronas)<500ms<350ms✅ Excedido
Taxa de Conclusão de Trabalhos95%+96,7%✅ Atingida
Uso de Memória (Ferramenta de Mapa de Código)<512MB<400MB✅ Otimizado
Cobertura de Testes Unitários>70%73%✅ Atingida
Velocidade do Pipeline CI/CD<5min~3min✅ Otimizada
Sobrecarga de Segurança<50ms<35ms✅ Otimizada
Política de Zero Código Mock100%100%✅ Alcançada

Status Específico por Ferramenta

Gerenciador de Tarefas Vibe

  • Status: Pronto para Produção (Funcional, mas ativamente aprimorado)
  • Cobertura de Testes: 99,9%
  • Recursos: Metodologia RDD, orquestração de agentes, processamento de linguagem natural, análise de artefatos, persistência de sessão, CLI abrangente
  • Desempenho: Tempo de resposta <50ms para operações de tarefa
  • Adições Recentes: Integração de PRD/lista de tarefas, rastreamento aprimorado de sessão, fluxos de trabalho de orquestração

Ferramenta Code Map

  • Status: Pronto para produção com recursos avançados
  • Otimização de memória: Redução de tokens de 95-97% alcançada
  • Suporte a idiomas: Mais de 35 linguagens de programação
  • Resolução de importações: Aprimorada com arquitetura baseada em adaptadores

Ferramenta de Curadoria de Contexto

  • Status: Pronto para produção com cache inteligente de codemaps
  • Suporte a idiomas: Mais de 35 linguagens de programação com precisão acima de 95%
  • Pipeline de fluxo de trabalho: Análise e curadoria inteligentes em 8 fases
  • Detecção de projetos: Independente de idioma com descoberta de arquivos por múltiplas estratégias
  • Otimização de desempenho: Sistema de cache inteligente que reutiliza codemaps recentes (configurável de 1 a 1440 minutos)

Ferramenta de Pesquisa

  • Status: Pronto para produção
  • Integração: API Perplexity Sonar
  • Desempenho: Resposta média de consulta de pesquisa em <2s

Outras Ferramentas

  • Gerador Fullstack: Pronto para produção
  • Geradores de PRD/Histórias de Usuário/Listas de Tarefas: Pronto para produção
  • Executor de Fluxos de Trabalho: Pronto para produção

Execução Local (Opcional)

Embora o uso principal seja a integração com um assistente de IA (usando stdio), você pode executar o servidor diretamente para testes:

Modos de Execução

  • Modo de Produção (Stdio):

    npm start
    • Os logs vão para stderr (simula a inicialização do assistente de IA)
    • Use NODE_ENV=production

  • Modo de Desenvolvimento (Stdio, Logs Formatados):

    npm run dev
    • Os logs vão para stdout com formatação amigável
    • Requer nodemon e pino-pretty
    • Use NODE_ENV=development

  • Modo SSE (Interface HTTP):

    # Production mode over HTTP
npm run start:sse

# Development mode over HTTP
npm run dev:sse

Solução de Problemas Detalhada

Problemas de Conexão

Servidor MCP Não Detectado no Assistente de IA

  1. Verifique o Caminho da Configuração:

    • Confirme se o caminho absoluto no array args está correto
    • Garanta que todas as barras sejam barras normais /, mesmo no Windows
    • Execute node <path-to-build/index.js> diretamente para testar se o Node consegue encontrá-lo

  2. Verifique o Formato da Configuração:

    • Certifique-se de que o JSON seja válido, sem erros de sintaxe
    • Verifique se as vírgulas entre as propriedades estão corretas
    • Confirme se o objeto mcpServers contém seu servidor

  3. Reinicie o Assistente:

    • Feche completamente (não apenas minimize) o aplicativo
    • Reabra e tente novamente

O Servidor Inicia, Mas as Ferramentas Não Funcionam

  1. Verifique a Flag Desabilitada:

    • Garanta que "disabled": false esteja definido
    • Remova quaisquer comentários //, pois o JSON não os suporta

  2. Verifique o Array autoApprove:

    • Confirme se os nomes das ferramentas no array autoApprove correspondem exatamente
    • Tente adicionar "process-request" ao array se estiver usando roteamento híbrido

Problemas com Chaves de API

  1. Problemas com a Chave do OpenRouter:

    • Verifique novamente se a chave foi copiada corretamente
    • Confirme se a chave está ativa no painel do OpenRouter
    • Verifique se você tem créditos suficientes

  2. Problemas com Variáveis de Ambiente:

    • Verifique se a chave está correta em ambos:
      • O arquivo .env (para execuções locais)
      • O bloco de ambiente da configuração do seu assistente de IA

Problemas de Caminho e Permissões

  1. Diretório de Build Não Encontrado:

    • Execute npm run build para garantir que o diretório de build exista
    • Verifique se a saída do build está indo para um diretório diferente (confira tsconfig.json)

  2. Erros de Permissão de Arquivo:

    • Garanta que seu usuário tenha acesso de escrita ao diretório workflow-agent-files
    • Em sistemas Unix, verifique se build/index.js tem permissão de execução

Depuração de Logs

  1. Para Execuções Locais:

    • Verifique a saída do console para mensagens de erro
    • Tente executar com LOG_LEVEL=debug no seu arquivo .env

  2. Para Execuções com Assistente de IA:

    • Defina "NODE_ENV": "production" na configuração de ambiente
    • Verifique se o assistente tem um console de log ou janela de saída

Problemas Específicos de Ferramentas

  1. Roteamento Semântico Não Funcionando:
    • A primeira execução pode baixar o modelo de embeddings - verifique mensagens de download
    • Tente uma solicitação mais explícita que mencione o nome da ferramenta

Documentação

Documentação Principal

  • Instruções do Sistema: VIBE_CODER_MCP_SYSTEM_INSTRUCTIONS.md - Guia de uso completo para clientes MCP
  • Guia de CI/CD: CI_CD_GUIDE.md - Documentação simplificada de pipeline (70% mais rápida)
  • Guia de Publicação no NPM: NPM_PUBLISHING_GUIDE.md - Processo de release e deploy
  • Arquitetura do Sistema: docs/ARCHITECTURE.md - Arquitetura abrangente do sistema com diagramas Mermaid
  • Desempenho e Testes: docs/PERFORMANCE_AND_TESTING.md - Métricas de desempenho, estratégias de teste e garantia de qualidade
  • Vibe Task Manager: src/tools/vibe-task-manager/README.md - Documentação abrangente de gerenciamento de tarefas
  • Ferramenta de Curadoria de Contexto: src/tools/curate-context/README.md - Documentação de análise de código independente de idioma
  • Ferramenta Code Map: src/tools/map-codebase/README.md - Documentação avançada de análise de código

Documentação de Ferramentas

  • READMEs Individuais de Ferramentas: Cada diretório de ferramenta contém documentação detalhada
  • Guias de Configuração: Configuração de ambiente e gerenciamento de configurações
  • Referência de API: Esquemas e parâmetros de ferramentas documentados nas instruções do sistema
  • Exemplos de Integração: Fluxos de trabalho práticos e padrões de uso

Documentação de Arquitetura

  • Arquitetura do Sistema: Diagramas Mermaid no README e nas instruções do sistema
  • Arquitetura de Ferramentas: Diagramas de arquitetura individuais das ferramentas
  • Métricas de Desempenho: Status atual e estratégias de otimização
  • Diretrizes de Desenvolvimento: Melhores práticas de contribuição e desenvolvimento

Contribuindo

Aceitamos contribuições! Consulte nossas diretrizes de contribuição e garanta que todos os testes passem antes de enviar pull requests.

Fluxo de Trabalho de Desenvolvimento

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações com testes abrangentes
  4. Garanta que todas as verificações passem localmente: 
    # Run CI checks (REQUIRED before PR - matches GitHub Actions)
npm run type-check    # TypeScript validation (must pass)
npm run lint          # Code quality checks (must pass)
npm run build         # Build verification (must pass)

# Run tests locally (RECOMMENDED before PR)
npm run test:unit     # Fast unit tests (~3 minutes)

# Optional: Thorough testing for major changes
npm run test:integration
npm test              # All tests
  5. Envie um pull request com descrição detalhada

Padrões de Qualidade

  • Segurança de Tipos: NENHUM tipo any - TypeScript estrito obrigatório
  • Pipeline de CI: Deve passar por type-check, lint e build (automatizado)
  • Testes: Execute testes unitários localmente antes do envio do PR
  • Cobertura de Testes: Mantenha cobertura >70% para testes unitários
  • Documentação: Atualize a documentação relevante para as alterações
  • Desempenho: Considere o impacto na velocidade do pipeline de CI (meta <5 min)

Solução de Problemas Comum

Problemas com a Chave de API do OpenRouter

Problema: Ferramentas falham com erros de autenticação

  • Solução: Verifique se sua chave de API do OpenRouter está configurada corretamente em .env
  • Verificação: Garanta que a chave não tenha espaços extras ou aspas
  • Confirmação: Teste sua chave em openrouter.ai
  • Créditos: Garanta que você tenha créditos suficientes na sua conta do OpenRouter

Problemas de Configuração de Caminho

Problema: Erros de "Caminho não encontrado" ou "Acesso negado"

  • Solução: Use caminhos absolutos com barras normais (/) em todas as configurações
  • Windows: Converta caminhos como C:\Users\name para C:/Users/name
  • Permissões: Garanta que o usuário tenha acesso de leitura/escrita aos diretórios configurados
  • Variáveis de Ambiente: Verifique se VIBE_CODER_OUTPUT_DIR e VIBE_PROJECT_ROOT estão configuradas corretamente (ou as variáveis legadas CODE_MAP_ALLOWED_DIR e VIBE_TASK_MANAGER_READ_DIR)

Falhas de Build

Problema: Erros de compilação TypeScript

  • Solução: Execute npm run clean && npm run build
  • Dependências: Exclua node_modules e package-lock.json, depois execute npm install
  • Versão do Node: Garanta que Node.js v20+ esteja instalado (node -v)
  • TypeScript: Verifique erros de sintaxe com npm run lint

Falhas de Teste

Problema: Testes falham localmente ou erros de type-check no CI

  • Erros de Tipo: Execute npm run type-check localmente para detectar problemas cedo
  • Problemas de Lint: Use npm run lint:fix para corrigir automaticamente problemas de estilo
  • Ambiente: Garanta que o arquivo .env exista com OPENROUTER_API_KEY válido
  • Memória: Testes podem falhar em sistemas com <4GB de RAM
  • Rede: Alguns testes exigem conectividade com a internet
  • Limpeza: Execute npm run clean antes de executar os testes
  • Pipeline de CI: Consulte o Guia de CI/CD para detalhes do pipeline

Problemas de Memória/Desempenho

Problema: Alto uso de memória ou desempenho lento

  • Codebases Grandes: A Ferramenta Code Map pode consumir memória significativa para projetos com >10.000 arquivos
  • Solução: Aumente o limite de memória do Node.js: NODE_OPTIONS='--max-old-space-size=4096' npm start
  • Cache: Limpe os diretórios de cache em VibeCoderOutput/ se crescerem demais
  • Monitoramento: Use npm run test:memory para identificar vazamentos de memória

Problemas de Conexão com Cliente MCP

Problema: Servidor não detectado pelo assistente de IA

  • Caminhos: Verifique se todos os caminhos na configuração MCP usam barras normais e são absolutos
  • Reinicialização: Feche e reinicie completamente o aplicativo do assistente de IA
  • Logs: Verifique LOG_LEVEL=debug na configuração para mensagens de erro detalhadas
  • Transporte: Garanta que "transport": "stdio" esteja configurado corretamente
  • Desabilitado: Verifique "disabled": false na sua configuração

Problemas Específicos de Ferramentas

Vibe Task Manager:

  • Se comandos em linguagem natural falharem, tente usar comandos estruturados
  • Verifique VibeCoderOutput/vibe-task-manager/ para arquivos de projeto
  • Garanta que os nomes dos projetos não contenham caracteres especiais

Ferramenta Code Map:

  • Para erros de permissão, verifique se CODE_MAP_ALLOWED_DIR está definido
  • Repositórios grandes podem expirar - tente subdiretórios menores
  • Algumas linguagens exigem configuração adicional (consulte o README da ferramenta)

Curador de Contexto:

  • Se a geração de codemap falhar, verifique codemaps recentes no cache
  • Verifique espaço em disco suficiente para pacotes de contexto grandes
  • Verifique permissões de arquivo nos diretórios de destino

Problemas de Rede e Proxy

Problema: Não é possível acessar serviços externos

  • Proxy: Defina as variáveis de ambiente HTTP_PROXY e HTTPS_PROXY se estiver atrás de um proxy
  • SSL: Para problemas de SSL, tente NODE_TLS_REJECT_UNAUTHORIZED=0 (apenas desenvolvimento)
  • Firewall: Garanta que o firewall permita conexões HTTPS de saída
  • DNS: Tente usar servidores DNS públicos se a resolução falhar

Obtendo Ajuda

Se os problemas persistirem:

  1. Verifique os problemas existentes em GitHub Issues
  2. Ative o log de depuração: LOG_LEVEL=debug
  3. Colete mensagens de erro e logs
  4. Crie um novo problema com:
    • Versão do Node.js (node -v)
    • Sistema operacional
    • Mensagens de erro
    • Passos para reproduzir

📅 Changelog

Versão 0.3.5 (Mais Recente)

  • Matcher Híbrido Aprimorado: Extração completa de parâmetros para todas as 15 ferramentas
  • Melhorias em CLI/REPL: Confirmações interativas, polling de jobs com progresso
  • Correções de Bugs: Gerador de lista de tarefas gera automaticamente histórias de usuário, conversas de múltiplas etapas corrigidas
  • Modo Estrito TypeScript: Zero tipos any, qualidade de código de nível de produção

Versão 0.3.1

  • Correções de sincronização de instalação global
  • Processo de build limpo aprimorado
  • Fluxo de trabalho de empacotamento NPM melhorado

Versão 0.2.8

  • Persistência de configuração do modo interativo CLI
  • Detecção aprimorada de raiz de projeto

Versão 0.2.7

  • Adicionados arquivos de configuração ausentes ao pacote npm
  • Resolvidos erros de carregamento de configuração

Versão 0.2.3

  • Modo REPL interativo com interface de chat
  • Assistente de configuração aprimorado com autodetecção
  • Modelos de configuração
  • Binário CLI unificado

Para o histórico completo de releases, consulte GitHub Releases

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.