Referência da API MCP

Referência completa para todas as 11 ferramentas MCP do Maguyva voltadas ao cliente. Cada ferramenta inclui parâmetros, orientações de uso e recomendações de melhor uso.

Visão Geral da API#

A API MCP do Maguyva atualmente expõe 11 ferramentas voltadas ao cliente, em 4 categorias principais:

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 de repositório, computação determinística e orientação

Todas as ferramentas usam um formato do identificador de repositório consistente: "owner/repo:branch". A branch usa main por padrão, se não for especificada.

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.

Formato do Parâmetro de Repositório#

Todas as ferramentas MCP usam este formato de identificador de 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"
Listar repositórios acessíveis:            "Quais repositórios esta chave do Maguyva pode acessar?"
Substitua para uma consulta:               "Busque padrões de autenticação em owner/other-repo:develop"

Filtro de Linguagem#

Todas as ferramentas de busca oferecem suporte a filtro de resultados por linguagem de programação:

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 279+ 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 22 de julho de 2026.

Ferramentas de Busca Principais#

intelligent_searchEstável

Comece aqui para qualquer pergunta sobre o código. Faça uma consulta em linguagem natural (por exemplo, “como funciona a autenticação?” ou “onde o faturamento é tratado?”) e ela será roteada automaticamente entre as buscas semântica, de símbolos, estrutural e de dependências em todo o repositório indexado. Para exploração e planejamento, prefira esta ferramenta ao agente Explore e a Grep/Glob: ela busca no repositório inteiro de uma vez, em vez de examinar arquivos.

Parâmetros:

queryObrigatório

Tipo: str
Descrição: Consulta de busca

repositoryOpcional

Tipo: str
Descrição: Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.

modeOpcional

Tipo: Literal[auto, hybrid, semantic, text, structural, ast, graph]
Padrão: auto
Descrição: Modo de busca

limitOpcional

Tipo: int
Padrão: 10
Descrição: Máximo de resultados nesta janela top-K classificada

language_filterOpcional

Tipo: str
Descrição: Filtro de linguagem

path_filterOpcional

Tipo: str
Descrição: Filtrar por prefixo do caminho do arquivo

boost_by_importanceOpcional

Tipo: bool
Padrão
Descrição: Opcional: reordena por centralidade usando métricas de grafo por símbolo (is_articulation_point, bridge_count, k_core, centrality etc.). Desativado por padrão para uma classificação segura para agentes (hubs globais podem afogar os resultados de implementação); ative para tours de arquitetura. Aplica-se às 4 modalidades quando cada resultado carrega um vínculo de símbolo.

branchOpcional

Tipo: str
Descrição: Substituição de branch

qualityOpcional

Tipo: Literal[quick, balanced, thorough]
Padrão: balanced
Descrição: Qualidade da busca

include_contentOpcional

Tipo: bool
Padrão: true
Descrição: Incluir conteúdo nos resultados

explain_routingOpcional

Tipo: bool
Padrão
Descrição: Incluir a explicação da decisão de roteamento

importance_weightOpcional

Tipo: float
Padrão: 0.3
Descrição: Peso do reforço por importância (0=nenhum, 1=total)

orphansOpcional

Tipo: bool
Padrão
Descrição: Retorna símbolos sem referências de entrada (potencial código morto). Útil para limpeza, mas pode incluir decoradores, funções internas, pontos de entrada de CLI.

include_community_contextOpcional

Tipo: bool
Padrão
Descrição: Inclui símbolos relacionados da mesma comunidade de código para contexto mais amplo. Útil ao explorar como uma funcionalidade ou módulo funciona.

community_depthOpcional

Tipo: int
Padrão: 1
Descrição: Profundidade de expansão do contexto da comunidade

graph_viewOpcional

Tipo: Literal[dependency, type, data_flow, control_flow]
Padrão: dependency
Descrição: Visualização do grafo para métricas

seed_symbol_idsOpcional

Tipo: list[str]
Descrição: Sementes de tarefas Tier-1: IDs de símbolos centrais para a tarefa atual. Quando definido, reclassifica os acertos fundidos pela proximidade de decaimento de profundidade Approach A (correspondência exata de semente + saltos na borda do gráfico). Aditivo — omitir para classificação global.

seed_file_pathsOpcional

Tipo: list[str]
Descrição: Sementes de tarefas Tier-1: caminhos de arquivos indexados que o agente abriu ou acabou de editar. Quando definido, reclassifica os hits fundidos por proximidade do caminho com decaimento de profundidade 1/(1+d) (mesmo arquivo → mesmo diretório → pacotes próximos). Aditivo — omitir para classificação global.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`query`	`str`	Sim	-	Consulta de busca
`repository`	`str`	Não	-	Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.
`mode`	`Literal[auto, hybrid, semantic, text, structural, ast, graph]`	Não	`auto`	Modo de busca
`limit`	`int`	Não	`10`	Máximo de resultados nesta janela top-K classificada
`language_filter`	`str`	Não	-	Filtro de linguagem
`path_filter`	`str`	Não	-	Filtrar por prefixo do caminho do arquivo
`boost_by_importance`	`bool`	Não		Opcional: reordena por centralidade usando métricas de grafo por símbolo (is_articulation_point, bridge_count, k_core, centrality etc.). Desativado por padrão para uma classificação segura para agentes (hubs globais podem afogar os resultados de implementação); ative para tours de arquitetura. Aplica-se às 4 modalidades quando cada resultado carrega um vínculo de símbolo.
`branch`	`str`	Não	-	Substituição de branch
`quality`	`Literal[quick, balanced, thorough]`	Não	`balanced`	Qualidade da busca
`include_content`	`bool`	Não	`true`	Incluir conteúdo nos resultados
`explain_routing`	`bool`	Não		Incluir a explicação da decisão de roteamento
`importance_weight`	`float`	Não	`0.3`	Peso do reforço por importância (0=nenhum, 1=total)
`orphans`	`bool`	Não		Retorna símbolos sem referências de entrada (potencial código morto). Útil para limpeza, mas pode incluir decoradores, funções internas, pontos de entrada de CLI.
`include_community_context`	`bool`	Não		Inclui símbolos relacionados da mesma comunidade de código para contexto mais amplo. Útil ao explorar como uma funcionalidade ou módulo funciona.
`community_depth`	`int`	Não	`1`	Profundidade de expansão do contexto da comunidade
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Não	`dependency`	Visualização do grafo para métricas
`seed_symbol_ids`	`list[str]`	Não	-	Sementes de tarefas Tier-1: IDs de símbolos centrais para a tarefa atual. Quando definido, reclassifica os acertos fundidos pela proximidade de decaimento de profundidade Approach A (correspondência exata de semente + saltos na borda do gráfico). Aditivo — omitir para classificação global.
`seed_file_paths`	`list[str]`	Não	-	Sementes de tarefas Tier-1: caminhos de arquivos indexados que o agente abriu ou acabou de editar. Quando definido, reclassifica os hits fundidos por proximidade do caminho com decaimento de profundidade 1/(1+d) (mesmo arquivo → mesmo diretório → pacotes próximos). Aditivo — omitir para classificação global.

Melhor Para:

Exploração em todo o índice ou em partida a frio quando a ferramenta certa não é clara
Classificação fundida multimodal entre busca semântica, textual, estrutural e de grafo

Não Recomendado Para:

Um nome de símbolo conhecido — use find_symbol diretamente
Um caminho conhecido em disco — use primeiro Read/Grep local

semantic_searchEstável

