Add validate_expression_tool for Mapbox expression validation

This commit adds a comprehensive Mapbox expression validation tool that
performs offline validation of style expressions without requiring API access.

Features:
- Validates all Mapbox expression operators (90+ operators supported)
- Checks expression syntax (array format, string operators)
- Validates argument counts for each operator
- Recursive validation of nested expressions
- Detects and warns about deeply nested expressions (depth > 10)
- Returns structured errors, warnings, and info messages with suggestions
- Provides metadata (expressionType, returnType, depth)
- Accepts both JSON strings and expression arrays as input

Supported operator categories:
- Decision: case, match, coalesce
- Lookup: get, has, in, index-of, length
- Math: +, -, *, /, %, ^, min, max, round, floor, ceil, abs, sqrt, log10, log2, ln, e, pi
- Comparison: ==, !=, >, <, >=, <=
- Logical: !, all, any
- String: concat, downcase, upcase
- Color: rgb, rgba, to-rgba
- Type conversion: array, boolean, number, string, to-boolean, to-color, to-number, to-string, typeof
- Interpolation: interpolate, step
- Feature data: get, has, feature-state, geometry-type, id, properties
- Camera: zoom, pitch, distance-from-center
- Variable binding: let, var

The tool is implemented as a BaseTool (offline, no HttpRequest dependency)
and includes 25 comprehensive test cases covering literals, valid expressions,
invalid expressions, nested expressions, error handling, and metadata.

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Author: mattpodwysocki

README.md

@@ -357,6 +357,87 @@ Generate a geojson.io URL to visualize GeoJSON data. This tool:
 - "Generate a preview URL for this GeoJSON data"
 - "Create a geojson.io link for my uploaded route.geojson file"
 
+#### Validate Expression tool
+
+Validates Mapbox style expressions for syntax, operators, and argument correctness. This offline validation tool performs comprehensive checks on Mapbox expressions without requiring API access.
+
+**Parameters:**
+
+- `expression` (string or array, required): Mapbox expression to validate (JSON string or expression array)
+- `context` (string, optional): Context where the expression will be used ("style", "filter", "layout", "paint")
+
+**What it validates:**
+
+- Expression syntax (array format with operator as first element)
+- Valid operators (get, case, match, interpolate, math operators, etc.)
+- Correct argument counts for each operator
+- Nested expression validation
+- Expression depth (warns about deeply nested expressions)
+
+**Returns:**
+
+Validation results including:
+
+- `valid` (boolean): Overall validity
+- `errors` (array): Critical errors that make the expression invalid
+- `warnings` (array): Non-critical issues (e.g., deeply nested expressions)
+- `info` (array): Informational messages
+- `metadata`: Object with expressionType, returnType, and depth
+
+Each issue includes:
+
+- `severity`: "error", "warning", or "info"
+- `message`: Description of the issue
+- `path`: Path to the problem in the expression (optional)
+- `suggestion`: How to fix the issue (optional)
+
+**Supported operators:**
+
+- **Decision**: case, match, coalesce
+- **Lookup**: get, has, in, index-of, length, slice
+- **Math**: +, -, \*, /, %, ^, min, max, round, floor, ceil, abs, sqrt, log10, log2, ln, e, pi
+- **Comparison**: ==, !=, >, <, >=, <=
+- **Logical**: !, all, any
+- **String**: concat, downcase, upcase
+- **Color**: rgb, rgba, to-rgba
+- **Type conversion**: array, boolean, number, string, to-boolean, to-color, to-number, to-string, typeof
+- **Interpolation**: interpolate, step
+- **Feature data**: get, has, feature-state, geometry-type, id, properties
+- **Camera**: zoom, pitch, distance-from-center
+- **Variable binding**: let, var
+
+**Example:**
+
+```json
+{
+  "expression": ["get", "population"]
+}
+```
+
+**Returns:**
+
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": [],
+  "info": [],
+  "metadata": {
+    "expressionType": "get",
+    "returnType": "any",
+    "depth": 0
+  }
+}
+```
+
+**Example prompts:**
+
+- "Validate this Mapbox expression: ['get', 'name']"
+- "Check if my case expression is correctly formatted"
+- "Is this interpolate expression valid?"
+
+**Note:** This is an offline validation tool that doesn't require API access or token scopes.
+
 #### Coordinate Conversion tool
 
 Convert coordinates between different coordinate reference systems (CRS), specifically between WGS84 (EPSG:4326) and Web Mercator (EPSG:3857).

src/tools/toolRegistry.ts

@@ -20,6 +20,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 { ValidateExpressionTool } from './validate-expression-tool/ValidateExpressionTool.js';
 import { httpRequest } from '../utils/httpPipeline.js';
 
 // Central registry of all tools
@@ -42,7 +43,8 @@ export const ALL_TOOLS = [
   new GetMapboxDocSourceTool({ httpRequest }),
   new GetReferenceTool(),
   new StyleComparisonTool(),
-  new TilequeryTool({ httpRequest })
+  new TilequeryTool({ httpRequest }),
+  new ValidateExpressionTool()
 ] as const;
 
 export type ToolInstance = (typeof ALL_TOOLS)[number];

src/tools/validate-expression-tool/ValidateExpressionTool.input.schema.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+
+import { z } from 'zod';
+
+export const ValidateExpressionInputSchema = z.object({
+  expression: z
+    .union([z.string(), z.any()])
+    .describe(
+      'Mapbox expression to validate (JSON string or expression array)'
+    ),
+  context: z
+    .enum(['style', 'filter', 'layout', 'paint'])
+    .optional()
+    .describe('Context where the expression will be used')
+});
+
+export type ValidateExpressionInput = z.infer<
+  typeof ValidateExpressionInputSchema
+>;

src/tools/validate-expression-tool/ValidateExpressionTool.output.schema.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+
+import { z } from 'zod';
+
+const ExpressionIssueSchema = z.object({
+  severity: z.enum(['error', 'warning', 'info']).describe('Issue severity'),
+  message: z.string().describe('Description of the issue'),
+  path: z.string().optional().describe('Path to the problem in the expression'),
+  suggestion: z.string().optional().describe('How to fix the issue')
+});
+
+export const ValidateExpressionOutputSchema = z.object({
+  valid: z.boolean().describe('Whether the expression is valid'),
+  errors: z.array(ExpressionIssueSchema).describe('Critical errors'),
+  warnings: z.array(ExpressionIssueSchema).describe('Non-critical warnings'),
+  info: z.array(ExpressionIssueSchema).describe('Informational messages'),
+  metadata: z
+    .object({
+      expressionType: z
+        .string()
+        .optional()
+        .describe('Detected expression type (e.g., "literal", "get", "match")'),
+      returnType: z
+        .string()
+        .optional()
+        .describe('Expected return type of the expression'),
+      depth: z.number().optional().describe('Maximum nesting depth')
+    })
+    .describe('Expression metadata')
+});
+
+export type ValidateExpressionOutput = z.infer<
+  typeof ValidateExpressionOutputSchema
+>;
+export type ExpressionIssue = z.infer<typeof ExpressionIssueSchema>;