mcp-graph: por que criei uma ferramenta open-source para matar o vibe coding

Vibe coding está matando a qualidade do software. E eu digo isso como alguém que usa IA para programar todos os dias.

Existe uma diferença enorme entre usar IA com disciplina e simplesmente jogar um prompt e torcer para o código funcionar. Nos últimos meses, observei um padrão preocupante: desenvolvedores colando PRDs inteiros no chat de um agente de IA, recebendo centenas de linhas de código sem testes, sem rastreabilidade, sem contexto persistente. Na próxima sessão? O agente esquece tudo. Volta à estaca zero. Mais tokens queimados, mais retrabalho, mais frustração.

Eu decidi resolver isso. Criei o mcp-graph - uma ferramenta open-source que transforma o modo como agentes de IA trabalham em projetos de software reais. Não é mais um wrapper de prompts. É infraestrutura para desenvolvimento estruturado com IA.

O problema real do vibe coding

Se você trabalha com agentes de IA no dia a dia, provavelmente reconhece esses cenários:

PRDs viram tarefas soltas

Você importa um documento de requisitos e as tarefas caem num board sem conexão entre si. Dependências entre features? Prioridades calculadas com base em impacto e risco? Critérios de aceite rastreáveis até o requisito original? Nada disso existe. O agente trata cada tarefa como uma ilha, sem entender como ela se conecta ao todo.

O resultado é previsível: tarefas implementadas fora de ordem, dependências quebradas descobertas tarde demais, e um backlog que não reflete a realidade do projeto.

Cada sessão começa do zero

O agente não lembra o que fez ontem. Você gasta tokens re-explicando contexto, re-lendo arquivos, re-descrevendo a arquitetura. É como treinar um estagiário que tem amnésia toda manhã - exceto que esse estagiário custa tokens por mensagem.

Na prática, entre 30% e 50% dos tokens gastos em sessões com agentes são contexto repetido. Informação que o agente já processou, mas não reteve. Isso não é apenas ineficiente - é caro. Em projetos grandes, estamos falando de centenas de milhares de tokens desperdiçados por semana.

Cada ferramenta de IA é uma ilha

Seu assistente de código não conversa com sua ferramenta de análise de impacto. Sua busca de documentação não alimenta o contexto do planejador de tarefas. O agente que escreve código não sabe o que o agente que analisa dependências descobriu. Zero coordenação entre ferramentas.

Esse isolamento significa que cada ferramenta opera com uma visão parcial do projeto. O assistente de código sugere um pattern que conflita com uma decisão arquitetural documentada em outra ferramenta. O planejador de tarefas não sabe que uma dependência crítica tem um breaking change iminente. Informação existe, mas está fragmentada.

Nenhuma disciplina é enforced

Talvez o problema mais insidioso: o agente gera código sem testes, sem tipagem estrita, sem seguir os patterns do projeto. E o desenvolvedor aceita porque “funciona” - até o dia que quebra em produção, e ninguém sabe por quê, porque não existe rastreabilidade entre o requisito original, a decisão de implementação e o código gerado.

Vibe coding não é usar IA para programar. Vibe coding é usar IA sem disciplina, sem estrutura, sem rastreabilidade. É o equivalente moderno de cowboy coding, só que com um modelo de linguagem no lugar do cowboy.

O que é o mcp-graph

mcp-graph é uma CLI local-first em TypeScript que converte PRDs (Markdown, TXT, PDF, HTML) em grafos de execução persistentes armazenados em SQLite.

Na prática, você importa um documento de requisitos e o sistema gera automaticamente uma árvore hierárquica de tarefas com 9 tipos de nós: epics, tasks, subtasks, requisitos, constraints, milestones, critérios de aceite, riscos e decisões. O sistema infere dependências entre nós, estima prioridades com base em impacto e complexidade, e cria um grafo navegável que qualquer agente de IA pode consultar.

Mas o grafo é só o começo. O mcp-graph é um ecossistema completo:

26 ferramentas MCP que qualquer assistente de IA pode usar - Claude, Copilot, Cursor, Windsurf, Zed
44 endpoints REST com API completa para integração programática
Dashboard interativo em React 19 + React Flow com 6 abas analíticas
Pipeline de RAG 100% local - sem chamadas para APIs externas de embedding
Zero infraestrutura externa - roda inteiramente na sua máquina

A ideia central é simples: o grafo é a fonte de verdade do projeto. Todas as ferramentas consultam e enriquecem o mesmo grafo. Todas as decisões são rastreáveis. Todo o contexto é persistente.

