Zum Inhalt springen

MCP-API-Referenz

Vollständige Referenz für alle 11 kundenseitigen Maguyva-MCP-Tools. Jedes Tool enthält Parameter, Nutzungshinweise und Empfehlungen zum optimalen Einsatz.

API-Übersicht#

Die Maguyva-MCP-API stellt derzeit 11 kundenseitige Tools in 4 Hauptkategorien bereit:

  • Zentrale Suchtools - Erweiterte Suchfunktionen für deine Codebase
  • Struktur- und Graph-Tools - AST-Abfragen, Symbol Lookup und Abhängigkeitsanalyse
  • Code-Analyse-Tools - Tiefgehende Code-Analyse und Beziehungs-Mapping
  • System- und Utility-Tools - Repository-Kontext, deterministische Berechnungen und Anleitung

Alle Tools verwenden ein einheitliches Repository-Identifikationsformat: "owner/repo:branch". Der Branch ist standardmäßig main, wenn nicht angegeben.

Lassen Sie repository weg, wenn Ihr MCP-Client einen Standardwert für die Anfrage bereitstellt oder der Schlüssel auf genau ein Repository zugreifen kann; übergeben Sie es andernfalls ausdrücklich. Prüfen Sie mit repository_context(action="info", repository="owner/repo"), wie ein Repository aufgelöst wird.

Repository-Parameterformat#

Alle MCP-Tools verwenden dieses Repository-Identifikationsformat:

  • Mit Branch: "owner/repo:branch" - z. B. "owner/repository:develop"
  • Standard-Branch: "owner/repo" - verwendet den main-Branch, wenn kein Branch angegeben ist "owner/repository"
  • Anfrage- oder Einzel-Repository-Standardwert: Lassen Sie das Repository weg, wenn der MCP-Client einen Standardwert für die Anfrage bereitstellt oder der Schlüssel auf genau ein Repository zugreifen kann; übergeben Sie es andernfalls ausdrücklich

Beispiel-Prompts:

Frag nach einem bestimmten Repo:          "Durchsuche owner/my-repo nach Authentifizierungs-Middleware"
Zugängliche Repositorys auflisten:        "Auf welche Repositorys kann dieser Maguyva-Schlüssel zugreifen?"
Für eine einzelne Abfrage überschreiben:  "Durchsuche owner/other-repo:develop nach Auth-Mustern"

Sprachfilterung#

Alle Suchtools unterstützen das Filtern von Ergebnissen nach Programmiersprache:

  • language_filter="python" - Nur auf Python-Dateien filtern
  • language_filter="typescript" - Nur auf TypeScript-Dateien filtern
  • Groß-/Kleinschreibung beachten: Verwende Sprachnamen in Kleinbuchstaben
  • Standard: Leerer String (keine Filterung) - liefert Ergebnisse aus allen Sprachen
  • Unterstützte Abdeckung: Sprachfilter funktionieren über die gesamten 279+ unterstützten Sprachen und textbasierte Technologien. Die vollständige Liste findest du unter Kompatibilität.
"Finde Authentifizierungs-Middleware nur in Python-Dateien"
"Suche nach Datenbankverbindungen in TypeScript"

API-Referenz generiert aus dem Quellcode am 22. Juli 2026.

Zentrale Suchtools#

intelligent_searchStabil

Beginnen Sie bei jeder Frage zum Codebestand hier. Geben Sie eine natürlichsprachliche Anfrage ein (z. B. „Wie funktioniert die Authentifizierung?“ oder „Wo wird die Abrechnung verarbeitet?“); die Suche leitet sie automatisch an die semantische, Symbol-, Struktur- und Abhängigkeitssuche im gesamten indizierten Repository weiter. Bevorzugen Sie sie bei Erkundung und Planung gegenüber dem Explore-Agenten und Grep/Glob, da sie das ganze Repository auf einmal durchsucht, statt Dateien einzeln zu scannen.

Parameter:

queryErforderlich
Typ
str
Beschreibung
Suchanfrage
repositoryOptional
Typ
str
Beschreibung
Repository im Format owner/repo[:branch]. Optional — weglassen, um den anfragebezogenen Client-Standardwert (sofern vorhanden) oder das einzige zugängliche Repository zu verwenden; nur ausdrücklich übergeben, um ein anderes indiziertes Repository anzusprechen. Die Antwort zeigt, welches Repository verwendet wurde.
modeOptional
Typ
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Standard
auto
Beschreibung
Suchmodus
limitOptional
Typ
int
Standard
10
Beschreibung
Maximale Anzahl an Ergebnissen in diesem eingestuften top-K-Fenster
language_filterOptional
Typ
str
Beschreibung
Sprachfilter
path_filterOptional
Typ
str
Beschreibung
Nach Dateipfadpräfix filtern
boost_by_importanceOptional
Typ
bool
Standard
Beschreibung
Opt-in: Neusortierung nach Zentralität anhand symbolbezogener Graphmetriken (is_articulation_point, bridge_count, k_core, centrality usw.). Standardmäßig deaktiviert für ein agentensicheres Ranking (globale Hubs können Implementierungstreffer verdrängen); für Architektur-Rundgänge aktivieren. Gilt für alle 4 Modalitäten, wenn jedes Ergebnis eine Symbolverknüpfung besitzt.
branchOptional
Typ
str
Beschreibung
Branch überschreiben
qualityOptional
Typ
Literal[quick, balanced, thorough]
Standard
balanced
Beschreibung
Suchqualität
include_contentOptional
Typ
bool
Standard
true
Beschreibung
Inhalt in die Ergebnisse aufnehmen
explain_routingOptional
Typ
bool
Standard
Beschreibung
Erklärung der Routing-Entscheidung einbeziehen
importance_weightOptional
Typ
float
Standard
0.3
Beschreibung
Gewichtung der Wichtigkeitsanhebung (0=keine, 1=voll)
orphansOptional
Typ
bool
Standard
Beschreibung
Gibt Symbole ohne eingehende Referenzen zurück (potenziell toter Code). Nützlich für Aufräumarbeiten, kann aber Decorators, innere Funktionen und CLI-Einstiegspunkte enthalten.
include_community_contextOptional
Typ
bool
Standard
Beschreibung
Verwandte Symbole aus derselben Code-Community für einen breiteren Kontext einschließen. Hilfreich, um zu erkunden, wie ein Feature oder Modul funktioniert.
community_depthOptional
Typ
int
Standard
1
Beschreibung
Tiefe der Erweiterung des Community-Kontexts
graph_viewOptional
Typ
Literal[dependency, type, data_flow, control_flow]
Standard
dependency
Beschreibung
Graphansicht für Metriken
seed_symbol_idsOptional
Typ
list[str]
Beschreibung
Tier-1-Aufgaben-Seeds: Symbol-IDs, die für die aktuelle Aufgabe von zentraler Bedeutung sind. Wenn diese Einstellung festgelegt ist, werden verschmolzene Treffer nach Approach A-Tiefenzerfallsnähe (exakte Startwertübereinstimmung + Diagrammkantensprünge) neu eingestuft. Additiv – für globales Ranking weglassen.
seed_file_pathsOptional
Typ
list[str]
Beschreibung
Tier-1-Task-Seeds: indizierte Dateipfade, die der Agent geöffnet oder gerade bearbeitet hat. Wenn diese Option festgelegt ist, werden verschmolzene Treffer nach Pfadnähe mit 1/(1+d)-Tiefenzerfall neu eingestuft (gleiche Datei → gleiches Verzeichnis → nahegelegene Pakete). Additiv – für globales Ranking weglassen.

