vs-token-safer search routing

vs-token-safer search routing

Code search runs through an OFFICIAL language server's index (clangd for C++, a Roslyn-based LSP for C#) and the result is token-capped to a compact file:line list — no source bodies. No IDE needs to be open; the engine is spawned headlessly. Karpathy-style rules: do the listed thing, do not improvise.

Tools (MCP server name: vs-search)

• Symbol / class / function / type / variable → search_symbol (args: q, projectPath, backend, maxResults). Never grep/rg for this.
• References / usages of a symbol → find_references (args: symbol NAME, or path+line+character — 0-based — includeDeclaration). Semantic, not a text match. direction=callers/callees + depth → a multi-hop call hierarchy (transitive callers = blast radius before an edit / callees) via LSP callHierarchy, instead of flat references.
• Definition of a symbol → goto_definition (args: path, line, character — 0-based). The kind arg picks WHICH: definition (default) · type_definition (the type of an expression) · implementation (concrete impls of an interface/abstract/virtual — "who implements this?") · declaration. For every usage (not the definition) use find_references instead.
• Type / signature at a position → hover (args: path, line, character).
• Outline a file (its classes/functions) → document_symbols (args: path; scope="directory" → a signatures-only skeleton of every code file under a dir, to grasp a module's shape without reading each file).
• Read ONE declaration's source (not the whole file) → read_symbol (args: symbol, optional path/line, signatureOnly). The read-side twin of the edit tools — name a symbol, get just its body. Prefer over the built-in Read when you only need one declaration.
• Errors / warnings → diagnostics (args: path, or scope="directory" to scan the project). Token-capped file:line:col severity: message, sorted error→hint with a count summary — read this instead of the raw build/compiler output.
• Rename a symbol project-wide → rename (args: path, line, character, newName, apply). Semantic (every reference), not a sed. Preview by default; apply=true writes the edits.
• Add / replace / delete a WHOLE declaration → edit it by NAME, don't Read-the-file-then-Edit:
  • Replace a function/method/class body (signature included) → replace_symbol_body (args: symbol, body, optional path/line, apply).
  • Add a declaration next to one → insert_symbol (args: symbol, text, position = after default / before, apply).
  • Remove a declaration → safe_delete (args: symbol, force, apply). Refuses while it's still referenced unless force=true.
  • The outline supplies the exact span, so you skip reading the whole file into context. Preview by default; apply=true writes. Use the built-in Edit for a sub-declaration tweak (a few lines inside a body); use these when the unit is the whole declaration.
  • Perforce: an apply=true write auto-runs p4 edit on a read-only file first (symbol edits write via the server, so a built-in Edit/Write p4 hook never sees them). Read-only-gated, so a git repo never calls p4; disable with VTS_P4_EDIT=0.
• Raw text / string / comment / config key (the symbol index can't answer) → search_text (args: q, projectPath). Token-capped; the sanctioned grep replacement.
• File by name (substring or glob) → find_files (args: q, projectPath). Replaces find -name.
• Admin/meta (rarely needed reflexively) → vts_admin with an op: config/setup (settings), savings/savings_reset (token ledger), warmup (pre-build the index), discover (find searches that bypassed vts), gen_compile_db (UE clangd DB), git/p4 (read-only VCS, output compacted). Put the op's args in params, e.g. vts_admin {op:"git", params:{argv:["status"]}}. (CLI keeps the bare subcommands: vts setup, vts git, …)
• Log file (.log/.jsonl, or a Logs/ dir) → NOT a vs-search tool. The language-server index covers source, not logs — use gamedev-log (/gamedev-log-analyzer:logs). vts-search results aimed at a log carry a one-line pointer there.

Delegate a whole "where is X / what calls Y / find file W" lookup to the code-locator subagent — it runs the searches in its own context and returns just the file:line table, so the matches never land in yours.

CLI equivalent (no MCP needed): vts symbol --q <name> --projectPath <root>, vts references --path <file> --line N --character N, vts definition --path <file> --line N --character N [--kind implementation], vts hover …, vts symbols --path <file>, vts diagnostics --path <file>, vts text --q <pattern>, vts files --q <glob>.

Backends & projectPath

• Backend auto-detects from the project root (strongest build-artifact first): compile_commands.json (or a .uproject) → clangd; a .sln/.csproj → roslyn; a tsconfig/jsconfig/package.json → typescript (tsserver); a pyproject.toml/*.py → pyright. Override with backend=clangd|roslyn|typescript|pyright or env VTS_BACKEND when a root carries more than one.
• Set the root via projectPath or env VTS_PROJECT_PATH (default: cwd).
• clangd needs compile_commands.json. Unreal: generate via UBT -mode=GenerateClangDatabase; CMake: -DCMAKE_EXPORT_COMPILE_COMMANDS=ON. Without it, clangd indexes nothing useful — tell the user to generate it.
• roslyn defaults to the csharp-ls dotnet tool; point VTS_ROSLYN_CMD/VTS_ROSLYN_ARGS at Microsoft.CodeAnalysis.LanguageServer for the exact Visual Studio engine. Currently best-effort.
• typescript (JS/TS) and pyright (Python) ship as plugin deps and auto-install — no setup. vts launches the bundled copy with node. Override via VTS_TS_CMD/VTS_PY_CMD.

Truncated results

Symbol/reference lists are capped at maxResults (default 60). A trailing … N more means the set was truncated — raise maxResults or narrow the query. For refactors/renames that must touch every call site, raise the cap (or narrow with a more specific symbol) before acting; don't act on a partial set and claim it's complete.

Why

• The language-server index resolves symbols semantically (no full-tree scan) and the result is token-capped to file:line — far less raw source reaches the model than grep-and-paste.
• grep over a large UE/.NET codebase floods context with thousands of lines; this caps the response.
• Caveat: on Unreal C++, search_symbol quality depends on compile_commands.json being current. Verify the result; regenerate the compile DB if a known symbol is missing.

Fallback

If a vs-search tool errors (engine missing/failed to spawn): clangd not installed → install LLVM clangd; roslyn not installed → dotnet tool install --global csharp-ls; typescript/pyright not found → re-run the session so the bundled deps reinstall (or set VTS_TS_CMD/VTS_PY_CMD). Until the engine works, code-grep is blocked by the hook — the user can set VTS_ENFORCE=0 to allow grep as a fallback. Do not loop on blocked grep; surface the fix and move on.