Os 3 diferenciais técnicos

1. Token Economy - 70-85% de redução no contexto

Este é o diferencial que mais impacta no dia a dia, e o que me motivou a construir o sistema inteiro.

Quando um agente precisa de contexto sobre seu projeto, a abordagem ingênua é despejar tudo no prompt: arquivos inteiros, histórico completo, todos os requisitos. Isso funciona em projetos pequenos, mas escala terrivelmente. Em projetos reais, a janela de contexto estoura antes de você conseguir incluir tudo que é relevante.

O mcp-graph resolve isso com compressão em 3 tiers:

Tier 1 (Summary): aproximadamente 20 tokens por nó - apenas ID, tipo, título e status. Perfeito para o agente entender a estrutura geral do projeto sem consumir contexto.
Tier 2 (Standard): aproximadamente 150 tokens por nó - contexto completo com dependências resolvidas e snippets de conhecimento relevante via BM25. O nível ideal para a maioria das interações.
Tier 3 (Deep): 500+ tokens por nó - tudo do Tier 2 mais documentos completos, critérios de aceite expandidos e histórico de decisões. Usado apenas quando o agente precisa de profundidade total em um nó específico.

O budget de tokens é alocado inteligentemente: 60% para dados do grafo, 30% para conhecimento contextual, 10% para metadados de navegação. Essa alocação é dinâmica - se o agente está focado em uma subtask específica, mais budget vai para o conhecimento relacionado àquele nó.

O resultado prático? 70-85% menos tokens comparado à abordagem “cole tudo no prompt”. Respostas mais rápidas, custos menores, e janelas de contexto que não estouram no meio de uma conversa importante.

Para dar uma dimensão concreta: em um projeto com 200 tarefas, a abordagem ingênua consumiria cerca de 100.000 tokens só para carregar o contexto. Com o mcp-graph em Tier 1, o mesmo panorama consome menos de 4.000 tokens. A diferença é de uma ordem de magnitude.

2. Multi-Agent Intelligence Mesh

O mcp-graph não trabalha sozinho. Ele coordena 5 MCPs através de um EventBus reativo que garante que todas as ferramentas compartilhem informação em tempo real:

mcp-graph → fonte de verdade do projeto (grafo de execução + knowledge store)
Serena → análise de código, navegação semântica, memória persistente do agente
GitNexus → inteligência de código, análise de impacto de mudanças, cálculo de blast radius
Context7 → documentação atualizada de bibliotecas e frameworks, cacheada localmente
Playwright → validação via browser, captura de screenshots, testes de interface

Quando você importa um PRD, o sistema dispara eventos que automaticamente acionam reindexação no GitNexus, sincronização de documentação via Context7, e rebuild de embeddings no knowledge store. Tudo coordenado pelo EventBus, sem intervenção manual.

O resultado é um grafo de conhecimento vivo que fica mais inteligente a cada interação. Quando o GitNexus detecta que um módulo crítico foi modificado, essa informação aparece automaticamente no contexto das tarefas relacionadas. Quando a Serena identifica um pattern recorrente no código, essa informação enriquece as sugestões futuras.

Essa coordenação não é apenas conveniência - é o que permite que agentes tomem decisões informadas. Um agente que só vê código é limitado. Um agente que vê código, dependências, requisitos, riscos e documentação atualizada toma decisões radicalmente melhores.

3. Knowledge Pipeline 100% Local

Enquanto a maioria das soluções de RAG depende de APIs de embedding pagas (OpenAI, Cohere), o mcp-graph implementa tudo localmente. Isso foi uma decisão consciente, motivada por três razões: custo, privacidade e latência.

O pipeline de conhecimento combina múltiplas estratégias de busca:

Busca keyword via SQLite FTS5 com ranking BM25 - rápida, precisa para termos técnicos
Busca semântica via TF-IDF com aproximadamente 10 MB de overhead, contra os 400+ MB de modelos transformer típicos
Modo híbrido que combina ambas as estratégias com deduplicação automática por relevância
5 fontes indexadas: uploads do projeto, memórias da Serena, código-fonte, documentação externa e capturas web
Deduplicação por SHA-256 - o sistema nunca armazena conteúdo duplicado

Na prática, isso significa: sem API keys para configurar, sem custos por query, sem dados saindo do seu ambiente, sem dependência de serviços externos que podem cair ou mudar preços. Tudo roda na sua máquina, com performance suficiente para uso em tempo real durante sessões de desenvolvimento.