Am besten geeignet für:

  • Indexweite oder Kaltstart-Exploration, wenn das richtige Werkzeug unklar ist
  • Multimodales, fusioniertes Ranking über semantische, Text-, Struktur- und Graphsuche hinweg

Nicht empfohlen für:

  • Ein bekannter Symbolname — verwenden Sie direkt find_symbol
  • Ein bekannter Pfad auf der Festplatte — verwenden Sie zuerst das lokale Read/Grep

semantic_searchStabil

Findet Code nach Bedeutung statt nach exaktem Text. Verwenden Sie dies für konzeptionelle Anfragen wie „Wiederholungslogik“ oder „Onboarding-Ablauf“, wenn Schlüsselwort oder Symbolname unbekannt sind. Liefert die relevantesten Codeabschnitte nach Wichtigkeit sortiert. Bei konzeptioneller Suche gegenüber Grep bevorzugen.

Parameter:

queryErforderlich
Typ
str
Beschreibung
Suchanfrage (konzeptionell, bedeutungsbasiert)
repositoryOptional
Typ
str
Beschreibung
Repository im Format owner/repo[:branch]. Optional — weglassen, um den anfragebezogenen Client-Standardwert (sofern vorhanden) oder das einzige zugängliche Repository zu verwenden; nur ausdrücklich übergeben, um ein anderes indiziertes Repository anzusprechen. Die Antwort zeigt, welches Repository verwendet wurde.
limitOptional
Typ
int
Standard
5
Beschreibung
Maximale Anzahl an Ergebnissen in diesem eingestuften top-K-Fenster
similarity_thresholdOptional
Typ
float
Standard
0.6
Beschreibung
Minimaler Ähnlichkeitswert
language_filterOptional
Typ
str
Beschreibung
Ergebnisse auf Dateien filtern, die als diese Programmiersprache erkannt wurden
path_filterOptional
Typ
str
Beschreibung
Nach Dateipfadpräfix filtern
boost_by_importanceOptional
Typ
bool
Standard
Beschreibung
Opt-in: Neusortierung nach PageRank-Zentralität (standardmäßig deaktiviert für ein agentensicheres Ranking; für Architektur-Rundgänge aktivieren)
branchOptional
Typ
str
Beschreibung
Branch überschreiben (Standard: aus dem repository-Parameter oder main)
include_contentOptional
Typ
bool
Standard
true
Beschreibung
Abschnittsinhalt in die Ergebnisse aufnehmen
graph_viewOptional
Typ
Literal[dependency, type, data_flow, control_flow]
Standard
dependency
Beschreibung
Graphansicht für Metriken

Am besten geeignet für:

  • Konzeptionelle Anfragen („Wie funktioniert die Authentifizierung?“, „Caching-Strategie“)
  • Paketübergreifende Ähnlichkeitssuche

Nicht empfohlen für:

  • Ein bekannter Symbolname — verwenden Sie stattdessen find_symbol
  • Exakte Zeichenfolgen oder Fehlermeldungen — verwenden Sie text_pattern_search

text_pattern_searchStabil

Durchsucht indizierte Inhalte. Die Modi exact und regex durchsuchen den vollständigen Datei-/Blob-Korpus; fuzzy content durchsucht den begrenzten semantischen Abschnittskorpus. Datei- und Symbolbereiche unterstützen nur fuzzy. Für ein enges, bereits lokales Verzeichnis verwenden Sie Grep.

Parameter:

queryErforderlich
Typ
str
Beschreibung
Textmuster
repositoryOptional
Typ
str
Beschreibung
Repository im Format owner/repo[:branch]. Optional — weglassen, um den anfragebezogenen Client-Standardwert (sofern vorhanden) oder das einzige zugängliche Repository zu verwenden; nur ausdrücklich übergeben, um ein anderes indiziertes Repository anzusprechen. Die Antwort zeigt, welches Repository verwendet wurde.
modeOptional
Typ
Literal[fuzzy, exact, regex]
Standard
exact
Beschreibung
Suchmodus
search_scopeOptional
Typ
Literal[content, symbols, files]
Standard
content
Beschreibung
Zu durchsuchender Bereich
limitOptional
Typ
int
Standard
5
Beschreibung
Maximale Anzahl der auf dieser Seite zurückgegebenen Ergebnisse
offsetOptional
Typ
int
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzugen Sie cursor aus pagination.next_cursor.
cursorOptional
Typ
str
Beschreibung
Undurchsichtiger Cursor aus pagination.next_cursor. Unverändert übergeben und Abfrage sowie Filter unverändert lassen.
language_filterOptional
Typ
str
Beschreibung
Sprachfilter
path_filterOptional
Typ
str
Beschreibung
Nach Dateipfadpräfix filtern
case_sensitiveOptional
Typ
bool
Standard
Beschreibung
Groß-/Kleinschreibung beachten
branchOptional
Typ
str
Beschreibung
Branch überschreiben
fuzzy_algorithmOptional
Typ
Literal[hybrid, trigram, levenshtein]
Standard
hybrid
Beschreibung
Algorithmus für unscharfe Übereinstimmung
thresholdOptional
Typ
float
Standard
0.05
Beschreibung
Mindestschwelle der Ähnlichkeit für die unscharfe Suche
semantic_fallbackOptional
Typ
bool
Standard
Beschreibung
Bei fehlenden Ergebnissen auf semantische Suche zurückgreifen

