refactor: per-tool MCP registry — eliminate tools[] + case-switch conflicts

[mschreib28]

Reviewers: for a 5-minute review path that surfaces only what to verify, see the review checklist comment below. The original description is preserved here for full technical detail.\n\n---\n\n## Summary\n\nToday every PR adding an MCP tool conflicts on the same two shared lists in src/mcp/tools.ts: the tools[] array (the list_tools surface) and the case switch in execute(). After this refactor:\n\nAdding a new MCP tool:\n\n1. Drop a file at src/mcp/tools/<name>.ts exporting a <NAME>_TOOL: ToolModule (definition + handlerKey).\n2. Add one import line and one array entry to src/mcp/tools/registry.ts.\n3. Implement handle<Name>(args) on ToolHandler in tools.ts and add the new key to HandlerKey in tools/types.ts.\n\nStep 3 is the only remaining "shared method on a single class" conflict surface. Extracting handler bodies into per-tool files (making step 3 also a single-file addition) is left as a follow-up — the cost/benefit favors landing this incremental win now.\n\n## What's new\n\n| File | Purpose |\n|---|---|\n| src/mcp/tool-types.ts (NEW) | Extracted ToolDefinition, ToolResult, PropertySchema, projectPathProperty so per-tool files import without circular deps. |\n| src/mcp/tools/types.ts (NEW) | ToolModule, HandlerKey string union, ToolHandlerLike interface — ToolHandler now implements ToolHandlerLike, making dispatch fully compile-time-checked. |\n| src/mcp/tools/<name>.ts × 9 (NEW) | One file per existing tool: callees, callers, context, explore, files, impact, node, search, status. ~25-30 lines each. |\n| src/mcp/tools/registry.ts (NEW) | Static-import barrel + lookup helpers + derived tools[] array. |\n| src/mcp/tools.ts | ~200 lines deleted (inline types + tools[] array). execute() rewrites the case-switch to a registry lookup with type-safe this[mod.handlerKey](args) dispatch. private async handle* → public async handle* to match the interface. |\n| src/mcp/index.ts | Tool-existence check switched from linear tools.find() scan to O(1) getToolModule() Map lookup. |\n\n## Tests\n\n387/387 pass. 7 new in __tests__/mcp-tool-registry.test.ts:\n\n- Definitions well-formed (name shape, description length)\n- handlerKey follows handle<UpperCase> convention\n- Every registered handlerKey resolves to a real method on ToolHandler\n- Exported tools[] exactly mirrors the registry\n- Canonical 9 main-line tools regression guard\n- execute() unknown-tool error path\n- End-to-end dispatch smoke test: execute('codegraph_status', {}) reaches the real handler body — would fail loudly if the dynamic dispatch chain ever breaks\n\n## Reviewer pass\n\nIndependent reviewer ran once. 2 REQUEST_CHANGES + 2 INFO addressed:\n\n1. ToolHandlerLike was defined but never enforced — ToolHandler now implements ToolHandlerLike. Eliminates the (this as unknown as Record<...>) cast in execute(); dispatch is fully compile-time-checked.\n2. No end-to-end dispatch test — added the smoke test above.\n3. MCPServer.handleToolsCall used a linear tools.find() scan while execute() used Map lookup — switched to getToolModule() for parity.\n4. Removed redundant .slice() in registry.ts.\n\n## Backward compat\n\nsrc/mcp/tools.ts still re-exports ToolDefinition, ToolResult, the mutable tools[] array, ToolHandler, and getExploreBudget. Every existing consumer (import { ToolDefinition, ToolResult, tools, ToolHandler } from './tools') keeps working unchanged.\n\n## Affected open PRs\n\n| PR | Change |\n|---|---|\n| colbymchenry#110 review-context | Rebases to 1 new file + 2 lines in registry + 1 method on ToolHandler + 1 line in HandlerKey |\n| colbymchenry#112 centrality+churn | Same shape for codegraph_hotspots |\n| colbymchenry#114 config-refs | Same shape for codegraph_config |\n| colbymchenry#115 sql-refs | Same shape for codegraph_sql |\n\nEach goes from a 4-way conflict (tools[] + case + handler + helpers) down to a 1-way conflict (HandlerKey + handler method on ToolHandler, both in tools.ts).\n\n## Test plan\n\n- [x] tsc --noEmit clean\n- [x] npm test — 387/387 passing\n- [x] End-to-end dispatch smoke test exercises real handler binding\n- [x] Reviewer agent: REQUEST_CHANGES → APPROVE after fixes (with new test)\n- [x] Backward compat: all existing exports preserved\n\n🤖 Generated with Claude Code\n\n

---

Copied from colbymchenry/codegraph#117