# Praxisrezepte

Canonical source: https://maguyva.ai/de/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).

Praktische Rezepte für die tägliche Arbeit mit Maguyva MCP. Jedes Rezept nennt Werkzeuge und Reihenfolge, ist aber keine vollständige Parameterreferenz. Werkzeugparameter findest du in der [MCP-API-Referenz](https://maguyva.ai/docs/mcp-api); für die Ersteinrichtung nutze den [Schnellstart](https://maguyva.ai/docs/quickstart).

### Das richtige Werkzeug wählen

Die meisten Fragen beginnen mit einem Aufruf. Geh nur dann weiter, wenn die erste Antwort zu allgemein ist oder zu wenig Informationen liefert.

- `intelligent_search` — starte hier mit einer natürlichsprachlichen Frage zur Codebasis. Standardmäßig leitet auto/balanced Definitionsfragen bei sicher erkannter Absicht an die strukturelle Suche weiter, Referenz- oder Auswirkungsfragen an den Graphen und Fragen nach exakten Treffern an die Textsuche. Andere Fragen nutzen semantische Bedeutung und indexierten Text. Mit mode=hybrid oder auto zusammen mit quality=thorough forderst du alle vier Suchmodalitäten an. Ein expliziter mode hat Vorrang vor quality.
- `find_symbol` — Funktions-, Klassen- oder Variablenname ist bereits bekannt.
- `dependency_search` — Auswirkungsradius: Aufrufer, abhängiger Code oder Auswirkungen vor und nach einer Änderung.
- `get_task_context` — für unbekannte Bereiche; liefert ein begrenztes Paket aus Dateien, Symbolen und Abhängigkeiten zu einer Aufgabenbeschreibung.
- `repository_context` — zugängliche Repositorys auflisten oder prüfen, wie ein Repositoryname aufgelöst wird.
- `ask_maguyva` mit `operation="guidance"` — lokale Hilfe bei Werkzeugauswahl und Maguyva-Nutzung, ohne das Repository zu verändern.

Die JSON-Blöcke sind Eingaben für MCP tools/call. Ersetze owner/repo, Branch- und Symbolnamen durch Werte aus deinem Repository.

### Client installieren und prüfen

Maguyva in deinen MCP-Client einbinden und die Verbindung anhand einer echten Repositoryliste bestätigen.

1. Erstelle in [app.maguyva.ai](https://app.maguyva.ai) einen API-Schlüssel; Schlüssel beginnen mit `mgv_`.
2. Verbinde und indexiere mindestens ein GitHub-Repository, das du bereits kennst.
3. Richte den Client anhand der [Installationsanleitung](https://maguyva.ai/docs/installation) ein: als Claude Code-Plugin oder über die native Remote-Konfiguration für Cursor, VS Code, Devin Desktop, Zed und weitere.
4. Frag deinen Agent "Welche Repositorys habe ich verbunden?" — damit werden Authentifizierung und `repository_context` durchgängig geprüft.
5. Stell eine echte Frage zu diesem Repository, deren Antwort du bewerten kannst. Du solltest Dateipfade und Zeilennummern aus dem indexierten Baum sehen.

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

Probleme mit Schlüsseln, Bridges oder fehlenden Repositorys? Siehe [Fehlerbehebung](https://maguyva.ai/docs/troubleshooting).

### Vor dem Bearbeiten nachfragen

Erfasse Symbole und Auswirkungsradius, bevor du gemeinsam genutzten Code änderst. Maguyva-Werkzeuge verändern deine Repositorys nicht; sie liefern die Grundlage für die lokale Änderung durch deinen Client.

1. Wenn du den Symbolnamen kennst, rufe `find_symbol` auf, um Definitionen und Verwendungen zu finden.
2. Wenn du nur eine Aufgabenbeschreibung hast, etwa „SSO hinzufügen“ oder „Billing-Webhook reparieren“, beginne mit `get_task_context` oder `intelligent_search`.
3. Rufe vor der Änderung eines gemeinsam genutzten Symbols `dependency_search` mit dependents- oder impact-Analyse auf; für eine PR-artige Analyse kannst du auch geänderte Pfade übergeben. So wird der Auswirkungsradius sichtbar.
4. Öffne die angegebenen Dateien — lokal für Dateien auf dem Datenträger, mit `get_file` für Remote- oder repositoryübergreifende Pfade — und gleiche den Plan mit echtem Code ab.
5. Prüfe nach der Änderung dieselben Symbole erneut mit `dependency_search`, verify_after_edit=true und targets oder changed_paths. Dabei wird der indexierte Graph gelesen, nicht lokale, noch nicht committete Änderungen: Prüfe indexed_commit_sha und die Aktualität des Index, bevor du das Ergebnis als Beleg für die neue Revision behandelst, und führe lokale Tests aus.

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

Alle Parameter: [MCP-API-Referenz](https://maguyva.ai/docs/mcp-api).

### Suchen, dann ändern

Der Standardablauf für Agents: erkunden → Symbole festlegen → belegt ändern.

1. Beginne mit `intelligent_search` und einer natürlichsprachlichen Frage wie „Wie funktioniert das Ablaufen einer Sitzung?“ oder „Wo liegt die Wiederholungslogik?“.
2. Grenze mit Sprach- oder Pfadfiltern ein, wenn die ersten Ergebnisse zu viel Rauschen enthalten. language_filter lässt den Graphen bei auto/hybrid weg; eine ausschließlich zum Graphen geroutete auto-Abfrage fällt auf semantische Suche und Textsuche zurück. Ein expliziter Graphmodus mit language_filter wird abgelehnt. Prüfe routing_decision.modalities_used, um den gewählten Suchplan zu sehen; warnings erscheint nur, wenn der Server eine Warnung ausgegeben hat.
3. Untersuche vielversprechende Treffer mit `find_symbol` oder `dependency_search`, statt dieselbe vage Frage erneut zu stellen.
4. Verwende `get_file` nur für einen bestimmten indexierten Pfad, der nicht lokal vorhanden ist.
5. Bearbeite den Code mit deinen üblichen Client-Werkzeugen. Maguyva dient der Erkundung und Prüfung, nicht dem Schreiben.

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

Warum dieser Ablauf funktioniert: [Funktionsweise](https://maguyva.ai/docs/how-it-works).

### Leere oder dürftige Ergebnisse

Wenn Werkzeuge nichts Brauchbares liefern, behebe zuerst die Namensauflösung des Repositorys und die Indexierung, statt die Anfrage endlos umzuschreiben.

1. Prüfe in [app.maguyva.ai](https://app.maguyva.ai), ob das Repository verbunden und vollständig indexiert ist.
2. Prüfe die Repositoryangabe: `"owner/repo"` verwendet den Standardbranch, `"owner/repo:branch"` legt einen Branch fest. Der Abgleich ignoriert Groß- und Kleinschreibung, ist aber nicht unscharf — Tippfehler werden nicht automatisch korrigiert.
3. Rufe `repository_context` mit `action="info"` auf und prüfe die Auflösungsmetadaten, beispielsweise `metadata.resolution_reason`.
4. Lass `repository` nur weg, wenn dein MCP-Client einen Standardwert bereitstellt oder der Schlüssel auf genau ein Repository zugreifen kann; andernfalls gib den Wert ausdrücklich an.
5. Versuche es mit einer genaueren Frage, einem bekannten Symbol über `find_symbol` oder einem Sprach-/Pfadfilter erneut. Ist die Verbindung selbst defekt, verwende [Fehlerbehebung](https://maguyva.ai/docs/troubleshooting).

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

Einrichtungsfehler: [Fehlerbehebung](https://maguyva.ai/docs/troubleshooting).

### Mit mehreren Repositorys arbeiten

Das richtige indexierte Repository ansprechen, wenn ein Schlüssel mehrere sehen kann.

1. Rufe `repository_context` einmal mit `action="list"` auf, um die exakten Slugs zu erfahren, die dein Schlüssel durchsuchen kann.
2. Übergib `repository` bei Such- und Symbolwerkzeugen ausdrücklich, wenn du ein anderes als das Standard-Repository brauchst, etwa `"owner/other-repo"` oder `"owner/other-repo:develop"`.
3. Eine Frage entspricht einem Repository, außer du vergleichst bewusst in getrennten Aufrufen.
4. Verwende `get_file`, wenn die Datei in einem indexierten Repository statt in deinem aktuellen Arbeitsbaum liegt.
5. Zur Erinnerung: Die Werkzeuge schreiben nie nach GitHub zurück. Der Multi-Repository-Kontext dient nur dem Lesen und Planen.

Details zum Repositoryformat: [MCP-API-Referenz](https://maguyva.ai/docs/mcp-api).

Zum ersten Mal einrichten? Beginne mit [Schnellstart](https://maguyva.ai/docs/quickstart) und nutze anschließend diese Anleitungen für alltägliche Aufgaben.