Zum Inhalt springen

MCP-API-Referenz

Erkunde die 11 MCP-Tools von Maguyva, ihre Parameter und passenden Einsatzzwecke. Die tools/list-Antwort deines verbundenen Clients zeigt dir die verfügbaren Argumente.

API-Übersicht

#

Die Tools sind in 4 Kategorien eingeteilt:

  • 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, Tool-Anleitung und Feedback

Für Tools, die ein Repository annehmen, nutze dieses Repository-Identifikationsformat: "owner/repo:branch". Ohne Angabe wird der Branch main verwendet.

Lass 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. Prüfe mit repository_context(action="info", repository="owner/repo"), wie ein Repository aufgelöst wird.

Repository-Parameterformat

#

Verwende diese Formate, wenn du ein Repository angibst:

  • 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: Lass das Repository weg, wenn der MCP-Client einen Standardwert für die Anfrage bereitstellt oder der Schlüssel auf genau ein Repository zugreifen kann; übergib 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

#

Nutze language_filter in unterstützten Suchmodi. Wähle für text_pattern_search search_scope="content"; verwende für get_task_context scope="semantic" ohne Startpunkte oder verwandten Kontext.

  • 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 285+ 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 21. Oktober 2026.

Zentrale Suchtools

#

intelligent_search Stabil

Starte hier bei jeder 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. language_filter lässt den Graphen bei auto/hybrid weg und wird bei explizitem mode=graph abgelehnt. Nutze dies bevorzugt statt Grep/Glob, wenn du den Pfad noch nicht kennst.

Parameter:

