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

[andreinknv]

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.

---

Summary

Today 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:

Adding a new MCP tool:

1. Drop a file at src/mcp/tools/<name>.ts exporting a <NAME>_TOOL: ToolModule (definition + handlerKey).
2. Add one import line and one array entry to src/mcp/tools/registry.ts.
3. Implement handle<Name>(args) on ToolHandler in tools.ts and add the new key to HandlerKey in tools/types.ts.

Step 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.

What's new

File	Purpose
src/mcp/tool-types.ts (NEW)	Extracted ToolDefinition, ToolResult, PropertySchema, projectPathProperty so per-tool files import without circular deps.
src/mcp/tools/types.ts (NEW)	ToolModule, HandlerKey string union, ToolHandlerLike interface — ToolHandler now implements ToolHandlerLike, making dispatch fully compile-time-checked.
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.
src/mcp/tools/registry.ts (NEW)	Static-import barrel + lookup helpers + derived tools[] array.
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.
src/mcp/index.ts	Tool-existence check switched from linear tools.find() scan to O(1) getToolModule() Map lookup.

Tests

387/387 pass. 7 new in __tests__/mcp-tool-registry.test.ts:

• Definitions well-formed (name shape, description length)
• handlerKey follows handle<UpperCase> convention
• Every registered handlerKey resolves to a real method on ToolHandler
• Exported tools[] exactly mirrors the registry
• Canonical 9 main-line tools regression guard
• execute() unknown-tool error path
• End-to-end dispatch smoke test: execute('codegraph_status', {}) reaches the real handler body — would fail loudly if the dynamic dispatch chain ever breaks

Reviewer pass

Independent reviewer ran once. 2 REQUEST_CHANGES + 2 INFO addressed:

1. 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.
2. No end-to-end dispatch test — added the smoke test above.
3. MCPServer.handleToolsCall used a linear tools.find() scan while execute() used Map lookup — switched to getToolModule() for parity.
4. Removed redundant .slice() in registry.ts.

Backward compat

src/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.

Affected open PRs

PR	Change
#110 review-context	Rebases to 1 new file + 2 lines in registry + 1 method on ToolHandler + 1 line in HandlerKey
#112 centrality+churn	Same shape for codegraph_hotspots
#114 config-refs	Same shape for codegraph_config
#115 sql-refs	Same shape for codegraph_sql

Each 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).

Test plan

• tsc --noEmit clean
• npm test — 387/387 passing
• End-to-end dispatch smoke test exercises real handler binding
• Reviewer agent: REQUEST_CHANGES → APPROVE after fixes (with new test)
• Backward compat: all existing exports preserved

🤖 Generated with Claude Code

[andreinknv]

Part of a coordinated 4-PR refactor that unblocks the open PR backlog. See #120 for the full merge-order guide explaining how this PR fits into the picture and how each open language/feature PR rebases onto the new pattern.

[andreinknv]

Maintainer review checklist (5-min path)

This refactor is behavior-preserving. Below is the shortest path to verify that without re-reading the patch.

1. What changed structurally

• New src/mcp/tool-types.ts (39 lines) — extracted shared types so per-tool files import without circular dep
• New src/mcp/tools/types.ts (50 lines) — ToolModule, HandlerKey union, ToolHandlerLike structural type
• New src/mcp/tools/<name>.ts × 9 — one file per tool, ~25-30 lines each, all the tool definitions previously inlined in tools.ts
• New src/mcp/tools/registry.ts (65 lines) — alphabetised barrel export
• Shrunk src/mcp/tools.ts (-200 lines net): inline definitions and the case-switch deleted; execute() does this[mod.handlerKey](args) with compile-time-checked dispatch via implements ToolHandlerLike

2. What stays exactly the same — verify in seconds

Public surface	File:line	Status
ToolDefinition, ToolResult types	src/mcp/tools.ts:20	re-exported from tool-types.ts
tools[] array consumed by list_tools	src/mcp/tools.ts:32	now derived from registry, same shape, same order via alpha sort
getExploreBudget(fileCount)	src/mcp/tools.ts:42	unmoved
ToolHandler class	src/mcp/tools.ts:71	same methods, now public instead of private so the structural interface can match

Existing imports import { ToolDefinition, ToolResult, tools, ToolHandler } from './tools' keep working unchanged. Grep confirms no consumer touches the formerly-private handler methods.

3. Invariants now enforced by tests (__tests__/mcp-tool-registry.test.ts, 7 tests)

• ✅ Every registered handlerKey resolves to a real method on ToolHandler — adding a tool with a typo'd handler name fails CI loudly
• ✅ The exported tools[] exactly mirrors the registry — drift between the two surfaces is impossible
• ✅ All 9 canonical tools registered (regression guard against accidental deletion)
• ✅ End-to-end dispatch smoke: execute('codegraph_status', {}) reaches the real handler body — guards against this-binding regressions in the dynamic dispatch
• ✅ execute() returns the standard error result for unknown tools

4. Reviewer pass — caught and fixed before this comment

1. ToolHandlerLike was defined but unused → ToolHandler implements ToolHandlerLike now (compile-time dispatch check; eliminates the unknown cast)
2. No e2e dispatch test → added (test Codegraphe does not work under Node v24. #5 above)
3. MCPServer.handleToolsCall did a linear tools.find() while execute() used a Map → switched to getToolModule() for parity
4. Redundant .slice() in registry.ts removed (map() already returns fresh)

5. Mergeability

• No upstream PR blockers — main is the only dep
• No other refactor blocks this — the 4 Phase-2 refactors are mutually independent (per Merge-order guide for the open PR backlog (4 refactor PRs unblock the rest) #120)
• Unblocks feat(mcp): codegraph_review_context — structured PR-review context from a diff #110, feat(graph): PageRank centrality + per-file churn metrics #112, feat(graph): config_refs — env var read sites as queryable graph data #114, feat(graph): sql_refs — SQL string-literal call sites (pairs with #95) #115 — each shrinks from 4-way conflict (tools[] + case-switch + handler + helpers) to 1-way (handler method on ToolHandler + HandlerKey entry)

If checklist sections 1-4 look right, this is safe to land. Happy to walk through any specific file in more detail.

🤖 Comment template generated with Claude Code

[colbymchenry]

Closing — this is well-engineered but I'm not adopting the per-file MCP tool organization. The refactor's primary value is reducing conflict surface for stacked future PRs (cited #110/#112/#114/#115 all from this same flood), and I've been declining most of those on independent grounds. Without those PRs merging, the refactor is net file-count growth for organizational change I didn't ask for.

If I decide later that I want per-file MCP tool organization, I'd rather scope and design that myself. Thanks for the work.