Add search-along-route prompt for POI discovery along routes

[mattpodwysocki]

Summary

Introduces a new search-along-route MCP prompt that orchestrates existing tools to find places of interest along a route corridor. This enables use cases like:

• "I want to go from Seattle to Portland, is there a Starbucks along the way?"
• "Find gas stations along my route from LA to San Francisco"
• "Show me rest stops between Denver and Salt Lake City"

Motivation

With the addition of offline geospatial tools (buffer, point-in-polygon, distance), we can now compose powerful workflows. Search-along-route combines:

1. directions_tool - Get route geometry
2. buffer_tool - Create corridor around route
3. search_and_geocode_tool / category_search_tool - Find POIs
4. point_in_polygon_tool - Filter to corridor
5. distance_tool - Order by proximity

This showcases how offline tools enhance search workflows without requiring new API endpoints.

Implementation

New Files

• src/prompts/SearchAlongRoutePrompt.ts - Prompt implementation with detailed orchestration instructions

Modified Files

• src/prompts/promptRegistry.ts - Register new prompt
• test/prompts/promptRegistry.test.ts - Test coverage for new prompt

Prompt Arguments

Required:

• from - Starting location (address, place name, or coordinates)
• to - Destination location (address, place name, or coordinates)
• search_for - Type of place to search for (e.g., "Starbucks", "gas stations")

Optional:

• mode - Travel mode: driving, walking, or cycling (default: driving)
• buffer_meters - Search corridor width on each side of route (default: 1000m)

Orchestration Steps

The prompt guides the AI through:

1. Geocode locations if needed
2. Get the route using directions_tool
3. Create search corridor using buffer_tool (configurable width)
4. Search for places within bounding box
5. Filter results using point_in_polygon_tool
6. Order results by route progress
7. Visualize and present on a map with clear formatting

Example Usage

User: "I want to go from Seattle to Portland, is there a Starbucks along the way?"

Prompt provides:
- Route line visualization
- All Starbucks locations within 1km corridor
- Each location's distance from route
- Position along route (e.g., "15 miles into your trip")
- Total route distance and time

Testing

✅ All 581 tests pass

• Added metadata tests for new prompt
• Verified argument validation (3 required, 2 optional)
• Follows existing prompt patterns

Prompt Generation

Entering the following data:

• Start: Seattle, WA
• End: Portland, OR
• POI: Starbucks

Output is the following:

{
  description: "Finds specific types of places along a route between two locations, using buffer analysis and POI search";
  messages: [
    0,
    {
      role: "user",

      content: {
        type: "text",
        text: `Find Starbucks along the driving route from Seattle, WA to Portland, OR.

Please follow these steps:

1. **Geocode locations** (if needed):
   - Use search_and_geocode_tool to convert Seattle, WA and Portland, OR to coordinates if they're not already in coordinate format

2. **Get the route**:
   - Use directions_tool with profile=driving to get the route geometry between the two points
   - Extract the route LineString geometry from the response

3. **Create search corridor**:
   - Use buffer_tool on the route geometry with distance=1000 meters
   - This creates a polygon corridor around the route

4. **Search for places**:
   - Use category_search_tool or search_and_geocode_tool to find "Starbucks"
   - Use the buffer polygon's bounding box as the search area
   - Consider searching in segments if the route is very long (>100km)

5. **Filter results**:
   - Use point_in_polygon_tool to confirm each result is actually within the buffer corridor
   - Use distance_tool to calculate distance from each POI to the route
   - Order results by their position along the route (use bearing or route progress)

6. **Visualize and present**:
   - Display a map showing:
     * The route line
     * Start and end markers
     * All found locations as markers
     * Optionally, the buffer corridor (semi-transparent)
   - Provide a list of results including:
     * Name and address of each place
     * Distance from route
     * Approximate position along route (e.g., "15 miles into your trip")
     * Total results found

7. **Additional context**:
   - Mention the total route distance and estimated travel time
   - Note if no results were found and suggest widening the search corridor
   - If many results (>20), show top 10-15 and mention there are more

Tips:
- For long routes, you may need to search in multiple segments
- Adjust buffer_meters if too many/few results (wider for highways, narrower for city streets)
- Consider the travel mode when setting buffer defaults (walking=500m, driving=1000m)

Make the output clear, actionable, and well-formatted.`,
      },
    },
  ];
}

Design Decisions

Why a prompt vs a tool?

• Composition: Reuses 5+ existing tools
• Flexibility: Users can adjust buffer, POI types, mode
• Educational: Shows how to combine geospatial operations
• Maintainability: No new API dependencies

Why not extend existing prompts?

• Different use case: route corridor vs point-based search
• Requires buffer analysis (not in find-places-nearby)
• Ordered by route progress (not just distance from point)

Follow-up Ideas

Future enhancements could include:

• Multiple search categories in one query
• Minimum spacing between results
• Route segment clustering (for very long routes)
• Integration with optimization_tool for multi-stop planning