Am besten geeignet für:

  • Exakte Zeichenfolgen, Fehlermeldungen und Regex
  • Trigram-Fuzzy-Abgleich für nahezu passenden Text

Nicht empfohlen für:

  • Ein bekannter Pfad auf der Festplatte — bevorzugen Sie das lokale Grep
  • Konzeptionelle Anfragen — verwenden Sie semantic_search

Struktur- und Graph-Tools#

structural_searchStabil

Bevorzugen Sie preset=functions|classes|methods|imports|variables (oder freies pattern=). Findet Code anhand der AST-Form (nicht des Texts). Filter der mittleren Ebene: name_pattern, node_type, decorator, parent_child. Path-/ltree-/call-Filter sind erweitert — setzen Sie advanced=true, wenn Sie sie gezielt verwenden; flache advanced-Schlüssel werden aus Kompatibilitätsgründen weiterhin akzeptiert. Geben Sie mindestens einen strukturellen Selektor an.

Parameter:

repositoryOptional
Typ
str
Beschreibung
Repository im Format owner/repo[:branch]. Optional — weglassen, um den anfragebezogenen Client-Standardwert (sofern vorhanden) oder das einzige zugängliche Repository zu verwenden; nur ausdrücklich übergeben, um ein anderes indiziertes Repository anzusprechen. Die Antwort zeigt, welches Repository verwendet wurde.
presetOptional
Typ
Literal[functions, classes, methods, imports, variables]
Beschreibung
Bevorzugter struktureller Selektor. Wird auf sprachübergreifende AST-Knotentypen erweitert — functions (Funktions-/Arrow-/Methodendefinitionen über Sprachen hinweg); classes (Class-/Struct-/Impl-Definitionen); methods (Methodendefinitionen, sowie function_definition für Sprachen ohne Methodenknoten); imports (import-/use-/include-Anweisungen); variables (variable-/let-/const-/static-Deklarationen). Für browse-artige Abfragen gegenüber freiem pattern/node_type zu bevorzugen.
patternOptional
Typ
str
Beschreibung
Freiform-Muster, wenn Presets zu grob sind (automatisch erkannt: 'def foo(' → node_type + name_pattern). Für Browse-Abfragen preset= bevorzugen.
name_patternOptional
Typ
str
Beschreibung
Symbolnamen-Muster (Shell-Wildcard, begrenzter POSIX-Regex oder Fuzzy-Text; max. 256 Zeichen)
node_typeOptional
Typ
str
Beschreibung
AST-Knotentyp (function_definition, class_definition usw.) — für gängige Formen preset= bevorzugen
decoratorOptional
Typ
str
Beschreibung
Decorator-Namensfilter
base_classOptional
Typ
str
Beschreibung
Basisklassen-Namensfilter (findet Klassen, die davon erben)
language_filterOptional
Typ
str
Beschreibung
Sprachfilter
limitOptional
Typ
int
Standard
20
Beschreibung
Maximale Anzahl der auf dieser Seite zurückgegebenen Ergebnisse
offsetOptional
Typ
int
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzugen Sie cursor aus pagination.next_cursor.
cursorOptional
Typ
str
Beschreibung
Undurchsichtiger Cursor aus pagination.next_cursor. Unverändert übergeben und Abfrage sowie Filter unverändert lassen.
path_filterOptional
Typ
str
Beschreibung
Nach Dateipfadpräfix filtern
branchOptional
Typ
str
Beschreibung
Branch überschreiben
query_typeOptional
Typ
Literal[node_type, name_pattern, parent_child]
Beschreibung
Expliziter Abfragetyp
parent_typeOptional
Typ
str
Beschreibung
Filter für den übergeordneten AST-Knotentyp
relationshipOptional
Typ
Literal[parent, ancestor]
Standard
parent
Beschreibung
Für parent_child-Abfragen: nur das direkte Elternelement oder ein beliebiger Vorfahr (ancestor für Klassenmethoden verwenden, die in einem Klassenrumpf/-block verschachtelt sind)
has_modifierOptional
Typ
str
Beschreibung
Nach Modifikator filtern (export, async, static usw.)
advancedOptional
Typ
bool
Standard
Beschreibung
Legen Sie true fest, wenn Sie absichtlich erweiterte Pfad-, Ltree- oder Aufruffilter verwenden (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Standardmäßig konzentriert sich false die Agentenoberfläche auf Voreinstellungen. Erweiterte Schlüssel im flachen Format funktionieren aus Gründen der Abwärtskompatibilität weiterhin mit einer Metadatenwarnung.
callee_textOptional
Typ
str
Beschreibung
Erweitert — bevorzugen Sie preset=functions|classes|methods|imports|variables. Filter für den Callee-Text eines Aufrufausdrucks. Setzen Sie advanced=true, wenn Sie path-/ltree-/call-Filter bewusst verwenden.
callee_nameOptional
Typ
str
Beschreibung
Erweitert — bevorzugen Sie preset=functions|classes|methods|imports|variables. Filter für den Callee-Namen eines Aufrufausdrucks. Setzen Sie advanced=true, wenn Sie path-/ltree-/call-Filter bewusst verwenden.
field_roleOptional
Typ
str
Beschreibung
Erweitert — bevorzugen Sie preset=functions|classes|methods|imports|variables. Filter für die AST-Feldrolle. Setzen Sie advanced=true, wenn Sie path-/ltree-/call-Filter bewusst verwenden.
ltree_ancestorOptional
Typ
str
Beschreibung
Erweitert — bevorzugen Sie preset=functions|classes|methods|imports|variables. Filter für den AST-ltree-Vorfahrenpfad. Setzen Sie advanced=true, wenn Sie path-/ltree-/call-Filter bewusst verwenden.
ltree_descendantOptional
Typ
str
Beschreibung
Erweitert — bevorzugen Sie preset=functions|classes|methods|imports|variables. Filter für den AST-ltree-Nachfahrenpfad. Setzen Sie advanced=true, wenn Sie path-/ltree-/call-Filter bewusst verwenden.
definition_nameOptional
Typ
str
Beschreibung
Erweitert — bevorzugen Sie preset=functions|classes|methods|imports|variables. Filter für den Definitionsnamen. Setzen Sie advanced=true, wenn Sie path-/ltree-/call-Filter bewusst verwenden.
min_depthOptional
Typ
int
Beschreibung
Erweitert — bevorzugen Sie preset=functions|classes|methods|imports|variables. Minimale AST-Tiefe. Setzen Sie advanced=true, wenn Sie path-/ltree-/call-Filter bewusst verwenden.
max_depthOptional
Typ
int
Beschreibung
Erweitert — bevorzugen Sie preset=functions|classes|methods|imports|variables. Maximale AST-Tiefe. Setzen Sie advanced=true, wenn Sie path-/ltree-/call-Filter bewusst verwenden.

Am besten geeignet für:

  • Struktur auf AST-Ebene: Klassen, Decorators, Function-/Method-Presets
  • Code anhand seiner Form statt seines Texts finden

Nicht empfohlen für:

  • Freitext- oder konzeptionelle Anfragen — verwenden Sie semantic_search oder intelligent_search

dependency_searchStabil

Primäre Auswirkungsradius-/Graph-Oberfläche. Beantwortet „Was ruft dies auf?“ / „Was verwendet dies?“ über den echten Aufruf-/Import-Graphen. Für die Auswirkungsprüfung vor einer Änderung: analysis_type="dependents" oder analysis_type="impact" (eingehend, standardmäßig shallow für impact), include_metrics=false standardmäßig (für Zentralität + refactor_risk optional aktivierbar). PR-/Diff-Auswirkung (P1-8): changed_paths und/oder patch (Unified Diff) übergeben — löst Symbole pro Pfad auf und liefert eine kompakte, flach eingehende dependents-Nutzlast ohne erforderlichen Symbolnamen. Nach einer Änderung verify_after_edit=true mit targets und/oder changed_paths setzen für eine kompakte Multi-Root-Nachabfrage betroffener Symbole. Unterstützt außerdem dependencies, centrality und orphans. analyze_dependencies ist ein dünner Alias für den impact-Pfad — für neue Agenten dieses Werkzeug bevorzugen.

Parameter:

repositoryOptional
Typ
str
Beschreibung
Repository im Format owner/repo[:branch]. Optional — weglassen, um den anfragebezogenen Client-Standardwert (sofern vorhanden) oder das einzige zugängliche Repository zu verwenden; nur ausdrücklich übergeben, um ein anderes indiziertes Repository anzusprechen. Die Antwort zeigt, welches Repository verwendet wurde.
queryOptional
Typ
str
Beschreibung
Symbolname oder Suchbegriff
targetOptional
Typ
str
Beschreibung
Symbolname (Alias für query)
changed_pathsOptional
Typ
list[str]
Beschreibung
Repo-relative Pfade für PR/diff-Auswirkungen (Standard) oder, mit verify_after_edit=true, Nachbearbeitung der Verifizierungswurzeln. PR/diff: Löst Symbole pro Pfad auf und geht flache eingehende Abhängige durch; kombinierbar mit patch=. Verifizieren: Löst bis zu 5 Symbole pro Pfad als Verifizierungswurzeln auf (im Verifizierungsmodus nach unten begrenzt). Für den PR/diff-Aufprall ist query/target nicht erforderlich.
patchOptional
Typ
str
Beschreibung
PR/diff-Auswirkungen: einheitlicher Diff/Git-Patch-Text. Pfade werden aus den Headern diff --git / --- / +++ analysiert. Gleicher kompakter Aufprallpfad wie changed_paths.
analysis_typeOptional
Typ
Literal[centrality, dependencies, dependents, impact, orphans]
Standard
dependencies
Beschreibung
Analysemodus. impact = Auswirkungsradius (eingehende dependents; shallow-Tiefe, wenn depth nicht angegeben ist). dependents beantwortet ebenfalls impact. Wenn changed_paths oder patch gesetzt ist, wird die Analyse auf PR-/Diff-impact erzwungen. centrality/orphans benötigen kein target.
depthOptional
Typ
Literal[shallow, balanced, deep]
Standard
balanced
Beschreibung
Traversierungstiefe. Für analysis_type=impact und PR-/Diff-impact ist der effektive Standardwert shallow, sofern depth nicht explizit gesetzt wird.
limitOptional
Typ
int
Standard
20
Beschreibung
Maximale Anzahl der auf dieser Seite zurückgegebenen Ergebnisse
offsetOptional
Typ
int
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzugen Sie cursor aus pagination.next_cursor.
cursorOptional
Typ
str
Beschreibung
Undurchsichtiger Cursor aus pagination.next_cursor. Unverändert übergeben und Abfrage sowie Filter unverändert lassen.
path_filterOptional
Typ
str
Beschreibung
Schränkt die Auflösung des Zielsymbols auf ein Dateipfad-Präfix ein; zurückgegebene Graphbeziehungen können über diesen Pfad hinausreichen
language_filterOptional
Typ
str
Beschreibung
Filtert Zielauflösung und Browse-Ergebnisse nach Sprache
directionOptional
Typ
Literal[outgoing, incoming, both]
Beschreibung
Traversierungsrichtung (überschreibt die Ableitung aus analysis_type)
relationship_typesOptional
Typ
list[str]
Beschreibung
Filtert Kantentypen (CALL, IMPORT, INHERITS_FROM usw.). Eine nicht leere Liste überschreibt die graph_view-Standardwerte.
exclude_test_pathsOptional
Typ
bool
Standard
true
Beschreibung
Standard true: schließt Test-, Fixture-, Vendor- und Beispielpfade aus Traversierungs- und Zentralitätsergebnissen aus. Auf false setzen, um sie einzuschließen. Die Orphan-Analyse wendet stets ihre eigenen strengeren Rauschausschlüsse an.
exclude_generated_pathsOptional
Typ
bool
Standard
Beschreibung
Schließen Sie generierte Deklarationen sowie Build-, Coverage-, Cache-, Source-Map- und minimierte Artefaktpfade von den Traversal-Ergebnissen aus
include_module_symbolsOptional
Typ
bool
Standard
Beschreibung
Standardmäßig schließt false Diagrammkanten aus, wenn from_name oder to_name das synthetische __module__-Symbol (Rauschen auf Modulebene) ist. Legen Sie true fest, um Kanten auf Modulebene in die Ergebnisse für Abhängigkeits- und Abhängigkeitsbeziehungen einzubeziehen.
branchOptional
Typ
str
Beschreibung
Branch überschreiben
per_hop_limitOptional
Typ
int
Beschreibung
Maximale Anzahl an Beziehungen pro Hop (1–300)
include_metricsOptional
Typ
bool
Standard
Beschreibung
Optionale Graphmetriken auf Ergebniszeilen (kompakt mit refactor_risk). Metriken werden auch intern abgerufen, wenn min_centrality>0 ist, aber nur zurückgegeben, wenn dies true ist.
metrics_detailOptional
Typ
Literal[summary, full]
Standard
summary
Beschreibung
Wenn include_metrics=true: summary (Standard) gibt Entscheidungssignale + refactor_risk zurück; full gibt den größeren kuratierten Metriksatz zurück
include_edge_metadataOptional
Typ
bool
Standard
Beschreibung
Rohkanten-Metadaten und -Gewichte einbeziehen (groß). Bei kompakten Impact-Nutzlasten entfällt dies.
symbol_typesOptional
Typ
list[str]
Beschreibung
Filtert zurückgegebene Symbole nach Art (function, class, method usw.)
exact_matchOptional
Typ
bool
Standard
Beschreibung
Erfordert exakten Symbolnamen-Abgleich (Groß-/Kleinschreibung wird ignoriert). Deaktiviert Fuzzy-Matching
find_similar_patternsOptional
Typ
bool
Standard
Beschreibung
Ähnliche Verwendungsmuster finden
min_centralityOptional
Typ
float
Standard
0
Beschreibung
Minimaler PageRank-Wert. Metriken werden intern zum Filtern abgerufen; graph_metrics werden nur zurückgegeben, wenn include_metrics=true ist.
graph_viewOptional
Typ
Literal[dependency, type, data_flow, control_flow]
Standard
dependency
Beschreibung
Graphansicht, die für Traversierungs-Beziehungsstandards, Metriken und Zentralitäts-Ranking verwendet wird; die Orphan-Analyse wird über alle Ansichten hinweg berechnet
verify_after_editOptional
Typ
bool
Standard
Beschreibung
P2-7-Post-Edit-Überprüfungsmodus: Fragen Sie das indizierte Auswirkungsdiagramm erneut nach kürzlich bearbeiteten Symbolen in einer kompakten Multi-Root-Antwort ab. Erfordert targets und/oder changed_paths (oder target/query). Standardmäßig werden flache eingehende Abhängige verwendet; Die Ergebnisse spiegeln das indizierte Diagramm wider (kann Live-Änderungen verzögern). Wenn „true“, hat es Vorrang vor der Auswirkung von PR/diff auf denselben changed_paths.
targetsOptional
Typ
list[str]
Beschreibung
Bei verify_after_edit=true: Symbolnamen zur erneuten Überprüfung (Anrufer/Angehörige). Wird mit target/query zusammengeführt, wenn beide angegeben sind.

Am besten geeignet für:

  • Auswirkungsradius-/Impact-Analyse vor der Änderung eines gemeinsam genutzten Symbols
  • PR-/Diff-Auswirkung über changed_paths oder patch
  • Verifizierung nach der Bearbeitung über verify_after_edit

Nicht empfohlen für:

  • Einfache Text- oder Symbolsuchen — verwenden Sie text_pattern_search oder find_symbol

Code-Analyse-Tools#

find_symbolStabil

Springt zur Definition und Verwendung einer Funktion, Klasse oder Variablen. Verwenden Sie dies, wenn der Name bekannt ist (z. B. „getCurrentUser“): schneller und präziser als Grep und über das gesamte indizierte Repository. Kann optional Referenzen und Wichtigkeitsmetriken liefern.

Parameter:

symbol_nameOptional
Typ
str
Beschreibung
Zu suchender Symbolname (optional — weglassen, um nach Metriken zu durchsuchen)
repositoryOptional
Typ
str
Beschreibung
Repository im Format owner/repo[:branch]. Optional — weglassen, um den anfragebezogenen Client-Standardwert (sofern vorhanden) oder das einzige zugängliche Repository zu verwenden; nur ausdrücklich übergeben, um ein anderes indiziertes Repository anzusprechen. Die Antwort zeigt, welches Repository verwendet wurde.
scopeOptional
Typ
Literal[definitions, references, both]
Standard
both
Beschreibung
Umfang: definitions|references|both
limitOptional
Typ
int
Standard
15
Beschreibung
Maximale Anzahl der auf dieser Seite zurückgegebenen Ergebnisse
offsetOptional
Typ
int
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzugen Sie cursor aus pagination.next_cursor.
cursorOptional
Typ
str
Beschreibung
Undurchsichtiger Cursor aus pagination.next_cursor. Unverändert übergeben und Abfrage sowie Filter unverändert lassen.
find_similarOptional
Typ
bool
Standard
Beschreibung
Ähnliche Symbole finden
include_metricsOptional
Typ
bool
Standard
Beschreibung
Zentralitätsmetriken einbeziehen
metrics_detailOptional
Typ
Literal[summary, full]
Standard
summary
Beschreibung
Wenn include_metrics=true: summary (Standard) gibt Entscheidungssignale + refactor_risk zurück; full gibt den größeren kuratierten Metriksatz zurück
path_filterOptional
Typ
str
Beschreibung
Nach Dateipfadpräfix filtern
branchOptional
Typ
str
Beschreibung
Branch überschreiben
symbol_typeOptional
Typ
Literal[function, class, variable, method, constant, module, interface, type]
Beschreibung
Symboltypfilter
high_impactOptional
Typ
bool
Standard
Beschreibung
Durchsucht architektonisch wichtige Symbole (symbol_name weglassen). Standardmodus ist popularity (oberstes PageRank-Dezil abzüglich Utility-Mega-Hubs). Für Artikulations-/Bridge-Schnittknoten high_impact_mode=risk setzen.
high_impact_modeOptional
Typ
Literal[popularity, risk]
Standard
popularity
Beschreibung
Wenn high_impact=true: Beliebtheit = oberstes PageRank-Dezil minus Versorgungs-Mega-Hubs/Module; Risiko = Artikulationspunkte, sortiert nach SMV bridge_count, dann k_core (strukturelles Refaktorierungsrisiko, nicht Hub-Popularität)
in_cycleOptional
Typ
bool
Standard
Beschreibung
Nur in Zyklus
exclude_test_pathsOptional
Typ
bool
Standard
true
Beschreibung
Schließen Sie beim Durchsuchen nach Diagrammmetriken vor dem Ranking Tests, fixtures, Code von Drittanbietern und Beispiele aus. Die Suche nach einem benannten Symbol bleibt unverändert.

Am besten geeignet für:

  • Nachschlagen der Definition, Referenzen und Graphmetriken eines bekannten Symbols
  • Durchsuchen nach centrality, high_impact oder in_cycle, wenn symbol_name weggelassen wird

Nicht empfohlen für:

  • Konzeptionelle Anfragen oder unbekannte Bereiche — verwenden Sie intelligent_search oder semantic_search

analyze_dependenciesStabil

Alias für Auswirkungsradius über dependency_search (dependents/incoming). Für neue Agenten dependency_search mit analysis_type="dependents" oder "impact" bevorzugen. Behält die alte Multi-Hop-impact-Antwortform bei (graph, connection_summary, optionale Metriken mit refactor_risk). Mit graph_view die Beziehungsfamilie eingrenzen: dependency (Standard), type, data_flow, control_flow.

Parameter:

repositoryOptional
Typ
str
Beschreibung
Repository im Format owner/repo[:branch]. Optional — weglassen, um den anfragebezogenen Client-Standardwert (sofern vorhanden) oder das einzige zugängliche Repository zu verwenden; nur ausdrücklich übergeben, um ein anderes indiziertes Repository anzusprechen. Die Antwort zeigt, welches Repository verwendet wurde.
targetErforderlich
Typ
str
Beschreibung
Zu analysierender Symbolname
depthOptional
Typ
Literal[shallow, balanced, deep]
Standard
balanced
Beschreibung
Analysetiefe (unterstützt Aliasse: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)
limitOptional
Typ
int
Standard
10
Beschreibung
Maximale Anzahl der auf dieser Seite zurückgegebenen Ergebnisse
offsetOptional
Typ
int
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzugen Sie cursor aus pagination.next_cursor.
cursorOptional
Typ
str
Beschreibung
Undurchsichtiger Cursor aus pagination.next_cursor. Unverändert übergeben und Abfrage sowie Filter unverändert lassen.
directionOptional
Typ
Literal[incoming, outgoing, both]
Standard
incoming
Beschreibung
Traversierungsrichtung: 'outgoing' = wovon dieses Symbol abhängt (seine Abhängigkeiten), 'incoming' = was von diesem Symbol abhängt (seine Abhängigen), 'both' = vollständiger Kontext. Verwende 'incoming', um alle Aufrufer/Nutzer eines Symbols zu finden.
relationship_typesOptional
Typ
list[str]
Beschreibung
Nach Kantenarten filtern (CALL, IMPORT, INHERITS_FROM usw.). Überschreibt bei Angabe immer den unten aus graph_view abgeleiteten Standard.
graph_viewOptional
Typ
Literal[dependency, type, data_flow, control_flow]
Standard
dependency
Beschreibung
Graphansicht: Bestimmt bei include_metrics=true sowohl die standardmäßigen Kantenarten für die Traversierung als auch die Ansicht, deren Metriken verwendet werden. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (Standard), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Wird nur dann als Standard für relationship_types verwendet, wenn relationship_types nicht ausdrücklich angegeben ist. Der Parametername entspricht für Konsistenz zwischen den Tools dem vorhandenen graph_view von dependency_search.
path_filterOptional
Typ
str
Beschreibung
Schränkt die Auflösung des Zielsymbols auf ein Dateipfad-Präfix ein; zurückgegebene Graphbeziehungen können über diesen Pfad hinausreichen
language_filterOptional
Typ
str
Beschreibung
Ergebnisse auf eine Sprache beschränken
branchOptional
Typ
str
Beschreibung
Branch überschreiben
per_hop_limitOptional
Typ
int
Beschreibung
Maximale Anzahl an Beziehungen pro Hop (1–300)
include_metricsOptional
Typ
bool
Standard
Beschreibung
Graphmetriken in die Ergebnisse aufnehmen, jeweils ergänzt um einen abgeleiteten refactor_risk-Block ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). Das Risiko ist "low", wenn das Symbol in der gewählten Ansicht kein Artikulationspunkt ist, "medium" bei einem Artikulationspunkt mit wenigen überbrückten Kanten und "high" bei vielen (heuristischer, nicht empirisch validierter Schwellenwert). Fehlt eine Metrikzeile für Symbol/Ansicht, wird der Block ausgelassen.
metrics_detailOptional
Typ
Literal[summary, full]
Standard
summary
Beschreibung
Wenn include_metrics=true: summary (Standard) gibt Entscheidungssignale + refactor_risk zurück; full gibt den größeren kuratierten Metriksatz zurück
include_edge_metadataOptional
Typ
bool
Standard
Beschreibung
Fügen Sie Raw-Edge-Metadaten und -Gewichtungen hinzu. Standardmäßig deaktiviert, da die Metadaten des Extraktors umfangreich sein können. Die Anreicherungsabdeckung wird gemeldet, wenn sie aktiviert ist.
exclude_test_pathsOptional
Typ
bool
Standard
true
Beschreibung
Standard true: Test-, Fixture-, Hersteller- und Beispielpfade von zurückgegebenen Diagrammkanten ausschließen. Stellen Sie false ein, um sie einzuschließen.
include_module_symbolsOptional
Typ
bool
Standard
Beschreibung
Standardmäßig schließt false Diagrammkanten aus, wenn from_name oder to_name das synthetische __module__-Symbol ist. Stellen Sie true ein, um Kanten auf Modulebene einzubeziehen.

