Referencia de la API de MCP

Referencia completa de las 11 herramientas MCP de Maguyva orientadas al cliente. Cada herramienta incluye parámetros, guía de uso y recomendaciones de para qué es mejor.

Resumen de la API#

La API MCP de Maguyva actualmente expone 11 herramientas orientadas al cliente en 4 categorías principales:

Herramientas de búsqueda principales - Capacidades de búsqueda avanzadas en todo tu codebase
Herramientas estructurales y de grafo - Consultas AST, búsqueda de símbolos y análisis de dependencias
Herramientas de análisis de código - Análisis profundo de código y mapeo de relaciones
Herramientas de sistema y utilidades - Contexto de repositorio, cómputo determinista y guía

Todas las herramientas usan un formato de identificador de repositorio consistente: "owner/repo:branch". La branch usa main por defecto si no se especifica.

Omite repository cuando el cliente MCP proporcione un valor predeterminado para la solicitud o la clave pueda acceder exactamente a un repositorio; de lo contrario, pásalo explícitamente. Usa repository_context(action="info", repository="owner/repo") para comprobar cómo se resuelve un repositorio.

Formato del parámetro de repositorio#

Todas las herramientas MCP usan este formato de identificador de repositorio:

Con branch: "owner/repo:branch" - por ej., "owner/repository:develop"
Branch por defecto: "owner/repo" - usa la branch main cuando no se especifica ninguna "owner/repository"
Valor predeterminado de la solicitud o del único repositorio: Omite el repositorio cuando el cliente MCP proporcione un valor predeterminado para la solicitud o la clave pueda acceder exactamente a un repositorio; de lo contrario, pásalo explícitamente

Ejemplos de prompts:

Pregunta sobre un repo específico:  "Busca middleware de autenticación en owner/my-repo"
Enumerar repositorios accesibles:   "¿A qué repositorios puede acceder esta clave de Maguyva?"
Anula para una sola consulta:       "Busca patrones de auth en owner/other-repo:develop"

Filtrado por lenguaje#

Todas las herramientas de búsqueda admiten filtrar resultados por lenguaje de programación:

language_filter="python" - Filtra solo archivos Python
language_filter="typescript" - Filtra solo archivos TypeScript
Sensible a mayúsculas: Usa nombres de lenguaje en minúsculas
Por defecto: Cadena vacía (sin filtro) - devuelve resultados de todos los lenguajes
Cobertura compatible: Los filtros de lenguaje funcionan en los más de 279 lenguajes y tecnologías basadas en texto compatibles. Consulta compatibilidad para ver la lista completa.

"Encuentra middleware de autenticación solo en archivos Python"
"Busca conexiones de base de datos en TypeScript"

Referencia de la API generada desde el código fuente el 22 de julio de 2026.

Herramientas de búsqueda principales#

intelligent_searchEstable

Empieza aquí para cualquier pregunta sobre el código. Escribe una consulta en lenguaje natural (p. ej., «cómo funciona la autenticación» o «dónde se gestiona la facturación») y se dirigirá automáticamente a la búsqueda semántica, de símbolos, estructural y de dependencias en todo el repositorio indexado. Para explorar y planificar, úsalo antes que el agente Explore y Grep/Glob: busca en todo el repositorio de una vez en lugar de recorrer archivos.

Parámetros:

queryRequerido

Tipo: str
Descripción: Consulta de búsqueda

repositoryOpcional

Tipo: str
Descripción: Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.

modeOpcional

Tipo: Literal[auto, hybrid, semantic, text, structural, ast, graph]
Predeterminado: auto
Descripción: Modo de búsqueda

limitOpcional

Tipo: int
Predeterminado: 10
Descripción: Máximo de resultados en esta ventana top-K clasificada

language_filterOpcional

Tipo: str
Descripción: Filtro de lenguaje

path_filterOpcional

Tipo: str
Descripción: Filtrar por prefijo de ruta de archivo

boost_by_importanceOpcional

Tipo: bool
Predeterminado
Descripción: Opcional: reordena por centralidad usando métricas de grafo por símbolo (is_articulation_point, bridge_count, k_core, centrality, etc.). Desactivado por defecto para un ranking seguro para agentes (los hubs globales pueden ahogar los resultados de implementación); actívalo para recorridos de arquitectura. Se aplica a las 4 modalidades cuando cada resultado lleva una vinculación de símbolo.

branchOpcional

Tipo: str
Descripción: Reemplazo de rama

qualityOpcional

Tipo: Literal[quick, balanced, thorough]
Predeterminado: balanced
Descripción: Calidad de búsqueda

include_contentOpcional

Tipo: bool
Predeterminado: true
Descripción: Incluir contenido en los resultados

explain_routingOpcional

Tipo: bool
Predeterminado
Descripción: Incluir la explicación de la decisión de enrutamiento

importance_weightOpcional

Tipo: float
Predeterminado: 0.3
Descripción: Peso del refuerzo por importancia (0=ninguno, 1=completo)

orphansOpcional

Tipo: bool
Predeterminado
Descripción: Devuelve símbolos sin referencias entrantes (posible código muerto). Útil para limpieza, pero puede incluir decoradores, funciones internas y puntos de entrada de CLI.

include_community_contextOpcional

Tipo: bool
Predeterminado
Descripción: Incluye símbolos relacionados de la misma comunidad de código para un contexto más amplio. Útil al explorar cómo funciona una feature o un módulo.

community_depthOpcional

Tipo: int
Predeterminado: 1
Descripción: Profundidad de expansión del contexto de comunidad

graph_viewOpcional

Tipo: Literal[dependency, type, data_flow, control_flow]
Predeterminado: dependency
Descripción: Vista del grafo para las métricas

seed_symbol_idsOpcional

Tipo: list[str]
Descripción: Semillas de tarea Tier-1: ID de símbolo centrales para la tarea actual. Cuando se configura, reclasifica los golpes fusionados por proximidad de caída de profundidad Approach A (coincidencia exacta de semillas + saltos de borde del gráfico). Aditivo: omitir para la clasificación global.

seed_file_pathsOpcional

Tipo: list[str]
Descripción: Semillas de tareas Tier-1: rutas de archivos indexadas que el agente ha abierto o acaba de editar. Cuando se configura, vuelve a clasificar los hits fusionados por proximidad de ruta con decaimiento de profundidad 1/(1+d) (mismo archivo → mismo directorio → paquetes cercanos). Aditivo: omitir para la clasificación global.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`query`	`str`	Sí	-	Consulta de búsqueda
`repository`	`str`	No	-	Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.
`mode`	`Literal[auto, hybrid, semantic, text, structural, ast, graph]`	No	`auto`	Modo de búsqueda
`limit`	`int`	No	`10`	Máximo de resultados en esta ventana top-K clasificada
`language_filter`	`str`	No	-	Filtro de lenguaje
`path_filter`	`str`	No	-	Filtrar por prefijo de ruta de archivo
`boost_by_importance`	`bool`	No		Opcional: reordena por centralidad usando métricas de grafo por símbolo (is_articulation_point, bridge_count, k_core, centrality, etc.). Desactivado por defecto para un ranking seguro para agentes (los hubs globales pueden ahogar los resultados de implementación); actívalo para recorridos de arquitectura. Se aplica a las 4 modalidades cuando cada resultado lleva una vinculación de símbolo.
`branch`	`str`	No	-	Reemplazo de rama
`quality`	`Literal[quick, balanced, thorough]`	No	`balanced`	Calidad de búsqueda
`include_content`	`bool`	No	`true`	Incluir contenido en los resultados
`explain_routing`	`bool`	No		Incluir la explicación de la decisión de enrutamiento
`importance_weight`	`float`	No	`0.3`	Peso del refuerzo por importancia (0=ninguno, 1=completo)
`orphans`	`bool`	No		Devuelve símbolos sin referencias entrantes (posible código muerto). Útil para limpieza, pero puede incluir decoradores, funciones internas y puntos de entrada de CLI.
`include_community_context`	`bool`	No		Incluye símbolos relacionados de la misma comunidad de código para un contexto más amplio. Útil al explorar cómo funciona una feature o un módulo.
`community_depth`	`int`	No	`1`	Profundidad de expansión del contexto de comunidad
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Vista del grafo para las métricas
`seed_symbol_ids`	`list[str]`	No	-	Semillas de tarea Tier-1: ID de símbolo centrales para la tarea actual. Cuando se configura, reclasifica los golpes fusionados por proximidad de caída de profundidad Approach A (coincidencia exacta de semillas + saltos de borde del gráfico). Aditivo: omitir para la clasificación global.
`seed_file_paths`	`list[str]`	No	-	Semillas de tareas Tier-1: rutas de archivos indexadas que el agente ha abierto o acaba de editar. Cuando se configura, vuelve a clasificar los hits fusionados por proximidad de ruta con decaimiento de profundidad 1/(1+d) (mismo archivo → mismo directorio → paquetes cercanos). Aditivo: omitir para la clasificación global.

