Prepare for dynamic tool registration based on MCP client capabilities

[mattpodwysocki]

Summary

Implements capability-aware tool registration infrastructure that adapts to client features. Fixes incorrect resource capability detection and removes duplicate tools that conflict with MCP resources.

Key Changes

1. Fixed Resource Capability Detection (src/index.ts)

Problem: Checked clientCapabilities?.resources which doesn't exist (resources is a SERVER capability, not CLIENT capability)

Solution: Detect clients by name using getClientVersion() - only register fallback tools for clients with 'claude' in their name

2. Removed Duplicate Tools (src/tools/toolRegistry.ts)

Problem: Tools duplicated functionality already provided by MCP resources

Solution: Moved resource-duplicating tools to RESOURCE_FALLBACK_TOOLS:

• resource_reader_tool - Generic fallback for reading any resource by URI
• category_list_tool - Duplicated CategoryListResource (mapbox://categories)

Split tools into three capability-based categories:

• CORE_TOOLS (19 tools): Work in all MCP clients, always available
• ELICITATION_TOOLS (0 tools): Empty, ready for future elicitation support
• RESOURCE_FALLBACK_TOOLS (2 tools): Only for clients with resource issues (Claude Desktop)

3. Dynamic Registration Infrastructure

1. Register CORE tools before connection
2. After connection, check client capabilities and version
3. Conditionally register ELICITATION_TOOLS if client supports elicitation (none yet)
4. Conditionally register RESOURCE_FALLBACK_TOOLS if client name includes 'claude'
5. Send notifications/tools/list_changed after dynamic registration
6. Advertise tools: { listChanged: true } capability

4. Tests (test/tools/toolRegistry.test.ts)

Added 15 comprehensive unit tests covering tool categorization, no overlap between categories, and proper counts.

MCP Inspector Output (After Fix)

Clients with proper resource support (Inspector, VS Code, etc.) now see:

Tools (19):

[
  "area_tool",
  "bbox_tool",
  "bearing_tool",
  "buffer_tool",
  "category_search_tool",
  "centroid_tool",
  "directions_tool",
  "distance_tool",
  "isochrone_tool",
  "map_matching_tool",
  "matrix_tool",
  "midpoint_tool",
  "optimization_tool",
  "point_in_polygon_tool",
  "reverse_geocode_tool",
  "search_and_geocode_tool",
  "simplify_tool",
  "static_map_image_tool",
  "version_tool"
]

Resources (1):

[
  "mapbox://categories"
]

Result: Inspector shows 19 tools (down from 21) - resource fallback tools only appear for Claude clients.

Benefits

✅ No duplication: Resource fallback tools only for clients that need them
✅ Correct behavior: Inspector and proper clients use resources instead of fallback tools
✅ Better UX: Cleaner tool list for clients with proper resource support
✅ Infrastructure ready: Framework in place for capability-dependent tools
✅ Zero breaking changes: Claude Desktop still gets fallback tools

Testing

• ✅ All 597 tests pass
• ✅ Build successful
• ✅ Verified in MCP Inspector
• ✅ Comprehensive logging for debugging

MCP Specification Compliance

Follows MCP 1.0 specification for dynamic tool registration:

• Uses notifications/tools/list_changed notification
• Advertises listChanged capability
• Registers tools after initialization handshake
• Properly detects client capabilities

Related

Follows the same pattern as mcp-devkit-server PR #61.