Add large response handling with temporary resources

[mattpodwysocki]

Overview

Implements conditional resource creation for DirectionsTool responses that exceed 50KB to prevent context window overflow.

Fixes the issue where long-distance routes (e.g., Washington DC to New York) return massive JSON responses that exceed the LLM's context window.

Solution

Conditional Resource Creation:

• Detects when response size > 50KB
• Creates temporary in-memory resource with URI: mapbox://temp/directions-{id}
• Returns summary (distance, duration) + lightweight structured content
• Small responses (<50KB) work unchanged - zero overhead

Resource Management:

• In-memory storage with 30-minute TTL
• Automatic cleanup every 5 minutes
• Full data available via MCP resource API
• Session-appropriate lifetime

LLM Guidance:

• Updated tool description to guide LLMs: use geometries="none" for route planning, geometries="geojson" only for visualization
• Updated search-along-route prompt to request compact responses by default
• Prevents unnecessary large geometry requests

Schema Compliance:

• Returns lightweight structured content for large responses to satisfy output schema validation
• Includes route summary data (distance, duration, leg summaries) without geometry
• Eliminates validation warnings that caused "Tool execution failed" errors in Claude Desktop

Example Output

Small Response (<50KB):

{
  "routes": [...full route with geometry...],
  "waypoints": [...]
}

Large Response (>50KB):

Route found: 225.6 miles, 252 minutes

Waypoints: 2

⚠️ Full response (342KB) exceeds context limit.

Full geometry and details stored as temporary resource.
Resource URI: mapbox://temp/directions-abc123
TTL: 30 minutes

Use the MCP resource API to retrieve full details if needed.
Or ask to read the resource by its URI.

Changes

• New: TemporaryResourceManager - In-memory resource storage with TTL
• New: TemporaryDataResource - MCP resource handler for temporary data
• Updated: DirectionsTool - Conditional resource creation for large responses
• Updated: DirectionsTool - Description guides LLMs to use geometries="none" for planning
• Updated: DirectionsTool - Returns schema-compliant structured content for large responses
• Updated: SearchAlongRoutePrompt - Uses geometries="none" and linear interpolation for sampling
• Updated: Resource registry - Registered temporary resource
• Updated: CHANGELOG.md - Documented all changes

Testing

✅ Build passes with no TypeScript errors
✅ Small responses work unchanged
✅ Large responses create resources and return summaries with structured content
✅ Resources retrievable via MCP API
✅ Cleanup works correctly
✅ No validation warnings or errors in Claude Desktop

Impact

• Performance: Prevents context overflow for long-distance routes
• UX: No more "Tool execution failed" errors in Claude Desktop
• Efficiency: LLMs now request compact responses by default, only requesting geometry when needed
• Compatibility: Fully backward compatible - small responses unchanged

Future Work

This pattern can be extended to other tools that may return large datasets:

• Search results with many POIs
• Matrix API results
• Other tools as needed

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

[mattpodwysocki]

✅ Verification - Feature Working Perfectly

Tested with query: "find gas stations between washington dc and new york"

Observed Behavior

Step 1 - Route Planning:

• DirectionsTool called with optimized parameters
• Route: ~362km (225 miles), ~4.3 hours
• Recognized as VERY LONG route → 6 sample points strategy
• Uses linear interpolation (no geometry extraction needed!)

Step 2 - Search Results:

• Clean, well-formatted output
• Gas stations organized by location along route:
  • Near Washington, DC (Mile 0-10)
  • Maryland — Baltimore Area (~Mile 40-50)
  • [continues through route]
• Route summary: ~225 miles via I-95 / NJ Turnpike, ~4.3 hours

Key Improvements Verified

✅ No "Tool execution failed" errors
✅ Single DirectionsTool call (not multiple retries)
✅ Compact response (no context overflow)
✅ Linear interpolation working correctly
✅ Proper sampling strategy based on route length
✅ Fast execution with clean results

---

Result: Feature working as designed! 🎉