MAST — Monorepo-AST-Suchtool

MAST ist eine Code-Suchmaschine, die entweder als MCP-Server (für KI-Assistenten) oder als eigenständiges CLI läuft. Sie parst TypeScript- und JavaScript-Quelldateien mit einem echten AST-Parser (tree-sitter), speichert den resultierenden Symbolgraphen und Code-Chunks in SQLite und beantwortet Abfragen mit lexikalischer BM25-Suche, die über Reciprocal Rank Fusion mit einem deklarationsgenauen Ranker fusioniert wird.

Das zentrale Designprinzip: genau den Code zurückgeben, den ein Assistent braucht, nicht mehr. Anstatt ganze Dateien zu lesen, gibt MAST die spezifische Funktion, Schnittstelle oder Typdeklaration zurück, die zu einer Abfrage passt — spart Tokens, reduziert Kontextrauschen und ermöglicht KI-Tools, große Codebasen zu durchsuchen, ohne in irrelevanten Inhalten zu ertrinken.

Inhalt

• Warum MAST?

• Voraussetzungen

• Installation

• Schnellstart

• Aus Ihrem KI-Assistenten verwenden

• Aktualisierung

• MAST in einem Monorepo verwenden

• CLI-Referenz

• MCP-Tool-Referenz

• Konfiguration

• So funktioniert es

• Token-Effizienz

• Verlauf

Related MCP server: codeix

Warum MAST?

Wenn ein KI-Assistent Code verstehen muss, besteht der naive Ansatz darin, ganze Dateien zu lesen. Das verschwendet Tokens (der Großteil einer 200-Zeilen-Datei ist für die Frage irrelevant), bläht Kontextfenster auf und zwingt das Modell, bei jedem Aufruf Signal von Rauschen zu trennen.

MAST verfolgt einen anderen Ansatz:

• AST-Ebene-Chunking — jede Funktion, Klasse, Schnittstelle und jeder Typalias ist ein eigener Chunk. Der Assistent erhält die genaue Deklaration, die er braucht, nicht die Datei, in der sie zufällig lebt.

