Add two-stage elicitations for DirectionsTool

[mattpodwysocki]

Summary

Implements a two-stage elicitation flow for DirectionsTool to provide better route selection UX:

Stage 1 (Routing Preferences): Ask users about their routing preferences before calling the API

• Fastest route (tolls OK)
• Avoid tolls (may be slower)
• Avoid highways/motorways (driving only)
• Avoid ferries

Stage 2 (Route Selection): Present actual routes for user selection after API call

• Show duration (e.g., "4h 48min")
• Show distance (e.g., "366.8km (227.9mi)")
• Show major roads (e.g., "via I-84 East, I-90 East")
• Show traffic levels: ✅ Light, 🟡 Moderate, ⚠️ Heavy
• Show incident counts (e.g., "2 incident(s)")

Implementation Details

• Helper methods: formatDuration() and formatDistance() for readable output
• Graceful fallback: Both stages catch errors and continue without blocking
• Works without elicitation: Returns all routes when elicitation is unavailable
• Smart triggering: Only elicits for simple A-to-B routes (2 coordinates), not multi-waypoint
• Forces alternatives: Stage 1 sets alternatives=true to get multiple routes for Stage 2

Test Scenarios

These scenarios demonstrate the two-stage elicitation flow. Screenshots to be added below.

Scenario 1: Full two-stage flow (NYC to Boston)

Input:

{
  "coordinates": [
    {"longitude": -74.006, "latitude": 40.7128},
    {"longitude": -71.0589, "latitude": 42.3601}
  ],
  "routing_profile": "mapbox/driving-traffic"
}

Expected behavior:

1. Stage 1 elicitation appears asking for routing preferences
2. User selects "Avoid tolls (may be slower)"
3. API called with exclude=toll,cash_only_tolls
4. Stage 2 elicitation shows 2+ routes with formatted details
5. User selects preferred route
6. Tool returns only the selected route

Screenshot placeholders:

• Stage 1: Routing preferences dialog

• Stage 2: Route selection dialog with traffic and incident info

• Final result: Selected single route returned

---

Scenario 2: User declines Stage 1 preferences

Input:

{
  "coordinates": [
    {"longitude": -118.24, "latitude": 34.05},
    {"longitude": -122.42, "latitude": 37.78}
  ],
  "routing_profile": "mapbox/driving"
}

Expected behavior:

1. Stage 1 elicitation appears
2. User declines/cancels
3. API called without exclude parameter
4. Stage 2 may still trigger if multiple routes returned
5. All routes returned if Stage 2 declined or not triggered

Screenshot placeholders:

• User declining Stage 1 dialog

• Result showing all routes

---

Scenario 3: Walking profile (no highway option)

Input:

{
  "coordinates": [
    {"longitude": -74.006, "latitude": 40.7128},
    {"longitude": -73.99, "latitude": 40.73}
  ],
  "routing_profile": "mapbox/walking"
}

Expected behavior:

1. Stage 1 shows only: Fastest, Avoid tolls, Avoid ferries (no "Avoid highways")
2. User selects preference
3. Continues with normal flow

Screenshot placeholders:

• Stage 1 for walking profile (3 options, no highways)

---

Scenario 4: Multi-waypoint route (no elicitation)

Input:

{
  "coordinates": [
    {"longitude": -74.006, "latitude": 40.7128},
    {"longitude": -73.9, "latitude": 41.0},
    {"longitude": -71.0589, "latitude": 42.3601}
  ]
}

Expected behavior:

1. No Stage 1 elicitation (only for 2-coordinate routes)
2. No Stage 2 elicitation
3. Returns standard response

---

Scenario 5: Exclude parameter already provided (no Stage 1)

Input:

{
  "coordinates": [
    {"longitude": -74.006, "latitude": 40.7128},
    {"longitude": -71.0589, "latitude": 42.3601}
  ],
  "exclude": "motorway"
}

Expected behavior:

1. No Stage 1 elicitation (exclude already set)
2. Stage 2 may still trigger if multiple routes returned
3. Uses provided exclude parameter

---

Testing

• ✅ All existing DirectionsTool tests pass (37 tests)
• ✅ Added 4 new tests for elicitation behavior:
  • Does not elicit when exclude already provided
  • Does not elicit for multi-waypoint routes
  • Returns multiple routes when no elicitation
  • Returns single route when only one available

Notes

• Elicitations are draft MCP spec feature
• Supported in VS Code and Cursor MCP clients
• Not yet supported in Claude Desktop
• Tool works without elicitation support (graceful fallback)