Encontre código pelo significado, não pelo texto exato. Use em consultas conceituais como “lógica de repetição” ou “fluxo de integração de usuários” quando você não souber a palavra-chave ou o símbolo. Retorna os trechos mais relevantes, classificados por importância. Em buscas conceituais, prefira esta ferramenta a Grep.

Parâmetros:

queryObrigatório

Tipo: str
Descrição: Consulta de busca (conceitual, baseada em significado)

repositoryOpcional

Tipo: str
Descrição: Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.

limitOpcional

Tipo: int
Padrão: 5
Descrição: Máximo de resultados nesta janela top-K classificada

similarity_thresholdOpcional

Tipo: float
Padrão: 0.6
Descrição: Pontuação mínima de similaridade

language_filterOpcional

Tipo: str
Descrição: Filtra resultados para arquivos detectados nesta linguagem de programação

path_filterOpcional

Tipo: str
Descrição: Filtrar por prefixo do caminho do arquivo

boost_by_importanceOpcional

Tipo: bool
Padrão
Descrição: Opcional: reordena por centralidade PageRank (desativado por padrão para classificação segura para agentes; ative para tours de arquitetura)

branchOpcional

Tipo: str
Descrição: Substituição de branch (padrão: parâmetro repository ou main)

include_contentOpcional

Tipo: bool
Padrão: true
Descrição: Incluir o conteúdo dos trechos nos resultados

graph_viewOpcional

Tipo: Literal[dependency, type, data_flow, control_flow]
Padrão: dependency
Descrição: Visualização do grafo para métricas

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`query`	`str`	Sim	-	Consulta de busca (conceitual, baseada em significado)
`repository`	`str`	Não	-	Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.
`limit`	`int`	Não	`5`	Máximo de resultados nesta janela top-K classificada
`similarity_threshold`	`float`	Não	`0.6`	Pontuação mínima de similaridade
`language_filter`	`str`	Não	-	Filtra resultados para arquivos detectados nesta linguagem de programação
`path_filter`	`str`	Não	-	Filtrar por prefixo do caminho do arquivo
`boost_by_importance`	`bool`	Não		Opcional: reordena por centralidade PageRank (desativado por padrão para classificação segura para agentes; ative para tours de arquitetura)
`branch`	`str`	Não	-	Substituição de branch (padrão: parâmetro repository ou main)
`include_content`	`bool`	Não	`true`	Incluir o conteúdo dos trechos nos resultados
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Não	`dependency`	Visualização do grafo para métricas

Melhor Para:

Consultas conceituais (“como funciona a autenticação?”, “estratégia de cache”)
Busca de similaridade entre pacotes

Não Recomendado Para:

Um nome de símbolo conhecido — use find_symbol em vez disso
Strings exatas ou mensagens de erro — use text_pattern_search

text_pattern_searchEstável

Busca o conteúdo indexado. Os modos exact e regex pesquisam todo o corpus de arquivos/blobs; fuzzy content pesquisa o corpus limitado de trechos semânticos. Os escopos de arquivo e símbolo aceitam apenas fuzzy. Use Grep local para um diretório restrito já disponível no disco.

Parâmetros:

queryObrigatório

Tipo: str
Descrição: Padrão de texto

repositoryOpcional

Tipo: str
Descrição: Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.

modeOpcional

Tipo: Literal[fuzzy, exact, regex]
Padrão: exact
Descrição: Modo de busca

search_scopeOpcional

Tipo: Literal[content, symbols, files]
Padrão: content
Descrição: O que buscar

limitOpcional

Tipo: int
Padrão: 5
Descrição: Máximo de resultados retornados nesta página

offsetOpcional

Tipo: int
Descrição: Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descrição: Cursor opaco de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.

language_filterOpcional

Tipo: str
Descrição: Filtro de linguagem

path_filterOpcional

Tipo: str
Descrição: Filtrar por prefixo do caminho do arquivo

case_sensitiveOpcional

Tipo: bool
Padrão
Descrição: Diferencia maiúsculas de minúsculas

branchOpcional

Tipo: str
Descrição: Substituição de branch

fuzzy_algorithmOpcional

Tipo: Literal[hybrid, trigram, levenshtein]
Padrão: hybrid
Descrição: Algoritmo de correspondência aproximada

thresholdOpcional

Tipo: float
Padrão: 0.05
Descrição: Limite mínimo de similaridade para a busca aproximada

semantic_fallbackOpcional

Tipo: bool
Padrão
Descrição: Recorrer à busca semântica se não houver resultados

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`query`	`str`	Sim	-	Padrão de texto
`repository`	`str`	Não	-	Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.
`mode`	`Literal[fuzzy, exact, regex]`	Não	`exact`	Modo de busca
`search_scope`	`Literal[content, symbols, files]`	Não	`content`	O que buscar
`limit`	`int`	Não	`5`	Máximo de resultados retornados nesta página
`offset`	`int`	Não	-	Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.
`cursor`	`str`	Não	-	Cursor opaco de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.
`language_filter`	`str`	Não	-	Filtro de linguagem
`path_filter`	`str`	Não	-	Filtrar por prefixo do caminho do arquivo
`case_sensitive`	`bool`	Não		Diferencia maiúsculas de minúsculas
`branch`	`str`	Não	-	Substituição de branch
`fuzzy_algorithm`	`Literal[hybrid, trigram, levenshtein]`	Não	`hybrid`	Algoritmo de correspondência aproximada
`threshold`	`float`	Não	`0.05`	Limite mínimo de similaridade para a busca aproximada
`semantic_fallback`	`bool`	Não		Recorrer à busca semântica se não houver resultados

Melhor Para:

Strings exatas, mensagens de erro e regex
Correspondência fuzzy por trigramas para texto quase correspondente

Não Recomendado Para:

Um caminho conhecido em disco — prefira Grep local
Consultas conceituais — use semantic_search

Ferramentas Estruturais e de Grafo#

structural_searchEstável

Prefira preset=functions|classes|methods|imports|variables (ou pattern= livre). Encontre código pela forma AST (não pelo texto). Filtros de nível intermediário: name_pattern, node_type, decorator, parent_child. Os filtros de caminho/ltree/chamada são avançados — defina advanced=true ao usá-los deliberadamente; as chaves avançadas no formato simples continuam aceitas por retrocompatibilidade. Forneça pelo menos um seletor estrutural.

Parâmetros:

repositoryOpcional

Tipo: str
Descrição: Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.

presetOpcional

Tipo: Literal[functions, classes, methods, imports, variables]
Descrição: Seletor estrutural preferido. Expande-se para tipos de nó AST entre linguagens — functions (definições de função/arrow/método conforme a linguagem); classes (definições de class/struct/impl); methods (definições de método, e function_definition para linguagens sem nó de método); imports (instruções import/use/include); variables (declarações variable/let/const/static). Prefira em vez de pattern/node_type livre para consultas de navegação.

patternOpcional

Tipo: str
Descrição: Padrão Free-form quando as predefinições são grosseiras demais (detecção automática: 'def foo(' → node_type + name_pattern). Prefira preset= para consultas de navegação.

name_patternOpcional

Tipo: str
Descrição: Padrão do nome do símbolo (curinga de shell, expressão regular POSIX limitada ou texto aproximado; máximo de 256 caracteres)

node_typeOpcional

Tipo: str
Descrição: Tipo de nó AST (function_definition, class_definition etc.) — prefira preset= para formatos comuns

decoratorOpcional

Tipo: str
Descrição: Filtro por nome de decorador

base_classOpcional

