MAST — モノレポAST検索ツール

MASTは、MCPサーバー（AIアシスタント用）またはスタンドアロンCLIとして動作するコード検索エンジンです。TypeScriptおよびJavaScriptのソースファイルを本格的なASTパーサー（tree-sitter）で解析し、結果のシンボルグラフとコードチャンクをSQLiteに格納し、BM25の語彙検索と宣言完全一致ランカーをReciprocal Rank Fusionで融合させたクエリに応答します。

中核となる設計原則は、アシスタントが必要とするコードだけを正確に返すことです。ファイル全体を読むのではなく、クエリに一致する特定の関数、インターフェース、型宣言を返すことで、トークンを節約し、コンテキストのノイズを減らし、AIツールが無関係なコンテンツに埋もれることなく大規模なコードベースをナビゲートできるようにします。

目次

• MASTとは

• 要件

• インストール

• クイックスタート

• AIアシスタントから使う

• アップグレード

• モノレポでのMASTの使い方

• CLIリファレンス

• MCPツールリファレンス

• 設定

• 仕組み

• トークン効率

• 履歴

Related MCP server: codeix

MASTとは何か

AIアシスタントがコードを理解する必要があるとき、素朴なアプローチはファイル全体を読むことです。これはトークンを無駄にし（200行のファイルの大半は質問に無関係）、コンテキストウィンドウを膨らませ、モデルに毎回シグナルとノイズの選別を強いることになります。

MASTは異なるアプローチを取ります：

• ASTレベルのチャンク化 — すべての関数、クラス、インターフェース、型エイリアスがそれぞれ独立したチャンクになります。アシスタントは、それが存在するファイルではなく、必要な正確な宣言を取得します。

• ランク付き検索 — BM25（FTS5）がキーワードと識別子のクエリを処理し、宣言完全一致ランカー（「ランカーD」）がBM25のトライグラムトークナイザーが一貫してランク付けできない正確なシンボル名クエリを捕捉します。両者は相互変換ランク融合（Reciprocal Rank Fusion）で融合され、両方のランカーが一致したチャンクは、片方だけが見つけたチャンクよりも上位にランク付けされます。

• 構造クエリ — 「この関数を呼び出しているのは誰？」「このインターフェースを実装しているのは何？」「このファイルは何をインポートしているか？」は、ソースをgrepするのではなく、事前に構築されたシンボルグラフから回答されます。回答は即座で、構造的に正しいものです。

• JITの陳腐化検出 — 読み取りのたびに、MASTはディスク上のファイルが最後にインデックスされてから変更されたかどうかをチェックします。変更されていれば、結果が返される前にファイルがバックグラウンドで透過的に再解析されます。インデックスがアシスタントに知られずに古くなることはありません。

• トークン会計 — すべてのツール応答には、返されたトークン数と、反実仮想的な「ファイル全体を素朴に読んだ場合のコスト」を含む_statsが含まれ、時間の経過に伴う効率の具体的な尺度が得られます。

要件

• Node.js ≥ 22（このリポジトリは.nvmrcで開発対象のバージョンを固定しています）

• C++ツールチェーン — 2つのネイティブモジュール（better-sqlite3、tree-sitter）用。 プリビルドバイナリはほとんどのプラットフォームをカバーしています。Node ABIに一致するものがない場合、node-gypがソースからビルドし、以下が必要です：

  • macOS — xcode-select --install

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

  • Windows — Visual Studio Build Toolsから「Desktop development with C++」ワークロードをインストール

サービスもAPIキーも不要で、クエリ時にネットワークも不要です。すべてローカルのSQLiteです。

インストール

インデックスしたいプロジェクトの開発依存関係として — 推奨。バージョンが他のすべてと一緒にロックファイルに固定されるためです：

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

または、複数のチェックアウトで1つのmastを使いたい場合はグローバルに：

pnpm add -g @spikedpunch/mast

確認：

mast --version

クイックスタート