A qualidade da busca é surpreendentemente boa. O BM25 combinado com TF-IDF cobre a grande maioria dos casos de uso em projetos de software, onde a terminologia é consistente e os padrões de busca são previsíveis. Para os raros casos onde busca semântica profunda seria superior, o sistema compensa com a riqueza do grafo - as conexões entre nós fornecem contexto que embedding puro não captura.

A metodologia Anti-Vibe-Coding

O mcp-graph não é apenas uma ferramenta - ele embute uma metodologia que chamo de Anti-Vibe-Coding, inspirada nos princípios de Extreme Programming (XP) adaptados para desenvolvimento com IA.

O princípio central é simples: disciplina sobre intuição, estrutura antes de código.

TDD enforced

Toda feature exige teste escrito ANTES da implementação. Red → Green → Refactor. Não é sugestão - é requisito. Se o agente sugere código sem teste correspondente, a resposta correta é recusar e pedir o teste primeiro.

Isso pode parecer lento, mas na prática acelera o desenvolvimento. Testes escritos antes do código servem como especificação executável. O agente sabe exatamente o que precisa implementar, sem ambiguidade. O resultado é código que funciona na primeira tentativa com muito mais frequência.

No mcp-graph, cada nó de tarefa no grafo pode ter critérios de aceite vinculados a testes específicos. Quando o teste passa, o critério é marcado automaticamente. Rastreabilidade total do requisito até o teste.

Skeleton & Organs

O humano define a arquitetura - o esqueleto. A IA implementa com disciplina - os órgãos. Nunca o contrário.

Você jamais pede “crie um SaaS de gestão de projetos”. Você define: stack (TypeScript + Fastify + PostgreSQL), serviços (auth, billing, projects), domínio (entidades, value objects, aggregates), infraestrutura (Docker, CI/CD, monitoramento). O agente recebe um esqueleto claro e preenche cada módulo seguindo os patterns definidos.

Essa separação de responsabilidades é crucial. O humano traz visão arquitetural, conhecimento de domínio e julgamento sobre trade-offs. A IA traz velocidade de implementação, consistência e capacidade de processar grandes volumes de código. Cada um faz o que faz melhor.

Anti-one-shot

Nunca gere um sistema inteiro em um prompt. Decomponha em tarefas atômicas - cada uma estimada em menos de um dia de trabalho - rastreadas no grafo, com dependências explícitas entre elas.

Essa decomposição não é burocracia. É o que permite que o agente trabalhe com contexto gerenciável, que erros sejam isolados e corrigidos rapidamente, e que o progresso seja medido objetivamente. Um grafo com 200 tarefas atômicas é infinitamente mais gerenciável do que um prompt de 5.000 palavras pedindo “construa tudo”.

Ciclo de 8 fases

O desenvolvimento segue um ciclo estruturado com 8 fases, cada uma com ferramentas dedicadas e coordenação de agentes específica:

ANALYZE → entender o problema, coletar requisitos, identificar riscos DESIGN → definir arquitetura, interfaces, contratos entre módulos PLAN → decompor em tarefas atômicas, estabelecer dependências, estimar esforço IMPLEMENT → escrever código seguindo TDD, usando o grafo como guia VALIDATE → rodar testes, verificar critérios de aceite, checar cobertura REVIEW → analisar impacto, verificar blast radius, validar contra padrões do projeto HANDOFF → documentar decisões, atualizar o grafo, preparar para a próxima iteração LISTENING → aguardar nova demanda, consolidar aprendizados

Cada fase alimenta a próxima. O grafo registra tudo. O CLAUDE.md funciona como especificação evolutiva - cada erro, pattern ou decisão arquitetural é documentado para treinar cumulativamente o agente. O agente melhora a cada iteração. Não começa do zero.

Números que importam

O mcp-graph está na versão 7.0, publicado no npm como @mcp-graph-workflow/mcp-graph, sob licença MIT.

Alguns números que refletem decisões de engenharia intencionais:

910+ testes distribuídos em 105 arquivos, totalizando 1.337+ test cases
1.017 símbolos indexados pelo GitNexus para navegação semântica
2.650 relacionamentos mapeados no grafo de código
67 fluxos de execução rastreados end-to-end
26 ferramentas MCP + 44 endpoints REST
155 skills multimodais (audio, video, computer vision, orquestração autônoma)
6 abas analíticas no dashboard interativo
TypeScript strict mode - zero any, zero console.log em código de produção

Cada um desses números representa uma escolha deliberada. Os 910+ testes não existem porque um agente gerou testes genéricos - existem porque cada feature foi desenvolvida com TDD, cada edge case foi identificado e coberto, cada regressão foi prevenida.

