Style builder tool

README.md

@@ -118,6 +118,10 @@ The `MAPBOX_ACCESS_TOKEN` environment variable is required. **Each tool requires
 
 Complete set of tools for managing Mapbox styles via the Styles API:
 
+**Style Builder Tool** - Create and modify Mapbox styles programmatically through conversational prompts
+
+📖 **[See the Style Builder documentation for detailed usage and examples →](./docs/STYLE_BUILDER.md)**
+
 **ListStylesTool** - List all styles for a Mapbox account
 
 - Input: `limit` (optional - max number of styles), `start` (optional - pagination token)

docs/STYLE_BUILDER.md

@@ -0,0 +1,241 @@
+# Mapbox Style Builder Tool
+
+## Overview
+
+The Style Builder tool is a powerful utility for creating and modifying Mapbox styles programmatically. It provides a conversational interface to build complex map styles with various customizations for layers, labels, boundaries, roads, POIs, and more.
+
+## Important Limitations
+
+⚠️ **Resource Access Limitation**: Style resources (sprites, glyphs, and other assets) cannot currently be accessed through clients like Claude Desktop. This is a known limitation when using the tool through MCP (Model Context Protocol) interfaces.
+
+## Getting Started
+
+To start building a style, you can initiate the conversation with prompts like:
+
+- "Can you help me building a style, what customizations can I make?"
+- "Create a new Mapbox style with specific features"
+- "Modify my existing style to add/remove layers"
+
+The tool can be used for both **creating new styles** and **modifying existing styles**.
+
+## Example Style Creation Prompts
+
+### 1. Comprehensive Style with All Labels
+
+**Prompt**: "Create a style with all possible labels enabled, make every label have a different look so that they can be distinguished. Include also all boundaries (countries, provinces). And all roads with different colors and opacities. POIs with icons."
+
+This creates a maximally detailed style where:
+
+- Every label type has distinct visual properties
+- All administrative boundaries are visible
+- Roads are color-coded by type
+- POIs display with appropriate icons
+
+### 2. Selective Administrative and Road Display
+
+**Prompt**: "Create a style with only administrative boundaries having admin_level 0 or 1, and roads with class motorway and oneway true"
+
+This creates a minimalist style focusing on:
+
+- Country and state/province boundaries only
+- Motorways that are one-way streets
+- Clean, uncluttered appearance
+
+### 3. Zoom-Based Road Visibility
+
+**Prompt**: "Create a style with minor roads only visible above zoom 14, service roads only above zoom 16, with zoom-based width increase"
+
+This creates a progressive detail style where:
+
+- Road visibility depends on zoom level
+- Road widths increase smoothly with zoom
+- Performance optimized for different zoom ranges
+
+### 4. Comprehensive POI Filtering
+
+**Prompt**: "Create a style with only POIs showing maki icons for restaurants, cafes, and bars, each in different colors"
+
+This creates a food & beverage focused style with:
+
+- Selective POI display
+- Color-coded categories
+- Clear maki icon representation
+
+### 5. Complex Boundary Rules
+
+**Prompt**: "Create a style with international boundaries (admin_level 0) that are not maritime and not disputed in solid black, disputed ones in red dashed"
+
+This creates a politically-aware style with:
+
+- Different styling for disputed boundaries
+- Maritime boundary filtering
+- Visual hierarchy for boundary types
+
+## Common Customizations
+
+The Style Builder supports extensive customizations including:
+
+### Layers
+
+- Add/remove specific layer types
+- Modify layer ordering
+- Apply filters and conditions
+
+### Labels
+
+- Control text size, font, and color
+- Set visibility by zoom level
+- Adjust label density and overlap behavior
+
+### Roads
+
+- Customize by road class (motorway, trunk, primary, secondary, etc.)
+- Apply different styles for bridges and tunnels
+- Control casing and width properties
+
+### Boundaries
+
+- Filter by administrative level
+- Style disputed boundaries differently
+- Control maritime boundary display
+
+### POIs (Points of Interest)
+
+- Filter by category or specific types
+- Customize icons and colors
+- Control density and zoom-based visibility
+
+### Buildings
+
+- 3D extrusion settings
+- Color by height or type
+- Opacity and visibility controls
+
+### Terrain and Hillshading
+
+- Add terrain layers
+- Adjust hillshade intensity
+- Control exaggeration factors
+
+## Advanced Features
+
+### Working with Existing Styles
+
+The tool can modify existing Mapbox styles:
+
+- Import a style by ID or URL
+- Make targeted modifications
+- Preserve existing customizations while adding new features
+
+### Performance Optimization
+
+The builder can optimize styles for:
+
+- Mobile devices (reduced layer count)
+- High-density displays
+- Specific zoom ranges
+
+### Theme Variations
+
+Create multiple versions of a style:
+
+- Light and dark modes
+- Seasonal variations
+- Brand-specific color schemes
+
+## Best Practices
+
+1. **Start Simple**: Begin with basic requirements and iteratively add complexity
+2. **Test at Multiple Zooms**: Ensure your style works well across zoom levels
+3. **Consider Performance**: More layers and complex filters can impact rendering speed
+4. **Use Consistent Naming**: When creating custom layers, use clear, descriptive IDs
+5. **Document Your Choices**: Keep notes on why certain styling decisions were made
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Resources Not Loading**: Remember that sprite and glyph resources may not be accessible in Claude Desktop
+2. **Layer Conflicts**: Check layer ordering if elements appear hidden
+3. **Performance Issues**: Reduce layer count or simplify filters for better performance
+4. **Zoom Range Problems**: Verify minzoom and maxzoom settings on layers
+
+### Getting Help
+
+When encountering issues, provide:
+
+- The style configuration you're trying to achieve
+- Any error messages received
+- The platform/client you're using
+
+## Technical Details
+
+The Style Builder tool:
+
+- Generates Mapbox GL JS compatible style specifications
+- Follows the Mapbox Style Specification v8
+- Supports all standard Mapbox layer types
+- Can output styles for use in Mapbox GL JS, native SDKs, and Mapbox Studio
+
+## Limitations and Considerations
+
+- Some advanced Studio-only features may not be available
+- Custom data sources need to be added separately
+- Sprite and font resources must be hosted and accessible
+- Complex expressions may need manual refinement
+
+## Integration with Other Tools
+
+Once you've built or modified a style using the Style Builder:
+
+### Creating a New Style
+
+Use the **CreateStyleTool** to save your generated style to your Mapbox account:
+
+- The tool will create a new style with your specifications
+- Returns a style ID that you can use for further modifications
+
+### Updating an Existing Style
+
+Use the **UpdateStyleTool** to apply modifications to an existing style:
+
+- Provide the style ID or name of the style you want to update (if the name uniquely identifies it)
+- The tool will update the style with your new specifications
+
+### Previewing Your Style
+
+Use the **PreviewStyleTool** to generate a preview URL:
+
+- Instantly view your style in a browser
+- Test different zoom levels and locations
+- Share the preview link with team members
+
+**Example workflow for new style:**
+
+1. "Build a style with only roads and labels"
+2. "Now create this style in my account" → Uses CreateStyleTool
+3. "Generate a preview link for this style" → Uses PreviewStyleTool
+
+**Example workflow for modifying existing style:**
+
+1. "Modify my 'Winter Theme' style to add POIs with restaurant icons"
+2. "Update the style in my account" → Uses UpdateStyleTool (finds style by name)
+3. "Generate a preview link for this style" → Uses PreviewStyleTool
+
+**Alternative with style ID:**
+
+1. "Modify style clxyz123... to add building extrusions"
+2. "Update the style in my account" → Uses UpdateStyleTool (uses style ID)
+3. "Generate a preview link for this style" → Uses PreviewStyleTool
+
+## Next Steps
+
+After creating or modifying your style:
+
+1. Test in your target environment using the preview URL
+2. Use the style in your applications with the style ID
+3. Optimize for your specific use case
+4. Consider creating variations for different contexts
+5. Your styles are also viewable and editable in Mapbox Studio if needed
+
+For more information on Mapbox styles, refer to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/).