何もない状態から検索可能なインデックスまで3つのコマンド：

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は、ファイルではなく一致する宣言を出力します：

$ 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

最後の行はスローガンではなく実際の会計です。すべての応答には、返された内容と参照ファイル全体を読む場合の上限を示す_statsが含まれます。小さなファイルでは節約はマイナスになることがあり、MASTはそれを勝利として丸めるのではなく、そのように明示します。

MASTが完全に保証できない回答は、結果を表示するのと同じ画面にその旨を表示します。インデックス後に編集されたファイルは、その下に表示される本文が古いものであるため、マークされます：

! 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]

そして空の回答は、空になる理由の2つを区別します：

$ 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.

--type、--language、--exported、--file、-nで絞り込みます：

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

作業中に最新の状態を保つか、gitフックに任せます：

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

ビルドに同梱されているすべてのものはオフラインで読めるため、自分のバージョンに一致するドキュメントを探す必要はありません：

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

AIアシスタントから使う

MASTはstdio上でMCPを話します。mast serveがサーバーコマンドです。以下の設定は、各ツールが設定ファイルをどこに置くかだけが異なります。

MASTをグローバルではなく開発依存としてインストールした場合は、これらのいずれでもmastをnpx @spikedpunch/mast（またはpnpm exec mast）に置き換えてください。

Claude Code

claude mcp add mast -- mast serve

--scope projectを追加して.mcp.jsonをリポジトリに書き込み、チームがチェックアウトから取得できるようにします。

Claude Desktop

macOSでは~/Library/Application Support/Claude/claude_desktop_config.json、Windowsでは%APPDATA%\Claude\claude_desktop_config.json：

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

Claude Desktopはプロジェクトディレクトリで実行されないため、MAST_STATE_DIRは絶対パスである必要があります。以下のCLIとエディタの統合は、作業ディレクトリからそれを推測します。

Cursor

プロジェクト内の.cursor/mcp.json、またはグローバルに~/.cursor/mcp.json：

{
  "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"] } }
  }
}

その他のMCPクライアント

プロジェクトルートからstdioを介してmast serveを実行します。11個の読み取りツールを宣伝し、serve以外の引数は必要ありません。

アシスタントに使い方を伝える

サーバーを登録するとモデルにツールが提供されますが、いつそれらを使うべきか、フラグ付きの回答をどう読むかは伝わりません。mast skillはそのために書かれた指示を出力します — システムプロンプト、CLAUDE.md、.cursorrules、またはスキルファイルに貼り付けてください：

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

--installは既に存在するファイル — CLAUDE.md、AGENTS.md、.cursorrules、.windsurfrules、.github/copilot-instructions.md — にのみ書き込み、マークされたブロック内に書き込むため、アップグレード後に再実行すると、2つ目を追加する代わりに前のコピーを置き換えます。単独で実行されることはなく、既に保持している設定ファイルを作成することもありません。

アップグレード

mast upgrade

これは新しいリリースをチェックし、あなたがインストールした方法の正確なコマンドを出力します — その場でアップグレードはしません。CLIはグローバルインストールと開発依存を確実に区別できないため、間違った推測をするとリポジトリで間違ったコマンドを実行することになるからです。

さらに重要なのは、パッケージマネージャーができないことを伝えることです：アップグレードがインデックススキーマを変更するかどうか。変更する場合、MASTはインデックスを破棄し、次のserveまたはindexで再構築します。再構築できないものは失われません — インデックスは派生状態です — ただし、大規模なモノレポでは数分かかり、説明のない停止として発見されるよりも事前に知っておく方が良いです。

モノレポでのMASTの使い方

リポジトリルートに1つのインデックスが通常は正しいです。パッケージ間のインポートが解決されるため、mast_callersは兄弟パッケージ内の呼び出し元を見つけます — これはパッケージごとに1つのインデックスではなくモノレポツールを使う理由です。