Am besten geeignet für:

  • Legacy-Aufrufer, die bereits auf dessen Antwortform (graph, connection_summary) eingerichtet sind

Nicht empfohlen für:

  • Neue Agenten-Loops — bevorzugen Sie dependency_search, das denselben Traversierungskern nutzt

get_task_contextStabil

Beginnen Sie die Arbeit in einem unbekannten Bereich? Beschreiben Sie die Aufgabe (z. B. „SSO-Unterstützung hinzufügen“, „Abrechnungs-Webhook reparieren“) und erhalten Sie in einem begrenzten Aufruf ein Bündel relevanter Dateien, Code, Symbole und Abhängigkeiten. Seed-Dateien liefern direkten indizierten Inhalt, selbst wenn sie keine Symbole definieren. Für weitere Ergebnisse mit dem spezialisierten Suchwerkzeug der jeweiligen Ebene fortfahren.

Parameter:

task_descriptionErforderlich
Typ
str
Beschreibung
Aufgabenbeschreibung
repositoryOptional
Typ
str
Beschreibung
Repository im Format owner/repo[:branch]. Optional — weglassen, um den anfragebezogenen Client-Standardwert (sofern vorhanden) oder das einzige zugängliche Repository zu verwenden; nur ausdrücklich übergeben, um ein anderes indiziertes Repository anzusprechen. Die Antwort zeigt, welches Repository verwendet wurde.
limitOptional
Typ
int
Standard
15
Beschreibung
Maximale Ergebnisse pro Ebene
scopeOptional
Typ
Literal[semantic, symbols, dependencies, all]
Standard
all
Beschreibung
Einzuschließende Kontextebenen. Gültig: 'semantic', 'symbols', 'dependencies', 'all'. Standard: ['semantic', 'symbols', 'dependencies']
language_filterOptional
Typ
str
Beschreibung
Ergebnisse auf Dateien filtern, die als diese Programmiersprache erkannt wurden
path_filterOptional
Typ
str
Beschreibung
Nach Dateipfadpräfix filtern
branchOptional
Typ
str
Beschreibung
Branch überschreiben
include_related_contextOptional
Typ
bool
Standard
Beschreibung
Verwandten Kontext aus benachbarten Symbolen einbeziehen
seed_symbol_idsOptional
Typ
list[str]
Beschreibung
Explizite Seeds der Stufe 1: Symbol-IDs, von denen der Agent bereits weiß, dass sie für die Aufgabe zentral sind (z. B. Symbole in geöffneten Dateien). Sie werden in den Ebenen dependencies/related_context vor aus Schlüsselwörtern abgeleiteten Seeds eingestuft. Additiv — weglassen, um das heutige reine Schlüsselwortverhalten beizubehalten.
seed_file_pathsOptional
Typ
list[str]
Beschreibung
Tier-1-Explizit-Seeds: indizierte Dateipfade, die der Agent geöffnet oder gerade bearbeitet hat. Liefert begrenzte direkte Dateibelege und löst bis zu 5 Symbole pro Datei für den Graphkontext auf, einschließlich symbolfreier Dokumentation und Konfiguration. Additiv — für ein reines Keyword-Verhalten weglassen.