Ideal para:

Exploración de todo el índice o en arranque en frío cuando no está claro qué herramienta usar
Clasificación fusionada multimodal entre búsqueda semántica, textual, estructural y de grafo

No recomendada para:

Un nombre de símbolo conocido — usa find_symbol directamente
Una ruta conocida en disco — usa primero Read/Grep en local

semantic_searchEstable

Encuentra código por su significado, no por texto exacto. Úsalo para consultas conceptuales como «lógica de reintentos» o «flujo de incorporación de usuarios» cuando no conozcas la palabra clave o el símbolo. Devuelve los fragmentos más pertinentes ordenados por importancia. Para búsquedas conceptuales, úsalo antes que Grep.

Parámetros:

queryRequerido

Tipo: str
Descripción: Consulta de búsqueda (conceptual, basada en el significado)

repositoryOpcional

Tipo: str
Descripción: Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.

limitOpcional

Tipo: int
Predeterminado: 5
Descripción: Máximo de resultados en esta ventana top-K clasificada

similarity_thresholdOpcional

Tipo: float
Predeterminado: 0.6
Descripción: Puntaje mínimo de similitud

language_filterOpcional

Tipo: str
Descripción: Filtra los resultados a archivos detectados como este lenguaje de programación

path_filterOpcional

Tipo: str
Descripción: Filtrar por prefijo de ruta de archivo

boost_by_importanceOpcional

Tipo: bool
Predeterminado
Descripción: Opcional: reordena por centralidad PageRank (desactivado por defecto para un ranking seguro para agentes; actívalo para recorridos de arquitectura)

branchOpcional

Tipo: str
Descripción: Reemplazo de rama (predeterminado: parámetro repository o main)

include_contentOpcional

Tipo: bool
Predeterminado: true
Descripción: Incluir el contenido de los fragmentos en los resultados

graph_viewOpcional

Tipo: Literal[dependency, type, data_flow, control_flow]
Predeterminado: dependency
Descripción: Vista del grafo para las métricas

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`query`	`str`	Sí	-	Consulta de búsqueda (conceptual, basada en el significado)
`repository`	`str`	No	-	Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.
`limit`	`int`	No	`5`	Máximo de resultados en esta ventana top-K clasificada
`similarity_threshold`	`float`	No	`0.6`	Puntaje mínimo de similitud
`language_filter`	`str`	No	-	Filtra los resultados a archivos detectados como este lenguaje de programación
`path_filter`	`str`	No	-	Filtrar por prefijo de ruta de archivo
`boost_by_importance`	`bool`	No		Opcional: reordena por centralidad PageRank (desactivado por defecto para un ranking seguro para agentes; actívalo para recorridos de arquitectura)
`branch`	`str`	No	-	Reemplazo de rama (predeterminado: parámetro repository o main)
`include_content`	`bool`	No	`true`	Incluir el contenido de los fragmentos en los resultados
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Vista del grafo para las métricas

Ideal para:

Consultas conceptuales («¿cómo funciona la autenticación?», «estrategia de caché»)
Búsqueda de similitud entre paquetes

No recomendada para:

Un nombre de símbolo conocido — usa find_symbol en su lugar
Cadenas exactas o mensajes de error — usa text_pattern_search

text_pattern_searchEstable

Busca en el contenido indexado. Los modos exact y regex recorren todo el corpus de archivos/blobs; fuzzy content busca en el corpus acotado de fragmentos semánticos. Los ámbitos de archivo y símbolo solo admiten fuzzy. Usa Grep local para un directorio reducido que ya esté en disco.

Parámetros:

queryRequerido

Tipo: str
Descripción: Patrón de texto

repositoryOpcional

Tipo: str
Descripción: Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.

modeOpcional

Tipo: Literal[fuzzy, exact, regex]
Predeterminado: exact
Descripción: Modo de búsqueda

search_scopeOpcional

Tipo: Literal[content, symbols, files]
Predeterminado: content
Descripción: Qué buscar

limitOpcional

Tipo: int
Predeterminado: 5
Descripción: Máximo de resultados devueltos en esta página

offsetOpcional

Tipo: int
Descripción: Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descripción: Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.

language_filterOpcional

Tipo: str
Descripción: Filtro de lenguaje

path_filterOpcional

Tipo: str
Descripción: Filtrar por prefijo de ruta de archivo

case_sensitiveOpcional

Tipo: bool
Predeterminado
Descripción: Sensible a mayúsculas y minúsculas

branchOpcional

Tipo: str
Descripción: Reemplazo de rama

fuzzy_algorithmOpcional

Tipo: Literal[hybrid, trigram, levenshtein]
Predeterminado: hybrid
Descripción: Algoritmo de coincidencia aproximada

thresholdOpcional

Tipo: float
Predeterminado: 0.05
Descripción: Umbral mínimo de similitud para la búsqueda aproximada

semantic_fallbackOpcional

Tipo: bool
Predeterminado
Descripción: Recurrir a la búsqueda semántica si no hay resultados

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`query`	`str`	Sí	-	Patrón de texto
`repository`	`str`	No	-	Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.
`mode`	`Literal[fuzzy, exact, regex]`	No	`exact`	Modo de búsqueda
`search_scope`	`Literal[content, symbols, files]`	No	`content`	Qué buscar
`limit`	`int`	No	`5`	Máximo de resultados devueltos en esta página
`offset`	`int`	No	-	Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.
`cursor`	`str`	No	-	Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.
`language_filter`	`str`	No	-	Filtro de lenguaje
`path_filter`	`str`	No	-	Filtrar por prefijo de ruta de archivo
`case_sensitive`	`bool`	No		Sensible a mayúsculas y minúsculas
`branch`	`str`	No	-	Reemplazo de rama
`fuzzy_algorithm`	`Literal[hybrid, trigram, levenshtein]`	No	`hybrid`	Algoritmo de coincidencia aproximada
`threshold`	`float`	No	`0.05`	Umbral mínimo de similitud para la búsqueda aproximada
`semantic_fallback`	`bool`	No		Recurrir a la búsqueda semántica si no hay resultados

Ideal para:

Cadenas exactas, mensajes de error y regex
Coincidencia difusa por trigramas para texto casi coincidente

No recomendada para:

Una ruta conocida en disco — prefiere Grep en local
Consultas conceptuales — usa semantic_search

Herramientas estructurales y de grafo#

structural_searchEstable

Prefiere preset=functions|classes|methods|imports|variables (o pattern= libre). Encuentra código por su forma AST (no por texto). Filtros de nivel intermedio: name_pattern, node_type, decorator, parent_child. Los filtros de ruta/ltree/llamada son avanzados — establece advanced=true cuando los uses deliberadamente; las claves avanzadas planas se siguen aceptando por retrocompatibilidad. Proporciona al menos un selector estructural.

Parámetros:

repositoryOpcional

Tipo: str
Descripción: Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.

presetOpcional