インデックスされるもの。 .ts、.tsx、.js、.jsx、.mdから、node_modules、dist、build、coverage、.next、.turbo、.mast、テストファイルを除いたもの。mast initで--extensionsと--excludeで上書きするか、.mast/config.jsonを編集します。

他の言語はインデックスされず、これは重要です。 MASTはTypeScriptとJavaScriptのみを解析します。Python、Go、Java、Rustで定義されたシンボルはインデックスに存在せず、リポジトリに存在しないのと同じように見えます。空の結果は「MASTは見つけられなかった」として扱い、「存在しない」とは決して扱わないでください — mast skillもモデルにそう伝えます。

.mast/を.gitignoreに追加します。 派生状態であり、大きく、マシン固有です。

カスタムインデックス場所は実行間で記憶されません。 --state-dirは渡した1つのコマンドにのみ適用されます。パス設定は永続化された設定から読み戻されることは意図的にありません — 以前の実行（または以前のコンテナ）が書いた絶対パスは、存在しなくなった場所、あるいは別のプロジェクトに属する場所を解決する可能性があります。カスタム場所を固定するには、ソース管理または環境に置きます：

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

export MAST_STATE_DIR=/absolute/path/to/index

解決順序は--state-dir → MAST_STATE_DIR → mast.config.json → .mastです。mast statusは解決したディレクトリを出力し、そこに何もインデックスされていない場合はその旨を明確に伝えます。

スケール。 VS Codeのコールドインデックス — 8,653ファイル、152,969チャンク — は約2分かかり、794 MBの状態ディレクトリを生成します。変更されたファイルの増分再インデックスはミリ秒です。

CLIリファレンス

mast init [path]

プロジェクトのMASTを初期化し、最初のフルインデックスを実行します。

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

理由： 状態ディレクトリ構造を作成し、config.jsonを書き込み、フルパース+シンボル抽出パスを実行します。これを一度実行しておくと、後続の増分実行は変更されたファイルのみを処理します。

mast search <query> [path]

インデックスを検索し、読みやすい結果を出力します。

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

理由： インデックスに実際に何が含まれているかを確認する最速の方法であり、MCPのmast_searchツールと同じコードパスです — ランキングを再実装するのではなく、登録されたハンドラーを介してディスパッチするため、CLIとアシスタントの結果が食い違うことはありません。陳腐化と切り捨てのフラグは結果の上に出力されます。インデックスがビジーだったために空になった空の結果は、その旨を明示します。

スクリプト用には、mast query mast_search '{...}'がバイト同一のMCP出力を提供します。

mast index [path]

インデックスを構築または更新します。

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.

増分の理由： 増分パスは現在のファイルマニフェストを保存されたmtimeと比較します。古いファイル、追加されたファイル、削除されたファイルのみが処理されます — 大規模なコードベースでは、ほとんどの実行でインデックス時間が秒からミリ秒に短縮されます。

mast serve

stdioを介してMCPサーバーを起動します。

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)

サーバーは4段階の起動ラダーを実装しており、大規模プロジェクトでもMCPクライアントが1秒未満で使用可能なサーバーを取得できます。詳細は起動ラダーを参照してください。

mast status [path]

インデックスの健全性を出力します。

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

last_indexed、indexed_files、chunk_count、stale_files、parse_errors、write_errors、index_fresh、freshness_causeを報告します。検索結果が古く見える場合の診断に使用します。

mast metrics [path]

トークン効率のメトリクスを表示します。

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

列揃えのテーブルを出力します：ツール名、呼び出し回数、返されたトークン、平均所要時間、効率比。メトリクスデータベースが無制限に増えないように、定期的に--rollup + --vacuumを使用します。

mast install-hooks [path]

mast index --incrementalを自動的に実行するgit post-commit / post-checkoutフックをインストールし、手動ステップなしでコミットとブランチ切り替えの間インデックスを最新に保ちます。

mast query <tool> [json] [path]

任意のMCP読み取りツールを直接呼び出し、MCPトランスポートとバイト同一の出力を出力します。

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 '{}'