Tipo: str
Descrição: Filtro por nome de classe base (encontra classes que herdam dela)

language_filterOpcional

Tipo: str
Descrição: Filtro de linguagem

limitOpcional

Tipo: int
Padrão: 20
Descrição: Máximo de resultados retornados nesta página

offsetOpcional

Tipo: int
Descrição: Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descrição: Cursor opaco de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.

path_filterOpcional

Tipo: str
Descrição: Filtrar por prefixo do caminho do arquivo

branchOpcional

Tipo: str
Descrição: Substituição de branch

query_typeOpcional

Tipo: Literal[node_type, name_pattern, parent_child]
Descrição: Tipo de consulta explícito

parent_typeOpcional

Tipo: str
Descrição: Filtro de tipo do nó AST pai

relationshipOpcional

Tipo: Literal[parent, ancestor]
Padrão: parent
Descrição: Para consultas parent_child: apenas o pai direto ou qualquer ancestral (use ancestor para métodos de classe aninhados no corpo/bloco de uma classe)

has_modifierOpcional

Tipo: str
Descrição: Filtrar por modificador (export, async, static etc.)

advancedOpcional

Tipo: bool
Padrão
Descrição: Defina true ao usar intencionalmente filtros avançados de caminho, ltree ou chamada (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Por padrão, false mantém a interface do agente focada nas predefinições. Chaves avançadas no formato simples ainda funcionam para compatibilidade com versões anteriores, com um aviso de metadados.

callee_textOpcional

Tipo: str
Descrição: Avançado — prefira preset=functions|classes|methods|imports|variables. Filtro de texto do callee em uma expressão de chamada. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.

callee_nameOpcional

Tipo: str
Descrição: Avançado — prefira preset=functions|classes|methods|imports|variables. Filtro de nome do callee em uma expressão de chamada. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.

field_roleOpcional

Tipo: str
Descrição: Avançado — prefira preset=functions|classes|methods|imports|variables. Filtro de papel de campo AST. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.

ltree_ancestorOpcional

Tipo: str
Descrição: Avançado — prefira preset=functions|classes|methods|imports|variables. Filtro de caminho ancestral AST ltree. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.

ltree_descendantOpcional

Tipo: str
Descrição: Avançado — prefira preset=functions|classes|methods|imports|variables. Filtro de caminho descendente AST ltree. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.

definition_nameOpcional

Tipo: str
Descrição: Avançado — prefira preset=functions|classes|methods|imports|variables. Filtro de nome de definição. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.

min_depthOpcional

Tipo: int
Descrição: Avançado — prefira preset=functions|classes|methods|imports|variables. Profundidade AST mínima. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.

max_depthOpcional

Tipo: int
Descrição: Avançado — prefira preset=functions|classes|methods|imports|variables. Profundidade AST máxima. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`repository`	`str`	Não	-	Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.
`preset`	`Literal[functions, classes, methods, imports, variables]`	Não	-	Seletor estrutural preferido. Expande-se para tipos de nó AST entre linguagens — functions (definições de função/arrow/método conforme a linguagem); classes (definições de class/struct/impl); methods (definições de método, e function_definition para linguagens sem nó de método); imports (instruções import/use/include); variables (declarações variable/let/const/static). Prefira em vez de pattern/node_type livre para consultas de navegação.
`pattern`	`str`	Não	-	Padrão Free-form quando as predefinições são grosseiras demais (detecção automática: 'def foo(' → node_type + name_pattern). Prefira preset= para consultas de navegação.
`name_pattern`	`str`	Não	-	Padrão do nome do símbolo (curinga de shell, expressão regular POSIX limitada ou texto aproximado; máximo de 256 caracteres)
`node_type`	`str`	Não	-	Tipo de nó AST (function_definition, class_definition etc.) — prefira preset= para formatos comuns
`decorator`	`str`	Não	-	Filtro por nome de decorador
`base_class`	`str`	Não	-	Filtro por nome de classe base (encontra classes que herdam dela)
`language_filter`	`str`	Não	-	Filtro de linguagem
`limit`	`int`	Não	`20`	Máximo de resultados retornados nesta página
`offset`	`int`	Não	-	Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.
`cursor`	`str`	Não	-	Cursor opaco de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.
`path_filter`	`str`	Não	-	Filtrar por prefixo do caminho do arquivo
`branch`	`str`	Não	-	Substituição de branch
`query_type`	`Literal[node_type, name_pattern, parent_child]`	Não	-	Tipo de consulta explícito
`parent_type`	`str`	Não	-	Filtro de tipo do nó AST pai
`relationship`	`Literal[parent, ancestor]`	Não	`parent`	Para consultas parent_child: apenas o pai direto ou qualquer ancestral (use ancestor para métodos de classe aninhados no corpo/bloco de uma classe)
`has_modifier`	`str`	Não	-	Filtrar por modificador (export, async, static etc.)
`advanced`	`bool`	Não		Defina true ao usar intencionalmente filtros avançados de caminho, ltree ou chamada (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Por padrão, false mantém a interface do agente focada nas predefinições. Chaves avançadas no formato simples ainda funcionam para compatibilidade com versões anteriores, com um aviso de metadados.
`callee_text`	`str`	Não	-	Avançado — prefira preset=functions\|classes\|methods\|imports\|variables. Filtro de texto do callee em uma expressão de chamada. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.
`callee_name`	`str`	Não	-	Avançado — prefira preset=functions\|classes\|methods\|imports\|variables. Filtro de nome do callee em uma expressão de chamada. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.
`field_role`	`str`	Não	-	Avançado — prefira preset=functions\|classes\|methods\|imports\|variables. Filtro de papel de campo AST. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.
`ltree_ancestor`	`str`	Não	-	Avançado — prefira preset=functions\|classes\|methods\|imports\|variables. Filtro de caminho ancestral AST ltree. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.
`ltree_descendant`	`str`	Não	-	Avançado — prefira preset=functions\|classes\|methods\|imports\|variables. Filtro de caminho descendente AST ltree. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.
`definition_name`	`str`	Não	-	Avançado — prefira preset=functions\|classes\|methods\|imports\|variables. Filtro de nome de definição. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.
`min_depth`	`int`	Não	-	Avançado — prefira preset=functions\|classes\|methods\|imports\|variables. Profundidade AST mínima. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.
`max_depth`	`int`	Não	-	Avançado — prefira preset=functions\|classes\|methods\|imports\|variables. Profundidade AST máxima. Defina advanced=true ao usar intencionalmente filtros de caminho/ltree/chamada.

Melhor Para:

Estrutura em nível de AST: classes, decorators, presets de function/method
Encontrar código pela forma, não pelo texto

Não Recomendado Para:

Consultas de texto livre ou conceituais — use semantic_search ou intelligent_search

dependency_searchEstável

Superfície principal de raio de impacto / grafo. Responde a “o que chama isto?” / “o que isto usa?” por meio do grafo real de chamadas/importações. Para impacto antes de editar: analysis_type="dependents" ou analysis_type="impact" (entrada, profundidade superficial padrão para impact), include_metrics=false por padrão (ative para centralidade + refactor_risk). Impacto PR/diff (P1-8): passe changed_paths e/ou patch (diff unificado) — resolve símbolos por caminho e retorna um payload compacto de dependentes de entrada superficiais sem exigir um nome de símbolo. Após uma edição, defina verify_after_edit=true com targets e/ou changed_paths para uma nova consulta compacta multi-raiz dos símbolos impactados. Também aceita dependencies, centrality e orphans. analyze_dependencies é um alias leve para o caminho impact — prefira esta ferramenta para novos agentes.

Parâmetros:

repositoryOpcional

Tipo: str
Descrição: Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.

queryOpcional

Tipo: str
Descrição: Nome do símbolo ou termo de busca

targetOpcional

Tipo: str
Descrição: Nome do símbolo (alias de query)

changed_pathsOpcional

Tipo: list[str]
Descrição: Caminhos relativos ao repositório para impacto PR/diff (padrão) ou, com verify_after_edit=true, raízes de verificação pós-edição. PR/diff: resolve símbolos por caminho e percorre dependentes de entrada superficiais; pode ser combinado com patch=. Verificar: resolve até 5 símbolos por caminho como raízes de verificação (limitado inferior dentro do modo de verificação). Não requer query/target para impacto PR/diff.

patchOpcional

Tipo: str
Descrição: Impacto PR/diff: texto de patch diff / git unificado. Os caminhos são analisados a partir dos cabeçalhos diff --git/---/+++; mesmo caminho de impacto compacto que changed_paths.

analysis_typeOpcional

Tipo: Literal[centrality, dependencies, dependents, impact, orphans]
Padrão: dependencies
Descrição: Modo de análise. impact = raio de impacto (dependentes de entrada; profundidade superficial quando depth é omitido). dependents também responde a impact. Quando changed_paths ou patch é definido, a análise é forçada para o impacto PR/diff. centrality/orphans não exigem target.

depthOpcional

Tipo: Literal[shallow, balanced, deep]
Padrão: balanced
Descrição: Profundidade de travessia. Para analysis_type=impact e o impacto PR/diff, o padrão efetivo é shallow, a menos que você defina depth explicitamente.

limitOpcional

Tipo: int
Padrão: 20
Descrição: Máximo de resultados retornados nesta página

offsetOpcional

Tipo: int
Descrição: Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descrição: Cursor opaco de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.

path_filterOpcional

Tipo: str
Descrição: Restringe a resolução do símbolo de destino pelo prefixo do caminho do arquivo; os relacionamentos de grafo retornados podem ultrapassar esse caminho.

language_filterOpcional

Tipo: str
Descrição: Filtra a resolução do alvo e os resultados de navegação por linguagem

directionOpcional

Tipo: Literal[outgoing, incoming, both]
Descrição: Direção da travessia (substitui a inferência de analysis_type)

relationship_typesOpcional

Tipo: list[str]
Descrição: Filtra os tipos de aresta (CALL, IMPORT, INHERITS_FROM etc.). Uma lista não vazia substitui os padrões de graph_view.

exclude_test_pathsOpcional

Tipo: bool
Padrão: true
Descrição: Padrão true: exclui caminhos de teste, fixture, fornecedor e exemplo dos resultados de travessia e centralidade. Defina false para incluí-los. A análise de órfãos sempre aplica suas próprias exclusões de ruído mais rígidas.

exclude_generated_pathsOpcional

Tipo: bool
Padrão
Descrição: Excluir declarações geradas, além de construção, cobertura, cache, mapa de origem e caminhos de artefato minificados dos resultados de travessia

include_module_symbolsOpcional

Tipo: bool
Padrão
Descrição: Por padrão, false exclui bordas do gráfico quando from_name ou to_name é o símbolo sintético __module__ (ruído no nível do módulo). Defina true para incluir arestas de nível de módulo nos resultados para relacionamentos dependentes e de dependência.

branchOpcional

Tipo: str
Descrição: Substituição de branch

per_hop_limitOpcional

Tipo: int
Descrição: Máximo de relações por salto (1-300)

include_metricsOpcional

Tipo: bool
Padrão
Descrição: Métricas de grafo opcionais nas linhas de resultado (compactadas com refactor_risk). As métricas também são obtidas internamente quando min_centrality>0, mas só são retornadas se isto for true.

metrics_detailOpcional

Tipo: Literal[summary, full]
Padrão: summary
Descrição: Quando include_metrics=true: summary (padrão) retorna sinais de decisão + refactor_risk; full retorna o maior conjunto de métricas selecionadas

include_edge_metadataOpcional

Tipo: bool
Padrão
Descrição: Inclui metadados e pesos de borda bruta (grande). Cargas de impacto compacto deixam isso de lado.

symbol_typesOpcional

Tipo: list[str]
Descrição: Filtra os símbolos retornados por tipo (function, class, method etc.)

exact_matchOpcional

Tipo: bool
Padrão
Descrição: Exige correspondência exata do nome do símbolo (sem diferenciar maiúsculas/minúsculas). Desativa a correspondência aproximada

find_similar_patternsOpcional

Tipo: bool
Padrão
Descrição: Encontrar padrões de uso semelhantes

min_centralityOpcional

Tipo: float
Padrão: 0
Descrição: Pontuação mínima de PageRank. As métricas são obtidas internamente para filtragem; graph_metrics só é retornado quando include_metrics=true.

graph_viewOpcional

Tipo: Literal[dependency, type, data_flow, control_flow]
Padrão: dependency
Descrição: Visualização do grafo usada para os padrões de relacionamento de travessia, métricas e classificação de centralidade; a análise de órfãos é calculada em todas as visualizações

verify_after_editOpcional

Tipo: bool
Padrão
Descrição: Modo de verificação pós-edição P2-7: consulte novamente o gráfico de impacto indexado para símbolos editados recentemente em uma resposta multi-raiz compacta. Requer targets e/ou changed_paths (ou target/query). O padrão é a entrada superficial de dependentes; os resultados refletem o gráfico indexado (podem atrasar as edições ao vivo). Quando verdadeiro, tem precedência sobre o impacto de PR/diff no mesmo changed_paths.

targetsOpcional

Tipo: list[str]
Descrição: Quando verify_after_edit=true: nomes de símbolos a reverificar (chamadores/dependentes). Fundido com target/query se ambos forem fornecidos.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`repository`	`str`	Não	-	Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.
`query`	`str`	Não	-	Nome do símbolo ou termo de busca
`target`	`str`	Não	-	Nome do símbolo (alias de query)
`changed_paths`	`list[str]`	Não	-	Caminhos relativos ao repositório para impacto PR/diff (padrão) ou, com verify_after_edit=true, raízes de verificação pós-edição. PR/diff: resolve símbolos por caminho e percorre dependentes de entrada superficiais; pode ser combinado com patch=. Verificar: resolve até 5 símbolos por caminho como raízes de verificação (limitado inferior dentro do modo de verificação). Não requer query/target para impacto PR/diff.
`patch`	`str`	Não	-	Impacto PR/diff: texto de patch diff / git unificado. Os caminhos são analisados a partir dos cabeçalhos diff --git/---/+++; mesmo caminho de impacto compacto que changed_paths.
`analysis_type`	`Literal[centrality, dependencies, dependents, impact, orphans]`	Não	`dependencies`	Modo de análise. impact = raio de impacto (dependentes de entrada; profundidade superficial quando depth é omitido). dependents também responde a impact. Quando changed_paths ou patch é definido, a análise é forçada para o impacto PR/diff. centrality/orphans não exigem target.
`depth`	`Literal[shallow, balanced, deep]`	Não	`balanced`	Profundidade de travessia. Para analysis_type=impact e o impacto PR/diff, o padrão efetivo é shallow, a menos que você defina depth explicitamente.
`limit`	`int`	Não	`20`	Máximo de resultados retornados nesta página
`offset`	`int`	Não	-	Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.
`cursor`	`str`	Não	-	Cursor opaco de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.
`path_filter`	`str`	Não	-	Restringe a resolução do símbolo de destino pelo prefixo do caminho do arquivo; os relacionamentos de grafo retornados podem ultrapassar esse caminho.
`language_filter`	`str`	Não	-	Filtra a resolução do alvo e os resultados de navegação por linguagem
`direction`	`Literal[outgoing, incoming, both]`	Não	-	Direção da travessia (substitui a inferência de analysis_type)
`relationship_types`	`list[str]`	Não	-	Filtra os tipos de aresta (CALL, IMPORT, INHERITS_FROM etc.). Uma lista não vazia substitui os padrões de graph_view.
`exclude_test_paths`	`bool`	Não	`true`	Padrão true: exclui caminhos de teste, fixture, fornecedor e exemplo dos resultados de travessia e centralidade. Defina false para incluí-los. A análise de órfãos sempre aplica suas próprias exclusões de ruído mais rígidas.
`exclude_generated_paths`	`bool`	Não		Excluir declarações geradas, além de construção, cobertura, cache, mapa de origem e caminhos de artefato minificados dos resultados de travessia
`include_module_symbols`	`bool`	Não		Por padrão, false exclui bordas do gráfico quando from_name ou to_name é o símbolo sintético __module__ (ruído no nível do módulo). Defina true para incluir arestas de nível de módulo nos resultados para relacionamentos dependentes e de dependência.
`branch`	`str`	Não	-	Substituição de branch
`per_hop_limit`	`int`	Não	-	Máximo de relações por salto (1-300)
`include_metrics`	`bool`	Não		Métricas de grafo opcionais nas linhas de resultado (compactadas com refactor_risk). As métricas também são obtidas internamente quando min_centrality>0, mas só são retornadas se isto for true.
`metrics_detail`	`Literal[summary, full]`	Não	`summary`	Quando include_metrics=true: summary (padrão) retorna sinais de decisão + refactor_risk; full retorna o maior conjunto de métricas selecionadas
`include_edge_metadata`	`bool`	Não		Inclui metadados e pesos de borda bruta (grande). Cargas de impacto compacto deixam isso de lado.
`symbol_types`	`list[str]`	Não	-	Filtra os símbolos retornados por tipo (function, class, method etc.)
`exact_match`	`bool`	Não		Exige correspondência exata do nome do símbolo (sem diferenciar maiúsculas/minúsculas). Desativa a correspondência aproximada
`find_similar_patterns`	`bool`	Não		Encontrar padrões de uso semelhantes
`min_centrality`	`float`	Não	`0`	Pontuação mínima de PageRank. As métricas são obtidas internamente para filtragem; graph_metrics só é retornado quando include_metrics=true.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Não	`dependency`	Visualização do grafo usada para os padrões de relacionamento de travessia, métricas e classificação de centralidade; a análise de órfãos é calculada em todas as visualizações
`verify_after_edit`	`bool`	Não		Modo de verificação pós-edição P2-7: consulte novamente o gráfico de impacto indexado para símbolos editados recentemente em uma resposta multi-raiz compacta. Requer targets e/ou changed_paths (ou target/query). O padrão é a entrada superficial de dependentes; os resultados refletem o gráfico indexado (podem atrasar as edições ao vivo). Quando verdadeiro, tem precedência sobre o impacto de PR/diff no mesmo changed_paths.
`targets`	`list[str]`	Não	-	Quando verify_after_edit=true: nomes de símbolos a reverificar (chamadores/dependentes). Fundido com target/query se ambos forem fornecidos.

Melhor Para:

Análise de raio de impacto antes de editar um símbolo compartilhado
Impacto PR/diff via changed_paths e/ou patch
Verificação após a edição via verify_after_edit

Não Recomendado Para:

Buscas simples de texto ou símbolo — prefira text_pattern_search ou find_symbol

Ferramentas de Análise de Código#

find_symbolEstável

Vá para a definição e os usos de uma função, classe ou variável. Use quando souber o nome (por exemplo, “getCurrentUser”): é mais rápido e preciso que Grep e cobre todo o repositório indexado. Também pode retornar referências e métricas de importância.

Parâmetros:

symbol_nameOpcional

Tipo: str
Descrição: Nome do símbolo a pesquisar (opcional — omita para explorar por métricas)

repositoryOpcional

Tipo: str
Descrição: Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.

scopeOpcional

Tipo: Literal[definitions, references, both]
Padrão: both
Descrição: Escopo: definitions|references|both

limitOpcional

Tipo: int
Padrão: 15
Descrição: Máximo de resultados retornados nesta página

offsetOpcional

Tipo: int
Descrição: Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descrição: Cursor opaco de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.

find_similarOpcional

Tipo: bool
Padrão
Descrição: Encontrar símbolos similares

include_metricsOpcional

Tipo: bool
Padrão
Descrição: Incluir métricas de centralidade

metrics_detailOpcional

Tipo: Literal[summary, full]
Padrão: summary
Descrição: Quando include_metrics=true: summary (padrão) retorna sinais de decisão + refactor_risk; full retorna o maior conjunto de métricas selecionadas

path_filterOpcional

Tipo: str
Descrição: Filtrar por prefixo do caminho do arquivo

branchOpcional

Tipo: str
Descrição: Substituição de branch

symbol_typeOpcional

Tipo: Literal[function, class, variable, method, constant, module, interface, type]
Descrição: Filtro de tipo de símbolo

high_impactOpcional

Tipo: bool
Padrão
Descrição: Navega pelos símbolos arquiteturalmente importantes (omita symbol_name). O modo padrão é popularity (decil superior de PageRank menos os mega-hubs utilitários). Defina high_impact_mode=risk para pontos de articulação/arestas de ponte.

high_impact_modeOpcional

Tipo: Literal[popularity, risk]
Padrão: popularity
Descrição: Quando high_impact=true: popularidade = decil PageRank superior menos mega-hubs/módulos utilitários; risco = pontos de articulação classificados por SMV bridge_count e depois k_core (risco de refatoração estrutural, não popularidade do hub)

in_cycleOpcional

Tipo: bool
Padrão
Descrição: Apenas em ciclo

exclude_test_pathsOpcional

Tipo: bool
Padrão: true
Descrição: Ao navegar pelas métricas do grafo, exclua testes, fixtures, código de terceiros e exemplos antes da classificação. A busca de símbolos por nome permanece inalterada.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`symbol_name`	`str`	Não	-	Nome do símbolo a pesquisar (opcional — omita para explorar por métricas)
`repository`	`str`	Não	-	Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.
`scope`	`Literal[definitions, references, both]`	Não	`both`	Escopo: definitions\|references\|both
`limit`	`int`	Não	`15`	Máximo de resultados retornados nesta página
`offset`	`int`	Não	-	Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.
`cursor`	`str`	Não	-	Cursor opaco de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.
`find_similar`	`bool`	Não		Encontrar símbolos similares
`include_metrics`	`bool`	Não		Incluir métricas de centralidade
`metrics_detail`	`Literal[summary, full]`	Não	`summary`	Quando include_metrics=true: summary (padrão) retorna sinais de decisão + refactor_risk; full retorna o maior conjunto de métricas selecionadas
`path_filter`	`str`	Não	-	Filtrar por prefixo do caminho do arquivo
`branch`	`str`	Não	-	Substituição de branch
`symbol_type`	`Literal[function, class, variable, method, constant, module, interface, type]`	Não	-	Filtro de tipo de símbolo
`high_impact`	`bool`	Não		Navega pelos símbolos arquiteturalmente importantes (omita symbol_name). O modo padrão é popularity (decil superior de PageRank menos os mega-hubs utilitários). Defina high_impact_mode=risk para pontos de articulação/arestas de ponte.
`high_impact_mode`	`Literal[popularity, risk]`	Não	`popularity`	Quando high_impact=true: popularidade = decil PageRank superior menos mega-hubs/módulos utilitários; risco = pontos de articulação classificados por SMV bridge_count e depois k_core (risco de refatoração estrutural, não popularidade do hub)
`in_cycle`	`bool`	Não		Apenas em ciclo
`exclude_test_paths`	`bool`	Não	`true`	Ao navegar pelas métricas do grafo, exclua testes, fixtures, código de terceiros e exemplos antes da classificação. A busca de símbolos por nome permanece inalterada.

Melhor Para:

Localizar a definição, as referências e as métricas de grafo de um símbolo conhecido
Navegar por centrality, high_impact ou in_cycle quando symbol_name é omitido

Não Recomendado Para:

Consultas conceituais ou áreas desconhecidas — use intelligent_search ou semantic_search

analyze_dependenciesEstável

Alias para o raio de impacto via dependency_search (dependents/incoming). Prefira dependency_search com analysis_type="dependents" ou "impact" para novos agentes. Mantém o formato legado de resposta de impacto multi-salto (graph, connection_summary, métricas opcionais com refactor_risk). Use graph_view para delimitar a família de relações: dependency (padrão), type, data_flow, control_flow.

Parâmetros:

repositoryOpcional

Tipo: str
Descrição: Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.

targetObrigatório

Tipo: str
Descrição: Nome do símbolo a analisar

depthOpcional

Tipo: Literal[shallow, balanced, deep]
Padrão: balanced
Descrição: Profundidade da análise (suporta aliases: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)

limitOpcional

Tipo: int
Padrão: 10
Descrição: Máximo de resultados retornados nesta página

offsetOpcional

Tipo: int
Descrição: Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descrição: Cursor opaco de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.

directionOpcional

Tipo: Literal[incoming, outgoing, both]
Padrão: incoming
Descrição: Direção da travessia: 'outgoing' = do que este símbolo depende (suas dependências), 'incoming' = o que depende deste símbolo (seus dependentes), 'both' = contexto completo. Use 'incoming' para encontrar todos os chamadores/usuários de um símbolo.

relationship_typesOpcional

Tipo: list[str]
Descrição: Filtrar por tipos de aresta (CALL, IMPORT, INHERITS_FROM etc.). Quando fornecido, sempre substitui o padrão derivado de graph_view abaixo.

graph_viewOpcional

Tipo: Literal[dependency, type, data_flow, control_flow]
Padrão: dependency
Descrição: Visualização do grafo: quando include_metrics=true, determina os tipos de aresta de travessia padrão e a visualização cujas métricas serão usadas. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (padrão), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Só é aplicada como padrão de relationship_types quando relationship_types não é fornecido explicitamente. O nome coincide com o parâmetro graph_view existente de dependency_search para manter a consistência entre as ferramentas.

path_filterOpcional

Tipo: str
Descrição: Restringe a resolução do símbolo de destino pelo prefixo do caminho do arquivo; os relacionamentos de grafo retornados podem ultrapassar esse caminho.

language_filterOpcional

Tipo: str
Descrição: Restringe resultados a uma linguagem

branchOpcional

Tipo: str
Descrição: Substituição de branch

per_hop_limitOpcional

Tipo: int
Descrição: Máximo de relações por salto (1-300)

include_metricsOpcional

Tipo: bool
Padrão
Descrição: Incluir métricas do grafo nos resultados, cada uma enriquecida com um bloco refactor_risk derivado ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). O risco é "low" quando não é um ponto de articulação na visualização selecionada, "medium" quando é um ponto que conecta poucas arestas e "high" quando conecta muitas (limiar heurístico, não validado empiricamente). O bloco é omitido quando não há linha de métricas para o símbolo/visualização.

metrics_detailOpcional

Tipo: Literal[summary, full]
Padrão: summary
Descrição: Quando include_metrics=true: summary (padrão) retorna sinais de decisão + refactor_risk; full retorna o maior conjunto de métricas selecionadas

include_edge_metadataOpcional

Tipo: bool
Padrão
Descrição: Inclui metadados e pesos de borda bruta. Desativado por padrão porque os metadados do extrator podem ser grandes; a cobertura de enriquecimento é relatada quando habilitada.

exclude_test_pathsOpcional

Tipo: bool
Padrão: true
Descrição: Padrão true: exclui caminhos de teste, fixação, fornecedor e exemplo das bordas do gráfico retornadas. Defina false para incluí-los.

include_module_symbolsOpcional

Tipo: bool
Padrão
Descrição: Por padrão, false exclui arestas do gráfico quando from_name ou to_name é o símbolo sintético __module__. Defina true para incluir arestas no nível do módulo.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`repository`	`str`	Não	-	Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.
`target`	`str`	Sim	-	Nome do símbolo a analisar
`depth`	`Literal[shallow, balanced, deep]`	Não	`balanced`	Profundidade da análise (suporta aliases: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)
`limit`	`int`	Não	`10`	Máximo de resultados retornados nesta página
`offset`	`int`	Não	-	Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.
`cursor`	`str`	Não	-	Cursor opaco de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.
`direction`	`Literal[incoming, outgoing, both]`	Não	`incoming`	Direção da travessia: 'outgoing' = do que este símbolo depende (suas dependências), 'incoming' = o que depende deste símbolo (seus dependentes), 'both' = contexto completo. Use 'incoming' para encontrar todos os chamadores/usuários de um símbolo.
`relationship_types`	`list[str]`	Não	-	Filtrar por tipos de aresta (CALL, IMPORT, INHERITS_FROM etc.). Quando fornecido, sempre substitui o padrão derivado de graph_view abaixo.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Não	`dependency`	Visualização do grafo: quando include_metrics=true, determina os tipos de aresta de travessia padrão e a visualização cujas métricas serão usadas. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (padrão), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Só é aplicada como padrão de relationship_types quando relationship_types não é fornecido explicitamente. O nome coincide com o parâmetro graph_view existente de dependency_search para manter a consistência entre as ferramentas.
`path_filter`	`str`	Não	-	Restringe a resolução do símbolo de destino pelo prefixo do caminho do arquivo; os relacionamentos de grafo retornados podem ultrapassar esse caminho.
`language_filter`	`str`	Não	-	Restringe resultados a uma linguagem
`branch`	`str`	Não	-	Substituição de branch
`per_hop_limit`	`int`	Não	-	Máximo de relações por salto (1-300)
`include_metrics`	`bool`	Não		Incluir métricas do grafo nos resultados, cada uma enriquecida com um bloco refactor_risk derivado ({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). O risco é "low" quando não é um ponto de articulação na visualização selecionada, "medium" quando é um ponto que conecta poucas arestas e "high" quando conecta muitas (limiar heurístico, não validado empiricamente). O bloco é omitido quando não há linha de métricas para o símbolo/visualização.
`metrics_detail`	`Literal[summary, full]`	Não	`summary`	Quando include_metrics=true: summary (padrão) retorna sinais de decisão + refactor_risk; full retorna o maior conjunto de métricas selecionadas
`include_edge_metadata`	`bool`	Não		Inclui metadados e pesos de borda bruta. Desativado por padrão porque os metadados do extrator podem ser grandes; a cobertura de enriquecimento é relatada quando habilitada.
`exclude_test_paths`	`bool`	Não	`true`	Padrão true: exclui caminhos de teste, fixação, fornecedor e exemplo das bordas do gráfico retornadas. Defina false para incluí-los.
`include_module_symbols`	`bool`	Não		Por padrão, false exclui arestas do gráfico quando from_name ou to_name é o símbolo sintético __module__. Defina true para incluir arestas no nível do módulo.

Melhor Para:

Chamadores legados já preparados para seu formato de resposta (graph, connection_summary)

Não Recomendado Para:

Novos loops de agente — prefira dependency_search, que compartilha o mesmo núcleo de travessia

get_task_contextEstável

Vai começar em uma área desconhecida? Descreva a tarefa (por exemplo, “adicionar suporte a SSO” ou “corrigir o webhook de faturamento”) e receba em uma única chamada um pacote limitado de arquivos, código, símbolos e dependências relevantes. Os arquivos semente contribuem com conteúdo indexado direto mesmo quando não definem símbolos. Para mais resultados, continue com a ferramenta de busca especializada dessa camada.

Parâmetros:

task_descriptionObrigatório

Tipo: str
Descrição: Descrição da tarefa

repositoryOpcional

Tipo: str
Descrição: Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.

limitOpcional

Tipo: int
Padrão: 15
Descrição: Máximo de resultados por camada

scopeOpcional

Tipo: Literal[semantic, symbols, dependencies, all]
Padrão: all
Descrição: Camadas de contexto a incluir. Válido: 'semantic', 'symbols', 'dependencies', 'all'. Padrão: ['semantic', 'symbols', 'dependencies']

language_filterOpcional

Tipo: str
Descrição: Filtra resultados para arquivos detectados nesta linguagem de programação

path_filterOpcional

Tipo: str
Descrição: Filtrar por prefixo do caminho do arquivo

branchOpcional

Tipo: str
Descrição: Substituição de branch

include_related_contextOpcional

Tipo: bool
Padrão
Descrição: Incluir contexto relacionado de símbolos adjacentes

seed_symbol_idsOpcional

Tipo: list[str]
Descrição: Sementes explícitas de nível 1: IDs de símbolos que o agente já sabe serem centrais para a tarefa (por exemplo, símbolos em arquivos abertos). Elas são classificadas antes das sementes derivadas de palavras-chave nas camadas dependencies/related_context. É aditivo: omita para manter o comportamento atual baseado apenas em palavras-chave.

seed_file_pathsOpcional

Tipo: list[str]
Descrição: Sementes explícitas de nível 1: caminhos de arquivos indexados que o agente tem abertos ou acabou de editar. Retorna evidências diretas de arquivo limitadas e resolve até 5 símbolos por arquivo para o contexto do grafo, incluindo documentação e configuração sem símbolos. Aditivo — omita para um comportamento baseado apenas em palavras-chave.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`task_description`	`str`	Sim	-	Descrição da tarefa
`repository`	`str`	Não	-	Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.
`limit`	`int`	Não	`15`	Máximo de resultados por camada
`scope`	`Literal[semantic, symbols, dependencies, all]`	Não	`all`	Camadas de contexto a incluir. Válido: 'semantic', 'symbols', 'dependencies', 'all'. Padrão: ['semantic', 'symbols', 'dependencies']
`language_filter`	`str`	Não	-	Filtra resultados para arquivos detectados nesta linguagem de programação
`path_filter`	`str`	Não	-	Filtrar por prefixo do caminho do arquivo
`branch`	`str`	Não	-	Substituição de branch
`include_related_context`	`bool`	Não		Incluir contexto relacionado de símbolos adjacentes
`seed_symbol_ids`	`list[str]`	Não	-	Sementes explícitas de nível 1: IDs de símbolos que o agente já sabe serem centrais para a tarefa (por exemplo, símbolos em arquivos abertos). Elas são classificadas antes das sementes derivadas de palavras-chave nas camadas dependencies/related_context. É aditivo: omita para manter o comportamento atual baseado apenas em palavras-chave.
`seed_file_paths`	`list[str]`	Não	-	Sementes explícitas de nível 1: caminhos de arquivos indexados que o agente tem abertos ou acabou de editar. Retorna evidências diretas de arquivo limitadas e resolve até 5 símbolos por arquivo para o contexto do grafo, incluindo documentação e configuração sem símbolos. Aditivo — omita para um comportamento baseado apenas em palavras-chave.

Melhor Para:

Contexto ciente da tarefa que combina arquivos semente com camadas semânticas, de símbolos e de dependências

Não Recomendado Para:

Buscas com uma única ferramenta quando uma ferramenta mais específica já responde à pergunta

get_fileEstável

Leia um arquivo do repositório indexado pelo caminho. Prefira a ferramenta Read local para arquivos em disco — use esta para consultas remotas ou entre repositórios quando o arquivo não estiver na sua árvore de trabalho. Aceita um intervalo de linhas opcional; continue uma resposta truncada por tokens a partir de metadata.next_line_start.

Parâmetros:

file_pathObrigatório

Tipo: str
Descrição: Caminho do arquivo relativo à raiz do repositório

repositoryOpcional

Tipo: str
Descrição: Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.

line_startOpcional

Tipo: int
Descrição: Linha inicial (indexada a partir de 1)

line_endOpcional

Tipo: int
Descrição: Linha final (indexada a partir de 1, inclusive; deve ser igual ou posterior a line_start)

branchOpcional

Tipo: str
Descrição: Substituição de branch

max_tokensOpcional

Tipo: int
Padrão: 5000
Descrição: Máximo de tokens

include_metadataOpcional

Tipo: bool
Padrão: true
Descrição: Incluir metadados

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`file_path`	`str`	Sim	-	Caminho do arquivo relativo à raiz do repositório
`repository`	`str`	Não	-	Repositório no formato owner/repo[:branch]. Opcional — omita para usar o padrão do cliente no escopo da solicitação (quando fornecido) ou o único repositório acessível; informe explicitamente apenas para selecionar outro repositório indexado. A resposta mostra qual repositório foi usado.
`line_start`	`int`	Não	-	Linha inicial (indexada a partir de 1)
`line_end`	`int`	Não	-	Linha final (indexada a partir de 1, inclusive; deve ser igual ou posterior a line_start)
`branch`	`str`	Não	-	Substituição de branch
`max_tokens`	`int`	Não	`5000`	Máximo de tokens
`include_metadata`	`bool`	Não	`true`	Incluir metadados

Melhor Para:

Snapshots de arquivos remotos ou indexados (intervalos de linhas, limites de tokens)

Não Recomendado Para:

Um caminho já presente no disco local — use a ferramenta Read local

Ferramentas de Sistema e Utilitários#

repository_contextEstável

Liste os repositórios que você pode pesquisar, ou obtenha informações de identidade de um deles (namespace/branch, indexed_commit_sha / atualidade do índice). Chame com action:"list" uma vez para descobrir o identificador exato aceito pelas ferramentas de busca. (Se sua chave tiver apenas um repositório, ele será usado por padrão — você pode pular esta etapa.) As contagens de arquivos/blobs/arestas em todo o namespace são opcionais via include_statistics=true.

Parâmetros:

actionObrigatório

Tipo: Literal[list, info]
Descrição: Ação: listar repositórios disponíveis ou obter informações de um repositório

repositoryOpcional

Tipo: str
Descrição: Repositório no formato owner/repo ou owner/repo:branch (obrigatório para info)

branchOpcional

Tipo: str
Descrição: Substituição de branch

patternOpcional

Tipo: str
Descrição: Padrão de filtro

include_statisticsOpcional

Tipo: bool
Padrão
Descrição: Opcional: inclui as contagens de dados indexados em todo o namespace (arquivo/blob/aresta). Falso por padrão — a identidade do repositório não exige esse agregado mais lento.

limitOpcional

Tipo: int
Padrão: 20
Descrição: Máximo de resultados retornados nesta página

offsetOpcional

Tipo: int
Descrição: Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descrição: Opaco cursor de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`action`	`Literal[list, info]`	Sim	-	Ação: listar repositórios disponíveis ou obter informações de um repositório
`repository`	`str`	Não	-	Repositório no formato owner/repo ou owner/repo:branch (obrigatório para info)
`branch`	`str`	Não	-	Substituição de branch
`pattern`	`str`	Não	-	Padrão de filtro
`include_statistics`	`bool`	Não		Opcional: inclui as contagens de dados indexados em todo o namespace (arquivo/blob/aresta). Falso por padrão — a identidade do repositório não exige esse agregado mais lento.
`limit`	`int`	Não	`20`	Máximo de resultados retornados nesta página
`offset`	`int`	Não	-	Deslocamento de compatibilidade obsoleto. Prefira cursor de pagination.next_cursor.
`cursor`	`str`	Não	-	Opaco cursor de pagination.next_cursor. Passe-o inalterado e mantenha a consulta e os filtros inalterados.

Melhor Para:

Listar os repositórios acessíveis
Resolver a identidade do repositório, o branch e a atualidade de HEAD em relação ao índice

Não Recomendado Para:

Estatísticas de todo o namespace por padrão — passe include_statistics=true explicitamente, já que pode ser mais lento que a resolução

ask_maguyvaEstável

Ajuda e feedback do Maguyva. Uso principal: obter orientação sobre ferramentas, ou enviar um relatório de bug / uma solicitação de recurso armazenados para os mantenedores do Maguyva. Nunca inclua segredos ou dados pessoais sensíveis no feedback. A operação evaluate permanece apenas por retrocompatibilidade — prefira computação local ou ferramentas do host para tarefas de matemática/hash/string.

Parâmetros:

operationObrigatório

Tipo: Literal[guidance, report_bug, request_feature, evaluate]
Descrição: Principal: guidance, report_bug, request_feature. Apenas legado/compatibilidade: evaluate (motor de expressões determinístico; não faz parte do fluxo de trabalho principal do agente).

queryOpcional

Tipo: str
Descrição: Tópico de orientação (por exemplo, tool_selection, semantic_search). Apenas para evaluate legado: string de expressão.

descriptionOpcional

Tipo: str
Descrição: Obrigatório para report_bug e request_feature. Feedback Free-form para os mantenedores do Maguyva. Nunca inclua segredos ou dados pessoais sensíveis.

related_toolOpcional

Tipo: Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
Descrição: Ferramenta opcional Maguyva mais intimamente relacionada ao feedback

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`operation`	`Literal[guidance, report_bug, request_feature, evaluate]`	Sim	-	Principal: guidance, report_bug, request_feature. Apenas legado/compatibilidade: evaluate (motor de expressões determinístico; não faz parte do fluxo de trabalho principal do agente).
`query`	`str`	Não	-	Tópico de orientação (por exemplo, tool_selection, semantic_search). Apenas para evaluate legado: string de expressão.
`description`	`str`	Não	-	Obrigatório para report_bug e request_feature. Feedback Free-form para os mantenedores do Maguyva. Nunca inclua segredos ou dados pessoais sensíveis.
`related_tool`	`Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]`	Não	-	Ferramenta opcional Maguyva mais intimamente relacionada ao feedback

Melhor Para:

Orientação sobre ferramentas (operation="guidance")
Relatórios de bugs duradouros e solicitações de recursos para os mantenedores do Maguyva

Não Recomendado Para:

Cálculos matemáticos/hash/de string — a operação evaluate permanece apenas por retrocompatibilidade; prefira a computação local ou as ferramentas do host

Boas Práticas#

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.
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.
Aproveite os Filtros de Linguagem: Use language_filter para restringir resultados e melhorar a performance.
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 a classificação segura para agentes. Passe boost_by_importance=true para ativar a reclassificação baseada em centralidade em tours de arquitetura.
Correspondência de repositório ignora maiúsculas/minúsculas, mas não é aproximada: repository_context corresponde nomes de repositório sem diferenciar maiúsculas de minúsculas — não corrige erros de digitação. Verifique metadata.resolution_reason na ação info ("exact" vs "corrected") para ver como um nome foi resolvido.
Combine Ferramentas: Use vários métodos de API juntos para uma análise abrangente.
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).
Use o ask_maguyva para Orientação sobre Ferramentas: A operação evaluate de ask_maguyva (hash, base64, JSON, matemática) é apenas legado / retrocompatibilidade. Em vez disso, chame ask_maguyva com operation="guidance" e query="tool_selection" para obter a matriz de prioridade de ferramentas locais e um guia rápido completo, ferramenta por ferramenta.
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 reverificação compacta dos mesmos símbolos.

Características de Performance#

Operação	Notas de performance
Busca semântica	Menos de um segundo, mas inclui uma chamada em tempo real à API de embeddings a cada vez (sem cache) — espere latência extra além da consulta vetorial
Busca de texto	Menos de um segundo para busca exata/regex; a busca aproximada de conteúdo pagina no lado do cliente, então offsets profundos custam mais — restrinja com path_filter/language_filter
Busca estrutural	Indexada por AST — o custo escala com o volume de resultados, não com o tamanho do repositório
Busca de dependências	O custo escala com a profundidade — prefira depth="shallow", a menos que precise de contexto multi-hop; per_hop_limit limita a expansão
Recuperação de arquivo	Quase instantânea para um único arquivo — pagine arquivos grandes com line_start/line_end ou max_tokens em vez de uma única extração grande
Contexto de repositório	A resolução de namespace é armazenada em cache apenas por solicitação, não entre chamadas — cada invocação de ferramenta a resolve novamente
ask_maguyva (guidance / evaluate)	Quase instantâneo — roda dentro do Worker, sem chamada ao banco de dados

Tratamento de Erros#

Todos os métodos da API retornam um envelope estruturado:

status: String — "success" ou "error". Sinais de correspondência degradada ou de atualização ficam em campos aninhados como metadata.resolution_reason em repository_context ou metadata.index_freshness.status.
tool: Nome da ferramenta que gerou a resposta
data: Payload de resultado quando bem-sucedido (a estrutura varia por ferramenta)
error: Objeto de erro estruturado quando status é "error" — inclui type, message, suggestions e recovery_actions
metadata: Informações adicionais sobre a operação (roteamento, cache, ajustes de parâmetro)
pagination: Presente em respostas de listagem — inclui has_more e next_cursor

Sempre confira o campo status antes de processar os resultados — ele só pode ser "success" ou "error". Para sinais de correspondência degradada ou de atualização, consulte o campo aninhado: metadata.resolution_reason em repository_context, ou metadata.index_freshness.status (known/partial/unknown/unavailable).

Primeiros Passos#

Configure o Cliente MCP: Aponte seu cliente MCP para o endpoint do servidor Maguyva
Confirmar acesso ao repositório: Use repository_context com list ou info para verificar os repositórios disponíveis para a chave de API
Comece a Buscar: Comece com intelligent_search e explore ferramentas especializadas conforme necessário
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.