O TypeScript strict mode com zero any não é vaidade - é a garantia de que o sistema de tipos trabalha a favor do desenvolvedor, não contra. Quando o compilador reclama, é porque encontrou um bug real, não porque o tipo foi relaxado para “qualquer coisa”.

O que mudou na v7: Harness Engineering

A v7.0 representou a maior evolução arquitetural do projeto. O mcp-graph deixou de ser apenas uma ferramenta de suporte e se tornou um ambiente de execução blindado, projetado para ser auditável e controlável por máquinas.

Harnessability Score

Diferente de apenas medir cobertura de testes, a v7 calcula um score composto por 4 dimensões que mede o quanto o código é “harnessable” (seguro para agentes manipularem):

Type Coverage (30%): ausência de any no TypeScript. Se o agente não sabe o tipo, ele alucina.
Test Coverage (30%): presença de testes unitários para cada módulo.
Fitness Score (20%): passagem em Architecture Fitness Functions (integridade de barrels, direção de dependências).
Docs Coverage (20%): presença de CLAUDE.md, regras e documentação clara.

Unified Gate System

Na v6.3, existiam múltiplos wrappers (lifecycle, code intelligence) que causavam bugs de deadlock e redundância. A v7 centralizou tudo num único gate, reduzindo 400 linhas de código e eliminando gargalos de IO. O resultado: 50% menos overhead por chamada MCP e 50% menos leituras de banco.

Knowledge Autoprune e Token Economy

O banco de conhecimento agora tem um “orçamento de tokens”. Na v6, ele crescia indefinidamente, degradando a performance do RAG. A v7 introduziu autoprune que deleta documentos baseado em Qualidade, Uso e Idade, mantendo o RAG sempre rápido (menos de 20ms para 500 documentos).

Performance: v6.3 vs v7.0

Operação	v6.3	v7.0	Melhoria
Overhead por chamada MCP	2 wrappers (100ms)	1 Unified Gate (50ms)	-50%
Leituras de banco (SQLite)	2x por chamada	1x por chamada	-50%
Search FTS5 (10k nós)	~350ms	menos de 200ms	~43%
Determinismo (AI-Free)	~80%	100%	Total

DORA Metrics (Nível Elite)

Em um projeto real com 415 nós e 923 arestas:

Deployment Frequency: 25.4 tarefas/dia (Elite)
MTTR: 0 horas (graças ao RAG local e self-healing)
Change Failure Rate: 0% (garantido pelo Unified Gate)

Para onde isso vai

Acredito que agentic workflows estruturados serão o padrão da indústria em breve. Não porque agentes de IA são moda, mas porque software complexo exige rastreabilidade, contexto persistente e coordenação entre ferramentas. As mesmas razões que fizeram CI/CD, testes automatizados e code review se tornarem padrão.

O vibe coding vai morrer da mesma forma que cowboy coding morreu: não por falta de produtividade, mas por falta de sustentabilidade. Código gerado sem disciplina funciona no demo, mas quebra em produção. Funciona no protótipo, mas não escala. Funciona quando uma pessoa entende o sistema, mas falha quando o time cresce.

O mcp-graph é open-source porque acredito que esse tipo de infraestrutura precisa ser da comunidade. Não deveria existir vendor lock-in em como você organiza seu workflow com IA. Não deveria existir uma API paga entre você e a capacidade de dar contexto persistente ao seu agente.

Se você trabalha com agentes de IA e sente que falta estrutura no seu workflow, convido você a experimentar. O repositório está no GitHub: github.com/DiegoNogueiraDev/mcp-graph-workflow

Contribuições, issues e feedback são bem-vindos. O projeto cresce com a comunidade.

Conclusão

A questão não é se você deve usar IA para programar - a resposta é obviamente sim. A questão é como você usa.

Vibe coding é o caminho fácil: cola o prompt, aceita o resultado, segue em frente. Funciona até não funcionar mais. E quando falha, falha espetacularmente, sem rastreabilidade para entender o que deu errado.

O caminho que proponho é mais disciplinado: decomponha requisitos em grafos, persista contexto entre sessões, coordene ferramentas, enforce TDD, rastreie decisões. É mais trabalho upfront, mas o ROI é exponencial à medida que o projeto cresce.

O mcp-graph é a ferramenta que eu queria que existisse quando comecei a trabalhar com agentes de IA. Agora ela existe, é open-source, e está pronta para uso.

A pergunta que fica: você vai continuar no vibe coding, ou vai estruturar seu workflow com IA?