find-references

Precise, AST-aware find-references / impact analysis as an MCP server. Answers "who uses this symbol, and what breaks if I change it?" — using tree-sitter instead of grep, so it ignores comments, strings, and substrings, and tells you how each hit is used.

find_references("validateToken")
→ { total: 7,
    by_kind: { definition: 1, call: 4, import: 2 },
    results: [ { file, line, kind, text }, … ] }

Why not grep?

grep validateToken also matches the word in a comment, inside a string, and as a substring of validateTokenCache. This walks the real syntax tree: only actual identifier nodes count, and each is classified as definition / call / import / type / reference.

Tools

• find_references(symbol, kind?, path?, limit?) — all references, classified, with the source line.
• find_definition(symbol) — just the declaration(s).
• reindex() — rebuild after files change.
• index_status() — files / distinct symbols / occurrences.

How it works

On first query it walks the project, parses each file with web-tree-sitter, and buckets every identifier occurrence by name (in memory) with a heuristic kind. Subsequent queries are instant; call reindex after edits.

Languages: TypeScript/TSX, JavaScript/JSX, Python, Go, Rust, Java, Ruby, C/C++, C#.

Setup

npm install
npm test

Register with an MCP client:

claude mcp add find-references -e FIND_REFERENCES_ROOT=/path/to/project -- node /abs/path/find-references/dist/server.js

Honest limits

• Kind classification is heuristic (parent-context based) — the precision (no comments/strings) is exact, but a call vs reference label can be off in edge cases.
• Name-based, not scope-resolved — two different foos in different scopes are bucketed together (it's a fast reference finder, not a full type resolver).
• In-memory index — fine into hundreds of thousands of occurrences; very large monorepos would want an on-disk index.

Version pin

web-tree-sitter is pinned to 0.22.6 to match the prebuilt grammars in [email protected] (newer web-tree-sitter changed its WASM ABI). Bump both together or neither.