Tipo: Literal[functions, classes, methods, imports, variables]
Descripción: Selector estructural preferido. Se expande a tipos de nodo AST multilenguaje — functions (definiciones de función/flecha/método según el lenguaje); classes (definiciones de clase/struct/impl); methods (definiciones de método, y function_definition para lenguajes sin nodo de método); imports (sentencias import/use/include); variables (declaraciones variable/let/const/static). Prefiérelo sobre pattern/node_type libre para consultas de tipo exploración.

patternOpcional

Tipo: str
Descripción: Patrón Free-form cuando los presets son demasiado generales (detección automática: 'def foo(' → node_type + name_pattern). Prefiere preset= para consultas de exploración.

name_patternOpcional

Tipo: str
Descripción: Patrón del nombre del símbolo (comodín de shell, expresión regular POSIX acotada o texto aproximado; máximo 256 caracteres)

node_typeOpcional

Tipo: str
Descripción: Tipo de nodo AST (function_definition, class_definition, etc.) — prefiere preset= para formas comunes

decoratorOpcional

Tipo: str
Descripción: Filtro por nombre de decorador

base_classOpcional

Tipo: str
Descripción: Filtro por nombre de clase base (encuentra clases que heredan de esta)

language_filterOpcional

Tipo: str
Descripción: Filtro de lenguaje

limitOpcional

Tipo: int
Predeterminado: 20
Descripción: Máximo de resultados devueltos en esta página

offsetOpcional

Tipo: int
Descripción: Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descripción: Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.

path_filterOpcional

Tipo: str
Descripción: Filtrar por prefijo de ruta de archivo

branchOpcional

Tipo: str
Descripción: Reemplazo de rama

query_typeOpcional

Tipo: Literal[node_type, name_pattern, parent_child]
Descripción: Tipo de consulta explícito

parent_typeOpcional

Tipo: str
Descripción: Filtro del tipo de nodo AST padre

relationshipOpcional

Tipo: Literal[parent, ancestor]
Predeterminado: parent
Descripción: Para consultas parent_child: solo el padre directo o cualquier ancestro (usa ancestor para métodos de clase anidados bajo el cuerpo/bloque de una clase)

has_modifierOpcional

Tipo: str
Descripción: Filtrar por modificador (export, async, static, etc.)

advancedOpcional

Tipo: bool
Predeterminado
Descripción: Establece true al usar intencionadamente filtros avanzados de rutas/ltree/llamadas (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). El valor predeterminado false mantiene la interfaz del agente orientada primero a presets; las claves avanzadas planas siguen admitiéndose por retrocompatibilidad, con una advertencia en los metadatos.

callee_textOpcional

Tipo: str
Descripción: Avanzado — prefiere preset=functions|classes|methods|imports|variables. Filtro de texto del callee de una expresión de llamada. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.

callee_nameOpcional

Tipo: str
Descripción: Avanzado — prefiere preset=functions|classes|methods|imports|variables. Filtro de nombre del callee de una expresión de llamada. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.

field_roleOpcional

Tipo: str
Descripción: Avanzado — prefiere preset=functions|classes|methods|imports|variables. Filtro de rol de campo AST. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.

ltree_ancestorOpcional

Tipo: str
Descripción: Avanzado — prefiere preset=functions|classes|methods|imports|variables. Filtro de ruta ancestro AST ltree. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.

ltree_descendantOpcional

Tipo: str
Descripción: Avanzado — prefiere preset=functions|classes|methods|imports|variables. Filtro de ruta descendiente AST ltree. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.

definition_nameOpcional

Tipo: str
Descripción: Avanzado — prefiere preset=functions|classes|methods|imports|variables. Filtro de nombre de definición. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.

min_depthOpcional

Tipo: int
Descripción: Avanzado — prefiere preset=functions|classes|methods|imports|variables. Profundidad AST mínima. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.

max_depthOpcional

Tipo: int
Descripción: Avanzado — prefiere preset=functions|classes|methods|imports|variables. Profundidad AST máxima. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`repository`	`str`	No	-	Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.
`preset`	`Literal[functions, classes, methods, imports, variables]`	No	-	Selector estructural preferido. Se expande a tipos de nodo AST multilenguaje — functions (definiciones de función/flecha/método según el lenguaje); classes (definiciones de clase/struct/impl); methods (definiciones de método, y function_definition para lenguajes sin nodo de método); imports (sentencias import/use/include); variables (declaraciones variable/let/const/static). Prefiérelo sobre pattern/node_type libre para consultas de tipo exploración.
`pattern`	`str`	No	-	Patrón Free-form cuando los presets son demasiado generales (detección automática: 'def foo(' → node_type + name_pattern). Prefiere preset= para consultas de exploración.
`name_pattern`	`str`	No	-	Patrón del nombre del símbolo (comodín de shell, expresión regular POSIX acotada o texto aproximado; máximo 256 caracteres)
`node_type`	`str`	No	-	Tipo de nodo AST (function_definition, class_definition, etc.) — prefiere preset= para formas comunes
`decorator`	`str`	No	-	Filtro por nombre de decorador
`base_class`	`str`	No	-	Filtro por nombre de clase base (encuentra clases que heredan de esta)
`language_filter`	`str`	No	-	Filtro de lenguaje
`limit`	`int`	No	`20`	Máximo de resultados devueltos en esta página
`offset`	`int`	No	-	Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.
`cursor`	`str`	No	-	Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.
`path_filter`	`str`	No	-	Filtrar por prefijo de ruta de archivo
`branch`	`str`	No	-	Reemplazo de rama
`query_type`	`Literal[node_type, name_pattern, parent_child]`	No	-	Tipo de consulta explícito
`parent_type`	`str`	No	-	Filtro del tipo de nodo AST padre
`relationship`	`Literal[parent, ancestor]`	No	`parent`	Para consultas parent_child: solo el padre directo o cualquier ancestro (usa ancestor para métodos de clase anidados bajo el cuerpo/bloque de una clase)
`has_modifier`	`str`	No	-	Filtrar por modificador (export, async, static, etc.)
`advanced`	`bool`	No		Establece true al usar intencionadamente filtros avanzados de rutas/ltree/llamadas (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). El valor predeterminado false mantiene la interfaz del agente orientada primero a presets; las claves avanzadas planas siguen admitiéndose por retrocompatibilidad, con una advertencia en los metadatos.
`callee_text`	`str`	No	-	Avanzado — prefiere preset=functions\|classes\|methods\|imports\|variables. Filtro de texto del callee de una expresión de llamada. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.
`callee_name`	`str`	No	-	Avanzado — prefiere preset=functions\|classes\|methods\|imports\|variables. Filtro de nombre del callee de una expresión de llamada. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.
`field_role`	`str`	No	-	Avanzado — prefiere preset=functions\|classes\|methods\|imports\|variables. Filtro de rol de campo AST. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.
`ltree_ancestor`	`str`	No	-	Avanzado — prefiere preset=functions\|classes\|methods\|imports\|variables. Filtro de ruta ancestro AST ltree. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.
`ltree_descendant`	`str`	No	-	Avanzado — prefiere preset=functions\|classes\|methods\|imports\|variables. Filtro de ruta descendiente AST ltree. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.
`definition_name`	`str`	No	-	Avanzado — prefiere preset=functions\|classes\|methods\|imports\|variables. Filtro de nombre de definición. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.
`min_depth`	`int`	No	-	Avanzado — prefiere preset=functions\|classes\|methods\|imports\|variables. Profundidad AST mínima. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.
`max_depth`	`int`	No	-	Avanzado — prefiere preset=functions\|classes\|methods\|imports\|variables. Profundidad AST máxima. Establece advanced=true cuando uses intencionadamente filtros de ruta/ltree/llamada.

Ideal para:

Estructura a nivel de AST: clases, decoradores, presets de function/method
Encontrar código por su forma en lugar de por su texto

No recomendada para:

Consultas de texto libre o conceptuales — usa semantic_search o intelligent_search

dependency_searchEstable