理由： スクリプトとデバッグのためのサーフェスです。mast searchは1つのツールへの読みやすいフロントドアですが、これは11個すべてに到達し、アシスタントが受け取るものとまったく同じものを返します — あなたが見たものとモデルが見たものの不一致は不可能です。存在しないツールを指定すると、存在するツールが一覧表示されます。

mast docs [topic]

インストールされたビルドに同梱されているドキュメント — readme、spec、またはskillを出力します。引数なしで、トピックとそのバージョンを一覧表示します。

理由： 読者が自分のバージョンを調べてから別のバージョンのドキュメントを見つける手順を排除します。mast docsが出力するものは、node_modules内のバイナリが行うものです。

mast skill [path]

MASTの指示をエージェントプロンプト、CLAUDE.md、.cursorrules、またはスキルファイルに貼り付けるために出力します。

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

理由: MCPサーバーを登録するとモデルにツールは与えられますが、判断力は与えられません。いつ検索する代わりに読むのか、コードトークンがクエリ内の散文に勝るのか、そして鮮度や切り詰めのフラグをどう読むのかという判断です。また、空の結果は「MASTが見つけなかった」という意味であり、「存在しない」という意味ではないことをモデルに伝えます。これは検索ツールについて正しく理解すべき最も重要なことです。

mast upgrade [path]

新しいリリースを確認し、インストール方法とそのコストを出力します。

理由: MASTがどのようにインストールされたかを検出し、実行するのではなく対応するコマンドを出力します。CLIはグローバルインストールと開発依存を確実に区別できないためです。また、アップグレードがインデックススキーマを変更するかどうかも報告します。これは次のserveで完全な再インデックスを強制しますが、パッケージマネージャーはそれを教えてくれません。

MCPツールリファレンス

MASTはMCPサーバーに11個のツールを登録します。すべての読み取りツールには_statsブロックが含まれます：

