feat: add API request validator tool

Add validate_api_request_tool to validate Mapbox API requests against
endpoint definitions before sending them to the API.

Features:
- Validates required parameters are present
- Checks parameter types (string, number, boolean, array, object)
- Validates enum constraints for parameters with allowed values
- Verifies token has required scopes for operations
- Detects extra/unknown parameters with warnings
- Returns detailed validation results with specific error messages
- Helps prevent failed API calls by catching issues early

Validation coverage:
- Path, query, and body parameters
- Type checking with clear error messages
- Enum validation (e.g., routing profiles, geocoding modes)
- Token scope verification
- Case-insensitive API and operation names

Implementation:
- Uses endpoint definitions from mapboxApiEndpoints.ts (from PR #75)
- Implements comprehensive validation logic
- 19 test cases covering all validation scenarios
- Proper MCP structured content with separated text and data
- Updated tool registry and documentation

This tool builds on top of explore_mapbox_api_tool by using the same
endpoint definitions to provide validation capabilities.

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

Author: mattpodwysocki

CHANGELOG.md

@@ -9,6 +9,14 @@
   - Optional detailed mode includes example requests and responses
   - Complements `get_latest_mapbox_docs_tool` by providing structured API reference data
   - No API access required - works with curated endpoint definitions
+- **API Request Validator Tool**: New `validate_api_request_tool` validates API requests before sending them
+  - Validates required parameters are present
+  - Checks parameter types (string, number, boolean, array, object)
+  - Validates enum constraints for parameters with allowed values
+  - Verifies token has required scopes for operations
+  - Detects extra/unknown parameters with warnings
+  - Returns detailed validation results with specific error messages
+  - Helps prevent failed API calls by catching issues early
 
 ### Documentation
 

README.md

@@ -148,6 +148,24 @@ The `MAPBOX_ACCESS_TOKEN` environment variable is required. **Each tool requires
 - "What scopes do I need for the Styles API?"
 - "How do I use the directions API? Show me examples"
 
+**validate_api_request_tool** - Validate Mapbox API requests before sending them. Checks that requests have all required parameters, correct types, valid enum values, and required token scopes. Returns detailed validation results to help catch errors early.
+
+**Features:**
+
+- Validates required vs optional parameters
+- Checks parameter types (string, number, boolean, array, object)
+- Validates enum constraints (e.g., routing profiles must be "driving", "walking", etc.)
+- Verifies token has required scopes
+- Detects unknown/extra parameters with warnings
+- Provides specific error messages for each issue
+
+**Example prompts:**
+
+- "Validate this geocoding request: {parameters}"
+- "Check if my token has the right scopes for creating a style"
+- "Is this directions API request valid?"
+- "What's wrong with this API request?"
+
 ### Reference Tools
 
 **get_reference_tool** - Access static Mapbox reference documentation and schemas. This tool provides essential reference information that helps AI assistants understand Mapbox concepts and build correct styles and tokens.

src/tools/toolRegistry.ts

@@ -24,6 +24,7 @@ import { StyleBuilderTool } from './style-builder-tool/StyleBuilderTool.js';
 import { StyleComparisonTool } from './style-comparison-tool/StyleComparisonTool.js';
 import { TilequeryTool } from './tilequery-tool/TilequeryTool.js';
 import { UpdateStyleTool } from './update-style-tool/UpdateStyleTool.js';
+import { ValidateApiRequestTool } from './validate-api-request-tool/ValidateApiRequestTool.js';
 import { ValidateExpressionTool } from './validate-expression-tool/ValidateExpressionTool.js';
 import { ValidateGeojsonTool } from './validate-geojson-tool/ValidateGeojsonTool.js';
 import { ValidateStyleTool } from './validate-style-tool/ValidateStyleTool.js';
@@ -55,6 +56,7 @@ export const CORE_TOOLS = [
   new GetFeedbackTool({ httpRequest }),
   new ListFeedbackTool({ httpRequest }),
   new TilequeryTool({ httpRequest }),
+  new ValidateApiRequestTool(),
   new ValidateExpressionTool(),
   new ValidateGeojsonTool(),
   new ValidateStyleTool()

src/tools/validate-api-request-tool/ValidateApiRequestTool.input.schema.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+
+export const ValidateApiRequestInputSchema = z.object({
+  api: z
+    .string()
+    .describe(
+      'API name to validate against (e.g., "geocoding", "styles", "tokens")'
+    ),
+  operation: z
+    .string()
+    .describe(
+      'Operation ID to validate (e.g., "forward-geocode", "create-style")'
+    ),
+  parameters: z
+    .object({
+      path: z
+        .record(z.any())
+        .optional()
+        .describe('Path parameters as key-value pairs'),
+      query: z
+        .record(z.any())
+        .optional()
+        .describe('Query parameters as key-value pairs'),
+      body: z
+        .record(z.any())
+        .optional()
+        .describe('Body parameters as key-value pairs')
+    })
+    .describe('Request parameters to validate'),
+  tokenScopes: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Token scopes to validate (optional). If provided, checks if token has required scopes for the operation.'
+    )
+});
+
+export type ValidateApiRequestInput = z.infer<
+  typeof ValidateApiRequestInputSchema
+>;

src/tools/validate-api-request-tool/ValidateApiRequestTool.output.schema.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+const ValidationIssueSchema = z.object({
+  type: z.enum(['error', 'warning']),
+  field: z.string(),
+  message: z.string(),
+  expected: z.string().optional(),
+  received: z.any().optional()
+});
+
+const ParameterValidationSchema = z.object({
+  provided: z.number(),
+  required: z.number(),
+  optional: z.number(),
+  missing: z.array(z.string()),
+  extra: z.array(z.string())
+});
+
+const ScopeValidationSchema = z.object({
+  hasRequired: z.boolean(),
+  required: z.array(z.string()),
+  provided: z.array(z.string()).optional(),
+  missing: z.array(z.string()).optional()
+});
+
+// Output schema defines only the structured content
+export const ValidateApiRequestOutputSchema = z.object({
+  valid: z.boolean(),
+  operation: z.object({
+    api: z.string(),
+    operation: z.string(),
+    method: z.string(),
+    endpoint: z.string()
+  }),
+  issues: z.array(ValidationIssueSchema),
+  parameters: z.object({
+    path: ParameterValidationSchema.optional(),
+    query: ParameterValidationSchema.optional(),
+    body: ParameterValidationSchema.optional()
+  }),
+  scopes: ScopeValidationSchema.optional()
+});
+
+export type ValidateApiRequestOutput = z.infer<
+  typeof ValidateApiRequestOutputSchema
+>;