Superficie principal de radio de impacto / grafo. Responde «¿qué llama a esto?» / «¿qué usa esto?» mediante el grafo real de llamadas/importaciones. Para el impacto antes de editar: analysis_type="dependents" o analysis_type="impact" (entrante, profundidad superficial por defecto para impact), include_metrics=false por defecto (actívalo para centralidad + refactor_risk). Impacto PR/diff (P1-8): pasa changed_paths y/o patch (diff unificado) — resuelve símbolos por ruta y devuelve una carga compacta de dependientes entrantes superficiales sin necesitar un nombre de símbolo. Tras una edición, establece verify_after_edit=true con targets y/o changed_paths para una nueva consulta compacta multi-raíz de los símbolos impactados. También admite dependencies, centrality y orphans. analyze_dependencies es un alias ligero de la ruta impact — prefiere esta herramienta para agentes nuevos.

Parámetros:

repositoryOpcional

Tipo: str
Descripción: Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.

queryOpcional

Tipo: str
Descripción: Nombre de símbolo o término de búsqueda

targetOpcional

Tipo: str
Descripción: Nombre del símbolo (alias de query)

changed_pathsOpcional

Tipo: list[str]
Descripción: Rutas relativas al repositorio para el impacto PR/diff (predeterminado) o, con verify_after_edit=true, raíces de verificación posteriores a la edición. PR/diff: resuelve símbolos por ruta y recorre los dependientes entrantes superficiales; se puede combinar con patch=. Verificar: resuelve hasta 5 símbolos por ruta como raíces de verificación (con un límite inferior dentro del modo de verificación). No requiere query/target para impacto PR/diff.

patchOpcional

Tipo: str
Descripción: Impacto de PR/diff: texto de parche unificado de diferencias y git. Las rutas se analizan a partir de los encabezados diff --git / --- / +++; La misma trayectoria de impacto compacta que changed_paths.

analysis_typeOpcional

Tipo: Literal[centrality, dependencies, dependents, impact, orphans]
Predeterminado: dependencies
Descripción: Modo de análisis. impact = radio de impacto (dependientes entrantes; profundidad superficial cuando se omite depth). dependents también responde a impact. Cuando se define changed_paths o patch, el análisis se fuerza al impacto PR/diff. centrality/orphans no requieren target.

depthOpcional

Tipo: Literal[shallow, balanced, deep]
Predeterminado: balanced
Descripción: Profundidad de recorrido. Para analysis_type=impact y el impacto PR/diff, el valor predeterminado efectivo es shallow a menos que definas depth explícitamente.

limitOpcional

Tipo: int
Predeterminado: 20
Descripción: Máximo de resultados devueltos en esta página

offsetOpcional

Tipo: int
Descripción: Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descripción: Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.

path_filterOpcional

Tipo: str
Descripción: Restringe la resolución del símbolo objetivo por prefijo de ruta de archivo; las relaciones del grafo devueltas pueden salir de esa ruta.

language_filterOpcional

Tipo: str
Descripción: Filtra la resolución del objetivo y los resultados de exploración por lenguaje

directionOpcional

Tipo: Literal[outgoing, incoming, both]
Descripción: Dirección de recorrido (reemplaza la inferencia de analysis_type)

relationship_typesOpcional

Tipo: list[str]
Descripción: Filtra los tipos de arista (CALL, IMPORT, INHERITS_FROM, etc.). Una lista no vacía sustituye los valores predeterminados de graph_view.

exclude_test_pathsOpcional

Tipo: bool
Predeterminado: true
Descripción: Por defecto true: excluye rutas de test, fixture, proveedor y ejemplo de los resultados de recorrido y centralidad. Establece false para incluirlas. El análisis de huérfanos siempre aplica sus propias exclusiones de ruido más estrictas.

exclude_generated_pathsOpcional

Tipo: bool
Predeterminado
Descripción: Excluir de los resultados del recorrido las declaraciones generadas, además de las rutas de compilación, cobertura, caché, mapa de origen y artefactos minimizados.

include_module_symbolsOpcional

Tipo: bool
Predeterminado
Descripción: Valor predeterminado false: descarta las aristas cuyo from_name o to_name sea el símbolo sintético __module__ (ruido de nivel de módulo). Establece true para incluir aristas de nivel de módulo en los resultados de dependientes/dependencias.

branchOpcional

Tipo: str
Descripción: Reemplazo de rama

per_hop_limitOpcional

Tipo: int
Descripción: Máximo de relaciones por salto (1-300)

include_metricsOpcional

Tipo: bool
Predeterminado
Descripción: Métricas de grafo opcionales en las filas de resultados (compactadas con refactor_risk). Las métricas también se obtienen internamente cuando min_centrality>0, pero solo se devuelven si esto es true.

metrics_detailOpcional

Tipo: Literal[summary, full]
Predeterminado: summary
Descripción: Cuando include_metrics=true: summary (predeterminado) devuelve señales de decisión + refactor_risk; full devuelve el conjunto seleccionado más amplio de métricas.

include_edge_metadataOpcional

Tipo: bool
Predeterminado
Descripción: Incluye los metadatos y pesos sin procesar de las aristas (grandes). Las cargas útiles compactas del radio de impacto lo dejan desactivado.

symbol_typesOpcional

Tipo: list[str]
Descripción: Filtra los símbolos devueltos por tipo (function, class, method, etc.)

exact_matchOpcional

Tipo: bool
Predeterminado
Descripción: Exige coincidencia exacta del nombre del símbolo (sin distinguir mayúsculas/minúsculas). Desactiva la coincidencia difusa

find_similar_patternsOpcional

Tipo: bool
Predeterminado
Descripción: Encontrar patrones de uso similares

min_centralityOpcional

Tipo: float
Predeterminado: 0
Descripción: Puntuación mínima de PageRank. Las métricas se obtienen internamente para el filtrado; graph_metrics solo se devuelve cuando include_metrics=true.

graph_viewOpcional

Tipo: Literal[dependency, type, data_flow, control_flow]
Predeterminado: dependency
Descripción: Vista del grafo usada para los valores predeterminados de las relaciones de recorrido, las métricas y la clasificación de centralidad; el análisis de huérfanos se calcula en todas las vistas

verify_after_editOpcional

Tipo: bool
Predeterminado
Descripción: Modo de verificación posedición P2-7: vuelva a consultar el gráfico de impacto indexado para símbolos editados recientemente en una respuesta compacta de múltiples raíces. Requiere targets y/o changed_paths (o target/query). Por defecto, los dependientes entrantes son poco profundos; los resultados reflejan el gráfico indexado (pueden retrasarse las ediciones en vivo). Cuando es verdadero, tiene prioridad sobre el impacto de PR/diff en el mismo changed_paths.

targetsOpcional

