{"_id":"@ahmedshaikh/find-references-mcp","name":"@ahmedshaikh/find-references-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ahmedshaikh/find-references-mcp","version":"0.1.0","type":"module","description":"Precise, AST-aware find-references / impact analysis as an MCP server — tree-sitter, not grep, so it ignores comments and strings and classifies each hit (definition / call / import / type / reference).","bin":{"find-references":"dist/server.js"},"engines":{"node":">=18"},"scripts":{"serve":"tsx src/server.ts","build":"tsc","test":"node --import tsx --test --test-force-exit test/*.test.ts","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","ignore":"^5.3.0","tree-sitter-wasms":"^0.1.13","web-tree-sitter":"^0.22.6","zod":"^3.23.8"},"devDependencies":{"@types/node":"^20.11.0","tsx":"^4.7.0","typescript":"^5.4.0"},"license":"MIT","author":{"name":"ahmedshaikh"},"keywords":["mcp","model-context-protocol","claude","agent","ai","references","tree-sitter","symbols","code-navigation"],"repository":{"type":"git","url":"git+https://github.com/RaziStuff/find-references-mcp.git"},"homepage":"https://github.com/RaziStuff/find-references-mcp#readme","bugs":{"url":"https://github.com/RaziStuff/find-references-mcp/issues"},"publishConfig":{"access":"public"},"gitHead":"65a2be7ce43026c1830cfa16d0dfa6d887c998d5","_id":"@ahmedshaikh/find-references-mcp@0.1.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-BJaWVqVcbum5PzAxtk39tz/xyiOFpJagrlxFsY3UJgj8+LZtAur2VfWeh/R2txbxhFVoUm7q3V6Y6YZWnWMoOw==","shasum":"0430f6f79b6d66fa8eff558bc3352c0f0ad41e94","tarball":"https://registry.npmjs.org/@ahmedshaikh/find-references-mcp/-/find-references-mcp-0.1.0.tgz","fileCount":7,"unpackedSize":15204,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDSGf0eKQUV34tCfgX4r6VRMhZGAQtnPMK9xcZFZc2m5AiEAvlt3CGiCWlhS3oaZNxP7HHbMk7tlzETjTHXt6UF2rmM="}]},"_npmUser":{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"},"directories":{},"maintainers":[{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/find-references-mcp_0.1.0_1782701020668_0.0802489429895199"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-29T02:43:40.552Z","0.1.0":"2026-06-29T02:43:40.795Z","modified":"2026-06-29T02:43:41.014Z"},"maintainers":[{"name":"ahmedshaikh","email":"ahmed@shaikh1.com"}],"description":"Precise, AST-aware find-references / impact analysis as an MCP server — tree-sitter, not grep, so it ignores comments and strings and classifies each hit (definition / call / import / type / reference).","homepage":"https://github.com/RaziStuff/find-references-mcp#readme","keywords":["mcp","model-context-protocol","claude","agent","ai","references","tree-sitter","symbols","code-navigation"],"repository":{"type":"git","url":"git+https://github.com/RaziStuff/find-references-mcp.git"},"author":{"name":"ahmedshaikh"},"bugs":{"url":"https://github.com/RaziStuff/find-references-mcp/issues"},"license":"MIT","readme":"# find-references\n\nPrecise, **AST-aware find-references / impact analysis** as an MCP server. Answers\n*\"who uses this symbol, and what breaks if I change it?\"* — using tree-sitter\ninstead of grep, so it ignores comments, strings, and substrings, and tells you\n*how* each hit is used.\n\n```\nfind_references(\"validateToken\")\n→ { total: 7,\n    by_kind: { definition: 1, call: 4, import: 2 },\n    results: [ { file, line, kind, text }, … ] }\n```\n\n## Why not grep?\n\n`grep validateToken` also matches the word in a comment, inside a string, and as\na substring of `validateTokenCache`. This walks the real syntax tree: only actual\nidentifier nodes count, and each is classified as **definition / call / import /\ntype / reference**.\n\n## Tools\n\n- **`find_references(symbol, kind?, path?, limit?)`** — all references, classified, with the source line.\n- **`find_definition(symbol)`** — just the declaration(s).\n- **`reindex()`** — rebuild after files change.\n- **`index_status()`** — files / distinct symbols / occurrences.\n\n## How it works\n\nOn first query it walks the project, parses each file with `web-tree-sitter`, and\nbuckets every identifier occurrence by name (in memory) with a heuristic kind.\nSubsequent queries are instant; call `reindex` after edits.\n\nLanguages: TypeScript/TSX, JavaScript/JSX, Python, Go, Rust, Java, Ruby, C/C++, C#.\n\n## Setup\n\n```bash\nnpm install\nnpm test\n```\n\nRegister with an MCP client:\n\n```bash\nclaude mcp add find-references -e FIND_REFERENCES_ROOT=/path/to/project -- node /abs/path/find-references/dist/server.js\n```\n\n## Honest limits\n\n- **Kind classification is heuristic** (parent-context based) — the *precision*\n  (no comments/strings) is exact, but a `call` vs `reference` label can be off in\n  edge cases.\n- **Name-based, not scope-resolved** — two different `foo`s in different scopes\n  are bucketed together (it's a fast reference finder, not a full type resolver).\n- **In-memory index** — fine into hundreds of thousands of occurrences; very large\n  monorepos would want an on-disk index.\n\n## Version pin\n\n`web-tree-sitter` is pinned to **0.22.6** to match the prebuilt grammars in\n`tree-sitter-wasms@0.1.13` (newer web-tree-sitter changed its WASM ABI). Bump both\ntogether or neither.\n","readmeFilename":"README.md","_rev":"1-4ea6f5982fd348d6fbbbe521768bf109"}