{
  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

インデックス化されたコードベースに対する字句BM25＋宣言完全一致検索。

{
  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
}

戻り値: { results[], suggestions?, _stats }。各結果にはfile_path、start_line、end_line、content、chunk_type、symbol_name、parent_symbol、is_exported、match_score（BM25スコア、負値。ランカーDのみでヒットした場合はnull）、rank、match_snippet、およびメソッドとそのクラスシェルの両方がマッチした場合のオプションのrelatedヒント（高いランクのもののみ返されます）が含まれます。suggestionsはresultsが空の場合のみ存在し、空の場合もあります。これはゼロ件結果の「もしかして」アシストです。

理由: grepとglobは正確な文字列を見つけ、呼び出し側がすでにパターンを知っていることを要求します。mast_searchはReciprocal Rank Fusionで融合された2つのシグナルにわたって関連性でランク付けします：

• BM25（FTS5、トライグラムトークン化） — 汎用の字句ランカー。キーワードクエリとサブトークン/キャメルケースのマッチを処理します。

• ランカーD（宣言完全一致） — チャンク自身のsymbol_name（完全名または最後のドットセグメント、大文字小文字を区別しない）への直接マッチ。BM25のトライグラムスコアリングが過小評価しうる正確なシンボルクエリを捕捉します。declaration_exact_ranker設定キー（デフォルトオン）によって制御され、オフのときmast_searchはBM25のみになります。

両方のランカーが一致するチャンクは、片方だけが見つけたチャンクよりも上位にランクされます。file_patternとlanguageは両方のランカーが引き出すプールを制限するため、スコープ指定された検索がスコープ外のファイルを返すことはありません。file_patternはインデックス時にexclude_patternsを適用するのと同じプリミティブでマッチされるグロブです：*は/をまたがず、**はまたぎ、?は1つの非/文字、マッチは大文字小文字を区別し、その他すべて（.、_、-）はリテラルです。

mast_project_skeleton

ファイルごとにグループ化されたすべてのエクスポートシンボル。オプションでディレクトリにスコープ指定可能。

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

戻り値: { files: [{ file_path, exports: string[] }], _stats }。

理由: コードベースをナビゲートする前に、アシスタントは「ここに何があるのか？」という方向付けを必要とします。すべてのファイルを読んでエクスポートを見つけるのは無駄です。mast_project_skeletonはディレクトリにスコープされたファイル→エクスポート名のマップを1回の呼び出しで返し、アシスタントがファイルを開かずにサブシステムのメンタルモデルを構築できるようにします。

mast_exports

型シグネチャとTSDoc付きの単一ファイルからのすべてのエクスポートシンボル。

{
  file_path: string                   // relative to project root
}

戻り値: { file_path, exports: [{ name, kind, signature, line, doc }], _stats }。

理由: mast_project_skeletonの自然なフォローアップです。アシスタントがどのファイルが関連するかを知ったら、mast_exportsは関数本体なしで完全なシグネチャを与えます。実装のコストを払わずにモジュールの公開サーフェスを理解するのに十分です。

メソッドは意図的に省略されます（親クラスでmast_signatureを介して表面化します）。そのため、結果はモジュールの公開契約に焦点を当てたままになります。

mast_signature

名前付きシンボルの宣言、TSDoc、解決されたパラメータ型コンテキスト。

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

戻り値: SignatureResultの配列。各要素にはsymbol、file_path、line、signature、doc、params、return_type、type_contextが含まれます。

type_contextは自動的に入力されます：シグネチャに現れるユーザー定義のPascalCase型名は、3つの優先順位のルックアップ（最初に同じファイル、次に名前付きインポート、最後にグローバルなエクスポート型フォールバック）を介して自身のシグネチャに解決されます。長いシグネチャは500文字で切り詰められます。つまり、1回のmast_signature呼び出しで、アシスタントは関数の完全な型像を別々のルックアップなしで得られます。

理由: アシスタントがfunction processOrder(order: Order, ctx: RequestContext): Promise<Result>を見たとき、Order、RequestContext、Resultのシグネチャを知ることは関数が何をするかを理解するために不可欠です。さらに3回ツールを呼び出すのではなく、mast_signatureはそれらをインラインで解決します。

mast_callers

指定されたシンボルを誰が呼ぶか。検証済みの呼び出し元（シンボルグラフから）と潜在的なマッチ（全文識別子検索から）に分かれます。

{
  symbol:              string,
  file_path?:          string | null,
  transitive?:         boolean,       // walk the full call chain (default false)
  include_potential?:  boolean        // include identifier_fts matches (default true)
}

戻り値: { verified_callers[], potential_matches[], summary: { verified_count, potential_count, transitive, checker_classified_non_call_site, checker_classified_different_declaration }, _stats }。

理由: リファクタリング前の影響分析には、誰がシンボルに依存しているかを知る必要があります。検証済みの呼び出し元はグラフ解決されます（決定的で、名前衝突による誤検出はありません）。潜在的なマッチは識別子FTSヒットで、呼び出しが静的に解決できなかったものです。誤検出の可能性はありますが、レビューする価値があります。この2つを分離することで、アシスタントは信頼度について推論できます：verified_countが3でpotential_countが0なら、リファクタリングの範囲はよく理解されています。potential_countが15なら、不確実性が大きくなります。mast index --checkerを実行すると、一部の潜在的なマッチが検証済みエッジにアップグレードされるか（または非呼び出しサイトのノイズが削除されます）— checker_classified_*カウントはその数を報告し、チェッカーパスが一度も実行されていない場合は0です。

mast_dependencies

ファイルに対して記録されたすべてのインポート。

{
  file_path: string
}

戻り値: { file_path, imports: [{ module, symbols[], is_external, resolved_path? }], _stats }。

理由: ファイルの依存関係サーフェスを理解することは、それが何をするかを推論する最初のステップです。外部インポート（resolved_pathなし）はフラグが立てられ、アシスタントが解決境界を知ることができます。内部インポートには解決されたパスが含まれるため、呼び出し側はチェーンを辿れます。

mast_implementors

指定されたインターフェースを実装するすべての具象クラスと、そのメソッドリスト。

{
  interface_name: string
}

戻り値: { results: [{ class_name, file_path, line, methods[] }], _stats }。

理由: 依存性注入コードベースでは、interface_name → implementorsが「ここで実際に何が実行されるのか？」への答えです。implements InterfaceNameをgrepする代わりに、MASTはインデックス時に明示的なIMPLEMENTSエッジをグラフに格納し、ルックアップを即時的かつ構造的に正しくします。

mast_rename_impact

シンボル名を変更するための複合リファクタチェックリスト：宣言サイト、検証済み呼び出し元、潜在的なマッチ、バレル再エクスポートを1回の呼び出しで。

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

戻り値: { symbol, declaration_sites[], verified_callers[], potential_matches[], barrel_exports[], summary: { declaration_count, verified_count, potential_count, barrel_count, checklist, checker_classified_non_call_site, checker_classified_different_declaration }, _stats }。

理由: 名前変更は呼び出しサイト以上に影響します。バレル再エクスポート（export { Foo } from './foo'、エイリアス付きの場合もある）も更新が必要で、単純な呼び出し元検索では見落としがちです。mast_rename_impactはmast_callersの仕組みをバレルエクスポート検出と組み合わせ、アシスタントが3つの別々のクエリではなく1つのチェックリストを得られるようにします。

mast_reindex

MCPセッション内から同期再インデックスをトリガーします。

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

戻り値: { files_indexed, files_skipped, chunks_added, chunks_removed, parse_errors, write_errors, duration_ms }。

理由: 長時間実行される編集セッションは鮮度の低下を蓄積します。新しいシンボルやファイルはインデックス化されるまでmast_searchで見つかりません（JIT鮮度処理はすでにインデックス化されたファイルの行座標を読み取り時に正しく保ちますが、真新しいファイルやシンボルを発見することはできません）。mast_reindexにより、アシスタントはMCPセッションを離れることなく、たとえば大規模なリファクタリングの後などに、オンデマンドでインデックスを更新できます。fullフラグは、インクリメンタル状態が破損している疑いがある場合に利用できます。

mast_status

インデックスの健全性スナップショット。

// no inputs

戻り値: { state_dir, last_indexed, indexed_files, chunk_count, stale_files, parse_errors, write_errors, index_fresh, freshness_cause, seed_commit? }。

index_freshはstale_files = 0かつインデックスが少なくとも1回実行されている場合のみtrueです。freshness_causeは、staleファイルが残っている場合は"phase1_stale"、新鮮な場合はnullです。stale_filesは、変更されたファイル、ディスク上に存在するがインデックスにまったくないファイル、およびディスクから消えたインデックス化済みファイルを数えます。これはmast statusが同じプロデューサーから報告する数と同じです。

理由: 正確なコードナビゲーションに依存する長いエージェント的ワークフローの前に、アシスタントはmast_statusを呼び出してインデックスが新鮮であることを確認したり、新鮮でない場合はstaleファイルの数をユーザーに提示したりできます。

mast_efficiency

現在のセッションまたは全期間のトークン節約レポート。

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

戻り値: { scope, window_started_at, tokens_returned, tokens_full_file_upper_bound, efficiency_ratio, calls_total, calls_by_tool, tokenizer, counterfactual }。

counterfactualフィールドは人間が読める文です：「素朴な全ファイル読み取りでは約14,200トークンかかったでしょう。約11,400トークン（80.3%）を節約しました。」

理由: トークン効率はMASTが存在するまさにその理由ですが、測定がなければ単なる主張にすぎません。すべてのツール呼び出しは、返されたトークンをmetricsに非同期で記録します（ファイア・アンド・フォーゲット、1ms未満）。mast_efficiencyはそれらの記録を集約し、正確なコードナビゲーションの価値を具体的かつ監査可能にします。

設定

MASTはプロジェクトルートのmast.config.json、環境変数、またはCLIフラグから設定を読み取ります。優先順位（高い順から低い順）：CLIフラグ → MAST_STATE_DIR環境変数 → mast.config.json → 組み込みデフォルト。

mast.config.json の例:

{
  "state_dir": ".mast",
  "exclude_patterns": ["node_modules/**", "dist/**", "**/*.test.ts"],
  "declaration_exact_ranker": true,
  "context_lines": 5
}

MAST_STATE_DIR — mast.config.json を変更せずに状態ディレクトリを上書きする。プロジェクトルートが読み取り専用である CI や Docker 環境で有用。

動作の仕組み

インデックス作成

runIndex は fast-glob でプロジェクトを走査し、mtime ベースのマニフェストを計算して、保存済みマニフェストと差分を比較し、古いファイル・追加されたファイル・削除されたファイルを特定する。処理が必要な各ファイルについて:

1. パース — tree-sitter がファイルを具象構文木（CST）にパースする。.ts と .tsx には TypeScript 文法、.js と .jsx には JavaScript 文法が使用される。Markdown ファイルは tree-sitter ではパースせず、見出し（markdown_heading_depth）でチャンク分割される。

2. チャンク化 — 抽出器が CST を型付きチャンクに分解する: function、class_shell（クラス宣言とメンバーシグネチャ。本体は含まない）、method（個々のメソッド）、interface、type、export、block、doc（Markdown セクション）。クラスは常に分解され、単一のメソッドを検索してもクラス全体が返らないようにする。

3. サブチャンク化 — chunk_split_threshold 行を超える宣言は、単一のチャンクが自己完結した検索結果として大きくなりすぎないよう、重複するセグメントに分割される。

4. シンボルグラフ — シンボル、インポート、エッジ（IMPLEMENTS、PARENT_OF、POTENTIAL_CALL）が SQLite に書き込まれる。2 パス書き込み戦略（最初に全ファイル、次にエッジ）により、エッジは同じ実行で後からパースされるファイルに定義されているシンボルも参照できる。

5. FTS — チャンクコンテンツは trigram トークナイザー付きの FTS5 仮想テーブルに書き込まれ、サブトークン検索とキャメルケース検索が可能になる。unicode61 トークナイザーを使用する identifier_fts テーブルは、mast_callers の潜在的な一致のための完全識別子ルックアップを処理する。

インデックス作成は単一フェーズである — チャンク/グラフ/FTS はすべて 1 回の runIndex パスで一緒に更新される。別個の埋め込みステップは存在しない。

ランク付き検索（BM25 + RRF によるランカー D）

クエリは 2 つのランカーを通過する:

BM25（FTS5）: クエリは trigram トークナイザーを使用して、SQLite 組み込みの BM25 ランキングで chunk_fts に対してマッチングされる。ファイルパターンと言語フィルターは、files テーブルに対する SQL 述語としてこのクエリにプッシュされる（FTS MATCH 述語ではない。SQLite FTS5 の UNINDEXED カラムに対する LIKE は MATCH と併用すると信頼性が低いため）。SQLite の規約では BM25 スコアは負の値であり、より負の値ほど強い一致を意味する。mast_search の match_score はその符号を保持する。

ランカー D（宣言の完全一致）: chunks.symbol_name に対する直接の SQL 述語 — 完全名一致または最後のドットセグメント一致、大文字小文字を区別しない、決定的順序。declaration_exact_ranker 設定キー（デフォルトはオン）で制御される。

RRF 融合: 2 つのランク付きリストは Reciprocal Rank Fusion で結合される:

score(chunk) = Σ 1 / (k + rank(chunk))

デフォルトの k = 60 で。両方のリストでランク 1 に現れるチャンクは、片方のリストにしか現れないチャンクの 2 倍のスコアになる。片方のリストにしか現れないチャンクも十分にスコアが高く、どちらのシグナルも支配的にはならない。

JIT 鮮度チェック

すべての読み取りツール（search、exports、signature、callers、dependencies、implementors）は、結果を返す前に jitRefreshFile を呼び出す。この関数は:

1. files テーブルからファイルの保存済み mtime を読み取る。

2. ディスク上のファイルに対して stat() を呼び出す。

3. ディスクの mtime が新しい場合、structure.lock を取得し、ファイルを即座に再パースする。

つまり、アシスタントがファイルを編集してすぐにクエリを実行しても、スケジュールされた再インデックスを待たずに常に最新バージョンを確認できる。（JIT 鮮度チェックはインデックスに既知のファイルを処理する。まったく新しいファイルやシンボルは、発見可能になるために依然として mast_reindex または次のスケジュール/ウォッチ再インデックスが必要である。）

起動ラダー

mast serve は 4 段階のラダーにより 1 秒未満で MCP 接続の受け入れを開始する:

Step 1  Bootstrap state directory; copy Docker seed layer if present;
        best-effort remove orphaned pre-vector-store state              < 500ms
Step 2  Schema version check; open SQLite                               < 1s
Step 3  Register all 11 MCP tools; open stdio transport                 < 500ms
Step 4  Background incremental reindex                                  async

ステップ 3 が完了するとすぐにすべてのツールがサービス提供可能になり、機能が制限された起動ウィンドウは存在しない。ビルド済みシードインデックスが /opt/mast-seed にある場合、ステップ 1 で状態ディレクトリにコピーされる — ステップ 4 のバックグラウンド再インデックスは、シードがビルドされてから変更されたファイルのみを処理すればよい。

並行性モデル

1 つのアドバイザリーロックが並行ライターを調整する:

• structure.lock — runIndex と JIT 再パースによって保持される。2 つのライターが同時に SQLite グラフを変更するのを防ぐ。

ロックは proper-lockfile（.lock マーカーファイルによる POSIX アドバイザリーロック）を使用する。10 秒のスケイルロックタイムアウトにより、クラッシュしたプロセスがシステムを無期限にブロックするのを防ぐ。読み取りツールは書き込みロックを取得しない — 並行再インデックス中に一時的に不整合な状態を確認する可能性があり、その場合は file_busy_returning_stale_cache: true を返す。

ストレージレイアウト

.mast/
  graph.db              SQLite — symbols, edges, imports, chunks, FTS5 tables, metrics
  file_manifest.json    mtime snapshot from the last index run
  index.json            schema version, file count, chunk count, last_indexed
  config.json           resolved config written at init/serve time
  structure              lock marker (proper-lockfile target)

トークン効率

すべてのツール呼び出しは、そのトークン数を非同期で metrics に記録する。レコードには以下が含まれる:

• tokens_returned — レスポンス内の実際のトークン数（Anthropic CL100k トークナイザー）

• tokens_full_file_upper_bound — 単純な全ファイル読み取りにかかったであろうコスト（計算可能な場合）

• duration_ms、session_id、status

metrics_daily はこれらを (day, tool_name) ごとに集計し、期間の移動平均とトークン数の累計を保持する。ロールアップの upsert は増分平均式を使用して、生の行を無期限に保存しないようにする:

avg_duration_ms = (old_avg * old_n + new_val) / (old_n + 1)

人間が読めるテーブルには mast metrics --since 7d を使用し、MCP セッション内からは mast_efficiency を使用して、counterfactual のナラティブ付きの機械可読な JSON サマリーを取得する。

履歴

MAST は当初、BM25 とベクトル埋め込み検索レッグ（LanceDB + ローカル ONNX 埋め込みモデル）を融合していた。測定結果はそれを維持することを支持しなかった: ベクトルストアは M2 決定に基づき 2026-08-06 に削除された（ADR 003 を参照）。削除前のシステム — 埋め込みパイプラインとそれを測定した評価機器を含む — は、その証拠を再実行したい人のために git タグ mast-pre-vector-delete に保存されている。