Pular para o conteúdo

Como o Maguyva Funciona

Conecte um repositório GitHub e o Maguyva o transforma em várias visões pesquisáveis que seu agente pode usar sob demanda. Em vez de despejar arquivos inteiros no contexto, o modelo recebe acesso fundamentado a símbolos, estrutura, documentação, dependências e fragmentos de código classificados.

O Problema do Contexto#

À medida que seus projetos crescem, os agentes de IA enfrentam dificuldades com:

  • Limitações da Janela de Contexto - Informação demais sobrecarrega os modelos de IA
  • Dados Irrelevantes - Os agentes de IA desperdiçam tokens com informações desnecessárias
  • Desempenho Ruim - Precisão reduzida e tempos de processamento mais lentos
  • Gerenciamento Manual - Desenvolvedores gastam horas organizando contexto manualmente
  • Custos Mais Altos - Sem gerenciamento de contexto, os custos de tokens aumentam a cada consulta

Quanto maior um projeto cresce, mais ruído entra na janela de contexto — e a precisão do agente cai como resultado.

A Solução do Maguyva#

Quando você conecta um repositório, o Maguyva executa pipelines de ingestão na nuvem sobre código, documentação, manifests, símbolos e metadados de dependência. O objetivo é construir uma memória de código durável uma única vez, em vez de fazer com que cada execução de agente redescubra o repositório do zero.

Esses pipelines produzem várias camadas de dados especializadas: busca de texto exata, recuperação semântica, buscas de símbolos e referências, visões estruturais e análise de grafo de dependências. Perguntas diferentes são roteadas para camadas diferentes.

A busca combina 5 modos de recuperação: semantic, AST, symbol, dependency e text. Os resultados são fundidos e classificados para que símbolos importantes apareçam antes de helpers de baixo valor.

As visões de repositório privado ficam lado a lado com dados de referência públicos para linguagens e tecnologias baseadas em texto suportadas. Seu agente acessa todo o sistema através das ferramentas MCP, nas quais você pode se apoiar fortemente durante o planejamento e a validação, ou usar como verificações pontuais durante a edição.

1. Ingestão do Repositório#

Depois que o GitHub se conecta, o Maguyva varre o repositório na nuvem e extrai as partes sobre as quais um agente realmente precisa raciocinar:

  • Análise de Estrutura de Código
     - Analisa arquivos em símbolos, referências e limites arquiteturais
  • Resolução de Dependências
     - Mapeia como arquivos, módulos e símbolos dependem uns dos outros
  • Integração de Documentação - Traz a documentação do repositório e material de referência relacionado junto com o código

2. Camadas de Recuperação Especializadas#

Em vez de um índice genérico, o Maguyva constrói várias superfícies de recuperação que respondem a diferentes perguntas rapidamente e com evidências diferentes:

Orçamento de contexto: o Maguyva retorna fragmentos de código classificados com caminhos de arquivo e números de linha, em vez de despejar arquivos inteiros no contexto. A redução real de tokens depende do tamanho do repositório e da especificidade da consulta.

Roteamento e Classificação#

  • Pontuação de Relevância
     - Escolhe o modo de recuperação certo e traz os resultados importantes primeiro
  • Redução de Ruído - Remove boilerplate, blocos redundantes e resultados de baixo valor
  • Priorização de Contexto - Ordena os resultados para que o agente veja os símbolos principais antes dos helpers de casos extremos

Representações Armazenadas#

  • Recuperação Semântica
     - Encontra código e documentação conceitualmente semelhantes, mesmo quando as palavras exatas são diferentes
  • Visões de Símbolos e Estruturais - Suporta a busca de símbolos exata, referências e perguntas no formato AST
  • Análise de Grafo de Dependências
     - Segue chamadores, imports e raio de impacto por toda a base de código

3. Camada de Ferramentas do Model Context Protocol (MCP)#

