project-graph-mcp ajuda agentes de AI a ver a arquitetura do projeto sem tokens desnecessários

Uma nova forma surgiu para agentes de IA navegarem rapidamente em código desconhecido: o project-graph-mcp constrói um grafo estrutural do projeto e o retorna como JSON comprimido. Em vez de ler dezenas de arquivos em sequência, um agente recebe um mapa da arquitetura, vê as dependências e depois se aprofunda nas áreas necessárias.

Como o servidor funciona

A ideia-chave por trás do project-graph-mcp é o chamado esqueleto do projeto. O servidor analisa o código-fonte, coleta informações sobre arquivos, classes, funções, importações e chamadas, e depois retorna tudo isso em uma estrutura compacta. Segundo o autor, a compressão alcança de 10 a 50 vezes, permitindo que o modelo compreenda a arquitetura geral sem consumir imenso contexto. Essa abordagem é especialmente útil para IDEs de agentes e orquestradores que precisam decidir rapidamente qual arquivo ler, para onde delegar subtarefas e como os módulos se relacionam.

A compressão alcança de 10 a 50 vezes.

Inicialmente, a ferramenta funcionava apenas com JavaScript através do parser AST Acorn, mas na versão 1.1 ganhou suporte para TypeScript, Python e Go. Para as novas linguagens, o autor escolheu uma abordagem baseada em regex: é mais simples, mais leve e não requer puxar bibliotecas externas pesadas apenas para navegação básica de código. Ao mesmo tempo, todos os parsers são padronizados para a mesma saída — listas de classes, funções, importações e chamadas — para que o agente trabalhe com o mesmo modelo de projeto independentemente da pilha tecnológica.

Quais problemas resolve

O projeto não termina com um único grafo. O servidor inclui ferramentas de análise incorporadas que permitem não apenas navegação, mas também identificação rápida de áreas problemáticas. O agente pode compreender quais seções de código estão potencialmente mortas, onde uma função cresceu para um tamanho desconfortável e qual cadeia de chamadas uma solicitação segue do middleware até a renderização ou manipulador de API. Isso torna o servidor mais do que apenas um mapa do projeto — é uma ferramenta para diagnóstico técnico inicial.

• `get_dead_code` encontra funções e módulos não utilizados
• `get_complexity` avalia complexidade ciclomática
• `get_large_files` identifica arquivos como candidatos a refatoração
• `get_call_chain` mostra o caminho entre funções relacionadas
• Health Score agrega resultados de verificações em uma pontuação de 0 a 100

Além disso, o project-graph-mcp inclui listas de verificação de testes através de anotações JSDoc `@test` e `@expect`. Um agente pode receber uma lista de verificações abertas, escrever código e depois marcar testes como aprovados. Isso funciona como uma ponte entre navegação do projeto e o ciclo de desenvolvimento real: primeiro o modelo compreende a estrutura da aplicação, depois faz alterações e imediatamente verifica contra o comportamento esperado. Para pilhas típicas também há regras incorporadas: 11 conjuntos com 86 convenções para React, Vue, Express, TypeScript e Symbiote.js.

Integração e segurança

A ferramenta é projetada como parte de uma estrutura de agente mais ampla. O autor descreve um cenário onde o agente principal na IDE primeiro solicita o esqueleto do projeto e depois delega tarefas individuais para workers de fundo via agent-pool-mcp. Cada worker executa o mesmo servidor localmente e invoca `expand`, `deps` e outros métodos para seções de código específicas. Dessa forma, o orquestrador não puxa arquivos desnecessários para o contexto e pode distribuir o trabalho mais rápido entre modelos com especializações diferentes.

Do ponto de vista da implementação, a barreira de entrada é baixa: Node.js 18+ é necessário, o servidor é executado via `npx`, pesa 132 KB, consiste em 47 arquivos e não tem dependências externas. A versão 1.2.0 já está disponível no npm. Os autores também abordaram especificamente a segurança. Todos os caminhos passam por validação através de `resolve` e `startsWith`, então o agente não pode escapar do diretório de trabalho. Tentar acessar algo como `../../etc/passwd` retorna um erro. Para ferramentas MCP que leem arquivos e dependências, tal proteção é crítica.

O que isto significa

Agentes de IA estão passando gradualmente de preenchimento automático simples para compreensão da arquitetura de projetos inteiros. O project-graph-mcp é interessante porque resolve um problema prático de contexto: em vez de centenas de linhas de código, o modelo obtém um mapa de sistema compacto e funciona com mais precisão. Para equipes que constroem seus próprios agentes de IA para desenvolvimento, isto já não é um experimento, mas uma camada de infraestrutura prática. Se tais servidores MCP se tornarem padrão, o desenvolvimento baseado em agentes enfrentará menos limites de token e mais frequentemente será limitado pela qualidade da lógica de engenharia em si.