Tipo: list[str]
Descripción: Cuando verify_after_edit=true: nombres de símbolos para volver a verificar (personas que llaman/dependientes). Fusionado con target/query si se suministran ambos.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`repository`	`str`	No	-	Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.
`query`	`str`	No	-	Nombre de símbolo o término de búsqueda
`target`	`str`	No	-	Nombre del símbolo (alias de query)
`changed_paths`	`list[str]`	No	-	Rutas relativas al repositorio para el impacto PR/diff (predeterminado) o, con verify_after_edit=true, raíces de verificación posteriores a la edición. PR/diff: resuelve símbolos por ruta y recorre los dependientes entrantes superficiales; se puede combinar con patch=. Verificar: resuelve hasta 5 símbolos por ruta como raíces de verificación (con un límite inferior dentro del modo de verificación). No requiere query/target para impacto PR/diff.
`patch`	`str`	No	-	Impacto de PR/diff: texto de parche unificado de diferencias y git. Las rutas se analizan a partir de los encabezados diff --git / --- / +++; La misma trayectoria de impacto compacta que changed_paths.
`analysis_type`	`Literal[centrality, dependencies, dependents, impact, orphans]`	No	`dependencies`	Modo de análisis. impact = radio de impacto (dependientes entrantes; profundidad superficial cuando se omite depth). dependents también responde a impact. Cuando se define changed_paths o patch, el análisis se fuerza al impacto PR/diff. centrality/orphans no requieren target.
`depth`	`Literal[shallow, balanced, deep]`	No	`balanced`	Profundidad de recorrido. Para analysis_type=impact y el impacto PR/diff, el valor predeterminado efectivo es shallow a menos que definas depth explícitamente.
`limit`	`int`	No	`20`	Máximo de resultados devueltos en esta página
`offset`	`int`	No	-	Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.
`cursor`	`str`	No	-	Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.
`path_filter`	`str`	No	-	Restringe la resolución del símbolo objetivo por prefijo de ruta de archivo; las relaciones del grafo devueltas pueden salir de esa ruta.
`language_filter`	`str`	No	-	Filtra la resolución del objetivo y los resultados de exploración por lenguaje
`direction`	`Literal[outgoing, incoming, both]`	No	-	Dirección de recorrido (reemplaza la inferencia de analysis_type)
`relationship_types`	`list[str]`	No	-	Filtra los tipos de arista (CALL, IMPORT, INHERITS_FROM, etc.). Una lista no vacía sustituye los valores predeterminados de graph_view.
`exclude_test_paths`	`bool`	No	`true`	Por defecto true: excluye rutas de test, fixture, proveedor y ejemplo de los resultados de recorrido y centralidad. Establece false para incluirlas. El análisis de huérfanos siempre aplica sus propias exclusiones de ruido más estrictas.
`exclude_generated_paths`	`bool`	No		Excluir de los resultados del recorrido las declaraciones generadas, además de las rutas de compilación, cobertura, caché, mapa de origen y artefactos minimizados.
`include_module_symbols`	`bool`	No		Valor predeterminado false: descarta las aristas cuyo from_name o to_name sea el símbolo sintético __module__ (ruido de nivel de módulo). Establece true para incluir aristas de nivel de módulo en los resultados de dependientes/dependencias.
`branch`	`str`	No	-	Reemplazo de rama
`per_hop_limit`	`int`	No	-	Máximo de relaciones por salto (1-300)
`include_metrics`	`bool`	No		Métricas de grafo opcionales en las filas de resultados (compactadas con refactor_risk). Las métricas también se obtienen internamente cuando min_centrality>0, pero solo se devuelven si esto es true.
`metrics_detail`	`Literal[summary, full]`	No	`summary`	Cuando include_metrics=true: summary (predeterminado) devuelve señales de decisión + refactor_risk; full devuelve el conjunto seleccionado más amplio de métricas.
`include_edge_metadata`	`bool`	No		Incluye los metadatos y pesos sin procesar de las aristas (grandes). Las cargas útiles compactas del radio de impacto lo dejan desactivado.
`symbol_types`	`list[str]`	No	-	Filtra los símbolos devueltos por tipo (function, class, method, etc.)
`exact_match`	`bool`	No		Exige coincidencia exacta del nombre del símbolo (sin distinguir mayúsculas/minúsculas). Desactiva la coincidencia difusa
`find_similar_patterns`	`bool`	No		Encontrar patrones de uso similares
`min_centrality`	`float`	No	`0`	Puntuación mínima de PageRank. Las métricas se obtienen internamente para el filtrado; graph_metrics solo se devuelve cuando include_metrics=true.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Vista del grafo usada para los valores predeterminados de las relaciones de recorrido, las métricas y la clasificación de centralidad; el análisis de huérfanos se calcula en todas las vistas
`verify_after_edit`	`bool`	No		Modo de verificación posedición P2-7: vuelva a consultar el gráfico de impacto indexado para símbolos editados recientemente en una respuesta compacta de múltiples raíces. Requiere targets y/o changed_paths (o target/query). Por defecto, los dependientes entrantes son poco profundos; los resultados reflejan el gráfico indexado (pueden retrasarse las ediciones en vivo). Cuando es verdadero, tiene prioridad sobre el impacto de PR/diff en el mismo changed_paths.
`targets`	`list[str]`	No	-	Cuando verify_after_edit=true: nombres de símbolos para volver a verificar (personas que llaman/dependientes). Fusionado con target/query si se suministran ambos.

Ideal para:

Análisis de radio de impacto antes de editar un símbolo compartido
Impacto PR/diff mediante changed_paths o patch
Verificación tras la edición mediante verify_after_edit

No recomendada para:

Búsquedas simples de texto o símbolos — usa text_pattern_search o find_symbol

Herramientas de análisis de código#

find_symbolEstable

Salta a la definición y los usos de una función, clase o variable. Úsalo cuando conozcas el nombre (p. ej., «getCurrentUser»): es más rápido y preciso que Grep y abarca todo el repositorio indexado. También puede devolver referencias y métricas de importancia.

Parámetros:

symbol_nameOpcional

Tipo: str
Descripción: Nombre del símbolo que se buscará (opcional — omítelo para explorar por métricas)

repositoryOpcional

Tipo: str
Descripción: Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.

scopeOpcional

Tipo: Literal[definitions, references, both]
Predeterminado: both
Descripción: Ámbito: definitions|references|both

limitOpcional

Tipo: int
Predeterminado: 15
Descripción: Máximo de resultados devueltos en esta página

offsetOpcional

Tipo: int
Descripción: Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descripción: Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.

find_similarOpcional

Tipo: bool
Predeterminado
Descripción: Buscar símbolos similares

include_metricsOpcional

Tipo: bool
Predeterminado
Descripción: Incluir métricas de centralidad

metrics_detailOpcional

Tipo: Literal[summary, full]
Predeterminado: summary
Descripción: Cuando include_metrics=true: summary (predeterminado) devuelve señales de decisión + refactor_risk; full devuelve el conjunto seleccionado más amplio de métricas.

path_filterOpcional

Tipo: str
Descripción: Filtrar por prefijo de ruta de archivo

branchOpcional

Tipo: str
Descripción: Reemplazo de rama

symbol_typeOpcional

Tipo: Literal[function, class, variable, method, constant, module, interface, type]
Descripción: Filtro por tipo de símbolo

high_impactOpcional

Tipo: bool
Predeterminado
Descripción: Explora los símbolos arquitectónicamente importantes (omite symbol_name). El modo predeterminado es popularity (decil superior de PageRank menos los megacentros de utilidad). Establece high_impact_mode=risk para puntos de articulación/aristas puente.

high_impact_modeOpcional

Tipo: Literal[popularity, risk]
Predeterminado: popularity
Descripción: Cuando high_impact=true: popularidad = decil superior de PageRank menos megacentros/módulos de utilidad; riesgo = puntos de articulación clasificados por SMV bridge_count y luego k_core (riesgo de refactor estructural, no popularidad del centro)

in_cycleOpcional

Tipo: bool
Predeterminado
Descripción: Solo en ciclo

exclude_test_pathsOpcional

Tipo: bool
Predeterminado: true
Descripción: Al explorar por métricas del grafo, excluye tests, fixtures, código de terceros y ejemplos antes de ordenar; la búsqueda de símbolos por nombre no cambia.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`symbol_name`	`str`	No	-	Nombre del símbolo que se buscará (opcional — omítelo para explorar por métricas)
`repository`	`str`	No	-	Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.
`scope`	`Literal[definitions, references, both]`	No	`both`	Ámbito: definitions\|references\|both
`limit`	`int`	No	`15`	Máximo de resultados devueltos en esta página
`offset`	`int`	No	-	Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.
`cursor`	`str`	No	-	Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.
`find_similar`	`bool`	No		Buscar símbolos similares
`include_metrics`	`bool`	No		Incluir métricas de centralidad
`metrics_detail`	`Literal[summary, full]`	No	`summary`	Cuando include_metrics=true: summary (predeterminado) devuelve señales de decisión + refactor_risk; full devuelve el conjunto seleccionado más amplio de métricas.
`path_filter`	`str`	No	-	Filtrar por prefijo de ruta de archivo
`branch`	`str`	No	-	Reemplazo de rama
`symbol_type`	`Literal[function, class, variable, method, constant, module, interface, type]`	No	-	Filtro por tipo de símbolo
`high_impact`	`bool`	No		Explora los símbolos arquitectónicamente importantes (omite symbol_name). El modo predeterminado es popularity (decil superior de PageRank menos los megacentros de utilidad). Establece high_impact_mode=risk para puntos de articulación/aristas puente.
`high_impact_mode`	`Literal[popularity, risk]`	No	`popularity`	Cuando high_impact=true: popularidad = decil superior de PageRank menos megacentros/módulos de utilidad; riesgo = puntos de articulación clasificados por SMV bridge_count y luego k_core (riesgo de refactor estructural, no popularidad del centro)
`in_cycle`	`bool`	No		Solo en ciclo
`exclude_test_paths`	`bool`	No	`true`	Al explorar por métricas del grafo, excluye tests, fixtures, código de terceros y ejemplos antes de ordenar; la búsqueda de símbolos por nombre no cambia.