O Maguyva é entregue como um servidor MCP hospedado na nuvem. Seu agente chama as ferramentas para a lente de que precisa, em vez de depender do modelo para lembrar sua arquitetura do zero. As quatro superfícies acima são visões agrupadas sobre as ferramentas concretas: Busca Semântica cobre semantic_search e intelligent_search; Busca de Símbolos cobre find_symbol e get_task_context; Busca Estrutural cobre structural_search e text_pattern_search; Grafo de Dependências cobre dependency_search e analyze_dependencies — junto com get_file, repository_context e ask_maguyva como utilitários de apoio. Veja a referência da API MCP completa para todas as 11 ferramentas.

Benefícios da Compatibilidade com MCP#

  • Use Mais ou Menos Ferramentas - Apoie-se fortemente no Maguyva durante o planejamento, ou apenas use-o para validar uma mudança arriscada
  • Melhor Validação de Planos - Confira ideias contra símbolos, referências e documentação reais antes de editar
  • Raio de Impacto Mais Claro - Ferramentas de dependência e grafo mostram o que pode quebrar se um símbolo mudar
  • Compatível com o Futuro - Funciona com qualquer cliente que suporte o padrão MCP

Arquitetura Técnica#

Pipeline de Processamento Seguro#

Recursos de Segurança#

  • Segurança de Transporte - As conexões com o serviço usam HTTPS/TLS
  • Armazenamento Gerenciado - Os dados indexados são armazenados em infraestrutura gerenciada, com criptografia em repouso no nível de armazenamento
  • Isolamento de Namespace - Os dados do repositório são escopados por workspace e namespace em todo o pipeline e nas consultas ao banco de dados
  • Controles de Acesso - O acesso ao repositório é restrito por limites de organização e namespace

Características de Desempenho#

O desempenho varia de acordo com o tamanho da base de código e a complexidade da consulta. O Maguyva foca em entregar o contexto mais relevante, em vez de despejar arquivos inteiros. Veja compatibilidade para linguagens e clientes suportados.

O Que Esperar#

Ao filtrar e organizar de forma inteligente o contexto da sua base de código, o Maguyva ajuda os agentes de IA a trabalhar de forma mais eficiente:

  • Melhor Precisão de Planejamento - Os agentes podem validar uma abordagem contra o repositório real antes de começar a codificar
  • Refatorações Mais Seguras - Verificações de raio de impacto e dependência reduzem quebras evitáveis
  • Menos Desperdício de Tokens - Apenas fragmentos relevantes são retornados, em vez de arquivos inteiros
  • Compreensão Mais Rápida do Repositório - O modelo recebe respostas fundamentadas rapidamente, em vez de redescobrir a estrutura do projeto a cada execução

Os resultados variam de acordo com o tamanho e a complexidade da sua base de código, e os tipos de consultas que seu agente de IA processa.

Mantendo Seu Índice Atualizado#

Atualizações Automáticas#

  • Sincronização de Repositório - Atualiza a partir de jobs de sincronização do GitHub conforme o código muda
  • Processamento Incremental - Processa apenas arquivos alterados para maior eficiência
  • Contexto com Reconhecimento de Branch - Mantém índices separados por branch do git, para que os agentes vejam o contexto certo para cada branch

Primeiros Passos#

Pronto para experimentar?

  1. Comece grátis - Não é necessário cartão de crédito
  2. Conecte seu repositório - vincule um repositório GitHub no portal do Maguyva
  3. Aponte seu agente para o Maguyva - Use as ferramentas MCP durante o planejamento, a verificação ou a edição (guia de instalação)

Comece grátis →

Gerenciamento de Repositórios#

Conecte seus repositórios GitHub pelo portal do Maguyva. A plataforma atualiza os índices a partir de jobs de sincronização do GitHub conforme o código muda, mantendo a camada de ferramentas MCP atualizada para cada branch. O portal também oferece visibilidade básica do uso da API, com análises mais detalhadas no roadmap.