Saltar al contenido

Recetas

Recetas prácticas para el trabajo diario Maguyva MCP. Cada receta nombra las herramientas y la secuencia, no una referencia completa de los parámetros. Para los parámetros de la herramienta, utilice Referencia de API MCP. Para la configuración por primera vez, utilice Quickstart.

Elija la herramienta adecuada#

La mayoría de las preguntas comienzan con una llamada. Escalar sólo cuando la primera respuesta sea demasiado amplia o demasiado débil.

  • intelligent_search: comience aquí para cualquier pregunta sobre el código base en lenguaje natural; recorre la búsqueda semántica, de símbolos, estructural y de dependencia.
  • find_symbol: ya conoce el nombre de la función, clase o variable.
  • dependency_search — radio de impacto: personas que llaman, dependientes o impacto antes (y después) de una edición.
  • get_task_context — zona desconocida; un paquete limitado de archivos, símbolos y dependencias para una descripción de tarea.
  • repository_context: enumera los repositorios accesibles o inspecciona cómo se resuelve el nombre de un repositorio.
  • ask_maguyva con operation="guidance": ayuda local sobre la selección de herramientas y el uso de Maguyva (sin mutación de repositorio).

Instalar y verificar un cliente#

Ingrese Maguyva a su cliente MCP y confirme la conexión con una lista de repositorios real.

  1. Cree una clave API en app.maguyva.ai (las claves comienzan con mgv_).
  2. Conecte e indexe al menos un repositorio GitHub que ya comprenda.
  3. Conecte su cliente utilizando Guía de instalación (complemento Claude Code o configuración remota nativa para Cursor, VS Code, Windsurf, Zed y otros).
  4. Pregúntele a su agente "¿Qué repositorios tengo conectados?", que ejerce la autenticación y repository_context de extremo a extremo.
  5. Haga una pregunta real sobre ese repositorio cuya respuesta pueda calificar. Debería ver las rutas de los archivos y los números de línea del árbol indexado.

¿Atascado en claves, puentes o repositorios faltantes? Troubleshooting.

Pregunta antes de editar#

Asigne símbolos y radio de impacto antes de cambiar el código compartido. Las herramientas Maguyva no modifican sus repositorios: informan la edición que su cliente aplica localmente.

  1. Si conoce el nombre del símbolo, llame a find_symbol para obtener definiciones y usos.
  2. Si solo tiene una descripción de la tarea ("agregar SSO", "arreglar el webhook de facturación"), comience con get_task_context o intelligent_search.
  3. Antes de editar un símbolo compartido, llame a dependency_search con análisis de dependientes/impacto (o pase las rutas modificadas para un impacto de estilo PR) para ver el radio de impacto.
  4. Abra los archivos citados (lectura local para archivos en el disco; get_file para rutas remotas/entre repositorios) y confirme el plan con el código real.
  5. Después de la edición, vuelva a verificar los mismos símbolos con dependency_search (incluida la verificación posterior a la edición cuando su cliente admita los indicadores de verificación) para que las personas que llaman sigan resolviendo como se esperaba.

Parámetros completos: Referencia de API MCP.

Buscar y luego cambiar#

Un bucle de agente predeterminado: explorar → fijar símbolos → editar con evidencia.

  1. Comience con intelligent_search y una consulta en lenguaje sencillo ("cómo funciona la caducidad de la sesión", "dónde está la lógica de reintento").
  2. Limite los filtros de idioma o ruta cuando la primera ventana tenga ruido.
  3. Promocione éxitos prometedores como find_symbol o dependency_search en lugar de volver a hacer la misma pregunta vaga.
  4. Utilice get_file solo cuando necesite una ruta indexada específica que no esté en el disco.
  5. Edite en sus herramientas habituales de cliente. Maguyva es para descubrimiento y verificación, no para escritura.

Por qué funciona este bucle: Cómo funciona.

Resultados vacíos o finos#

Cuando las herramientas no devuelvan nada útil, corrija la resolución y la indexación antes de reescribir la consulta para siempre.

  1. Confirme que el repositorio esté conectado y finalizado la indexación en app.maguyva.ai.
  2. Verifique la cadena del repositorio: "owner/repo" usa la rama predeterminada; "owner/repo:branch" fija una rama. La coincidencia no distingue entre mayúsculas y minúsculas, no es confusa: los errores tipográficos no se corrigen automáticamente.
  3. Llame a repository_context con action="info" e inspeccione los metadatos de resolución (por ejemplo, metadata.resolution_reason).
  4. Omita repository solo cuando su cliente MCP proporcione una solicitud predeterminada o la clave pueda acceder exactamente a un repositorio; de lo contrario, páselo explícitamente.
  5. Vuelva a intentarlo con una consulta más específica, un nombre de símbolo conocido a través de find_symbol o un filtro de idioma/ruta. Si la conexión en sí está rota, utilice Troubleshooting.

Fallos de configuración: Troubleshooting.

Trabajar en múltiples repositorios#

Apunte al repositorio indexado correcto cuando una clave pueda ver más de uno.

  1. Llame a repository_context con action="list" una vez para conocer los slugs exactos que su clave puede buscar.
  2. Pase repository explícitamente en las herramientas de búsqueda y símbolos cuando necesite un repositorio no predeterminado (por ejemplo, "owner/other-repo" o "owner/other-repo:develop").
  3. Mantenga una pregunta = un repositorio a menos que compare intencionalmente entre repositorios en llamadas separadas.
  4. Utilice get_file cuando el archivo se encuentre en un repositorio indexado que no sea su árbol de trabajo actual.
  5. Recuerde: las herramientas nunca escriben en GitHub; el contexto de repositorios múltiples es solo para lectura y planificación.

Detalles del formato del repositorio: Referencia de API MCP.

¿Nuevo en Maguyva? Primero camine por Quickstart y luego regrese aquí para realizar los circuitos del segundo día.

Próximos pasos#