Ideal para:

Localizar la definición, las referencias y las métricas de grafo de un símbolo conocido
Explorar por centrality, high_impact o in_cycle cuando se omite symbol_name

No recomendada para:

Consultas conceptuales o áreas desconocidas — usa intelligent_search o semantic_search

analyze_dependenciesEstable

Alias del radio de impacto vía dependency_search (dependents/incoming). Prefiere dependency_search con analysis_type="dependents" o "impact" para agentes nuevos. Mantiene la forma de respuesta heredada de impacto multi-salto (graph, connection_summary, métricas opcionales con refactor_risk). Usa graph_view para acotar la familia de relaciones: dependency (por defecto), type, data_flow, control_flow.

Parámetros:

repositoryOpcional

Tipo: str
Descripción: Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.

targetRequerido

Tipo: str
Descripción: Nombre del símbolo que se analizará

depthOpcional

Tipo: Literal[shallow, balanced, deep]
Predeterminado: balanced
Descripción: Profundidad del análisis (admite alias: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)

limitOpcional

Tipo: int
Predeterminado: 10
Descripción: Máximo de resultados devueltos en esta página

offsetOpcional

Tipo: int
Descripción: Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descripción: Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.

directionOpcional

Tipo: Literal[incoming, outgoing, both]
Predeterminado: incoming
Descripción: Dirección del recorrido: 'outgoing' = de qué depende este símbolo (sus dependencias), 'incoming' = qué depende de este símbolo (sus dependientes), 'both' = contexto completo. Usa 'incoming' para encontrar todos los llamadores/usuarios de un símbolo.

relationship_typesOpcional

Tipo: list[str]
Descripción: Filtrar por tipos de arista (CALL, IMPORT, INHERITS_FROM, etc.). Si se proporciona, siempre reemplaza el valor predeterminado derivado de graph_view que se indica abajo.

graph_viewOpcional

Tipo: Literal[dependency, type, data_flow, control_flow]
Predeterminado: dependency
Descripción: Vista del grafo: cuando include_metrics=true, determina tanto los tipos de arista de recorrido predeterminados como la vista cuyas métricas se utilizan. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (predeterminada), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Solo se aplica como valor predeterminado de relationship_types cuando relationship_types no se proporciona explícitamente. El nombre coincide con el parámetro graph_view existente de dependency_search para mantener la coherencia entre herramientas.

path_filterOpcional

Tipo: str
Descripción: Restringe la resolución del símbolo objetivo por prefijo de ruta de archivo; las relaciones del grafo devueltas pueden salir de esa ruta.

language_filterOpcional

Tipo: str
Descripción: Restringe los resultados a un lenguaje

branchOpcional

Tipo: str
Descripción: Reemplazo de rama

per_hop_limitOpcional

Tipo: int
Descripción: Máximo de relaciones por salto (1-300)

include_metricsOpcional

Tipo: bool
Predeterminado
Descripción: Incluir métricas del grafo en los resultados, cada una enriquecida con un bloque refactor_risk derivado ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). El riesgo es "low" si no es un punto de articulación en la vista seleccionada, "medium" si conecta pocas aristas y "high" si conecta muchas (umbral heurístico no validado empíricamente). Se omite cuando no existe una fila de métricas para el símbolo y la vista.

metrics_detailOpcional

Tipo: Literal[summary, full]
Predeterminado: summary
Descripción: Cuando include_metrics=true: summary (predeterminado) devuelve señales de decisión + refactor_risk; full devuelve el conjunto seleccionado más amplio de métricas.

include_edge_metadataOpcional

Tipo: bool
Predeterminado
Descripción: Incluye los metadatos y pesos sin procesar de las aristas. Está desactivado de forma predeterminada porque los metadatos del extractor pueden ser grandes; cuando se activa, se informa de la cobertura del enriquecimiento.

exclude_test_pathsOpcional

Tipo: bool
Predeterminado: true
Descripción: Valor predeterminado true: excluye las rutas de tests, fixtures, proveedores y ejemplos de las aristas del grafo devueltas. Establece false para incluirlas.

include_module_symbolsOpcional

