Add find_dead_code MCP tool

[kapillamba4]

Summary

• New MCP tool find_dead_code that flags functions, methods, and classes with no references outside their own body, returning each with a confidence score (0.0-0.99) and human-readable reasons.
• Reuses existing helpers (validate_directory, validate_top_k, ToolLogger, errors.format_error) and matches the response/validation patterns of the other tools.
• Cross-references the indexed symbols and references_ tables; pre-fetches references once and groups by name to avoid an N+1 query pattern.

How it works

• A symbol is a candidate if no reference to its name exists outside [line_start, line_end] of its own definition.
• Confidence is composed from privacy (_foo/__foo), public-API risk, name-share count, kind, file (__init__.py / index.{js,ts} / mod.rs lower it), and decorator detection (best-effort by reading the line above).
• Excludes Python dunders, main, anonymous symbols, file-fallback symbols, and test files (override via include_tests=True).
• Always reports limitations, including the member-access blind spot for JS/TS/Go/Rust/C++/Kotlin, name-share ambiguity, and dynamic-dispatch caveats.

Files changed

• queries.py — find_dead_code plus _is_test_path, _is_excluded_from_dead_code, _score_dead_code_candidate, _has_decorator_above, _source_excerpt.
• server.py — @mcp.tool() find_dead_code(directory, min_confidence=0.5, kinds=None, include_tests=False, top_k=50) with full input validation.
• api_types.py — DeadCodeCandidate and FindDeadCodeResponse TypedDicts; added to ToolResponse union.
• tests/test_dead_code.py — 59 new tests covering helpers, exclusions, scoring, basic detection (dead/alive/recursive/sibling-method), filters (min_confidence/kinds/top_k), response shape, cross-file behavior, server validation, and end-to-end via a pre-populated DB that bypasses embedding-model loading.

Test plan

• Unit tests for each helper (_is_test_path, _is_excluded_from_dead_code, _score_dead_code_candidate, _has_decorator_above, _source_excerpt)
• Behavior tests: dead function flagged, alive function not flagged, recursion still flagged, sibling-method calls keep the method alive
• Exclusion tests: dunders, main, anonymous, file-fallback, test files (default + opt-in)
• Filter tests: min_confidence, kinds, top_k, empty kinds list, sorted-desc output
• Cross-file tests: external ref in another file, shared name across multiple definitions
• Server-tool validation: bad directory, out-of-range min_confidence, invalid kinds, oversized top_k
• End-to-end: calls server.find_dead_code against a pre-populated DB
• Full suite: 70 → 129 tests, all passing; ruff check clean

🤖 Generated with Claude Code