feat: Add API request validator tool

[mattpodwysocki]

Summary

Implements validate_api_request_tool to validate Mapbox API requests against endpoint definitions before sending them. Builds on top of PR #75 (API Endpoint Explorer) by reusing the endpoint definitions from mapboxApiEndpoints.ts.

This PR targets feature/api-endpoint-explorer (PR #75) and should be merged after #75 is merged.

Features

• Required parameter validation: Checks all required parameters are present
• Type validation: Validates parameter types (string, number, boolean, array, object)
• Enum validation: Ensures values match allowed enums (e.g., routing profiles)
• Token scope verification: Checks if token has required scopes for the operation
• Unknown parameter detection: Warns about extra parameters not in API definition
• Detailed error messages: Returns specific validation results for each issue

Use Cases

1. Pre-flight validation: Validate requests before making API calls to catch errors early
2. Token scope checking: Verify your token has the right scopes before attempting operations
3. Parameter debugging: Get specific feedback about what's wrong with a request
4. Learning tool: Understand what parameters are required for each API operation

Implementation

• Extends BaseTool with proper input/output schemas
• Reuses MAPBOX_API_ENDPOINTS from PR feat: Add API endpoint explorer tool #75
• Comprehensive validation logic for all parameter types
• Returns both markdown text and structured validation results
• 19 test cases covering all validation scenarios

Testing

• ✅ 19 new test cases (all passing)
• ✅ All 576 project tests pass
• ✅ Tool snapshot updated
• ✅ Build successful
• ✅ Output schema validated

Test Coverage

• Valid request validation
• Missing required parameters (path, query, body)
• Type mismatches
• Invalid enum values
• Extra/unknown parameters (warnings)
• Token scope validation
• Multiple APIs (geocoding, styles, directions)
• Case-insensitive API/operation names

Example Usage

{
  "api": "geocoding",
  "operation": "forward-geocode",
  "parameters": {
    "path": {
      "mode": "mapbox.places",
      "query": "San Francisco"
    },
    "query": {
      "access_token": "pk.test"
    }
  },
  "tokenScopes": ["geocoding:read", "styles:read"]
}

Returns: Detailed validation result with ✅/❌ status, parameter summary, and specific error messages.

Documentation

• Updated README.md with tool description and example prompts
• Updated CHANGELOG.md with feature entry
• Complements explore_mapbox_api_tool by providing validation capabilities

Dependencies

• Requires PR feat: Add API endpoint explorer tool #75 - Uses mapboxApiEndpoints.ts from the API Explorer tool
• Targets feature/api-endpoint-explorer branch

🤖 Generated with Claude Code

[Valiunia]

I can see how it might backfire, e.g. new APIs, is this a valid concern or how we avoid that?

[mattpodwysocki]

Addressed the feedback about handling new APIs!

Changes Made

I've updated the tool to clearly communicate that it validates against a curated list of known APIs, not all possible Mapbox APIs:

1. Updated Class Documentation

Added a note explaining:

• This validates against a curated list
• New APIs may not be included yet
• Users should refer to official docs or open an issue for new APIs

2. Improved Error Message

When an API isn't found, the new message:

• ✅ Clearly states it's "not found in our curated endpoint definitions"
• ✅ Suggests using explore_mapbox_api_tool to see what's available
• ✅ Points to official Mapbox API docs for newer APIs
• ✅ Reminds users they can still make requests without validation

3. Updated Tool Description

Now says "known endpoint definitions" and clarifies the limitation upfront.

4. Added README Note

Added a visible note in the README explaining the limitation and how to handle it.

Why This Works

This approach:

• Acknowledges the limitation without trying to hide it
• Provides clear next steps when encountering unknown APIs
• Sets correct expectations that this is a helper tool for known APIs
• Doesn't block users from working with newer APIs

The tool is designed as a quality-of-life helper for common APIs, not a comprehensive validator for every possible Mapbox endpoint. Users working with brand new APIs can skip validation and proceed directly to testing.

If new APIs become popular, contributors can add them to mapboxApiEndpoints.ts through a PR.