query Erforderlich
Typ
str minLength=1
Beschreibung
Suchanfrage
repository Optional
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. Exakt indizierte Branches werden bevorzugt; ein nicht verfügbarer Branch kann auf main oder den einzigen zugänglichen Branch zurückfallen. Die Antwortmetadaten zeigen die angeforderte und die aufgelöste Identität und warnen bei einem Fallback.
mode Optional
Typ
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Standard
auto
Beschreibung
Suchmodus
limit Optional
Typ
int minimum=1, maximum=50
Standard
10
Beschreibung
Maximale Anzahl an Ergebnissen in diesem eingestuften top-K-Fenster
language_filter Optional
Typ
str
Beschreibung
Sprachfilter
path_filter Optional
Typ
str
Beschreibung
Filtert Suchkandidaten nach Dateipfadpräfix. Benachbarte Knoten im Graphen und beigefügter Community-Kontext können Dateien außerhalb dieses Präfixes enthalten.
boost_by_importance Optional
Typ
bool
Standard
false
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 Agent-sicheres 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.
branch Optional
Typ
str
Beschreibung
Branch überschreiben
quality Optional
Typ
Literal[quick, balanced, thorough]
Standard
balanced
Beschreibung
Voreinstellung für die Suchqualität
include_content Optional
Typ
bool
Standard
true
Beschreibung
Inhalt in die Ergebnisse aufnehmen
explain_routing Optional
Typ
bool
Standard
false
Beschreibung
Erklärung der Routing-Entscheidung einbeziehen
importance_weight Optional
Typ
float minimum=0, maximum=1
Standard
0.3
Beschreibung
Gewichtung der Wichtigkeitsanhebung (0=keine, 1=voll)
orphans Optional
Typ
bool
Standard
false
Beschreibung
Verwaiste Symbole einbeziehen (ohne eingehende Referenzen)
include_community_context Optional
Typ
bool
Standard
false
Beschreibung
Verwandte Symbole aus derselben Code-Community einbeziehen
community_depth Optional
Typ
int minimum=1, maximum=3
Standard
1
Beschreibung
Tiefe der Erweiterung des Community-Kontexts
graph_view Optional
Typ
Literal[dependency, type, data_flow, control_flow]
Standard
dependency
Beschreibung
Graphansicht für Metriken
seed_symbol_ids Optional
Typ
list[str] maxItems=20
Beschreibung
Aufgaben-Seeds der Stufe 1: Symbol-IDs, die für die aktuelle Aufgabe zentral sind. Bei Angabe werden zusammengeführte Treffer nach der mit zunehmender Tiefe abnehmenden Nähe gemäß Approach A neu sortiert (exakte Seed-Übereinstimmung + Schritte entlang von Graphkanten). Additiv — für globales Ranking weglassen.
seed_file_paths Optional
Typ
list[str] maxItems=10
Beschreibung
Aufgaben-Seeds der Stufe 1: indexierte Dateipfade, die der Agent geöffnet oder gerade bearbeitet hat. Bei Angabe werden zusammengeführte Treffer nach Pfadnähe neu sortiert, gewichtet mit 1/(1+d) bei zunehmender Tiefe (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 — verwende direkt find_symbol
  • Ein bekannter Pfad auf der Festplatte — verwende zuerst das lokale Read/Grep

semantic_search Stabil

Code nach Bedeutung statt exaktem Text finden. Für konzeptionelle Abfragen wie „Wiederholungslogik“ oder „Benutzereinführung“, wenn Schlüsselwort oder Symbolname unbekannt sind. Liefert relevante Chunks mit begrenzter Dateivielfalt; die Neusortierung nach Graphwichtigkeit wird über boost_by_importance optional aktiviert. Bei konzeptioneller Suche gegenüber Grep bevorzugen.

Parameter:

query Erforderlich
Typ
str minLength=1
Beschreibung
Suchanfrage (konzeptionell, bedeutungsbasiert)
repository Optional
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. Exakt indizierte Branches werden bevorzugt; ein nicht verfügbarer Branch kann auf main oder den einzigen zugänglichen Branch zurückfallen. Die Antwortmetadaten zeigen die angeforderte und die aufgelöste Identität und warnen bei einem Fallback.
limit Optional
Typ
int minimum=1, maximum=50
Standard
5
Beschreibung
Maximale Anzahl an Ergebnissen in diesem eingestuften top-K-Fenster
similarity_threshold Optional
Typ
float minimum=0, maximum=1
Standard
0.6
Beschreibung
Minimaler Ähnlichkeitswert
language_filter Optional
Typ
str
Beschreibung
Sprachfilter (python, typescript usw.)
path_filter Optional
Typ
str
Beschreibung
Nach Dateipfadpräfix filtern
boost_by_importance Optional
Typ
bool
Standard
false
Beschreibung
Optional aktivierbar: Neusortierung nach normalisierter Graphwichtigkeit je Symbol (standardmäßig aus; auf das 1,5-Fache der Ähnlichkeit begrenzt).
branch Optional
Typ
str
Beschreibung
Branch überschreiben (Standard: aus dem repository-Parameter oder main)
include_content Optional
Typ
bool
Standard
true
Beschreibung
Abschnittsinhalt in die Ergebnisse aufnehmen
graph_view Optional
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 — verwende stattdessen find_symbol
  • Exakte Zeichenfolgen oder Fehlermeldungen — verwende text_pattern_search

text_pattern_search Stabil

Indexierte Inhalte durchsuchen. exact und regex durchsuchen den gesamten Datei-/Blob-Korpus mit grep; fuzzy content durchsucht den begrenzten semantischen Chunk-Korpus. Die Bereiche file und symbol unterstützen nur Trigramme — der Standard mode=exact wird in fuzzy umgewandelt. Sprach-, Groß-/Kleinschreibungs- und eigene Schwellenwertoptionen erfordern den Bereich content. Pfadfilter nutzen ein begrenztes Kandidatenfenster und melden unvollständige Abdeckung. Für ein eng begrenztes Verzeichnis auf der Festplatte lokales Grep verwenden.

Parameter:

query Erforderlich
Typ
str minLength=1
Beschreibung
Textmuster
repository Optional
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. Exakt indizierte Branches werden bevorzugt; ein nicht verfügbarer Branch kann auf main oder den einzigen zugänglichen Branch zurückfallen. Die Antwortmetadaten zeigen die angeforderte und die aufgelöste Identität und warnen bei einem Fallback.
mode Optional
Typ
Literal[fuzzy, exact, regex]
Standard
exact
Beschreibung
Suchmodus. Regex führt die erweiterte/POSIX-Syntax von PostgreSQL aus; verwende \y für Wortgrenzen (\b bedeutet Rücktaste). Muster durchlaufen zusätzlich einen JavaScript-Sicherheitsvalidator, sodass PostgreSQL-spezifische Konstrukte wie inline-(?i)-Flags abgelehnt werden; verwende stattdessen case_sensitive.
search_scope Optional
Typ
Literal[content, symbols, files]
Standard
content
Beschreibung
Zu durchsuchender Bereich
limit Optional
Typ
int minimum=1, maximum=50
Standard
5
Beschreibung
Maximale Ergebnisse pro Seite ohne cursor. Bei Fortsetzung wird die in cursor gespeicherte Seitengröße verwendet; cursor weglassen, um mit einem anderen limit zu starten.
offset Optional
Typ
int minimum=0
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzuge den cursor aus pagination.next_cursor.
cursor Optional
Typ
str
Beschreibung
Undurchsichtiger cursor aus pagination.next_cursor. Unverändert übergeben und query sowie Filter unverändert lassen. Seine Position und Seitengröße überschreiben offset und limit.
language_filter Optional
Typ
str
Beschreibung
Sprachfilter
path_filter Optional
Typ
str
Beschreibung
Nach Dateipfadpräfix filtern
case_sensitive Optional
Typ
bool
Standard
false
Beschreibung
Groß-/Kleinschreibung beachten
branch Optional
Typ
str
Beschreibung
Branch überschreiben
fuzzy_algorithm Optional
Typ
Literal[hybrid, trigram, levenshtein]
Standard
hybrid
Beschreibung
Algorithmus für unscharfe Übereinstimmung
threshold Optional
Typ
float minimum=0, maximum=1
Standard
0.05
Beschreibung
Mindestschwelle der Ähnlichkeit für die unscharfe Suche
semantic_fallback Optional
Typ
bool
Standard
false
Beschreibung
Versucht eine semantische Suche, nachdem die erste lexikalische Seite leer war; metadata.fallback_status unterscheidet zwischen used, empty und unavailable als Fallback-Status.

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 — bevorzuge das lokale Grep
  • Konzeptionelle Anfragen — verwende semantic_search

Struktur- und Graph-Tools

#

structural_search Stabil

Bevorzuge preset=functions|classes|methods|imports|variables oder ein freies pattern=. Suche Code anhand der AST-Form, nicht des Texts. Mittlere Filterstufe: name_pattern, node_type, decorator, parent_child. Pfad-, ltree- und Aufruffilter sind erweitert — setze advanced=true, wenn du sie gezielt nutzt. Andernfalls werden die erweiterten Filter ebenfalls angewendet, aber mit einer Metadatenwarnung. Gib mindestens einen strukturellen Selektor an.

Parameter:

repository Optional
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. Exakt indizierte Branches werden bevorzugt; ein nicht verfügbarer Branch kann auf main oder den einzigen zugänglichen Branch zurückfallen. Die Antwortmetadaten zeigen die angeforderte und die aufgelöste Identität und warnen bei einem Fallback.
preset Optional
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-/Interface-Deklarationen, Typkörper und Implementierungen); 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.
pattern Optional
Typ
str
Beschreibung
Ein frei formuliertes pattern füllt fehlende Selektoren auf (automatisch erkannt: 'def foo(' → node_type + name_pattern). Kann mit preset kombiniert werden; explizite Selektoren haben Vorrang. Für Browse-Abfragen preset= bevorzugen.
name_pattern Optional
Typ
str maxLength=256
Beschreibung
Symbolnamen-Muster (Shell-Wildcard, begrenzter POSIX-Regex oder Fuzzy-Text; max. 256 Zeichen)
node_type Optional
Typ
str
Beschreibung
AST-Knotentyp (function_definition, class_definition usw.) — für gängige Formen preset= bevorzugen
decorator Optional
Typ
str
Beschreibung
Decorator-Namensfilter
base_class Optional
Typ
str
Beschreibung
Basisklassenfilter
language_filter Optional
Typ
str
Beschreibung
Sprachfilter (python, typescript usw.)
limit Optional
Typ
int minimum=1, maximum=50
Standard
20
Beschreibung
Maximale Ergebnisse pro Seite ohne cursor. Bei Fortsetzung wird die in cursor gespeicherte Seitengröße verwendet; cursor weglassen, um mit einem anderen limit zu starten.
offset Optional
Typ
int minimum=0
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzuge den cursor aus pagination.next_cursor.
cursor Optional
Typ
str
Beschreibung
Undurchsichtiger cursor aus pagination.next_cursor. Unverändert übergeben und query sowie Filter unverändert lassen. Seine Position und Seitengröße überschreiben offset und limit.
path_filter Optional
Typ
str
Beschreibung
Nach Dateipfadpräfix filtern
branch Optional
Typ
str
Beschreibung
Branch überschreiben
query_type Optional
Typ
Literal[node_type, name_pattern, parent_child]
Beschreibung
Expliziter Abfragetyp
parent_type Optional
Typ
str
Beschreibung
Filter für den übergeordneten AST-Knotentyp
relationship Optional
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_modifier Optional
Typ
str
Beschreibung
Nach Modifikator filtern (export, async, static usw.)
advanced Optional
Typ
bool
Standard
false
Beschreibung
Setze true, wenn du gezielt erweiterte Pfad-, ltree- oder Aufruffilter verwendest (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Bei false werden angegebene erweiterte Filter mit einer Metadatenwarnung angewendet. Bevorzuge preset= für übliche strukturelle Abfragen.
callee_text Optional
Typ
str
Beschreibung
Erweitert — bevorzuge preset=functions|classes|methods|imports|variables. Filter für den Callee-Text eines Aufrufausdrucks. Setze advanced=true, wenn du path-/ltree-/call-Filter bewusst verwendest.
callee_name Optional
Typ
str
Beschreibung
Erweitert — bevorzuge preset=functions|classes|methods|imports|variables. Filter für den Callee-Namen eines Aufrufausdrucks. Setze advanced=true, wenn du path-/ltree-/call-Filter bewusst verwendest.
field_role Optional
Typ
str
Beschreibung
Erweitert — bevorzuge preset=functions|classes|methods|imports|variables. Filter für die AST-Feldrolle. Setze advanced=true, wenn du path-/ltree-/call-Filter bewusst verwendest.
ltree_ancestor Optional
Typ
str
Beschreibung
Erweitert — bevorzuge preset=functions|classes|methods|imports|variables. Filter für den AST-ltree-Vorfahrenpfad. Setze advanced=true, wenn du path-/ltree-/call-Filter bewusst verwendest.
ltree_descendant Optional
Typ
str
Beschreibung
Erweitert — bevorzuge preset=functions|classes|methods|imports|variables. Filter für den AST-ltree-Nachfahrenpfad. Setze advanced=true, wenn du path-/ltree-/call-Filter bewusst verwendest.
definition_name Optional
Typ
str
Beschreibung
Erweitert — bevorzuge preset=functions|classes|methods|imports|variables. Filter für den Definitionsnamen. Setze advanced=true, wenn du path-/ltree-/call-Filter bewusst verwendest.
min_depth Optional
Typ
int
Beschreibung
Erweitert — bevorzuge preset=functions|classes|methods|imports|variables. Minimale AST-Tiefe. Setze advanced=true, wenn du path-/ltree-/call-Filter bewusst verwendest.
max_depth Optional
Typ
int
Beschreibung
Erweitert — bevorzuge preset=functions|classes|methods|imports|variables. Maximale AST-Tiefe. Setze advanced=true, wenn du path-/ltree-/call-Filter bewusst verwendest.

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 — verwende semantic_search oder intelligent_search

dependency_search Stabil

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: 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 nutzt dieselbe Traversierung für die Auswirkungsanalyse über mehrere Schritte. dependents/impact enthalten standardmäßig production_callers: eindeutige Verwendungsstellen im Produktionscode nach Art (call, instantiate, value_reference für als Werte übergebene Funktionen) sowie IMPORT-Stellen, ohne Tests und mit EXTRACTED/INFERRED-Vertrauensstufe — keine bloße Metriksammlung.

Parameter:

repository Optional
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. Exakt indizierte Branches werden bevorzugt; ein nicht verfügbarer Branch kann auf main oder den einzigen zugänglichen Branch zurückfallen. Die Antwortmetadaten zeigen die angeforderte und die aufgelöste Identität und warnen bei einem Fallback.
query Optional
Typ
str
Beschreibung
Symbolname oder Suchbegriff
target Optional
Typ
str
Beschreibung
Symbolname (Alias für query)
symbol_id Optional
Typ
UUID
Beschreibung
Wähle per UUID ein bestimmtes Vorkommen aus den Kandidaten für die benannte query bzw. das benannte target, nachdem nach Namespace, Pfad und Sprache gefiltert wurde. Verwende eine ID aus find_symbol oder aus den alternativen Graph-Ergebnissen. Nur für Traversierungen mit angegebenem Namen; eine ID außerhalb des begrenzten Kandidatenfensters führt zu einem Fehler.
changed_paths Optional
Typ
list[str] maxItems=50
Beschreibung
Exakte repo-relative Dateipfade für PR-/Diff-Auswirkungsanalysen (Standard) oder, bei verify_after_edit=true, als Startpunkte für die Prüfung nach einer Änderung. Nicht auflösbare Pfade können markierte Vorschläge liefern; vorgeschlagene Dateien werden jedoch nie zu Auswirkungs-Startpunkten. PR/diff: Ohne Zeileninformation werden die Top-Level-Definitionen jedes Pfads durchlaufen (exportierte zuerst, in Dateireihenfolge), und changed_lines_unknown wird gemeldet; für zeilengenau geänderte Symbole patch= übergeben. Prüfung: bis zu 5 Top-Level-Definitionen pro Pfad als Startpunkte (im Prüfmodus gilt eine niedrigere Obergrenze). Für PR-/Diff-Auswirkungsanalysen ist query/target nicht erforderlich.
patch Optional
Typ
str maxLength=500000
Beschreibung
PR-/Diff-Auswirkungsanalyse: Text im Unified-Diff- bzw. Git-Patch-Format. Pfade stammen aus den Headern diff --git / --- / +++; Hunk-Zeilen (alte Seite = der indexierte Commit) werden den umschließenden Funktionen, Methoden und Klassen zugeordnet, die dann auf exakte Abhängige, public_api_changed und die vom Diff nicht berührten Aufrufer durchlaufen werden.
head_commit Optional
Typ
str pattern=^[0-9a-fA-F]{7,64}$
Beschreibung
Commit-SHA des Codes, nach dem du fragst (git rev-parse HEAD oder der Basis-Commit des Patches). complete:true setzt voraus, dass der Index auf diesem Commit steht und mit dem aktuellen Resolver erstellt wurde; andernfalls bleibt es bei complete:false mit index_stale / index_freshness_unverified / index_built_by_older_resolver, und index_basis.statement gibt an, innerhalb welcher Grenzen die Antwort vollständig ist. Auch die Zeile 'base-commit:' eines Patches (git format-patch --base) liefert diesen Wert.
analysis_type Optional
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. orphans sind Kandidaten für ungenutzten Code, kein Nachweis, dass er gefahrlos entfernt werden kann; prüfe die Referenzen im Quellcode.
depth Optional
Typ
Literal[shallow, balanced, deep]
Beschreibung
Traversierungstiefe. Standardmäßig balanced; impact und PR/diff impact verwenden standardmäßig shallow. Ein explizit gesetztes depth überschreibt diese Standardwerte. Der Verify-Modus verwendet immer shallow.
limit Optional
Typ
int minimum=1, maximum=50
Standard
20
Beschreibung
Maximale Ergebnisse pro Seite ohne cursor. Bei Fortsetzung wird die in cursor gespeicherte Seitengröße verwendet; cursor weglassen, um mit einem anderen limit zu starten.
offset Optional
Typ
int minimum=0
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzuge den cursor aus pagination.next_cursor.
cursor Optional
Typ
str
Beschreibung
Undurchsichtiger cursor aus pagination.next_cursor. Unverändert übergeben und query sowie Filter unverändert lassen. Seine Position und Seitengröße überschreiben offset und limit.
path_filter Optional
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_filter Optional
Typ
str
Beschreibung
Filtert Zielauflösung und Browse-Ergebnisse nach Sprache
direction Optional
Typ
Literal[outgoing, incoming, both]
Beschreibung
Traversierungsrichtung (überschreibt die Ableitung aus analysis_type)
relationship_types Optional
Typ
list[str]
Beschreibung
Filtert Kantentypen (CALL, IMPORT, INHERITS_FROM usw.). Eine nicht leere Liste überschreibt die graph_view-Standardwerte.
exclude_test_paths Optional
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 berücksichtigt dies nur, wo das bereitgestellte Backend es unterstützt; andernfalls behält sie ihre eigenen strengeren Rauschausschlüsse bei und meldet die Anpassung.
exclude_generated_paths Optional
Typ
bool
Standard
false
Beschreibung
Schließt generierte Deklarationen sowie Build-, Coverage-, Cache-, Source-Map- und minifizierte Artefaktpfade aus den Traversierungsergebnissen aus
include_module_symbols Optional
Typ
bool
Standard
false
Beschreibung
Standard false: Entfernt Kanten, bei denen from_name oder to_name das synthetische Symbol __module__ ist (Rauschen auf Modulebene). Setze true, um Kanten auf Modulebene in dependents-/dependencies-Ergebnisse einzubeziehen.
include_isolated Optional
Typ
bool
Beschreibung
Nur für Orphans. Standard false. Auf true setzen, um auch Symbole ohne Zeile in den Graph-Metriken zurückzugeben (keinerlei Graphkanten). Solange exclude_test_paths true ist, bleiben Stylesheet-, Markup- und Datensymbole (CSS, HTML, ...), .d.ts-Deklarationen sowie test/fixture/vendor/example-Pfade ausgeschlossen, sofern das Backend dies unterstützt, es sei denn, language_filter nennt die betreffende Sprache; Eigenschaften von TypeScript-Objektliteralen können weiterhin als isolierte Funktionen erscheinen.
exclude_exported Optional
Typ
bool
Standard
false
Beschreibung
Nur für verwaiste Symbole. Standard false: Exportierte Symbole (öffentliche API), die im Repository nicht verwendet werden, werden mit is_exported=true zurückgegeben. Für ausschließlich interne Kandidaten auf true setzen.
branch Optional
Typ
str
Beschreibung
Branch überschreiben
per_hop_limit Optional
Typ
int minimum=1, maximum=300
Beschreibung
Maximale Anzahl an Beziehungen pro Hop (1–300)
include_metrics Optional
Typ
bool
Standard
false
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_detail Optional
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_metadata Optional
Typ
bool
Standard
false
Beschreibung
Rohe Kantenmetadaten und Gewichtungen einbeziehen (umfangreich). Bei kompakten Impact-Antworten bleibt diese Option deaktiviert.
symbol_types Optional
Typ
list[str]
Beschreibung
Filtert zurückgegebene Symbole nach Art (function, class, method usw.). Wird in der orphan-Analyse nicht unterstützt; dort stattdessen path_filter oder language_filter verwenden. Eine leere Liste wendet keinen Art-Filter an.
exact_match Optional
Typ
bool
Standard
false
Beschreibung
Erfordert eine exakte Übereinstimmung des Symbolnamens
find_similar_patterns Optional
Typ
bool
Standard
false
Beschreibung
Ähnliche Verwendungsmuster finden
min_centrality Optional
Typ
float minimum=0
Standard
0
Beschreibung
Minimaler PageRank-Wert für die Traversierung benannter Symbole und die PR-/Diff-Auswirkungsanalyse. In den Browse-Modi centrality/orphans werden positive Schwellenwerte nicht unterstützt. Metriken werden intern zum Filtern abgerufen; graph_metrics werden nur zurückgegeben, wenn include_metrics=true ist. Wird von verify_after_edit ignoriert, das feste kompakte Steuerungen verwendet.
graph_view Optional
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_edit Optional
Typ
bool
Standard
false
Beschreibung
Fragt den indexierten Impact-Graphen für bearbeitete Symbole in einer kompakten Multi-Root-Antwort erneut ab. Erfordert targets und/oder changed_paths (oder target/query). Verwendet eine feste shallow-Traversierung und kompakte Budgets; die Steuerungen depth/limit/cursor/metrics gelten nicht. Standardmäßig werden incoming dependents zurückgegeben; die Ergebnisse spiegeln den indexierten Graphen wider (kann hinter Live-Änderungen zurückliegen). Bei true hat dies Vorrang vor PR/diff impact für dieselben changed_paths.
targets Optional
Typ
list[str] maxItems=15
Beschreibung
Bei verify_after_edit=true: erneut zu prüfende Symbolnamen (Aufrufer/abhängiger Code). Wird mit target/query zusammengeführt, wenn beides angegeben ist.

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 — verwende text_pattern_search oder find_symbol

Code-Analyse-Tools

#

find_symbol Stabil

Springt zur Definition und Verwendung einer Funktion, Klasse oder Variablen. Nutze 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_name Optional
Typ
str
Beschreibung
Zu suchender Symbolname (optional — weglassen, um nach Metriken zu durchsuchen)
repository Optional
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. Exakt indizierte Branches werden bevorzugt; ein nicht verfügbarer Branch kann auf main oder den einzigen zugänglichen Branch zurückfallen. Die Antwortmetadaten zeigen die angeforderte und die aufgelöste Identität und warnen bei einem Fallback.
scope Optional
Typ
Literal[definitions, references, both]
Standard
both
Beschreibung
Suchbereich; references erfordert ein nicht leeres symbol_name.
limit Optional
Typ
int minimum=1, maximum=50
Standard
15
Beschreibung
Maximale Ergebnisse pro Seite ohne cursor. Bei Fortsetzung wird die in cursor gespeicherte Seitengröße verwendet; cursor weglassen, um mit einem anderen limit zu starten.
offset Optional
Typ
int minimum=0
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzuge den cursor aus pagination.next_cursor.
cursor Optional
Typ
str
Beschreibung
Undurchsichtiger cursor aus pagination.next_cursor. Unverändert übergeben und query sowie Filter unverändert lassen. Seine Position und Seitengröße überschreiben offset und limit.
find_similar Optional
Typ
bool
Standard
false
Beschreibung
Ähnliche Symbolnamen einbeziehen
include_metrics Optional
Typ
bool
Standard
false
Beschreibung
Zentralitätsmetriken einbeziehen
metrics_detail Optional
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_filter Optional
Typ
str
Beschreibung
Nach Dateipfadpräfix filtern
branch Optional
Typ
str
Beschreibung
Branch überschreiben
symbol_type Optional
Typ
str minLength=1
Beschreibung
Nach indizierter Symbolart filtern, z. B. function, class, struct, enum oder trait. Verwende die von einem Symbolergebnis zurückgegebene Art; die Art variiert je nach Sprache.
high_impact Optional
Typ
bool
Standard
false
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_mode Optional
Typ
Literal[popularity, risk]
Standard
popularity
Beschreibung
Wenn high_impact=true: popularity = Symbole im obersten PageRank-Dezil ohne Utility-Mega-Hubs/Module; risk = Artikulationspunkte, sortiert nach SMV bridge_count und dann k_core (strukturelles Refactoring-Risiko, nicht Hub-Popularität)
in_cycle Optional
Typ
bool
Standard
false
Beschreibung
Filtert auf Symbole mit erfasster Zugehörigkeit zu einem Abhängigkeitszyklus.
exclude_test_paths Optional
Typ
bool
Standard
true
Beschreibung
Beim Durchsuchen nach Graphmetriken Tests, Fixtures, Drittanbieter-Code und Beispiele vor dem Ranking ausschließen; die Suche nach einem benannten Symbol bleibt unverändert
reference_views Optional
Typ
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
Beschreibung
Graphansichten, deren eingehende Kanten references/reference_count füllen (scope references/both). Standard ["dependency", "type"]: Aufrufe, Importe, Exporte, Referenzen, Instanziierungen, Vererbung, Überschreibungen, Dekoratoren und Typverwendung. Ohne Auswahl von data_flow werden exakt aufgelöste data_flow-Verwendungen (Callbacks, Handler, Sortierschlüssel) separat als value_references/value_reference_count zurückgegeben, ohne nur aus Namen abgeleitete Treffer. data_flow oder control_flow hinzufügen oder ["all"] für alle Kantentypen und Stufen übergeben. Dieselben Ansichtsfamilien wie graph_view von dependency_search.
relationship_types Optional
Typ
list[str]
Beschreibung
Explizite Referenzkantentypen (CALL, IMPORT, READS usw.). Eine nicht leere Liste überschreibt reference_views.

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 — verwende intelligent_search oder semantic_search

analyze_dependencies Stabil

Analysiert den Auswirkungsradius mit derselben Traversierung wie dependency_search (dependents/incoming). Bevorzuge für Auswirkungsanalysen dependency_search mit analysis_type="dependents" oder "impact". Liefert eine mehrstufige Auswirkungsantwort mit graph, connection_summary und optionalen Metriken mit refactor_risk. Mit graph_view die Beziehungsfamilie eingrenzen: dependency (Standard), type, data_flow, control_flow. connection_summary zählt für den gewählten Ausgangsknoten die auf die Beziehungsfamilie eingegrenzten Kanten, und zwar vor jeder Test-/Pfadfilterung. Die veralteten Felder incoming_production/outgoing_production bezeichnen Kanten außerhalb von Modulen, Tests eingeschlossen; sie sind keine Anzahl von Produktionsaufrufern.

Parameter:

repository Optional
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. Exakt indizierte Branches werden bevorzugt; ein nicht verfügbarer Branch kann auf main oder den einzigen zugänglichen Branch zurückfallen. Die Antwortmetadaten zeigen die angeforderte und die aufgelöste Identität und warnen bei einem Fallback.
target Erforderlich
Typ
str minLength=1
Beschreibung
Zu analysierender Symbolname
symbol_id Optional
Typ
UUID
Beschreibung
Wähle per UUID ein bestimmtes Vorkommen aus den target-Kandidaten, nachdem nach Namespace, Pfad und Sprache gefiltert wurde; IDs außerhalb des begrenzten Kandidatenfensters führen zu einem Fehler.
depth Optional
Typ
Literal[shallow, balanced, deep]
Standard
balanced
Beschreibung
Analysetiefe
limit Optional
Typ
int minimum=1, maximum=50
Standard
10
Beschreibung
Maximale Ergebnisse pro Seite ohne cursor. Bei Fortsetzung wird die in cursor gespeicherte Seitengröße verwendet; cursor weglassen, um mit einem anderen limit zu starten.
offset Optional
Typ
int minimum=0
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzuge den cursor aus pagination.next_cursor.
cursor Optional
Typ
str
Beschreibung
Undurchsichtiger cursor aus pagination.next_cursor. Unverändert übergeben und query sowie Filter unverändert lassen. Seine Position und Seitengröße überschreiben offset und limit.
direction Optional
Typ
Literal[incoming, outgoing, both]
Standard
incoming
Beschreibung
Traversierungsrichtung
relationship_types Optional
Typ
list[str]
Beschreibung
Filtert Kantentypen (CALL, IMPORT, INHERITS_FROM usw.). Eine nicht leere Liste überschreibt die graph_view-Standardwerte; eine leere Liste verwendet diese Standardwerte.
graph_view Optional
Typ
Literal[dependency, type, data_flow, control_flow]
Standard
dependency
Beschreibung
Graph-Ansicht: bestimmt sowohl die standardmäßig durchlaufenen Kantentypen als auch, welche Ansicht-Metriken bei include_metrics=true 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 als Standardwert für relationship_types verwendet, wenn relationship_types weggelassen wird oder leer ist. Entspricht dem bestehenden graph_view-Parameternamen von dependency_search für Konsistenz zwischen den Tools.
path_filter Optional
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_filter Optional
Typ
str
Beschreibung
Ergebnisse auf eine Sprache beschränken
branch Optional
Typ
str
Beschreibung
Branch überschreiben
per_hop_limit Optional
Typ
int minimum=1, maximum=300
Beschreibung
Maximale Anzahl an Beziehungen pro Hop (1–300)
include_metrics Optional
Typ
bool
Standard
false
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, entfallen die Metriken für dieses Symbol.
metrics_detail Optional
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_metadata Optional
Typ
bool
Standard
false
Beschreibung
Rohe Kantenmetadaten und Gewichtungen einbeziehen. Standardmäßig deaktiviert, da Extraktor-Metadaten umfangreich sein können; bei Aktivierung wird die Abdeckung der Metadatenanreicherung ausgewiesen.
exclude_test_paths Optional
Typ
bool
Standard
true
Beschreibung
Standard true: Test-, Fixture-, Drittanbieter- und Beispielpfade aus den zurückgegebenen Graphkanten ausschließen. Setze false, um sie einzubeziehen.
include_module_symbols Optional
Typ
bool
Standard
false
Beschreibung
Standard false: Entfernt Kanten, bei denen from_name oder to_name das synthetische Symbol __module__ ist. Setze true, um Kanten auf Modulebene einzubeziehen.
head_commit Optional
Typ
str pattern=^[0-9a-fA-F]{7,64}$
Beschreibung
Commit-SHA des Codes, nach dem du fragst (git rev-parse HEAD oder der Basis-Commit des Patches). complete:true setzt voraus, dass der Index auf diesem Commit steht und mit dem aktuellen Resolver erstellt wurde; andernfalls bleibt es bei complete:false mit index_stale / index_freshness_unverified / index_built_by_older_resolver, und index_basis.statement gibt an, innerhalb welcher Grenzen die Antwort vollständig ist. Auch die Zeile 'base-commit:' eines Patches (git format-patch --base) liefert diesen Wert.

Am besten geeignet für:

  • Auswirkungsanalyse über mehrere Schritte, wenn du die Antwortfelder graph und connection_summary benötigst

Nicht empfohlen für:

  • Allgemeine Auswirkungsanalyse — bevorzuge dependency_search für flexible Traversierung und Prüfungen mit mehreren Startpunkten

get_task_context Stabil

Arbeit in einem unbekannten Bereich beginnen? Beschreibe die Aufgabe (z. B. „SSO-Unterstützung hinzufügen“, „Billing-Webhook reparieren“) und erhalte in einem einzigen Aufruf ein begrenztes Bündel relevanter Dateien, Code, Symbole und Abhängigkeiten. Als Seed übergebene Dateien liefern direkt indexierten Inhalt, auch wenn sie keine Symbole definieren. Fehlgeschlagene Ebenen werden gekennzeichnet; schlägt der gesamte Abruf fehl, wird ein Tool-Fehler zurückgegeben. Für weitere Ergebnisse anschließend das spezialisierte Suchwerkzeug für diese Ebene verwenden.

Parameter:

task_description Erforderlich
Typ
str minLength=1
Beschreibung
Aufgabenbeschreibung
repository Optional
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. Exakt indizierte Branches werden bevorzugt; ein nicht verfügbarer Branch kann auf main oder den einzigen zugänglichen Branch zurückfallen. Die Antwortmetadaten zeigen die angeforderte und die aufgelöste Identität und warnen bei einem Fallback.
limit Optional
Typ
int minimum=1, maximum=50
Standard
15
Beschreibung
Maximale Ergebnisse pro Ebene
scope Optional
Typ
Literal[semantic, symbols, dependencies, all]
Standard
all
Beschreibung
Einzubeziehende Kontextebenen
language_filter Optional
Typ
str
Beschreibung
Sprachfilter: erfordert scope=semantic ohne explizite Startpunkte oder verwandten Kontext; Indizes anderer Ebenen können die Sprache nicht erzwingen.
path_filter Optional
Typ
str
Beschreibung
Dateipfadpräfix für Semantik- und Schlüsselwort-Abfragewurzeln. Explizite Seeds können außerhalb dieses Präfixes liegen; der Graphkontext kann Verzeichnisgrenzen überschreiten.
branch Optional
Typ
str
Beschreibung
Branch überschreiben
include_related_context Optional
Typ
bool
Standard
false
Beschreibung
Verwandten Kontext aus benachbarten Symbolen einbeziehen
seed_symbol_ids Optional
Typ
list[str] maxItems=20
Beschreibung
Explizite Aufgaben-Seeds: stehen in der Symbolebene an erster Stelle und bleiben innerhalb des begrenzten dependencies/related_context-Fensters erhalten. Die Graphebenen ordnen explizite Seeds und deren nächste Nachbarschaft vor dem Keyword-Fallback ein; die Wichtigkeit entscheidet nur bei gleicher Relevanz. Die Graph-Erweiterung erfordert scope=all|dependencies (scope=symbols|semantic führt die Abhängigkeitstraversierung nie aus). Weglassen für eine reine Keyword-Rangfolge nach tiefenabhängig abnehmender Wichtigkeit.
seed_file_paths Optional
Typ
list[str] maxItems=10
Beschreibung
Explizite Seeds: exakte indizierte Dateipfade, die der Agent geöffnet oder gerade bearbeitet hat. Liefert direkte Dateibelege in begrenztem Umfang sowie bis zu 5 Graph-Seeds pro Datei und bevorzugt dabei exakte Treffer auf den Aufgabennamen aus einem begrenzten Symbol-Lookup vor Definitionen und beiläufigen Symbolen. Auch symbolfreie Dateien liefern Belege. Fehlende Dateien können markierte Vorschläge liefern, die jedoch keine Seeds sind. Die Graph-Erweiterung erfordert scope=all|dependencies.

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_file Stabil

Liest eine Datei aus dem indizierten Repository anhand des Pfads. Bevorzuge lokale Datei-Tools für Dateien auf der Festplatte; dieses Tool ist für entfernte indizierte Snapshots gedacht. Setze begrenzte Antworten mit metadata.next_line_start und next_character_start fort. Entferne den abschließenden Zeilenumbruch plus die [truncated]-Markierung nur, wenn metadata.truncated=true ist; andernfalls könnte es sich um wörtlichen Quelltext handeln.

Parameter:

file_path Erforderlich
Typ
str
Beschreibung
Dateipfad relativ zum Repository-Stammverzeichnis
repository Optional
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. Exakt indizierte Branches werden bevorzugt; ein nicht verfügbarer Branch kann auf main oder den einzigen zugänglichen Branch zurückfallen. Die Antwortmetadaten zeigen die angeforderte und die aufgelöste Identität und warnen bei einem Fallback.
line_start Optional
Typ
int minimum=1
Beschreibung
Startzeile (1-basiert)
line_end Optional
Typ
int minimum=1
Beschreibung
Endzeile (1-indiziert, einschließlich; muss bei oder nach line_start liegen)
character_start Optional
Typ
int minimum=0
Standard
0
Beschreibung
Offset in UTF-16-Codeeinheiten nur innerhalb der Startzeile (0-basiert). Mit metadata.next_character_start innerhalb einer unvollständig gelesenen Zeile fortsetzen.
branch Optional
Typ
str
Beschreibung
Branch überschreiben
max_tokens Optional
Typ
int minimum=1, maximum=50000
Standard
5000
Beschreibung
Ungefähres Inhaltsbudget (4 UTF-16-Codeeinheiten pro Token; keine exakte Tokenizer-Grenze).
include_metadata Optional
Typ
bool
Standard
true
Beschreibung
Beschreibende Dateimetadaten einschließen. Metadaten zu Kürzung und Fortsetzung werden immer zurückgegeben.

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 — verwende das lokale Read-Werkzeug

System- und Utility-Tools

#

repository_context Stabil

Listet die durchsuchbaren Repositories auf oder ruft Identitätsinformationen zu einem einzelnen ab (namespace/branch, indexed_commit_sha / Aktualität des Index). Verwende action:"list", wenn der Repository-Slug unbekannt ist; die Suchwerkzeuge akzeptieren einen bekannten Slug direkt oder verwenden standardmäßig das einzige Repository deines Schlüssels. list verwendet pattern und Pagination; info erfordert repository und unterstützt branch sowie optional include_statistics=true.

Parameter:

action Erforderlich
Typ
Literal[list, info]
Beschreibung
Aktion: verfügbare Repositorys auflisten oder Repository-Informationen abrufen
repository Optional
Typ
str
Beschreibung
Nur für info: Repository im Format owner/repo oder owner/repo:branch (für info erforderlich)
branch Optional
Typ
str
Beschreibung
Nur für info: Branch überschreiben
pattern Optional
Typ
str
Beschreibung
Nur für list: Groß-/Kleinschreibung wird ignoriert – Teilzeichenfolge des Repository-Namens
include_statistics Optional
Typ
bool
Standard
false
Beschreibung
Nur zur Information: bezieht begrenzte Indexdatenzählungen ein. Die file/blob-Zählungen sind exakt; größere Indexzählungen sind Schätzungen. Siehe count_accuracy und estimate_analyzed_at. Standardmäßig false.
limit Optional
Typ
int minimum=1, maximum=50
Standard
20
Beschreibung
Maximale Ergebnisse pro Seite ohne cursor. Bei Fortsetzung wird die in cursor gespeicherte Seitengröße verwendet; cursor weglassen, um mit einem anderen limit zu starten.
offset Optional
Typ
int minimum=0
Beschreibung
Veralteter Kompatibilitäts-Offset. Bevorzuge den cursor aus pagination.next_cursor.
cursor Optional
Typ
str
Beschreibung
Undurchsichtiger cursor aus pagination.next_cursor. Unverändert übergeben und query sowie Filter unverändert lassen. Seine Position und Seitengröße überschreiben offset und limit.

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 — übergib include_statistics=true explizit, da dies langsamer als die reine Auflösung sein kann

ask_maguyva Stabil

Erhalte Anleitungen zu Maguyva-Tools oder übermittle einen Fehlerbericht beziehungsweise Funktionswunsch, der für das Wartungsteam von Maguyva gespeichert wird. Feedback darf keine Geheimnisse oder sensiblen personenbezogenen Daten enthalten. evaluate unterstützt deterministische Ausdrücke; bevorzuge lokale Berechnungen oder Host-Tools für Mathematik, Hashes und Zeichenfolgen.

Parameter:

operation Erforderlich
Typ
Literal[guidance, report_bug, request_feature, evaluate]
Beschreibung
Nutze guidance für Tool-Hilfe, report_bug für Fehler oder request_feature für Vorschläge. evaluate führt deterministische Ausdrücke aus; bevorzuge lokale Werkzeuge für Berechnungen.
query Optional
Typ
str maxLength=500
Beschreibung
Hilfethema (z. B. tool_selection, semantic_search) oder eine Ausdruckszeichenfolge für evaluate.
description Optional
Typ
str minLength=1, maxLength=4000
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_tool Optional
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:

  • Berechnungen mit Mathematik, Hashes oder Zeichenfolgen — bevorzuge lokale Berechnungen oder Host-Tools

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 Agent-sicher 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. Wenn die ausgelieferte Identität von der angefragten abweicht, meldet metadata.resolution_reason entweder "defaulted" (es wurde kein Branch angefragt) oder "fallback" (der angefragte Branch oder das Repository ist nicht verfügbar). Bei exakter Übereinstimmung entfällt das Feld.
  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: Rufe ask_maguyva mit operation="guidance" und query="tool_selection" auf, um Hinweise und Beispiele zur Tool-Auswahl zu erhalten. Verwende lokale Tools für Berechnungen und Zeichenfolgentransformationen.
  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. Dabei wird der indexierte Graph geprüft. Lokale, noch nicht committete Änderungen werden nicht gelesen, und lokale Tests werden nicht ersetzt. Prüfe indexed_commit_sha und die Aktualität des Index, bevor du Ergebnisse als Beleg für eine neue Revision behandelst.

Performance-Merkmale

#
Operation Performance-Hinweise
Semantische Suche Umfasst die Erzeugung des Anfrage-Embeddings und die Vektorsuche. Die Latenz hängt von beiden Vorgängen ab.
Textsuche Bei unscharfer Inhaltssuche werden für spätere Seiten mehr Kandidaten abgerufen. Grenze die Anfrage mit path_filter und language_filter ein.
Strukturelle Suche Fragt indexierte AST-Knoten ab. Verwende ein konkretes Profil oder Muster und begrenze die Ergebniszahl.
Abhängigkeitssuche Kosten skalieren mit der Tiefe — bevorzuge depth="shallow", außer du brauchst Multi-Hop-Kontext; per_hop_limit begrenzt die Streuung
Dateiabruf Lies den benötigten Bereich mit line_start/line_end oder max_tokens und nutze bei gekürzten Inhalten die zurückgegebenen Fortsetzungsmetadaten.
Repository-Kontext Die Repository-Auflösung erfolgt bei jedem Tool-Aufruf. Übergib repository ausdrücklich, wenn du ein bestimmtes Repository benötigst.
ask_maguyva (guidance / evaluate) Läuft im MCP-Server, ohne den Repository-Index abzufragen.

Fehlerbehandlung

#

Tool-Antworten enthalten gemeinsame Statusfelder und toolspezifische Nutzdatenfelder auf oberster Ebene. Suchen liefern results; get_file liefert content. Gemeinsame Felder sind:

  • status: String — "success" oder "error". Degradierte Treffer und Freshness-Signale haben eigene Felder: metadata.resolution_reason unter metadata sowie index_freshness.status auf oberster Ebene der info-Aktion von repository_context.
  • timing_ms: Verstrichene Ausführungszeit des Tools in Millisekunden
  • applied_filters: Für die Operation aufgezeichnete, tatsächlich angewendete Anfrageparameter
  • error: Fehlermeldung als Zeichenfolge, wenn status gleich "error" ist; sie kann Hinweise zur Fehlerbehebung enthalten.
  • metadata: Zusätzliche Informationen zur Operation (Routing, Caching, Parameteranpassungen)
  • pagination: Bei cursorbasiert paginierten Sammlungsantworten vorhanden — enthält has_more und next_cursor. Ranggeordnete Suchfenster liefern begrenzte Top-K-Ergebnisse, keine vollständig paginierten Sammlungen.

Prüfe das Feld status, bevor du ein Tool-Payload verarbeitest — seine Werte sind "success" oder "error". Behandle außerdem MCP/JSON-RPC-Transport- und Request-Validierungsfehler, die auftreten können, bevor überhaupt ein Tool-Payload entsteht. Für degradierte Treffer oder Freshness-Signale liest du stattdessen das dafür vorgesehene Feld: metadata.resolution_reason unter metadata oder index_freshness.status auf oberster Ebene der info-Aktion von repository_context (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.

Verwandt

Weiterlesen