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.

[mattpodwysocki]

✅ Applied same solution as devkit PR #61: Explicit opt-in via environment variable

Removed all client name detection logic and replaced with CLIENT_NEEDS_RESOURCE_FALLBACK environment variable.

Why this approach?

The problem with name-based detection:

• ❌ Can't keep up with all MCP clients (race condition)
• ❌ Maintenance burden tracking client names/versions
• ❌ Brittle (names change, versions evolve)
• ❌ Defeats the purpose of being adaptive

The solution:
Let users explicitly configure their client's capabilities via environment variable.

Configuration

Default (unset): Skip resource fallback tools

• Assumes client supports resources (the common case)
• Works for: Claude Desktop, VS Code, MCP Inspector, and most clients

Opt-in: CLIENT_NEEDS_RESOURCE_FALLBACK=true

• Includes resource fallback tools for clients without resource support
• Required for: smolagents and other non-compliant clients

Benefits

✅ No maintenance burden (no client tracking)
✅ Better default (most clients support resources)
✅ Works for all current and future clients
✅ Explicit configuration by users who know their client
✅ Scales indefinitely

Documentation

Added new section in README explaining:

• What resource fallback tools are (resource_reader_tool, category_list_tool)
• When to set the environment variable
• Which clients need it vs. which don't

Commit: 2530021