Recetas

Recetas prácticas para el trabajo diario con Maguyva MCP. Cada receta indica las herramientas y su secuencia de uso; no es una referencia completa de parámetros. Para consultar los parámetros de las herramientas, usa Referencia de API MCP. Para la configuración inicial, usa Inicio rápido.

Los bloques JSON son entradas para MCP tools/call. Sustituye owner/repo y los nombres de rama y de símbolo por los valores de tu repositorio.

La mayoría de las preguntas comienzan con una llamada. Amplía la búsqueda solo cuando la primera respuesta sea demasiado general o no aporte suficiente información.

• intelligent_search — empieza aquí para hacer una pregunta en lenguaje natural sobre la base de código. Por defecto, auto/balanced dirige las preguntas sobre definiciones cuya intención identifica con confianza a la búsqueda estructural, las de referencias o impacto al grafo y las de coincidencia exacta al texto. Las demás preguntas usan el significado semántico y el texto indexado. Usa mode=hybrid o auto con quality=thorough para solicitar las cuatro modalidades de búsqueda. Un mode explícito tiene prioridad sobre quality.
• find_symbol — ya conoces el nombre de la función, clase o variable.
• dependency_search — radio de impacto: código que llama, código dependiente 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).

Configura Maguyva en tu cliente MCP y confirma la conexión con una lista real de repositorios.

1. Crea una clave de API en app.maguyva.ai (las claves comienzan con mgv_).
2. Conecta e indexa al menos un repositorio de GitHub que ya conozcas.
3. Conecta tu cliente siguiendo Guía de instalación (plugin de Claude Code o configuración remota nativa para Cursor, VS Code, Devin Desktop, Zed y otros).
4. Pregúntale a tu agente "¿Qué repositorios tengo conectados?": así pones a prueba la autenticación y repository_context de extremo a extremo.
5. Haz una pregunta real sobre ese repo cuya respuesta puedas evaluar. Deberías ver rutas de archivos y números de línea del árbol indexado.

{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}

¿Atascado en claves, bridges o repositorios faltantes? Solución de problemas.

Identifica los símbolos y su radio de impacto antes de cambiar código compartido. Las herramientas de Maguyva no modifican tus repositorios: aportan información para la edición que tu cliente aplica localmente.

1. Si conoces el nombre del símbolo, llama a find_symbol para encontrar definiciones y usos.
2. Si solo tienes una descripción de la tarea ("agregar SSO", "arreglar el webhook de facturación"), empieza con get_task_context o intelligent_search.
3. Antes de editar un símbolo compartido, llama a dependency_search para analizar el código que depende de él y su impacto (o pasa las rutas modificadas para un análisis de impacto de tipo PR) y así ver el radio de impacto.
4. Abre los archivos citados (lectura local para los archivos en disco; get_file para rutas remotas o de otros repositorios) y confirma el plan con el código real.
5. Tras editar, vuelve a comprobar los mismos símbolos con dependency_search, usando verify_after_edit=true y targets o changed_paths. Esto lee el grafo indexado, no los cambios locales sin confirmar: comprueba indexed_commit_sha y la actualidad del índice antes de tratarlo como prueba de la nueva revisión, y ejecuta las pruebas locales.

{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}

Parámetros completos: Referencia de API MCP.

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

1. Empieza 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. Acota con filtros de lenguaje o ruta si los primeros resultados contienen demasiado ruido. language_filter excluye el grafo de auto/hybrid; una consulta auto dirigida solo al grafo recurre a la búsqueda semántica y de texto. El modo de grafo explícito con language_filter se rechaza. Consulta routing_decision.modalities_used para ver el plan de búsqueda seleccionado; warnings solo aparece cuando el servidor ha emitido alguna advertencia.
3. Profundiza en los resultados prometedores con find_symbol o dependency_search, en lugar de repetir la misma pregunta vaga.
4. Usa get_file solo cuando necesites una ruta indexada específica que no esté en disco.
5. Edita con las herramientas habituales de tu cliente. Maguyva sirve para descubrir y verificar, no para escribir.

{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}

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

Cuando las herramientas no devuelvan nada útil, corrige la resolución del repositorio y la indexación antes de pasarte el tiempo reescribiendo la consulta.

1. Confirma que el repositorio esté conectado y que haya terminado de indexarse en app.maguyva.ai.
2. Revisa 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, pero no es aproximada: los errores tipográficos no se corrigen automáticamente.
3. Llama a repository_context con action="info" e inspecciona los metadatos de resolución (por ejemplo, metadata.resolution_reason).
4. Omite repository solo cuando tu cliente MCP proporcione un repositorio predeterminado para la solicitud o la clave pueda acceder exactamente a un repositorio; de lo contrario, pásalo explícitamente.
5. Vuelve a intentarlo con una consulta más específica, un nombre de símbolo conocido mediante find_symbol o un filtro de lenguaje o ruta. Si falla la conexión, usa Solución de problemas.

{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}

Fallos de configuración: Solución de problemas.

Apunta al repositorio indexado correcto cuando una clave pueda acceder a más de uno.

1. Llama una vez a repository_context con action="list" para conocer los slugs exactos de los repositorios en los que tu clave permite buscar.
2. Pasa repository explícitamente a las herramientas de búsqueda y símbolos cuando necesites un repo distinto del predeterminado (por ejemplo, "owner/other-repo" o "owner/other-repo:develop").
3. Mantén una pregunta = un repositorio, salvo que quieras comparar repositorios mediante llamadas separadas.
4. Usa get_file cuando el archivo esté en un repo indexado que no sea tu árbol de trabajo actual.
5. Recuerda: las herramientas nunca escriben en GitHub; el contexto de múltiples repositorios sirve solo para leer y planificar.

Detalles del formato del repositorio: Referencia de API MCP.

• Inicio rápido — clave, indexación, conexión y primera respuesta evaluada
• Guía de instalación — Configuración MCP por cliente
• Referencia de API MCP — cada herramienta, parámetro por parámetro
• Solución de problemas — Fallos de clave de API, bridge y repositorio