Referência da API MCP

Explore as 11 ferramentas MCP do Maguyva, seus parâmetros e quando usar cada uma. Consulte a resposta tools/list do cliente conectado para saber quais argumentos estão disponíveis.

As ferramentas estão organizadas em 4 categorias:

• Ferramentas de Busca Principais - Capacidades avançadas de busca no seu codebase
• Ferramentas Estruturais e de Grafo - Consultas AST, busca de símbolos e análise de dependências
• Ferramentas de Análise de Código - Análise profunda de código e mapeamento de relações
• Ferramentas de Sistema e Utilitários - Contexto do repositório, orientação sobre ferramentas e comentários

Para ferramentas que aceitam um repositório, use este formato do identificador de repositório: "owner/repo:branch". Sem especificação, a branch padrão é main.

Omita repository quando o cliente MCP fornecer um padrão para a solicitação ou quando a chave puder acessar exatamente um repositório; caso contrário, informe-o explicitamente. Use repository_context(action="info", repository="owner/repo") para verificar como um repositório é resolvido.

Use estes formatos ao especificar um repositório:

• Com branch: "owner/repo:branch" - ex.: "owner/repository:develop"
• Branch padrão: "owner/repo" - usa a branch main quando nenhuma branch é especificada "owner/repository"
• Padrão da solicitação ou do único repositório: Omita o repositório quando o cliente MCP fornecer um padrão para a solicitação ou quando a chave puder acessar exatamente um repositório; caso contrário, informe-o explicitamente

Exemplos de prompts:

Pergunte sobre um repositório específico:       "Busque middleware de autenticação em owner/my-repo"
Liste os repositórios acessíveis:               "Quais repositórios esta chave do Maguyva pode acessar?"
Substitua o repositório em uma única consulta:  "Busque padrões de autenticação em owner/other-repo:develop"

Use language_filter nos modos de busca compatíveis. Para text_pattern_search, escolha search_scope="content"; para get_task_context, use scope="semantic" sem sementes ou contexto relacionado.

• language_filter="python" - Filtra apenas arquivos Python
• language_filter="typescript" - Filtra apenas arquivos TypeScript
• Sensível a maiúsculas/minúsculas: Use nomes de linguagem em minúsculas
• Padrão: String vazia (sem filtro) - retorna resultados de todas as linguagens
• Cobertura suportada: Os filtros de linguagem funcionam em toda a cobertura de 285+ linguagens e tecnologias baseadas em texto suportados. Veja compatibilidade para a lista completa.

"Encontre middleware de autenticação só em arquivos Python"
"Busque conexões de banco de dados em TypeScript"

Referência de API gerada a partir do código-fonte em 21 de outubro de 2026.

1. Use substituições explícitas de forma consciente: Omita o repositório quando o cliente MCP fornecer um padrão para a solicitação ou quando a chave puder acessar exatamente um repositório; caso contrário, informe-o explicitamente.
2. Escolha o Modo de Busca Certo: Use intelligent_search com mode="auto" na maioria dos casos. Especifique um modo quando você souber exatamente o que precisa.
3. Aproveite os Filtros de Linguagem: Use language_filter para restringir resultados e melhorar a performance.
4. GraphRAG Boosting: O boosting de importância do GraphRAG vem desativado por padrão para a busca semântica (boost_by_importance=false), para manter uma ordenação segura para os agentes. Passe boost_by_importance=true para ativar a reordenação baseada em centralidade em tours de arquitetura.
5. Correspondência de repositório ignora maiúsculas/minúsculas, mas não é aproximada: repository_context compara nomes de repositório sem diferenciar maiúsculas de minúsculas — mas não corrige erros de digitação. Quando a identidade entregue difere da solicitada, metadata.resolution_reason informa "defaulted" (nenhum branch foi solicitado) ou "fallback" (o branch ou repositório solicitado está indisponível). O campo é omitido quando a solicitação corresponde exatamente.
6. Combine Ferramentas: Use vários métodos de API juntos para uma análise abrangente.
7. Lide com Resultados Grandes: Use limit e controles de paginação específicos de cada ferramenta (por exemplo, line_start/line_end em get_file).
8. Use o ask_maguyva para Orientação sobre Ferramentas: Chame ask_maguyva com operation="guidance" e query="tool_selection" para orientações e exemplos de seleção de ferramentas. Use ferramentas locais para cálculos e transformações de strings.
9. Verifique o Impacto Antes e Depois de Editar: Antes de editar um símbolo compartilhado, chame dependency_search com analysis_type="impact" (ou passe changed_paths para o impacto de um PR/diff) para ver seu raio de impacto. Depois de editar, defina verify_after_edit=true com targets e/ou changed_paths para uma nova verificação compacta do grafo indexado. Essa verificação lê o grafo indexado, não alterações locais ainda não commitadas, e não substitui os testes locais. Confira indexed_commit_sha e a atualização do índice antes de tratar os resultados como evidência de uma nova revisão.

As respostas contêm campos de status comuns e campos de conteúdo específicos de cada ferramenta no nível superior. Buscas retornam results; get_file retorna content. Os campos comuns incluem:

• status: String — "success" ou "error". Sinais de correspondência degradada e de atualidade ficam em campos próprios: metadata.resolution_reason dentro de metadata e index_freshness.status no nível superior da ação info do repository_context.
• timing_ms: Tempo de execução da ferramenta em milissegundos
• applied_filters: Parâmetros efetivos da solicitação registrados para a operação
• error: String da mensagem de erro quando status é "error"; pode incluir orientações de recuperação.
• metadata: Informações adicionais sobre a operação (roteamento, cache, ajustes de parâmetro)
• pagination: Presente em respostas de coleções paginadas por cursor — inclui has_more e next_cursor. As janelas de busca ordenadas por relevância são resultados top-K limitados, não coleções completas paginadas.

Verifique o campo status antes de processar o payload de uma ferramenta — seus valores são "success" ou "error". Trate também erros de transporte MCP/JSON-RPC e de validação da requisição, que podem ocorrer antes de qualquer payload ser produzido. Para sinais de correspondência degradada ou de atualidade, leia o campo dedicado: metadata.resolution_reason dentro de metadata, ou index_freshness.status no nível superior da ação info do repository_context (known/partial/unknown/unavailable).

1. Configure o Cliente MCP: Aponte seu cliente MCP para o endpoint do servidor Maguyva
2. Confirme o Acesso ao Repositório: Use repository_context com list ou info para verificar os repositórios disponíveis para a chave de API
3. Comece a Buscar: Comece com intelligent_search e explore ferramentas especializadas conforme necessário
4. Combine Ferramentas: Use várias ferramentas juntas para uma análise de código abrangente

Para instruções de integração detalhadas, veja o guia de instalação.