Am besten geeignet für:

  • Aufgabenbezogener Kontext, der Seed-Dateien mit semantischen, Symbol- und Abhängigkeitsebenen verbindet

Nicht empfohlen für:

  • Einzelabfragen, bei denen ein spezifischeres Werkzeug die Frage bereits beantwortet

get_fileStabil

Liest eine Datei anhand des Pfads aus dem indizierten Repository. Für Dateien auf der Festplatte das lokale Read-Werkzeug bevorzugen — dies für repository-übergreifende oder entfernte Nachschlagevorgänge verwenden, wenn sich die Datei nicht in Ihrem Arbeitsbaum befindet. Unterstützt einen optionalen Zeilenbereich; eine token-abgeschnittene Antwort ab metadata.next_line_start fortsetzen.

Parameter:

file_pathErforderlich
Typ
str
Beschreibung
Dateipfad relativ zum Repository-Stammverzeichnis
repositoryOptional
Typ
str
Beschreibung
Repository im Format owner/repo[:branch]. Optional — weglassen, um den anfragebezogenen Client-Standardwert (sofern vorhanden) oder das einzige zugängliche Repository zu verwenden; nur ausdrücklich übergeben, um ein anderes indiziertes Repository anzusprechen. Die Antwort zeigt, welches Repository verwendet wurde.
line_startOptional
Typ
int
Beschreibung
Startzeile (1-basiert)
line_endOptional
Typ
int
Beschreibung
Endzeile (1-indiziert, einschließlich; muss bei oder nach line_start liegen)
branchOptional
Typ
str
Beschreibung
Branch überschreiben
max_tokensOptional
Typ
int
Standard
5000
Beschreibung
Maximale Anzahl an Tokens
include_metadataOptional
Typ
bool
Standard
true
Beschreibung
Metadaten einschließen

