# Recetas

Canonical source: https://maguyva.ai/es/docs/cookbook

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

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](https://maguyva.ai/docs/mcp-api). Para la configuración inicial, usa [Inicio rápido](https://maguyva.ai/docs/quickstart).

### Elige la herramienta adecuada

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).

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.

### Instalar y verificar un cliente

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](https://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](https://maguyva.ai/docs/installation) (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.

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

¿Atascado en claves, bridges o repositorios faltantes? [Solución de problemas](https://maguyva.ai/docs/troubleshooting).

### Pregunta antes de editar

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.

```json
{
  "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](https://maguyva.ai/docs/mcp-api).

### Buscar y luego cambiar

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.

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

Por qué funciona este bucle: [Cómo funciona](https://maguyva.ai/docs/how-it-works).

### Resultados vacíos o insuficientes

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](https://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](https://maguyva.ai/docs/troubleshooting).

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

Fallos de configuración: [Solución de problemas](https://maguyva.ai/docs/troubleshooting).

### Trabajar en múltiples repositorios

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](https://maguyva.ai/docs/mcp-api).

¿Es tu primera configuración? Empieza con [Inicio rápido](https://maguyva.ai/docs/quickstart) y después usa estas recetas para las tareas cotidianas.