Tipo: bool
Predeterminado
Descripción: Valor predeterminado false: descarta las aristas cuyo from_name o to_name sea el símbolo sintético __module__. Establece true para incluir aristas de nivel de módulo.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`repository`	`str`	No	-	Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.
`target`	`str`	Sí	-	Nombre del símbolo que se analizará
`depth`	`Literal[shallow, balanced, deep]`	No	`balanced`	Profundidad del análisis (admite alias: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)
`limit`	`int`	No	`10`	Máximo de resultados devueltos en esta página
`offset`	`int`	No	-	Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.
`cursor`	`str`	No	-	Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.
`direction`	`Literal[incoming, outgoing, both]`	No	`incoming`	Dirección del recorrido: 'outgoing' = de qué depende este símbolo (sus dependencias), 'incoming' = qué depende de este símbolo (sus dependientes), 'both' = contexto completo. Usa 'incoming' para encontrar todos los llamadores/usuarios de un símbolo.
`relationship_types`	`list[str]`	No	-	Filtrar por tipos de arista (CALL, IMPORT, INHERITS_FROM, etc.). Si se proporciona, siempre reemplaza el valor predeterminado derivado de graph_view que se indica abajo.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Vista del grafo: cuando include_metrics=true, determina tanto los tipos de arista de recorrido predeterminados como la vista cuyas métricas se utilizan. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (predeterminada), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Solo se aplica como valor predeterminado de relationship_types cuando relationship_types no se proporciona explícitamente. El nombre coincide con el parámetro graph_view existente de dependency_search para mantener la coherencia entre herramientas.
`path_filter`	`str`	No	-	Restringe la resolución del símbolo objetivo por prefijo de ruta de archivo; las relaciones del grafo devueltas pueden salir de esa ruta.
`language_filter`	`str`	No	-	Restringe los resultados a un lenguaje
`branch`	`str`	No	-	Reemplazo de rama
`per_hop_limit`	`int`	No	-	Máximo de relaciones por salto (1-300)
`include_metrics`	`bool`	No		Incluir métricas del grafo en los resultados, cada una enriquecida con un bloque refactor_risk derivado ({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). El riesgo es "low" si no es un punto de articulación en la vista seleccionada, "medium" si conecta pocas aristas y "high" si conecta muchas (umbral heurístico no validado empíricamente). Se omite cuando no existe una fila de métricas para el símbolo y la vista.
`metrics_detail`	`Literal[summary, full]`	No	`summary`	Cuando include_metrics=true: summary (predeterminado) devuelve señales de decisión + refactor_risk; full devuelve el conjunto seleccionado más amplio de métricas.
`include_edge_metadata`	`bool`	No		Incluye los metadatos y pesos sin procesar de las aristas. Está desactivado de forma predeterminada porque los metadatos del extractor pueden ser grandes; cuando se activa, se informa de la cobertura del enriquecimiento.
`exclude_test_paths`	`bool`	No	`true`	Valor predeterminado true: excluye las rutas de tests, fixtures, proveedores y ejemplos de las aristas del grafo devueltas. Establece false para incluirlas.
`include_module_symbols`	`bool`	No		Valor predeterminado false: descarta las aristas cuyo from_name o to_name sea el símbolo sintético __module__. Establece true para incluir aristas de nivel de módulo.

Ideal para:

Llamadores heredados ya preparados para su forma de respuesta (graph, connection_summary)

No recomendada para:

Bucles de agentes nuevos — prefiere dependency_search, que comparte el mismo núcleo de recorrido

get_task_contextEstable

¿Empiezas a trabajar en una zona desconocida? Describe la tarea (p. ej., «añadir compatibilidad con SSO» o «corregir el webhook de facturación») y obtén en una sola llamada un paquete acotado de archivos, código, símbolos y dependencias pertinentes. Los archivos semilla aportan contenido indexado directo aunque no definan ningún símbolo. Para más resultados, continúa con la herramienta de búsqueda especializada de esa capa.

Parámetros:

task_descriptionRequerido

Tipo: str
Descripción: Descripción de la tarea

repositoryOpcional

Tipo: str
Descripción: Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.

limitOpcional

Tipo: int
Predeterminado: 15
Descripción: Máximo de resultados por capa

scopeOpcional

Tipo: Literal[semantic, symbols, dependencies, all]
Predeterminado: all
Descripción: Capas de contexto a incluir. Válidas: 'semantic', 'symbols', 'dependencies', 'all'. Por defecto: ['semantic', 'symbols', 'dependencies']

language_filterOpcional

Tipo: str
Descripción: Filtra los resultados a archivos detectados como este lenguaje de programación

path_filterOpcional

Tipo: str
Descripción: Filtrar por prefijo de ruta de archivo

branchOpcional

Tipo: str
Descripción: Reemplazo de rama

include_related_contextOpcional

Tipo: bool
Predeterminado
Descripción: Incluir contexto relacionado de símbolos adyacentes

seed_symbol_idsOpcional

Tipo: list[str]
Descripción: Semillas explícitas de nivel 1: ID de símbolos que el agente ya sabe que son centrales para la tarea (p. ej., símbolos de archivos que tiene abiertos). Se clasifican antes que las semillas derivadas de palabras clave en las capas dependencies/related_context. Es aditivo: omítelo para conservar el comportamiento actual basado solo en palabras clave.

seed_file_pathsOpcional

Tipo: list[str]
Descripción: Semillas explícitas de nivel 1: rutas de archivos indexados que el agente tiene abiertos o acaba de editar. Devuelve evidencia directa de archivo acotada y resuelve hasta 5 símbolos por archivo para el contexto del grafo, incluyendo documentación y configuración sin símbolos. Aditivo — omítelo para un comportamiento basado solo en palabras clave.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`task_description`	`str`	Sí	-	Descripción de la tarea
`repository`	`str`	No	-	Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.
`limit`	`int`	No	`15`	Máximo de resultados por capa
`scope`	`Literal[semantic, symbols, dependencies, all]`	No	`all`	Capas de contexto a incluir. Válidas: 'semantic', 'symbols', 'dependencies', 'all'. Por defecto: ['semantic', 'symbols', 'dependencies']
`language_filter`	`str`	No	-	Filtra los resultados a archivos detectados como este lenguaje de programación
`path_filter`	`str`	No	-	Filtrar por prefijo de ruta de archivo
`branch`	`str`	No	-	Reemplazo de rama
`include_related_context`	`bool`	No		Incluir contexto relacionado de símbolos adyacentes
`seed_symbol_ids`	`list[str]`	No	-	Semillas explícitas de nivel 1: ID de símbolos que el agente ya sabe que son centrales para la tarea (p. ej., símbolos de archivos que tiene abiertos). Se clasifican antes que las semillas derivadas de palabras clave en las capas dependencies/related_context. Es aditivo: omítelo para conservar el comportamiento actual basado solo en palabras clave.
`seed_file_paths`	`list[str]`	No	-	Semillas explícitas de nivel 1: rutas de archivos indexados que el agente tiene abiertos o acaba de editar. Devuelve evidencia directa de archivo acotada y resuelve hasta 5 símbolos por archivo para el contexto del grafo, incluyendo documentación y configuración sin símbolos. Aditivo — omítelo para un comportamiento basado solo en palabras clave.

Ideal para:

Contexto adaptado a la tarea que combina archivos semilla con capas semánticas, de símbolos y de dependencias

No recomendada para:

Búsquedas con una sola herramienta cuando una herramienta más específica ya responde la pregunta

get_fileEstable

Lee un archivo del repositorio indexado por su ruta. Prefiere la herramienta Read local para archivos en disco — úsala para consultas remotas o entre repositorios cuando el archivo no esté en tu árbol de trabajo. Admite un intervalo de líneas opcional; continúa una respuesta truncada por tokens desde metadata.next_line_start.

Parámetros:

file_pathRequerido

Tipo: str
Descripción: Ruta del archivo relativa a la raíz del repositorio

repositoryOpcional

Tipo: str
Descripción: Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.

line_startOpcional

Tipo: int
Descripción: Línea inicial (índice desde 1)

line_endOpcional

Tipo: int
Descripción: Línea final (indexada desde 1, inclusive; debe ser igual o posterior a line_start)

branchOpcional

Tipo: str
Descripción: Reemplazo de rama

max_tokensOpcional

Tipo: int
Predeterminado: 5000
Descripción: Máximo de tokens

include_metadataOpcional

Tipo: bool
Predeterminado: true
Descripción: Incluir metadatos

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`file_path`	`str`	Sí	-	Ruta del archivo relativa a la raíz del repositorio
`repository`	`str`	No	-	Repositorio con el formato owner/repo[:branch]. Opcional — omítelo para usar el valor predeterminado del cliente limitado a la solicitud (si se proporciona) o el único repositorio accesible; pásalo explícitamente solo para seleccionar otro repositorio indexado. La respuesta muestra qué repositorio se utilizó.
`line_start`	`int`	No	-	Línea inicial (índice desde 1)
`line_end`	`int`	No	-	Línea final (indexada desde 1, inclusive; debe ser igual o posterior a line_start)
`branch`	`str`	No	-	Reemplazo de rama
`max_tokens`	`int`	No	`5000`	Máximo de tokens
`include_metadata`	`bool`	No	`true`	Incluir metadatos

Ideal para:

Instantáneas de archivos remotos o indexados (rangos de líneas, límites de tokens)

No recomendada para:

Una ruta ya presente en el disco local — usa la herramienta Read local

Herramientas de sistema y utilidades#

repository_contextEstable

Enumera los repositorios que puedes consultar, u obtén la información de identidad de uno (espacio de nombres/rama, indexed_commit_sha / actualidad del índice). Llama una vez con action:"list" para conocer el identificador exacto que aceptan las herramientas de búsqueda. (Si tu clave solo tiene un repositorio, se usará de forma predeterminada — puedes omitir este paso.) Los recuentos de archivos/blobs/aristas a nivel de espacio de nombres son opcionales mediante include_statistics=true.

Parámetros:

actionRequerido

Tipo: Literal[list, info]
Descripción: Acción: enumerar repositorios disponibles u obtener información de uno

repositoryOpcional

Tipo: str
Descripción: Repositorio con formato owner/repo u owner/repo:branch (obligatorio para info)

branchOpcional

Tipo: str
Descripción: Reemplazo de rama

patternOpcional

Tipo: str
Descripción: Patrón de filtro

include_statisticsOpcional

Tipo: bool
Predeterminado
Descripción: Opcional: incluye los recuentos de datos indexados a nivel de espacio de nombres (archivo/blob/arista). Falso por defecto — la identidad del repositorio no requiere este agregado más lento.

limitOpcional

Tipo: int
Predeterminado: 20
Descripción: Máximo de resultados devueltos en esta página

offsetOpcional

Tipo: int
Descripción: Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.

cursorOpcional

Tipo: str
Descripción: Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`action`	`Literal[list, info]`	Sí	-	Acción: enumerar repositorios disponibles u obtener información de uno
`repository`	`str`	No	-	Repositorio con formato owner/repo u owner/repo:branch (obligatorio para info)
`branch`	`str`	No	-	Reemplazo de rama
`pattern`	`str`	No	-	Patrón de filtro
`include_statistics`	`bool`	No		Opcional: incluye los recuentos de datos indexados a nivel de espacio de nombres (archivo/blob/arista). Falso por defecto — la identidad del repositorio no requiere este agregado más lento.
`limit`	`int`	No	`20`	Máximo de resultados devueltos en esta página
`offset`	`int`	No	-	Desplazamiento de compatibilidad obsoleto. Prefiere el cursor de pagination.next_cursor.
`cursor`	`str`	No	-	Cursor opaco de pagination.next_cursor. Pásalo sin cambios y mantén sin cambios la consulta y los filtros.

Ideal para:

Listar los repositorios accesibles
Resolver la identidad del repositorio, la rama y la actualidad de HEAD frente al índice

No recomendada para:

Estadísticas de todo el namespace por defecto — pasa include_statistics=true explícitamente, ya que puede ser más lento que la resolución

ask_maguyvaEstable

Ayuda y comentarios de Maguyva. Uso principal: obtener orientación sobre herramientas, o enviar un informe de error / una solicitud de función que se guarda para los mantenedores de Maguyva. Nunca incluyas secretos ni datos personales sensibles en los comentarios. La operación evaluate se mantiene solo por retrocompatibilidad — prefiere el cómputo local o las herramientas del host para tareas de matemáticas/hash/cadenas.

Parámetros:

operationRequerido

Tipo: Literal[guidance, report_bug, request_feature, evaluate]
Descripción: Principal: guidance, report_bug, request_feature. Solo heredado/compatibilidad: evaluate (motor de expresiones determinista; no forma parte del flujo de trabajo principal del agente).

queryOpcional

Tipo: str
Descripción: Tema de la guía (p. ej., tool_selection, semantic_search). Solo para evaluate heredado: cadena de expresión.

descriptionOpcional

Tipo: str
Descripción: Obligatorio para report_bug y request_feature. Comentario Free-form para los mantenedores de Maguyva. Nunca incluyas secretos ni datos personales sensibles.

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]
Descripción: Herramienta opcional de Maguyva más estrechamente relacionada con los comentarios.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`operation`	`Literal[guidance, report_bug, request_feature, evaluate]`	Sí	-	Principal: guidance, report_bug, request_feature. Solo heredado/compatibilidad: evaluate (motor de expresiones determinista; no forma parte del flujo de trabajo principal del agente).
`query`	`str`	No	-	Tema de la guía (p. ej., tool_selection, semantic_search). Solo para evaluate heredado: cadena de expresión.
`description`	`str`	No	-	Obligatorio para report_bug y request_feature. Comentario Free-form para los mantenedores de Maguyva. Nunca incluyas secretos ni datos personales sensibles.
`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]`	No	-	Herramienta opcional de Maguyva más estrechamente relacionada con los comentarios.