Am besten geeignet für:

  • Entfernte oder indizierte Datei-Schnappschüsse (Zeilenbereiche, Token-Limits)

Nicht empfohlen für:

  • Ein Pfad, der bereits lokal auf der Festplatte liegt — verwenden Sie das lokale Read-Werkzeug

System- und Utility-Tools#

repository_contextStabil

Listet die durchsuchbaren Repositorys auf oder liefert Identitätsinformationen zu einem (namespace/branch, indexed_commit_sha / Index-Aktualität). Rufen Sie einmal mit action:"list" auf, um den exakten Repository-Slug zu erfahren, den die Suchwerkzeuge akzeptieren. (Hat Ihr Schlüssel nur ein Repository, verwenden die Suchwerkzeuge dieses standardmäßig — dann können Sie dies überspringen.) Namespace-weite Datei-/Blob-/Edge-Anzahlen sind über include_statistics=true optional abrufbar.

Parameter:

actionErforderlich
Typ
Literal[list, info]
Beschreibung
Aktion: verfügbare Repositorys auflisten oder Repository-Informationen abrufen
repositoryOptional
Typ
str
Beschreibung
Repository im Format owner/repo oder owner/repo:branch (für info erforderlich)
branchOptional
Typ
str
Beschreibung
Branch überschreiben
patternOptional
Typ
str
Beschreibung
Filtermuster
include_statisticsOptional
Typ
bool
Standard
Beschreibung
Opt-in: schließt namespace-weite Anzahlen indizierter Daten ein (Datei/Blob/Edge). Standard false — die Repository-Identität erfordert dieses langsamere Aggregat nicht.
limitOptional
Typ
int
Standard
20
Beschreibung
Maximale Anzahl der auf dieser Seite zurückgegebenen Ergebnisse
offsetOptional
Typ
int
Beschreibung
Veralteter Kompatibilitätsoffset. Bevorzugen Sie cursor von pagination.next_cursor.
cursorOptional
Typ
str
Beschreibung
Undurchsichtiges cursor von pagination.next_cursor. Übergeben Sie es unverändert und behalten Sie die Abfrage und Filter unverändert bei.

