Zum Inhalt springen

Praxisrezepte

Praktische Rezepte für die tägliche Arbeit mit Maguyva MCP. Jedes Rezept nennt Werkzeuge und Reihenfolge, ist aber keine vollständige Parameterreferenz. Werkzeugparameter finden Sie in der MCP-API-Referenz; für die Ersteinrichtung verwenden Sie den Schnellstart.

Das richtige Werkzeug wählen#

Die meisten Fragen beginnen mit einem Aufruf. Wechseln Sie nur dann zu einem spezielleren Werkzeug, wenn die erste Antwort zu breit oder zu dünn ist.

  • intelligent_search — beginnen Sie hier bei jeder natürlichsprachlichen Frage zur Codebasis; der Aufruf verteilt auf semantische, Symbol-, Struktur- und Abhängigkeitssuche.
  • find_symbol — Funktions-, Klassen- oder Variablenname ist bereits bekannt.
  • dependency_search — Auswirkungsradius: Aufrufer, Abhängige 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.

Client installieren und prüfen#

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

  1. Erstellen Sie in app.maguyva.ai einen API-Schlüssel; Schlüssel beginnen mit mgv_.
  2. Verbinden und indexieren Sie mindestens ein GitHub-Repository, das Sie bereits kennen.
  3. Richten Sie den Client anhand der Installationsanleitung ein: als Claude Code-Plugin oder über die native Remote-Konfiguration für Cursor, VS Code, Windsurf, Zed und weitere.
  4. Fragen Sie Ihren Agenten "Welche Repositorys habe ich verbunden?" — damit werden Authentifizierung und repository_context durchgängig geprüft.
  5. Stellen Sie eine echte Frage zu diesem Repository, deren Antwort Sie bewerten können. Sie sollten Dateipfade und Zeilennummern aus dem indexierten Baum sehen.

Probleme mit Schlüsseln, Bridges oder fehlenden Repositorys? Siehe Fehlerbehebung.

Vor dem Bearbeiten nachfragen#

Erfassen Sie Symbole und Auswirkungsradius, bevor Sie gemeinsam genutzten Code ändern. Maguyva-Werkzeuge verändern Ihre Repositorys nicht; sie liefern die Grundlage für die lokale Änderung durch Ihren Client.

  1. Wenn Sie den Symbolnamen kennen, rufen Sie find_symbol auf, um Definitionen und Verwendungen zu finden.
  2. Wenn Sie nur eine Aufgabenbeschreibung haben, etwa „SSO hinzufügen“ oder „Billing-Webhook reparieren“, beginnen Sie mit get_task_context oder intelligent_search.
  3. Rufen Sie vor der Änderung eines gemeinsam genutzten Symbols dependency_search mit Abhängigen- oder Wirkungsanalyse auf; für eine PR-artige Analyse können Sie auch geänderte Pfade übergeben. So wird der Auswirkungsradius sichtbar.
  4. Öffnen Sie die angegebenen Dateien — lokal für Dateien auf dem Datenträger, mit get_file für Remote- oder repositoryübergreifende Pfade — und gleichen Sie den Plan mit echtem Code ab.
  5. Prüfen Sie dieselben Symbole nach der Änderung erneut mit dependency_search; verwenden Sie, falls unterstützt, auch die Prüfoptionen nach der Änderung. So stellen Sie sicher, dass Aufrufer weiterhin wie erwartet aufgelöst werden.

Alle Parameter: MCP-API-Referenz.

Suchen, dann ändern#

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

  1. Beginnen Sie mit intelligent_search und einer natürlichsprachlichen Frage wie „Wie funktioniert der Ablauf einer Sitzung?“ oder „Wo liegt die Wiederholungslogik?“.
  2. Grenzen Sie mit Sprach- oder Pfadfiltern ein, wenn das erste Ergebnisfenster zu viel Rauschen enthält.
  3. Untersuchen Sie vielversprechende Treffer mit find_symbol oder dependency_search, statt dieselbe vage Frage erneut zu stellen.
  4. Verwenden Sie get_file nur für einen bestimmten indexierten Pfad, der nicht lokal vorhanden ist.
  5. Bearbeiten Sie mit Ihren üblichen Client-Werkzeugen. Maguyva dient der Erkundung und Prüfung, nicht dem Schreiben.

Warum dieser Ablauf funktioniert: Funktionsweise.

Leere oder dürftige Ergebnisse#

Wenn Werkzeuge nichts Brauchbares liefern, beheben Sie zuerst Auflösung und Indexierung, statt die Anfrage endlos umzuschreiben.

  1. Prüfen Sie in app.maguyva.ai, ob das Repository verbunden und vollständig indexiert ist.
  2. Prüfen Sie 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. Rufen Sie repository_context mit action="info" auf und prüfen Sie die Auflösungsmetadaten, beispielsweise metadata.resolution_reason.
  4. Lassen Sie repository nur weg, wenn Ihr MCP-Client einen Standardwert bereitstellt oder der Schlüssel genau ein Repository sehen kann; andernfalls geben Sie den Wert ausdrücklich an.
  5. Versuchen Sie es mit einer genaueren Frage, einem bekannten Symbol über find_symbol oder einem Sprach-/Pfadfilter erneut. Ist die Verbindung selbst defekt, verwenden Sie Fehlerbehebung.

Einrichtungsfehler: Fehlerbehebung.

Mit mehreren Repositorys arbeiten#

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

  1. Rufen Sie repository_context einmal mit action="list" auf, um die exakten Slugs zu erfahren, die Ihr Schlüssel durchsuchen kann.
  2. Übergeben Sie repository bei Such- und Symbolwerkzeugen ausdrücklich, wenn Sie ein anderes als das Standard-Repository benötigen, etwa "owner/other-repo" oder "owner/other-repo:develop".
  3. Eine Frage entspricht einem Repository, außer Sie vergleichen bewusst in getrennten Aufrufen.
  4. Verwenden Sie get_file, wenn die Datei in einem indexierten Repository statt in Ihrem 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.

Neu bei Maguyva? Arbeiten Sie zuerst den Schnellstart durch und kommen Sie für die Abläufe des zweiten Tages hierher zurück.

Nächste Schritte#