Ideal para:

Orientación sobre herramientas (operation="guidance")
Informes de errores duraderos y solicitudes de funciones para los mantenedores de Maguyva

No recomendada para:

Cálculos matemáticos/hash/de cadenas — la operación evaluate se mantiene solo por retrocompatibilidad; prefiere el cómputo local o las herramientas del host

Buenas prácticas#

Usa deliberadamente las anulaciones explícitas: Omite el repositorio cuando el cliente MCP proporcione un valor predeterminado para la solicitud o la clave pueda acceder exactamente a un repositorio; de lo contrario, pásalo explícitamente.
Elige el modo de búsqueda correcto: Usa intelligent_search con mode="auto" para la mayoría de los casos. Especifica un modo cuando sepas exactamente qué necesitas.
Aprovecha los filtros de lenguaje: Usa language_filter para acotar los resultados y mejorar el rendimiento.
Boosting de GraphRAG: El boosting de importancia de GraphRAG está desactivado por defecto en la búsqueda semántica (boost_by_importance=false), para mantener la clasificación segura para agentes. Pasa boost_by_importance=true para habilitar el reordenamiento basado en centralidad en recorridos de arquitectura.
La coincidencia de repositorio no distingue mayúsculas, pero no es difusa: repository_context hace coincidir los nombres de repositorio sin distinguir mayúsculas de minúsculas — no corrige errores de tipeo. Revisa metadata.resolution_reason en la acción info ("exact" frente a "corrected") para ver cómo se resolvió un nombre.
Combina herramientas: Usa varios métodos de la API en conjunto para un análisis integral.
Maneja resultados grandes: Usa limit y los controles de paginación específicos de cada herramienta (por ejemplo line_start/line_end en get_file).
Usa ask_maguyva para orientación de herramientas: La operación evaluate de ask_maguyva (hash, base64, JSON, matemáticas) es solo legacy / retrocompatibilidad. Llama a ask_maguyva con operation="guidance" y query="tool_selection" en su lugar para obtener la matriz de prioridad de herramientas locales y una chuleta completa herramienta por herramienta.
Verifica el impacto antes y después de editar: Antes de editar un símbolo compartido, llama a dependency_search con analysis_type="impact" (o pasa changed_paths para el impacto de un PR/diff) para ver su radio de impacto. Después de editar, define verify_after_edit=true con targets y/o changed_paths para una reverificación compacta de los mismos símbolos.

Características de rendimiento#

Operación	Notas de rendimiento
Búsqueda semántica	Menos de un segundo, pero incluye una llamada en vivo a la API de embeddings cada vez (sin caché) — espera latencia adicional además de la consulta vectorial
Búsqueda de texto	Menos de un segundo para coincidencias exactas/regex; la búsqueda difusa de contenido pagina del lado del cliente, así que los offsets profundos cuestan más — acota con path_filter/language_filter
Búsqueda estructural	Indexada por AST — el costo escala con el volumen de resultados, no con el tamaño del repositorio
Búsqueda de dependencias	El costo escala con la profundidad — prefiere depth="shallow" a menos que necesites contexto multi-salto; per_hop_limit limita la expansión
Recuperación de archivos	Casi instantánea para un solo archivo — pagina archivos grandes con line_start/line_end o max_tokens en lugar de una sola extracción grande
Contexto de repositorio	La resolución del espacio de nombres se almacena en caché solo por solicitud, no entre llamadas — cada invocación de herramienta la resuelve de nuevo
ask_maguyva (guidance / evaluate)	Casi instantáneo — se ejecuta dentro del Worker sin llamada a base de datos

Manejo de errores#

Todos los métodos de la API devuelven un sobre estructurado:

status: Cadena — "success" o "error". Las señales de coincidencia degradada o de vigencia se encuentran en campos anidados como metadata.resolution_reason en repository_context o metadata.index_freshness.status.
tool: Nombre de la herramienta que generó la respuesta
data: Payload del resultado cuando hay éxito (la estructura varía según la herramienta)
error: Objeto de error estructurado cuando status es "error" — incluye type, message, suggestions y recovery_actions
metadata: Información adicional sobre la operación (enrutamiento, caché, ajustes de parámetros)
pagination: Presente en respuestas de tipo lista — incluye has_more y next_cursor

Verifica siempre el campo status antes de procesar los resultados — solo puede ser "success" o "error". Para señales de coincidencia degradada o de vigencia, consulta en su lugar el campo anidado: metadata.resolution_reason en repository_context, o metadata.index_freshness.status (known/partial/unknown/unavailable).

Primeros pasos#

Configura el cliente MCP: Apunta tu cliente MCP al endpoint del servidor de Maguyva
Confirmar el acceso al repositorio: Usa repository_context con list o info para revisar los repositorios disponibles para la clave de API
Empieza a buscar: Comienza con intelligent_search y explora herramientas especializadas según lo necesites
Combina herramientas: Usa varias herramientas en conjunto para un análisis de código integral

Para instrucciones detalladas de integración, consulta la guía de instalación.