vs-search

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.