• Rangfolgesuche — BM25 (FTS5) verarbeitet Schlüsselwort- und Bezeichnerabfragen; ein deklarationsgenauer Ranker („Ranker D") erfasst exakte Symbolnamen-Abfragen, die BM25s Trigramm-Tokenizer inkonsistent einordnen kann. Beide werden über Reciprocal Rank Fusion fusioniert, sodass ein Chunk, auf den sich beide Ranker einigen, höher eingestuft wird als einer, den nur einer von ihnen gefunden hat.

• Strukturabfragen — „Wer ruft diese Funktion auf?", „Was implementiert diese Schnittstelle?", „Was importiert diese Datei?" werden aus einem vorgebauten Symbolgraphen beantwortet, nicht durch Durchsuchen des Quellcodes. Antworten sind sofort verfügbar und strukturell korrekt.

• JIT-Veraltungserkennung — bei jedem Lesezugriff prüft MAST, ob sich die Datei auf der Festplatte seit der letzten Indizierung geändert hat. Wenn ja, wird die Datei im Hintergrund transparent neu geparst, bevor das Ergebnis zurückgegeben wird. Der Index wird nie veraltet, ohne dass der Assistent es weiß.

• Token-Abrechnung — jede Tool-Antwort enthält _stats mit der Anzahl der zurückgegebenen Tokens und der kontrafaktischen Angabe „Was hätte ein naives vollständiges Dateilesen gekostet?", was ein konkretes Maß für die Effizienz im Laufe der Zeit ergibt.

Voraussetzungen

• Node.js ≥ 22 (dieses Repository pinnt die Version, gegen die es entwickelt wird, in .nvmrc)

• Eine C++-Toolchain für die beiden nativen Module (better-sqlite3, tree-sitter). Vorkompilierte Binärdateien decken die meisten Plattformen ab; wenn keine mit Ihrer Node-ABI übereinstimmt, baut node-gyp aus dem Quellcode und benötigt:

  • macOS — xcode-select --install

  • Debian/Ubuntu — sudo apt install build-essential python3

  • Windows — installieren Sie die Workload „Desktopentwicklung mit C++" aus den Visual Studio Build Tools

Keine Dienste, keine API-Schlüssel, kein Netzwerk zur Abfragezeit. Alles ist lokales SQLite.

Installation

Als Entwicklungsabhängigkeit des Projekts, das Sie indizieren möchten — empfohlen, da die Version dann zusammen mit allem anderen in Ihrer Lockfile gepinnt ist:

pnpm add -D @spikedpunch/mast     # or: npm i -D / yarn add -D

Oder global, wenn Sie ein mast für viele Checkouts möchten:

pnpm add -g @spikedpunch/mast

Überprüfen:

mast --version

Schnellstart

Drei Befehle von nichts zu einem durchsuchbaren Index:

cd /path/to/your/project

mast init                    # write .mast/, then run the first full index
mast status                  # confirm it is fresh
mast search "createUser"     # search it

mast search gibt die passende Deklaration aus, nicht die Datei, in der sie lebt:

$ mast search "compareVersions" -n 1
src/cli/upgrade-cmd.ts:39  compareVersions  function  (exported)
    /** Semver compare, prerelease-aware. Returns <0, 0, or >0. */
    export function compareVersions(a: string, b: string): number {
      ...
    }

270 tokens returned vs 2140 to read the files whole — 87% saved

Die letzte Zeile ist echte Abrechnung, kein Slogan: Jede Antwort trägt _stats mit dem, was sie zurückgegeben hat, und einer Obergrenze für das vollständige Lesen der referenzierten Dateien. Bei einer kleinen Datei kann die Ersparnis negativ sein, und MAST sagt das, anstatt es zu einer Erfolgsmeldung zu runden.

Eine Antwort, hinter der MAST nicht vollständig stehen kann, sagt das auf derselben Oberfläche, die das Ergebnis anzeigt. Eine Datei, die seit der Indizierung bearbeitet wurde, wird markiert, weil der darunter gedruckte Text der alte ist:

! 1 of 2 results are from files that changed since indexing —
  the code shown below may be out of date. Run `mast index` to refresh.

src/a.ts:1  alphaFunction  function  (exported)  [STALE]

Und eine leere Antwort unterscheidet die beiden Gründe, warum sie leer sein kann:

$ mast search "kept_symbol"
no matches (mast indexes TypeScript, JavaScript, and Markdown only —
a symbol in any other language is invisible to it, not absent from the repo)

$ mast search "anything"          # in a directory with no index
nothing is indexed at this path — this is not evidence the symbol is absent.
run `mast index` first, or check `mast status` for the path being used.

Eingrenzen mit --type, --language, --exported, --file, -n:

mast search "greet" --type method --exported -n 5
mast search "config" --file "src/store/**"

Halten Sie es aktuell, während Sie arbeiten — oder lassen Sie einen Git-Hook das erledigen:

mast index --incremental     # reindex only what changed
mast install-hooks           # reindex automatically after commits and checkouts

Alles, was mit Ihrem Build ausgeliefert wird, ist offline lesbar, sodass Sie nie herausfinden müssen, welche Dokumentation zu Ihrer Version passt:

mast docs                    # list the topics
mast docs spec               # the full behavioural specification
mast skill                   # the instructions to paste into an agent prompt

Aus Ihrem KI-Assistenten verwenden

MAST spricht MCP über stdio. mast serve ist der Serverbefehl; die folgende Konfiguration unterscheidet sich nur darin, wo jedes Tool seine Konfigurationsdatei aufbewahrt.

Wenn Sie MAST als Entwicklungsabhängigkeit statt global installiert haben, ersetzen Sie mast in allen diesen Beispielen durch npx @spikedpunch/mast (oder pnpm exec mast).

Claude Code

claude mcp add mast -- mast serve

Fügen Sie --scope project hinzu, um .mcp.json in das Repository zu schreiben, damit Ihr Team es aus dem Checkout übernimmt.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json auf macOS, %APPDATA%\Claude\claude_desktop_config.json unter Windows:

{
  "mcpServers": {
    "mast": {
      "command": "mast",
      "args": ["serve"],
      "env": { "MAST_STATE_DIR": "/absolute/path/to/your/project/.mast" }
    }
  }
}

Claude Desktop läuft nicht in Ihrem Projektverzeichnis, daher muss MAST_STATE_DIR absolut sein. Das CLI und die Editor-Integrationen unten leiten es aus dem Arbeitsverzeichnis ab.

Cursor

.cursor/mcp.json im Projekt oder ~/.cursor/mcp.json global:

{
  "mcpServers": {
    "mast": { "command": "mast", "args": ["serve"] }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "mast": { "type": "stdio", "command": "mast", "args": ["serve"] }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mast": { "command": "mast", "args": ["serve"] }
  }
}

Zed

settings.json:

{
  "context_servers": {
    "mast": { "command": { "path": "mast", "args": ["serve"] } }
  }
}

Jeder andere MCP-Client

Führen Sie mast serve über stdio aus dem Projektstammverzeichnis aus. Es bietet elf Lese-Tools an und benötigt außer serve keine Argumente.

Dem Assistenten die Verwendung erklären

Das Registrieren des Servers gibt dem Modell die Tools; es sagt ihm nicht, wann es sie verwenden soll oder wie es eine markierte Antwort liest. mast skill gibt dafür geschriebene Anweisungen aus — fügen Sie sie in Ihren System-Prompt, CLAUDE.md, .cursorrules oder eine Skill-Datei ein:

mast skill                    # print it
mast skill --install          # splice it into this project's agent config files
mast skill --install --dry-run

--install schreibt nur in Dateien, die bereits existieren — CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md — und schreibt innerhalb eines markierten Blocks, sodass ein erneuter Lauf nach einem Upgrade die vorherige Kopie ersetzt, anstatt eine zweite hinzuzufügen. Es läuft nie von selbst und erstellt nie eine Konfigurationsdatei, die Sie nicht bereits geführt haben.

Aktualisierung

mast upgrade

Dies prüft auf eine neuere Version und gibt den genauen Befehl dafür aus, wie Sie es installiert haben — es aktualisiert nicht direkt, weil ein CLI eine globale Installation nicht zuverlässig von einer Entwicklungsabhängigkeit unterscheiden kann, und eine falsche Vermutung führt den falschen Befehl in Ihrem Repository aus.

Wichtiger noch: Es sagt Ihnen das eine, was Ihr Paketmanager nicht kann: ob das Upgrade das Indexschema ändert. Wenn ja, verwirft MAST den Index und baut ihn beim nächsten serve oder index neu auf. Nichts geht verloren, das nicht neu aufgebaut werden kann — der Index ist abgeleiteter Zustand — aber bei einem großen Monorepo sind das Minuten, und es ist besser, es im Voraus zu wissen, als es als unerklärlichen Stillstand zu entdecken.

MAST in einem Monorepo verwenden

Ein Index im Repository-Stammverzeichnis ist normalerweise richtig. Paketübergreifende Importe werden aufgelöst, sodass mast_callers Aufrufer in Schwesterpaketen findet — das ist der Grund, ein Monorepo-Tool zu verwenden anstatt einen Index pro Paket.

Was indiziert wird. .ts, .tsx, .js, .jsx und .md, minus node_modules, dist, build, coverage, .next, .turbo, .mast und Testdateien. Überschreiben mit --extensions und --exclude bei mast init oder bearbeiten Sie .mast/config.json.

Andere Sprachen werden nicht indiziert, und das ist wichtig. MAST parst nur TypeScript und JavaScript. Ein Symbol, das in Python, Go, Java oder Rust definiert ist, fehlt im Index, was genau wie „im Repository nicht vorhanden" aussieht. Behandeln Sie ein leeres Ergebnis als „MAST hat es nicht gefunden", niemals als „es existiert nicht" — mast skill sagt dies auch dem Modell.

Fügen Sie .mast/ zu .gitignore hinzu. Es ist abgeleiteter Zustand, es ist groß und es ist maschinenspezifisch.

Ein benutzerdefinierter Indexspeicherort wird nicht zwischen Läufen gespeichert. --state-dir gilt für den einen Befehl, dem Sie es übergeben. Pfadeinstellungen werden bewusst nie aus einer persistierten Konfiguration zurückgelesen — ein absoluter Pfad, der von einem früheren Lauf (oder einem früheren Container) geschrieben wurde, kann an einem Ort aufgelöst werden, der nicht mehr existiert, oder schlimmer, an einem Ort, der zu einem anderen Projekt gehört. Um einen benutzerdefinierten Speicherort dauerhaft zu machen, legen Sie ihn in die Versionskontrolle oder die Umgebung:

// mast.config.json, at the project root
{ "state_dir": ".cache/mast" }

export MAST_STATE_DIR=/absolute/path/to/index

Die Auflösungsreihenfolge ist --state-dir → MAST_STATE_DIR → mast.config.json → .mast. mast status gibt das aufgelöste Verzeichnis aus und sagt klar, wenn dort nichts indiziert wurde.

Skalierung. Ein Kaltindex von VS Code — 8.653 Dateien, 152.969 Chunks — dauert etwa zwei Minuten und erzeugt ein 794 MB großes Zustandsverzeichnis. Inkrementelle Neuindizierung einer geänderten Datei dauert Millisekunden.

CLI-Referenz

mast init [path]

Initialisiert MAST für ein Projekt und führt den anfänglichen vollständigen Index aus.

Options:
  --state-dir <dir>        Where to write index state (default: <path>/.mast)
  --extensions <ext,...>   File extensions to index (default: .ts,.tsx,.js,.jsx,.md)
  --exclude <pattern,...>  Glob patterns to exclude
  --no-index               Create config only; skip initial indexing

Warum: Erstellt die Zustandsverzeichnisstruktur, schreibt config.json und führt einen vollständigen Parse- + Symbolextraktionsdurchlauf aus. Wenn Sie dies einmal im Voraus ausführen, berühren nachfolgende inkrementelle Läufe nur geänderte Dateien.

mast search <query> [path]

Durchsucht den Index und gibt lesbare Ergebnisse aus.

Options:
  -n, --limit <n>        Max results, 1-50 (default: 10)
  -t, --type <kind>      function | method | class_shell | interface | type | export | block | doc
  -l, --language <lang>  typescript | javascript | markdown
  -e, --exported         Only exported symbols
  -f, --file <glob>      Restrict to files matching a glob
      --state-dir <dir>  State directory
      --json             Emit the raw MCP response instead of text

Warum: der schnellste Weg, um zu prüfen, was der Index tatsächlich enthält, und derselbe Codepfad wie das MCP-Tool mast_search — es leitet über den registrierten Handler weiter, anstatt das Ranking neu zu implementieren, sodass CLI- und Assistentenergebnisse nicht voneinander abweichen können. Veraltungs- und Kürzungsflags werden über den Ergebnissen ausgegeben; ein leeres Ergebnis, das weil der Index beschäftigt war leer ist, sagt das.

Für Skripte gibt mast query mast_search '{...}' byteidentische MCP-Ausgabe.

mast index [path]

Erstellt oder aktualisiert den Index.

Options:
  --state-dir <dir>    State directory
  --incremental        Only reindex files changed since last run
  --show-progress      Print indexing progress to stderr
  --checker            Opt-in TypeScript-checker pass: upgrades heuristic potential_matches
                        into verified caller edges (or drops non-call-site noise). Can take
                        tens of seconds on a large monorepo — not part of the default path.

Warum inkrementell: Der inkrementelle Pfad vergleicht das aktuelle Dateimanifest mit gespeicherten mtimes. Nur veraltete, hinzugefügte oder gelöschte Dateien werden verarbeitet — bei einer großen Codebasis verkürzt dies die Indexzeit bei den meisten Läufen von Sekunden auf Millisekunden.

mast serve

Startet den MCP-Server über stdio.

Options:
  --state-dir <dir>         State directory
  --no-startup-reindex      Skip the startup staleness check (not recommended)
  --watch                   Watch source files and incrementally reindex on change
                             (interactive use; not needed in the container ladder)

Der Server implementiert eine vierteilige Startleiter, sodass MCP-Clients auch bei großen Projekten in unter einer Sekunde einen nutzbaren Server erhalten. Siehe Startleiter für Details.

mast status [path]

Gibt die Indexgesundheit aus.

Options:
  --state-dir <dir>    State directory
  --json               Output as JSON

Meldet last_indexed, indexed_files, chunk_count, stale_files, parse_errors, write_errors, index_fresh und freshness_cause. Verwenden Sie dies, um zu diagnostizieren, warum Suchergebnisse veraltet aussehen.

mast metrics [path]

Zeigt Token-Effizienzmetriken.

Options:
  --since <window>        Time window: 7d, 24h, 30m (default: 7d)
  --rollup                Collapse raw rows older than --keep-days into daily roll-ups
  --vacuum                Delete daily roll-up rows older than --keep-days
  --keep-days <n>         Retention days (default: 7 for rollup, 90 for vacuum)
  --state-dir <dir>       State directory

Gibt eine spaltenausgerichtete Tabelle aus: Toolname, Aufrufanzahl, zurückgegebene Tokens, durchschnittliche Dauer und Effizienzverhältnis. Verwenden Sie --rollup + --vacuum regelmäßig, um zu verhindern, dass die Metrikdatenbank unbegrenzt wächst.

mast install-hooks [path]

Installiert Git-post-commit-/post-checkout-Hooks, die mast index --incremental automatisch ausführen, damit der Index über Commits und Branch-Wechsel hinweg ohne manuellen Schritt aktuell bleibt.

mast query <tool> [json] [path]

Ruft jedes MCP-Lese-Tool direkt auf, mit byteidentischer Ausgabe zum MCP-Transport.

Options:
  --state-dir <dir>   State directory
  --json              Emit the exact single-line MCP response (default pretty-prints)

mast query mast_callers '{"symbol":"resolveConfig"}'
mast query mast_project_skeleton '{}'

Warum: die Skript- und Debugging-Oberfläche. mast search ist die lesbare Eingangstür zu einem Tool; dies erreicht alle elf und gibt genau das zurück, was ein Assistent erhalten würde — sodass eine Abweichung zwischen dem, was Sie sehen, und dem, was das Modell gesehen hat, nicht möglich ist. Die Benennung eines nicht existierenden Tools listet die vorhandenen auf.

mast docs [topic]

Gibt Dokumentation aus, die mit der installierten Version ausgeliefert wird — readme, spec oder skill. Kein Argument listet die Themen mit der Version auf, zu der sie gehören.

Warum: entfernt den Schritt, bei dem ein Leser seine Version nachschlägt und dann Dokumentation für eine andere findet. Was mast docs ausgibt, ist das, was die Binärdatei in Ihrem node_modules tut.

mast skill [path]

Gib die MAST-Anweisungen aus, um sie in einen Agent-Prompt, CLAUDE.md, .cursorrules oder eine Skill-Datei einzufügen.

Options:
  --install    Splice into this project's existing agent config files
  --dry-run    With --install, report what would change without writing

Warum: Das Registrieren des MCP-Servers gibt einem Modell die Tools, aber nicht das Urteilsvermögen – wann es suchen statt lesen sollte, dass Code-Token in einer Abfrage besser als Prosa sind und wie es ein Staleness- oder Truncation-Flag liest. Es vermittelt dem Modell außerdem, dass ein leeres Ergebnis „MAST hat es nicht gefunden“ bedeutet, nicht „es existiert nicht“ – das ist die wichtigste Sache, die man bei einem Suchwerkzeug richtig verstehen muss.

mast upgrade [path]

Prüft auf eine neuere Version; gibt aus, wie man sie installiert und was sie kostet.

Warum: Es erkennt, wie MAST installiert wurde, und gibt den passenden Befehl aus, statt ihn auszuführen, denn ein CLI kann eine globale Installation nicht zuverlässig von einer Entwicklungsabhängigkeit unterscheiden. Es meldet außerdem, ob das Upgrade das Index-Schema anhebt – was beim nächsten serve eine vollständige Neuindizierung erzwingt – und das kann dein Paketmanager dir nicht sagen.

MCP-Toolreferenz

MAST registriert 11 Tools beim MCP-Server. Jede Lesetool enthält einen _stats-Block:

{
  tool: string,
  tokens_returned: number,
  tokens_full_file_upper_bound: number,
  files_referenced: string[],
  efficiency_ratio: number,           // 1 - (returned / full_file)
  duration_ms: number,
}

mast_search

Lexikalische BM25- und deklarationsgenaue Suche über der indizierten Codebasis.

{
  query:         string,              // natural language or identifier
  limit?:        number,              // max results (default 10, max 50)
  language?:     "typescript" | "javascript" | "markdown" | null,
  file_pattern?: string | null,       // glob: "src/api/**"
  chunk_type?:   "function" | "method" | "class_shell" | "interface" | "type" | "export" | "block" | "doc" | null,
  only_exported?: boolean
}

Rückgabe: { "results": [], "suggestions": ?, "_stats": {} }. Jedes Ergebnis enthält file_path, start_line, end_line, content, chunk_type, symbol, parent_symbol, is_exported, match_score (BM25-Wert, negativ; null, wenn der Treffer nur von Ranker D stammt), rank, match_snippet und einen optionalen related-Hinweis, wenn eine Methode und ihr Klassen- shell beide matchen (nur das höher bewertete wird zurückgegeben). suggestions ist vorhanden, möglicherweise leer, genau dann, wenn results leer ist – eine „Meintest du?“-Unterstützung bei null Ergebnissen.

Warum: grep und glob finden exakte Zeichenketten und verlangen, dass der Aufrufer das Muster bereits kennt. mast_search bewertet die Relevanz anhand zweier Signale, die mit Reciprocal Rank Fusion verknüpft werden:

• BM25 (FTS5, Trigramm-Token) – der allgemeine lexikalische Ranker; verarbeitet Schlüsselwortanfragen und Sub-Token/camelCase-Treffer.

• Ranker D (deklarationsgenau) – ein direkter Treffer auf den symbol_name des Chunks selbst (voller Name oder letztes Vertex-Segment, ohne Groß-/Kleinschreibung). Er fängt exakte Symbolanfragen werken ab, wie BM25-Trigrom-Bewertung unterbewerten kann. Er wird über den Konfigurationsschlüssel declaration_exact_ranker gesteuert (Standard: an); wenn aus, ist mast_search nur BM25.

Ein Chunk, den beide Ranker bearbeiten, wird höher eingestuft als einer, den nur einer der beiden findet. file_pattern und language begrenzen den Pool, aus dem beide Ranker schöpfen, sodass eine eingeschränkte Suche nie eine Datei außerhalb des Bereichs zurückgibt. file_pattern ist ein Glob, der mit der gleichen Primitivierung abgeglichen wird, die exclude_patterns beim Indexieren anwendet: * überschreitet kein /, ** überträgt, ? ist ein einzelnes Nicht-/-Zeichen, der Abgleich unterscheidet Groß-/Kleinschreibung und alles andere – ., _, - – ist wörtlich.

mast_project_skeleton

Alle exportierten Symbole, gruppiert nach Datei, optional auf eine Verzeichnis begrenzt.

{
  directory?:    string | null,       // path prefix: "src/api"
  max_depth?:    number,              // max subdirectory depth (default unlimited)
  file_pattern?: string | null        // glob filter on file paths
}

Rückgabe: { "files": [{ "file_path", "exports": string[] }], "_stats": {} }.

Warum: Bevor in einem Codebase navigiert, braucht ein Assistent die Orientierung – „Was gibt es hier?“. Das Lesen der Dateien, um deren Exportada zu finden, ist verschwenderisch. mast_project_skeleton liefert in einem einzigen Aufruf eine verzeichnisbezogene Zuordnung Datei → exportierte Namen und lässt den Assistenten ein mentales Modell eines Subsystems aufbauen, ohne Dateien zu öffnen.

mast_exports

Alle exportierten Symbole aus einer einzelnen Datei mit Typ-Signaturen und TSDoc.

{
  file_path: string                   // relative to project root
}

Rückgabe: {"file_path", "exports": [{ "name", "kind", "signature", "line", "doc" }], "_stats": {}}.

Warum: Die natürliche Fortsetzung von mast_project_skeleton. Sobald der Assistent weiß, welche Datei relevant ist, liefert mast_exports vollständige Signaturen ohne Funktionen – genug, um die öffentliche Fläche eines Moduls zu verstehen, ohne einen Code dafür zu bezahlen. Methoden werden bei also ausgelassen (sie werden über mast_signature der Elternklasse sichtbar), damit das Ergebnis auf die öffentlichen Vertrag des Moduls fokussiert bleibt.

mast_signature

Deklaration, TSDoc und aufgelöste Parametertyp-Kontext für ein benanntes Symbol.

{
  symbol:     string,                 // e.g. "handleLogin", "AuthService"
  file_path?: string | null           // narrow to a specific file
}

Rückgabe: Ein Array von "SignatureResult", jeweils mit symbol, file_path, line, signature, doc, params, return_type und type_context.

type_context wird automatisch befüllt: benutzerdefinierte PascalCase-Typnamen, die in der Signatur vorkommen, werden über eine dreistufige Suche auf ihre eigenen Signaturen aufgelöst – zuerst dieselbe Datei, dann benannte Importe, dann ein globales Fallback für exportierte Typen. Lange Signaturen werden bei 500 Zeichen abgeschnitten. Ein einziger mast_signature-Aufruf gibt dem Assistenten also das vollständige Typbild einer Funktion, ohne separate Regeln zu benötigen.

Warum: Wenn ein Assistent function processOrder(order: Order, ctx: RequestContext): Promise<Result> sieht, benötigt er die Signaturen von Order und RequestContext, um zu verstehen, was passiert. mast_signature löst diese inline auf, statt drei weitere Tool-Aufrufe auszuführen.

mast_callers

Wer ruft das Symbol auf, getrennt in verifizierte (aus dem Symbolgraphen) und potenzielle Treffer (aus der Volltextsuche)? GXP35

Rückgabe: {"verified_callers": [], "potential_matches": [], "summary": {"verified_count": 1, "potential_count": 1, "transitive": 0, "checker_classified_non_call_site": false, "checker_classified_different_declaration": false}, "_stats": {}}.

Warum: Wi before a refactor: who depends on a symbol? Verifizierte Aufrufer sind graphauflösbar und definitiv; potential matches sind ID-FTS-Treffer, aber unsichere Treffer – sie können falsch positiv sein, sollten aber geprüft werden. Die Aufgabe ist, beide zu differenzieren, damit das Tool die Unsicherheit „12 potenzielle Treffer“ von „3 verifizierte Treffer“ unterscheiden kann. Ein Aufruf von mast index --checker stärkt einige potenzielle Hinweise in bestätigte Kanten, oder erkennt checker_classified_non_call_site und checker_classified_different_declaration, wie viele der Kategorien zuzuordnen sind. mast_callers macht diese Klassifizierung transparent.

mast_dependencies

Alle Importe, die für eine Datei aufgezeichnet sind.

{
  file_path: string
}

Rückgabe: {"file_path": "", "imports": [{ "module": "", "symbols": [], "is_external": true, "resolved_path": "/path" }], "_stats": {}}.

Warum: Ein Verständnis der Abhängigkeiten einer Datei ist der erste Schritt, um zu verstehen, was sie tut. Externe Importe (ohne resolved_path) sind markiert, damit der Aufrufer den Endpunkt kennt. Interne Imports enthalten den Pfad, damit sein Follow-up möglich ist.

mast_implementors

Alle konkreten Klassen, die ein bestimmtes Interface implementieren, plus ihrer Methodenlisten.

{
  interface_name: string
}

Rückgabe: {"result": [{"class_name": "string", "file_id": "path", "line": 1, "methods": [], "_stats": {}}]}.

Warum: In einer DI-Codebase ist interface_name → implementors die wichtigste Ersetzung von „Welche Plugin?“. Statt nach implements InterfaceName zu grepen, werden durch MAST die expliziten IMPLEMENTS-Kanten im Graph beim Indexzeitpunkt erfasst.

mast_rename_impact

Checkliste für das Rename-Auswirkung: Stellen, Aufrufer, Rückverweise & Barrel-Exports in einem Aufruf.

{
  symbol:     string,
  file_path?: string | null
}

Rückgabe: {"symbol": "name", "declaration_sites": [], "verified_callers": [], "potential_matches": [], "barrel_exports": [], "summary": {"declaration_count": 1, "verified_count": 1, "potential_count": 1, "barrel_count": 0, "transitive": 0, "checker_classified_non_call_site": false, "checker_classified_different_declaration": false}, "_stats": {}}.

Warum: Ein Umbenennen ist nicht nur ein Wechseln der Aufrufstelle: auch barrel-Re-Exports mit dem Namen sind zu ändern, und die wichtigsten möglichen Fehler leiden nicht nach Fehlercode, sondern in Aktualisierung bestehender barrels. mast_rename_impact misst und zeigt, welche Pfade geändert werden müssen – source-Verweise, Export-Aliasse, barrel-Fälle und unklar sind.

Warum: Ein Umbenennen ist nicht nur ein reexport. Dateien, die über den barrel re-exportiert werden, sind ebenso zu aktualisieren, und man kann sie mit einem reinen Aufrufer-Fehler leicht übersehen. mast_rename_impact kombiniert die mast_callers-Mechanik mit der Barrel-Exporter-Erkennung, sodass der Assistent eine Checkliste anstelle von drei separaten Abfragen erhält.

Aus dem Summary finden Sie checker_classified_non_call_site und checker_classified_different_declaration Informationen, ob der checker-Pass nach Einträgen klassifiziert hat.

mast_reindex

Löst eine synchrone Neuindizierung innerhalb einer MCP-Sitzung aus.

{
  full?: boolean                      // force full reindex (default: incremental)
}

Rückgabe: {"files_indexed": 1, "files_skipped": 0, "chunks_added": 1, "chunks_removed": 0, "parse_errors": 0, "write_errors": 0, "duration_ms": 123}

Warum: Lang laufende Bearbeitungssitzungen erzeugen Staleness, d.h. Dateien können neu indexiert werden, bevor sie durch die Suche gefunden werden. Das Tool erzwingt die erforderliche Neuindexierung, ohne dass der Benutzer den MCP-Server anhalten und mast index mit --checker ausführen muss. Siehe mast_status zu Indikator für den Zustand.

mast_status

Gesundheitscheck des Indexes.

// no inputs

Rückgabe: {"state_dir": "~/.mast", "last_indexed": "ISO-8601", "indexed_files": 1, "chunk_count": 1, "stale_files": 0, "parse_errors": 0, "write_errors": 0, "index_fresh": true, "freshness_cause": "stale_files=1", "seed_commit": null}

Warum: Während des Start eines MCP-Servers wissen Langläufe, ob Dateien auf dem Stand noch aktuell oder ob ein editiertes Objekt den Index sint. stale_files zählt alle Dateien, die seit dem letzten Index geändert wurden. index_fresh ist nur true, wenn keine geändert Dateien und MCP-Server in einem Laufzustand vorhanden sind.

(Achtung: stale_files ist identisch mit dem Count aus mast status – derselbe Produzent.)

mast_efficiency

Token-Report: wie viel Kontext pro Tool zurückgegeben werden, durch "Gegenfaktischlesung".

{
  scope:          "session" | "global",
  since_minutes?: number              // global scope: restrict to last N minutes
}

Rückgabe: {"scope": "session", "window_started_at": "2024-", "tokens_returned": 1234, "tokens_full_file_upper_bound": 4567, "efficiency_ratio": 0.30, "calls_total": 12, "calls_by_tool": {"mast_search": 10}, "tokenizer": "tiktoken", "counterfactual": "Would have cost ~14,200 tokens with naive full-file reads; saved ~11,400 tokens (80.2%)."}

Das counterfactual-Feld ist ein ansprechender Strict mit einem token-Kontingente, das anzeigt, „drei Drittel des Volumens überfläche". Dies ist nicht nur ein Bericht, sondern die Währung der MASTYP-Theorie: präziser Code-Navigation spart Tokens und damit Priced, und kann nachgewiesen werden.

Warum: Tokeneffizienz ist der Grund, warum MAST existiert. Jeder Aufruf gibt nicht den vollständigen Dateiinhalt zurück (nur content extrahierten Chunk), und unterstützt so 30-80%iges Kontextsparpotenzial.

Die geSAMT

Die obigen 11 Tools bilden zusammen einen umfassenden, orchestrierbaren MCP-Server. Jedes Tool ist begrenzt und spezifisch; jeder gibt _stats zurück; jede unterstützt den Assistenten bei der Verständnis einer Codebasis und des Umbenennen effenbaren. Denken Sie daran, Platzhalter wie den GXP-IDs sind spezifische Vorkommen, die wir anpassen müssen.

---

Ich habe die Struktur beibehalten, alle Markierungen/Code (`GXP29`–`GXP41` als Kommentare) sowie Formatierungen. Haben Sie noch einen Wunsch? Möchten Sie z.B. die Inhalte an Ihrer ``Datei`- oder einem anderen Modul anpassung?

| Key                        | Default                                                                                    | Beschreibung                                                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `state_dir`                | `.mast`                                                                                    | Verzeichnis für den gesamten Indexzustand (relativ zum Projektstamm)                                                        |
| `file_extensions`          | `.ts,.tsx,.js,.jsx,.md`                                                                    | Zu indexierende Quelldatei-Erweiterungen                                                                                    |
| `exclude_patterns`         | `node_modules/**`, `dist/**`, `coverage/**`, `.kluster/**`, `**/*.test.ts`, `**/*.spec.ts` | Zu überspringende Glob-Muster                                                                                               |
| `rrf_k`                    | `60`                                                                                       | Reciprocal-Rank-Fusion-Konstante (höher = flachere Rangfolge)                                                               |
| `declaration_exact_ranker` | `true`                                                                                     | Fügt Ranker D (exakte Übereinstimmung der Deklaration) in `mast_search` ein. Setzen Sie `false`, um ohne Codeänderung zur reinen BM25-Rangfolge zurückzukehren. |
| `chunk_split_threshold`    | `100`                                                                                      | Zeilen, ab denen eine Deklaration in überlappende Unter-Chunks aufgeteilt wird                                              |
| `context_lines`            | `3`                                                                                        | Quellzeilen vor/nach AST-Grenzen, die im gespeicherten Inhalt enthalten sind                                                |
| `markdown_heading_depth`   | `2`                                                                                        | Maximale ATX-Überschriftsebene (`##`), die einen neuen Markdown-Dokument-Chunk startet                                      |

**`mast.config.json`-Beispiel:**

GXP42

**`MAST_STATE_DIR`** — überschreibt das Zustandsverzeichnis, ohne `mast.config.json` anzufassen. Nützlich in CI- oder Docker-Umgebungen, in denen das Projektstammverzeichnis schreibgeschützt ist.

***

## So funktioniert es

### Indizierung

`runIndex` durchläuft das Projekt mit `fast-glob`, berechnet ein auf mtime basierendes Manifest und vergleicht es mit dem gespeicherten Manifest, um veraltete, hinzugefügte und gelöschte Dateien zu finden. Für jede Datei, die verarbeitet werden muss:

1. **Parsen** — `tree-sitter` parst die Datei in einen konkreten Syntaxbaum. Die TypeScript-Grammatik wird für `.ts` und `.tsx` verwendet; die JavaScript-Grammatik für `.js` und `.jsx`. Markdown-Dateien werden nach Überschriften (`markdown_heading_depth`) in Chunks aufgeteilt, nicht mit tree-sitter geparst.
2. **Chunking** — der Extraktor zerlegt den CST in typisierte Chunks: `function`, `class_shell` (die Klassendeklaration plus Mitgliedssignaturen, ohne Rümpfe), `method` (einzelne Methoden), `interface`, `type`, `export`, `block` und `doc` (Markdown-Abschnitte). Klassen werden immer zerlegt, damit eine Suche nach einer einzelnen Methode nicht den gesamten Klassenrumpf zurückgibt.
3. **Unter-Chunking** — Deklarationen, die länger als `chunk_split_threshold` Zeilen sind, werden in überlappende Segmente aufgeteilt, damit kein einzelner Chunk zu groß ist, um ein nützliches, in sich geschlossenes Suchergebnis zu sein.
4. **Symbolgraph** — Symbole, Importe und Kanten (IMPLEMENTS, PARENT\_OF, POTENTIAL\_CALL) werden in SQLite geschrieben. Die Zwei-Pass-Schreibstrategie (zuerst alle Dateien, dann Kanten) stellt sicher, dass Kanten auf Symbole verweisen können, die möglicherweise in einer Datei definiert sind, die später im selben Lauf geparst wird.
5. **FTS** — Chunk-Inhalte werden in eine virtuelle FTS5-Tabelle mit einem Trigramm-Tokenizer geschrieben, was Sub-Token- und camelCase-Suchen ermöglicht. Eine `identifier_fts`-Tabelle mit einem unicode61-Tokenizer übernimmt exakte Bezeichner-Suchen für potenzielle `mast_callers`-Übereinstimmungen.

Die Indizierung ist eine einzelne Phase — Chunk/Graph/FTS werden alle zusammen in einem `runIndex`-Durchlauf aktualisiert; es gibt keinen separaten Einbettungsschritt.

### Rangfolgesuche (BM25 + Ranker D über RRF)

Eine Abfrage durchläuft zwei Ranker:

**BM25 (FTS5):** Die Abfrage wird mit SQLites integriertem BM25-Ranking über einen Trigramm-Tokenizer gegen `chunk_fts` abgeglichen. Dateimuster- und Sprachfilter werden als SQL-Prädikate gegen die `files`-Tabelle in diese Abfrage eingefügt (nicht als FTS-MATCH-Prädikate, da SQLite FTS5 LIKE auf UNINDEXED-Spalten mit MATCH unzuverlässig ist). BM25-Werte sind in SQLites Konvention negativ — negativer bedeutet eine stärkere Übereinstimmung; `match_score` von `mast_search` behält dieses Vorzeichen bei.

**Ranker D (exakte Deklaration):** Ein direktes SQL-Prädikat gegen `chunks.symbol_name` — Übereinstimmung mit dem vollständigen Namen oder dem letzten Punktsegment, ohne Berücksichtigung der Groß-/Kleinschreibung, deterministisch geordnet. Gesteuert durch den Konfigurationsschlüssel `declaration_exact_ranker` (standardmäßig aktiviert).

**RRF-Fusion:** Die beiden Ranglisten werden mithilfe der Reciprocal Rank Fusion kombiniert:

GXP43

mit Standardwert `k = 60`. Ein Chunk, der in beiden Listen auf Rang 1 erscheint, erzielt doppelt so viele Punkte wie ein Chunk, der nur in einer erscheint. Chunks, die nur in einer Liste erscheinen, erzielen trotzdem gute Werte — keines der beiden Signale dominiert.

### JIT-Veraltetheitsprüfungen

Jedes Lesewerkzeug (search, exports, signature, callers, dependencies, implementors) ruft vor der Rückgabe von Ergebnissen `jitRefreshFile` auf. Diese Funktion:

1. Liest die gespeicherte mtime für die Datei aus der `files`-Tabelle.
2. Ruft `stat()` für die Datei auf der Festplatte auf.
3. Wenn die mtime auf der Festplatte neuer ist, erwirbt sie die `structure.lock` und parst die Datei sofort neu.

Das bedeutet, dass ein Assistent, der eine Datei bearbeitet und sie sofort abfragt, immer die aktuelle Version sieht, ohne auf eine geplante Neuindizierung zu warten. (JIT-Veraltetheit behandelt Dateien, die dem Index bereits bekannt sind; eine brandneue Datei oder ein brandneues Symbol benötigt weiterhin `mast_reindex` oder die nächste geplante/überwachte Neuindizierung, um auffindbar zu sein.)

### Startleiter

`mast serve` beginnt über eine vierschrittige Leiter in unter 1 Sekunde, MCP-Verbindungen anzunehmen:

GXP44

Alle Werkzeuge sind bereit, sobald Schritt 3 abgeschlossen ist — es gibt kein Startfenster mit reduzierter Funktionalität. Wenn ein vorgefertigter Seed-Index unter `/opt/mast-seed` verfügbar ist, wird er in Schritt 1 in das Zustandsverzeichnis kopiert — die Hintergrund-Neuindizierung in Schritt 4 muss dann nur noch Dateien verarbeiten, die seit der Erstellung des Seeds geändert wurden.

### Nebenläufigkeitsmodell

Eine Advisory-Lock koordiniert gleichzeitige Schreiber:

* **`structure.lock`** — wird von `runIndex` und JIT-Neu-Parses gehalten. Verhindert, dass zwei Schreiber den SQLite-Graphen gleichzeitig ändern.

Die Sperre verwendet `proper-lockfile` (POSIX-Advisory-Locks über eine `.lock`-Markierungsdatei). Ein 10-Sekunden-Timeout für veraltete Sperren verhindert, dass ein abgestürzter Prozess das System auf unbestimmte Zeit blockiert. Lesewerkzeuge erwerben nie eine Schreibsperre — sie können während einer gleichzeitigen Neuindizierung einen kurzzeitig inkonsistenten Zustand sehen und geben in diesem Fall `file_busy_returning_stale_cache: true` zurück.

### Speicherlayout

GXP45

***

## Token-Effizienz

Jeder Werkzeugaufruf zeichnet seine Token-Anzahl asynchron in `metrics` auf. Der Datensatz umfasst:

* `tokens_returned` — tatsächliche Token in der Antwort (Anthropic CL100k-Tokenizer)
* `tokens_full_file_upper_bound` — was ein naives vollständiges Dateilesen gekostet hätte (wenn berechenbar)
* `duration_ms`, `session_id` und `status`

`metrics_daily` fasst diese nach `(day, tool_name)` zusammen, mit einem laufenden Durchschnitt für die Dauer und laufenden Summen für die Token-Anzahlen. Das Rollup-Upsert verwendet eine inkrementelle Durchschnittsformel, um nicht alle Rohzeilen auf unbestimmte Zeit zu speichern:

GXP46

Verwenden Sie `mast metrics --since 7d` für eine menschenlesbare Tabelle oder `mast_efficiency` innerhalb einer MCP-Sitzung für eine maschinenlesbare JSON-Zusammenfassung mit einer `counterfactual`-Erzählung.

***

## Verlauf

MAST fusionierte ursprünglich BM25 mit einem Vektor-Einbettungs-Suchzweig (LanceDB + ein lokales ONNX-Einbettungsmodell). Die Messung unterstützte dessen Beibehaltung nicht: Der Vektorspeicher wurde am 2026-08-06 gemäß der M2-Entscheidung entfernt (siehe [ADR 003](adr/003-2026-08-04-vector-store-deletion.md)). Das System vor der Löschung — einschließlich der Einbettungspipeline und der Bewertungsinstrumente, die es gemessen haben — ist unter dem Git-Tag `mast-pre-vector-delete` für alle erhalten, die diese Beweise erneut ausführen möchten.