docs/style-resource-example.md

@@ -0,0 +1,144 @@
+# Mapbox Style Layers Resource Example
+
+This example demonstrates how the Mapbox Style Layers Resource guides LLMs in creating Mapbox styles based on natural language requests.
+
+## How It Works
+
+1. The `MapboxStyleLayersResource` is registered as an MCP resource at `resource://mapbox-style-layers`
+2. When an LLM receives a request like "create a style that highlights railways and parks, and changes water to yellow", it can:
+   - Query the resource to understand available layers
+   - Get the correct source-layer names, filters, and properties
+   - Generate proper Mapbox GL style JSON
+
+## Example User Requests
+
+### Request 1: "Highlight railways and parks, make water yellow"
+
+The resource guides the LLM to:
+
+- Use `water` layer (source-layer: "water") with `fill-color: "#ffff00"`
+- Use `landuse` layer filtered by `class: "park"` with bright green color
+- Use `road` layer filtered by `class: ["major_rail", "minor_rail"]` with red color
+
+### Request 2: "Create a dark mode map with prominent buildings"
+
+The resource guides the LLM to:
+
+- Set `land` background layer to dark color
+- Use `building` layer with light color and high opacity
+- Adjust text colors for visibility on dark background
+
+### Request 3: "Show only major roads and hide all labels"
+
+The resource guides the LLM to:
+
+- Include only `motorways` and `primary_roads` layers
+- Exclude all label layers (`place_labels`, `road_labels`, `poi_labels`)
+- Use appropriate filters like `["match", ["get", "class"], ["motorway", "trunk"], true, false]`
+
+## Resource Content Structure
+
+The resource provides:
+
+1. **Quick Reference**: Maps common user requests to specific layers
+2. **Layer Categories**: Groups layers by type (water, transportation, labels, etc.)
+3. **Detailed Specifications**: For each layer:
+   - Description
+   - Source layer name
+   - Layer type (fill, line, symbol, etc.)
+   - Common filters
+   - Paint properties with examples
+   - Layout properties with examples
+   - Example user requests
+
+4. **Expression Examples**: Common Mapbox GL expression patterns:
+   - Zoom-based interpolation
+   - Feature property matching
+   - Conditional styling
+
+## Usage in LLM Context
+
+When the LLM needs to create or modify a Mapbox style:
+
+1. It reads the resource to understand available layers
+2. Maps user intent to specific layers using the descriptions and examples
+3. Generates proper filter expressions using the provided patterns
+4. Creates valid paint and layout properties
+
+## Example Generated Style
+
+Based on "highlight railways and parks, yellow water":
+
+```json
+{
+  "version": 8,
+  "name": "Custom Style",
+  "sources": {
+    "composite": {
+      "type": "vector",
+      "url": "mapbox://mapbox.mapbox-streets-v8"
+    }
+  },
+  "layers": [
+    {
+      "id": "land",
+      "type": "background",
+      "paint": {
+        "background-color": "#f8f4f0"
+      }
+    },
+    {
+      "id": "water",
+      "type": "fill",
+      "source": "composite",
+      "source-layer": "water",
+      "paint": {
+        "fill-color": "#ffff00"
+      }
+    },
+    {
+      "id": "parks",
+      "type": "fill",
+      "source": "composite",
+      "source-layer": "landuse",
+      "filter": ["==", ["get", "class"], "park"],
+      "paint": {
+        "fill-color": "#00ff00",
+        "fill-opacity": 0.9
+      }
+    },
+    {
+      "id": "railways",
+      "type": "line",
+      "source": "composite",
+      "source-layer": "road",
+      "filter": [
+        "match",
+        ["get", "class"],
+        ["major_rail", "minor_rail"],
+        true,
+        false
+      ],
+      "paint": {
+        "line-color": "#ff0000",
+        "line-width": [
+          "interpolate",
+          ["exponential", 1.5],
+          ["zoom"],
+          14,
+          2,
+          20,
+          8
+        ]
+      }
+    }
+  ]
+}
+```
+
+## Benefits
+
+1. **Accuracy**: LLM uses correct source-layer names and properties
+2. **Completeness**: All necessary filter expressions are included
+3. **Best Practices**: Follows Mapbox GL style specification patterns
+4. **Natural Language**: Users can describe what they want without knowing technical details