Am besten geeignet für:

  • Auflisten der zugänglichen Repositorys
  • Ermitteln der Repository-Identität, des Branch und der Aktualität von HEAD gegenüber dem Index

Nicht empfohlen für:

  • Namespace-weite Statistiken standardmäßig — übergeben Sie include_statistics=true explizit, da dies langsamer als die reine Auflösung sein kann

ask_maguyvaStabil

Hilfe und Feedback zu Maguyva. Primär: Werkzeug-Anleitungen erhalten oder einen Fehlerbericht / Funktionswunsch einreichen, der für die Maguyva-Maintainer gespeichert wird. Niemals Geheimnisse oder sensible personenbezogene Daten in Feedback aufnehmen. Die evaluate-Operation existiert nur noch aus Kompatibilitätsgründen — für Mathe-/Hash-/String-Arbeiten lokale Berechnung oder Host-Werkzeuge bevorzugen.

Parameter:

operationErforderlich
Typ
Literal[guidance, report_bug, request_feature, evaluate]
Beschreibung
Primär: guidance, report_bug, request_feature. Nur Legacy/Kompatibilität: evaluate (deterministische Ausdrucks-Engine; nicht Teil des primären Agenten-Workflows).
queryOptional
Typ
str
Beschreibung
Anleitungsthema (z. B. tool_selection, semantic_search). Nur für das Legacy-evaluate: Ausdrucks-String.
descriptionOptional
Typ
str
Beschreibung
Erforderlich für report_bug und request_feature. Frei formuliertes Feedback für die Maguyva-Maintainer. Niemals Geheimnisse oder sensible personenbezogene Daten aufnehmen.
related_toolOptional
Typ
Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
Beschreibung
Optionales Maguyva-Tool, das am engsten mit dem Feedback zusammenhängt

