Referencia de la API de MCP

Explora las 11 herramientas MCP de Maguyva, sus parámetros y cuándo usar cada una. Consulta la respuesta tools/list del cliente conectado para conocer los argumentos disponibles.

Las herramientas se organizan en 4 categorías:

• 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 del repositorio, orientación sobre herramientas y comentarios

En las herramientas que aceptan un repositorio, usa este formato de identificador de repositorio: "owner/repo:branch". La rama predeterminada es main 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.

Usa estos formatos al especificar un repositorio:

• Con rama: "owner/repo:branch" - por ej., "owner/repository:develop"
• Rama predeterminada: "owner/repo" - usa la rama 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"
Enumera los repositorios accesibles:           "¿A qué repositorios puede acceder esta clave de Maguyva?"
Cambia el repositorio para una sola consulta:  "Busca patrones de auth en owner/other-repo:develop"

Usa language_filter en los modos de búsqueda compatibles. Para text_pattern_search, elige search_scope="content"; para get_task_context, usa scope="semantic" sin semillas ni contexto relacionado.

• 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 285 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 21 de octubre de 2026.

1. Sobrescribe los valores predeterminados de forma deliberada: 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.
2. 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.
3. Aprovecha los filtros de lenguaje: Usa language_filter para acotar los resultados y mejorar el rendimiento.
4. 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 una ordenación segura para los agentes. Pasa boost_by_importance=true para habilitar el reordenamiento basado en centralidad en recorridos de arquitectura.
5. La coincidencia de repositorio no distingue mayúsculas, pero no es difusa: repository_context compara nombres de repositorio sin distinguir mayúsculas y minúsculas, pero no corrige erratas. Cuando la identidad servida difiere de la solicitada, metadata.resolution_reason informa "defaulted" (no se solicitó ninguna rama) o "fallback" (la rama o el repositorio solicitado no está disponible). El campo se omite cuando la solicitud coincidió exactamente.
6. Combina herramientas: Usa varios métodos de la API en conjunto para un análisis integral.
7. 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).
8. Usa ask_maguyva para orientación de herramientas: Llama a ask_maguyva con operation="guidance" y query="tool_selection" para obtener consejos y ejemplos de selección de herramientas. Usa herramientas locales para cálculos y transformaciones de cadenas.
9. 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 comprobación compacta del grafo indexado. Esta comprobación lee el grafo indexado, no los cambios locales sin confirmar, y no sustituye las pruebas locales. Comprueba indexed_commit_sha y la actualidad del índice antes de tratar los resultados como prueba de una nueva revisión.

Las respuestas contienen campos de estado comunes y campos de contenido específicos de cada herramienta en el nivel superior. Las búsquedas devuelven results; get_file devuelve content. Los campos comunes incluyen:

• status: Cadena — "success" o "error". Las señales de coincidencia degradada y de frescura tienen sus propios campos: metadata.resolution_reason dentro de metadata y index_freshness.status en el nivel superior de la acción info de repository_context.
• timing_ms: Tiempo de ejecución de la herramienta en milisegundos
• applied_filters: Parámetros efectivos de la solicitud registrados para la operación
• error: Cadena del mensaje de error cuando status es "error"; puede incluir instrucciones de recuperación.
• metadata: Información adicional sobre la operación (enrutamiento, caché, ajustes de parámetros)
• pagination: Presente en las respuestas de colecciones paginadas por cursor; incluye has_more y next_cursor. Las ventanas de búsqueda ordenada son resultados top-K acotados, no colecciones completas paginadas.

Comprueba el campo status antes de procesar la carga útil de una herramienta: sus valores son "success" o "error". Gestiona también los errores de transporte MCP/JSON-RPC y de validación de la solicitud, que pueden producirse antes de que exista una carga útil. Para señales de coincidencia degradada o de frescura, lee el campo dedicado: metadata.resolution_reason dentro de metadata, o index_freshness.status en el nivel superior de la acción info de repository_context (known/partial/unknown/unavailable).

1. Configura el cliente MCP: Apunta tu cliente MCP al endpoint del servidor de Maguyva
2. Confirma el acceso al repositorio: Usa repository_context con list o info para revisar los repositorios disponibles para la clave de API
3. Empieza a buscar: Comienza con intelligent_search y explora herramientas especializadas según lo necesites
4. 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.