Am besten geeignet für:

  • Werkzeug-Anleitung (operation="guidance")
  • Dauerhafte Fehlerberichte und Funktionswünsche für die Maguyva-Maintainer

Nicht empfohlen für:

  • Mathe-/Hash-/String-Berechnung — die evaluate-Operation existiert nur noch aus Kompatibilitätsgründen; bevorzugen Sie lokale Berechnung oder Host-Werkzeuge

Bewährte Praktiken#

  1. Explizite Überschreibungen bewusst einsetzen: Lasse das Repository weg, wenn dein MCP-Client einen Standardwert für die Anfrage bereitstellt oder der Schlüssel auf genau ein Repository zugreifen kann; übergib es andernfalls ausdrücklich.
  2. Den richtigen Suchmodus wählen: Verwende intelligent_search mit mode="auto" für die meisten Fälle. Gib einen Modus an, wenn du genau weißt, was du brauchst.
  3. Sprachfilter nutzen: Verwende language_filter, um Ergebnisse einzugrenzen und die Performance zu verbessern.
  4. GraphRAG-Boosting: Die GraphRAG-Relevanzgewichtung ist standardmäßig für die semantische Suche deaktiviert (boost_by_importance=false), damit das Ranking agentensicher bleibt. Übergib boost_by_importance=true, um zentralitätsbewusstes Re-Ranking für Architektur-Touren zu aktivieren.
  5. Repository-Abgleich ist Groß-/Kleinschreibung-unabhängig, nicht fuzzy: repository_context gleicht Repository-Namen unabhängig von Groß-/Kleinschreibung ab — es korrigiert keine Tippfehler. Prüfe metadata.resolution_reason bei der info-Aktion ("exact" vs. "corrected"), um zu sehen, wie ein Name aufgelöst wurde.
  6. Tools kombinieren: Nutze mehrere API-Methoden zusammen für eine umfassende Analyse.
  7. Große Ergebnisse handhaben: Verwende limit und toolspezifische Paging-Steuerungen (zum Beispiel line_start/line_end in get_file).
  8. ask_maguyva für Tool-Guidance nutzen: Die ask_maguyva-Operation evaluate (Hash, Base64, JSON, Mathe) ist nur Legacy / Rückwärtskompatibilität. Rufe stattdessen ask_maguyva mit operation="guidance" und query="tool_selection" auf, für die Local-Tool-Wins-Matrix und eine vollständige Tool-für-Tool-Übersicht.
  9. Auswirkungen vor und nach dem Editieren prüfen: Rufe vor dem Editieren eines geteilten Symbols dependency_search mit analysis_type="impact" auf (oder übergib changed_paths für PR-/Diff-Auswirkungen), um den Auswirkungsradius zu sehen. Setze nach dem Editieren verify_after_edit=true mit targets und/oder changed_paths für eine kompakte erneute Prüfung derselben Symbole.

Performance-Merkmale#

OperationPerformance-Hinweise
Semantische SucheUnter einer Sekunde, aber jedes Mal mit einem Live-Embedding-API-Aufruf (nicht gecacht) — rechne mit zusätzlicher Latenz oben auf die Vektor-Query
TextsucheUnter einer Sekunde für exakt/regex; die Fuzzy-Volltextsuche paginiert clientseitig, daher kosten tiefe Offsets mehr — mit path_filter/language_filter eingrenzen
Strukturelle SucheAST-indexiert — Kosten skalieren mit der Ergebnismenge, nicht mit der Repository-Größe
AbhängigkeitssucheKosten skalieren mit der Tiefe — bevorzuge depth="shallow", außer du brauchst Multi-Hop-Kontext; per_hop_limit begrenzt die Streuung
DateiabrufNahezu sofort für eine einzelne Datei — große Dateien mit line_start/line_end oder max_tokens seitenweise abrufen statt eines einzigen großen Pulls
Repository-KontextNamespace-Auflösung wird nur pro Anfrage gecacht, nicht über Aufrufe hinweg — jeder Tool-Aufruf löst erneut auf
ask_maguyva (guidance / evaluate)Nahezu sofort — läuft im Worker ohne Datenbankaufruf

Fehlerbehandlung#

Alle API-Methoden geben einen strukturierten Envelope zurück:

  • status: String — "success" oder "error". Degradierte Treffer und Freshness-Signale liegen in verschachtelten Feldern wie metadata.resolution_reason bei repository_context oder metadata.index_freshness.status.
  • tool: Name des Tools, das die Antwort erzeugt hat
  • data: Ergebnis-Payload bei Erfolg (Struktur variiert je nach Tool)
  • error: Strukturiertes Fehlerobjekt, wenn status gleich "error" ist — enthält type, message, suggestions und recovery_actions
  • metadata: Zusätzliche Informationen zur Operation (Routing, Caching, Parameteranpassungen)
  • pagination: Vorhanden bei Listenantworten — enthält has_more und next_cursor

Überprüfe immer das Feld status, bevor du Ergebnisse verarbeitest — es ist ausschließlich "success" oder "error". Für degradierte Treffer oder Freshness-Signale lies stattdessen das verschachtelte Feld: metadata.resolution_reason bei repository_context oder metadata.index_freshness.status (known/partial/unknown/unavailable).

Erste Schritte#

  1. MCP-Client konfigurieren: Richte deinen MCP-Client auf den Maguyva-Server-Endpunkt aus
  2. Repository-Zugriff bestätigen: Mit list oder info von repository_context die für den API-Schlüssel verfügbaren Repositorys prüfen
  3. Mit der Suche beginnen: Beginne mit intelligent_search und erkunde bei Bedarf spezialisierte Tools
  4. Tools kombinieren: Nutze mehrere Tools zusammen für eine umfassende Code-Analyse

Detaillierte Integrationsanweisungen findest du in der Installationsanleitung.